nativeapps

README

Floe Native Apps

A private graphical runtime for applications on your Linux host.

Prepare Xpra, a headless X server, and their native dependencies through one Go API. Keep applications on the host, with their own files, identity, and permissions.

Get started · Integration · Platforms · Contributing · Security

What it does

Floe Native Apps supplies the optional native graphics layer behind a host application launcher. A server can start without a desktop environment or a monitor. The SDK acquires a pinned component set into a private directory, verifies it, and proves that it can render a window, receive input, and retain the same application across WebSocket viewer disconnects before making it available to the product.

• Private installation: no root password, system package installation, global loader configuration, or changes to the host's software sources.
• Verified acquisition: exact archive sizes and SHA-256 digests, bounded extraction, contained links, and atomic activation after a graphical check.
• Recoverable preparation: observable progress, owner-scoped cancellation, idempotent requests, explicit interruption after restart, and offline delivery.
• Native execution: the user's applications run directly on Linux. No production container or virtual machine sits between the application and host.

This is an embeddable preparation SDK. The consuming product supplies the app catalog, authorization, session lifecycle, viewer, and user interface. Redeven is one consumer.

flowchart LR
    Catalog["Pinned publisher archives"] --> Verify["Download & verify"]
    Offline["Offline ZIP"] --> Verify
    Verify --> Stage["Private staging directory"]
    Stage --> Check["Launch · pixels · input"]
    Check --> Ready["Atomic activation"]

Get started

Use Go 1.27.1, aligned with Redeven. Install the released module:

go get github.com/floegence/floe-native-apps@v0.5.0

Select a supported package and create one long-lived manager for an absolute, private state directory. Construction does not download or execute components. Start preparation only after the host product admits the user's action.

pkg, err := nativeapps.NativePackage()
if err != nil {
    return err // Unsupported hosts must not offer Linux preparation.
}
manager, err := nativeapps.New(stateRoot, pkg, nil)
if err != nil {
    return err
}
defer manager.Close()

// Derive owner from the authenticated session. Retain requestID across retries.
status, err := manager.Start(owner, requestID, "download", 0)
if err != nil {
    return err
}
_ = status // Observe progress with Watch and Snapshot until ready or failure.

Import the package as nativeapps "github.com/floegence/floe-native-apps". The compiling lifecycle example demonstrates subscription, terminal states, context cancellation, and tool resolution. In a service, keep the manager alive across HTTP requests; closing it cancels active preparation.

To try the standalone qualification tool on a Linux host:

go run ./cmd/floe-native-apps -state "$HOME/.local/share/floe-native-apps"

The command reports JSON progress, performs the real graphical check, and prints the installed directory when ready. It prepares components; it does not expose a remote desktop or launch a user's application.

Integration contract

Owner	Responsibilities
This SDK	Fixed catalog, downloads, verification, extraction, private support environment, durable preparation, graphical self-check
Host product	User admission, authentication, state-directory ownership, application metadata, private display/session, application launch, viewer and window lifetime
Operating system	Process identity, filesystem permissions, network policy, executable mounts, and security policy

Observe current state. Watch provides coalesced invalidations, not an event log. Subscribe, read Snapshot(owner), and read it again after each notification. Unsubscribing or losing an observer does not cancel preparation. state reports one preparation operation; installed.ready independently reports the current usable installation. Directory continues resolving it during an update and after failure, cancellation or interruption. Retry requires an explicit user action. No partial installation is activated.

Update components independently. SDK upgrades continue accepting published r1 and r2 installations for the matching architecture and private Xpra 6 contract. update_available compares the active installation with the reviewed recommendation; it does not disable the installed feature. The v1 operation record is migrated atomically to v2 with an explicit installed identity. Unknown records are rejected without rewriting them, and damaged installations retain a distinct diagnostic. Package digests and existing package trees are unchanged. The r1 recipe retains its known short-frame decoder defect; compatibility does not claim that old bytes contain the r2 fix. Offer the r2 update to improve connection stability. Do not prepare components merely because a status was read.

Keep running applications on their original components. Persist the selected installed.digest with a new backend and use DirectoryFor when recovering it. InstallationForProcess can identify a legacy private loader from a verified Linux process generation; the host must still verify application ownership and backend identity. Updates retain previous package directories and change the selection only after the target passes graphical qualification. There is no automatic installed-package garbage collection.

Transfer only missing archives. After explicit user action, Plan(ctx) verifies the host cache and reports the target digest and missing original archive identities/bytes. Complete caches use Start(..., "cache", 0) with no network or upload. Otherwise the host downloads missing files, or Desktop uses WriteTransferBundle with its own trusted matching catalog. Plans cannot select URLs, paths or unrecognized artifacts. An old Desktop must report a target mismatch rather than silently substituting its package. The receiver verifies the union of cached and uploaded files; stale plans fail without changing the installed selection. Complete offline ZIPs remain supported.

Preserve request identity. Retry an uncertain Start response with the same owner, request ID, source, and upload size. A competing operation returns ErrBusy. Only the authenticated operation owner may upload or cancel. The consumer must authorize reads and writes before calling the SDK; an owner string is an identity binding, not an authentication mechanism.

Keep support libraries out of host applications. Use the complete toolset from ResolveTools and Tools.Environment for support processes. Before a GIO launch, restore the saved FLOE_NATIVE_APPLICATION_ENV map onto the application's launch context and remove that variable and FLOE_NATIVE_ROOT. Retain the session's private display and D-Bus addresses. Never export the private loader path to user applications or substitute the support Python for their interpreter.

Keep the trust boundary closed. Use the checked-in catalog selected through NativePackage or ForPlatform. Do not accept executable paths, artifact URLs, hashes as acquisition specifications, or custom catalogs from renderer/client input. Transfer plan identities may only select a subset of the matching compiled catalog. Pass nil as the validator to retain the built-in graphical check. A custom validator is a trusted host integration hook, not a client option.

Disable unused audio completely. Append XpraNoAudioArgs() when starting a silent Xpra 6.x graphics session. It disables the audio subsystem, PulseAudio, speaker, and microphone support. --speaker=off and --microphone=off only start muted; they still initialize audio codecs and can make every window inventory query wait five seconds when an audio backend is unavailable. The graphical self-check uses the same options and requires two inventory queries to complete within three seconds each, in addition to proving decoded pixels and input. Consumers retain their own authentication, private display, process lifetime, transport, and actual-window readiness checks.

Offline delivery

Hosts that supply another reviewed archive catalog can use the public github.com/floegence/floe-native-apps/artifactcache package. This is the same acquisition implementation used by native component preparation and offline bundles. It downloads original publisher bytes without extracting or executing them, independently of the downloading machine's OS and architecture.

result, err := artifactcache.Acquire(ctx, privateCacheDirectory, artifactcache.Spec{
    URL: pinnedPublisherURL,
    SHA256: pinnedSHA256,
    SizeBytes: pinnedSize,
}, artifactcache.Options{
    OnProgress: func(p artifactcache.Progress) error {
        // Absolute byte counts; checking, downloading, or verifying.
        return report(p)
    },
})
// Use result.Path only after success. result.FromCache identifies a verified hit.

The host chooses the catalog, absolute private cache directory and user consent before calling Acquire; renderer-supplied URLs, digests and paths are not a trusted catalog. Cache filenames are exact SHA-256 digests. Every reuse checks length and digest without network access. Verify validates an existing regular file without modifying it; integrity errors match artifactcache.ErrIntegrity, while cancellation and filesystem errors retain their normal classifications. HTTP redirects cannot downgrade HTTPS. Invalid or incomplete downloads never replace a cache entry. Concurrent acquisitions serialize through an OS-backed cache lease, recheck verified files after waiting, and release ownership on cancellation or process exit. The returned path from Acquire must not race with maintenance. Consumers that read archives while maintenance is enabled use OpenSession, then its Acquire, Verify, and Path methods, retaining the session until the last read.

Session.Prune and standalone Maintain accept an opt-in artifactcache.Policy with MaxIdleAge and MaxBytes. Zero disables each limit. Maintenance first removes expired archives, then evicts the least recently used archives to meet the byte budget. Successful acquisition or Session.Touch refreshes file mtime; existing files use their original mtime without an index migration. Only recognized regular archive and abandoned download files are removed. Symlinks, unknown files, subdirectories and the stable lease file are preserved. Maintain can return ErrBusy immediately instead of waiting for active readers.

WriteBundleWithOptions and WriteTransferBundleWithOptions retain this lease through ZIP creation. BundleOptions supplies optional retention and structured progress: waiting, checking, downloading and packing. Cache/download totals remain absent until inspection completes; downloaded bytes count only network reads. Maintenance runs after packing or failure; its separate callback reports cleanup errors without replacing the acquisition result. Existing bundle methods delegate to the same path without enabling archive eviction. Products own consent, private placement, policy values and localized presentation. This API grants neither permission to install nor to execute an archive.

Acquire original publisher archives on Linux, macOS, or Windows for a Linux target. Acquisition does not execute those components on the downloading machine.

go run ./cmd/floe-native-apps \
  -arch arm64 \
  -state /absolute/private/cache \
  -bundle /absolute/native-arm64.zip

On the receiving host:

1. Call Start(owner, requestID, "upload", actualZIPSize).
2. Send ordered chunks of at most 256 KiB through WriteChunk using the returned operation ID. An identical replay is accepted; gaps and conflicting replays are rejected. Resume an interrupted connection from ReceivedBytes.
3. Call CompleteUpload. The host verifies every original archive and performs the same installation and graphical qualification as a direct download.

A process restart reports an interrupted operation and discards incomplete staging; begin a new admitted operation. An already activated package remains available. Redistributing the ZIP carries the components' license obligations.

Platforms and requirements

Capability	Platforms
Install and execute native graphics	Linux amd64, Linux arm64; glibc and musl hosts
Acquire an offline ZIP	Linux, macOS, Windows; portable CLI builds checked for amd64 and arm64
macOS application capture and control	Owned by the consuming product's macOS integration

The pinned stack uses Alpine 3.23 packages, Xpra 6.2.2, and Xpra HTML5 v20. Each architecture includes its own musl loader and library closure. It does not replace the host's libc. Applications still use their own installed dependencies.

The host needs an executable writable state filesystem, a compatible Linux kernel, /bin/sh and basic shell utilities, ordinary process/Unix socket permissions, and access to the catalog's HTTPS publishers (or an offline ZIP). A physical monitor, desktop session, GPU, and system Xpra installation are not required. X11 applications are the target; native Wayland-only applications, GPU/DRM capture, and arbitrary third-party application compatibility are outside this SDK's guarantee. SELinux, AppArmor, and other host policies remain in force; a denied operation fails without changing policy or escalating privileges.

Qualification evidence

The component set shipped since v0.1.2 passed GIO application launch, a live private D-Bus connection, window discovery, decoded pixels, and input delivery:

Environment	Architecture	Evidence scope
Ubuntu 22.04; Debian 11	arm64; amd64 respectively	Native hosts
Debian 13; Alpine 3.23	amd64 and arm64	Clean unprivileged userspace fixtures
Arch Linux; Rocky Linux 9; AlmaLinux 9; RHEL UBI 9	amd64	Clean unprivileged userspace fixtures

RHEL UBI qualifies the userspace image, not a subscribed RHEL host, its kernel, or every SELinux policy. The release qualification workflow repeats fresh installation on native GitHub Linux runners for both architectures and runs the clean distribution fixtures. Its logs record the actual images and results. Containers are test fixtures only.

Development and maintenance

./scripts/check.sh
# Network-backed security checks, also scheduled and required for releases:
go tool govulncheck ./...
go tool govulncheck golang.org/x/vuln/cmd/govulncheck github.com/rhysd/actionlint/cmd/actionlint

The source gate checks formatting, module tidiness and checksums, vet, race tests, workflow syntax, Python/shell syntax, and six portable build targets. Tests cover malicious archives, integrity, ownership, idempotency, cancellation, restart, persistence failure, and activation. The runtime uses the Go standard library; go.mod and go.sum additionally pin maintained development tools and their transitive dependencies. Native archive integrity is separately pinned in catalog.json.

CodeQL scans Go, Python, and GitHub Actions daily and on demand with extended security queries. Dependency vulnerability checks run daily and before release. Dependabot proposes weekly dependency and action updates; updates require review and passing checks. See CONTRIBUTING.md for release criteria, platform qualification, catalog changes, and commit attribution.

License and security

The Go SDK, installer, and repository code are MIT-licensed. Downloaded components retain their original licenses; each catalog entry records its publisher URL, SHA-256, license, and source location. This repository releases source and a catalog, not a combined third-party binary distribution. If you redistribute archives or an installed stack, satisfy the relevant licenses, including applicable source availability obligations. Retained original license files and catalog metadata are evidence, not a substitute for those obligations.

Report vulnerabilities through GitHub's private reporting form. See SECURITY.md for the security boundary and supported versions.

Application lifetime primitives

WriteApplicationLauncher supplies a Linux GIO launcher that restores the host application environment and observes the launched process tree, including adopted descendants. Invoke it using the native tools’ Python with the selected absolute desktop-entry path and a private receipt path. The atomic receipt reports running, exited, or failed; running does not imply a window or decoded pixels. XpraApplicationLifetimeArgs keeps the display alive until that monitored child exits, independently of viewer detachment or window count.

ObserveProcess and ProcessIdentity.Alive distinguish one Linux process generation from a reused PID across host restarts. This is observation, not authorization or permission to signal a persisted PID. A consumer recovering a backend must also verify its private endpoint identity. Consumers continue to own application inventory, authorization, instance persistence, sharing connections, resource limits and explicit termination policy. These primitives do not create a background service or recover applications whose display server was destroyed.

Client-owned input

Input protocol version 1 gives the client sole ownership of composition and candidate selection. The host has no composition engine or candidate window. It delivers keys through Xpra and confirmed Unicode through the application's toolkit context or the commit-only xcb-imdkit bridge, without clipboard injection.

Probe the interpreter owning Xpra with ProbeClientInput. Managed tools expose Tools.Python; SystemClientInputPython resolves a supported installed script's interpreter. Both use the same launcher and scheduler. The current contract requires the Xpra 6 server API, GIO and xcb-imdkit/xcb libraries; managed r3 supplies that closure. Existing r1/r2 installations remain identifiable for surviving apps but do not acquire this capability merely by upgrading the SDK. The same aggregate server adapter is qualified with managed Xpra 6.2.2 and system Xpra 6.5.3; it does not depend on their different internal input mixins.

PrepareClientInput installs adapters in a new private session directory. Run its Launcher with that interpreter, normal Xpra arguments and XpraArgs. Start the private application bus first and pass its address explicitly to the application environment. The bridge starts before applications. These input settings are confined to that session; host desktop IBus/Fcitx and global input sources are untouched. GTK3 and GTK4 adapters require glibc 2.31 or later (GTK4 4.0 or later); Qt5 requires 5.15 or later, and Qt6 requires 6.4 with glibc 2.36 or later. Other XIM-aware apps use the protocol bridge with a UTF-8 locale; non-Unicode XIM contexts are rejected before delivery. Incompatible/private toolkit loaders are not claimed as supported adapters. GTK4 modules use a private, ABI-specific GTK_PATH; GTK3 retains its module cache. No GTK4 library is injected into GTK3 or generic GIO processes.

PrepareInputClient prepares Xpra HTML5 v20/v21 with external input ownership. The bootstrap window.floeXpraInput.version is 2, independently of the unchanged version 1 text and pointer protocols. It identifies the prepared focus contract and GTK4-capable release. Consumers must reject older prepared sessions before creating input controllers; preserve their processes and ask users to save, quit and reopen. Reconnecting alone does not replace a running application's assets. The host obtains the client with window.floeXpraInput.getClient() and uses client.floeInput. bindTarget(wid) returns an immutable connection/window token; sendKey, commitText, release, clipboard and paste consume it. Wire these to the published floe-webapp remote-input controller and attach paste to its textarea. The host owns permissions, first-frame gating, labels, keyboard controls and errors. The adapter registers no DOM input. Xpra's old keyboard/tablet/virtual keyboard listeners and focus-stealing clipboard handlers are removed; graphics, windows, pointer and clipboard transport stay with Xpra.

OpenClientAssets(preparedDirectory) creates an immutable public-resource snapshot of that prepared client. It precompresses assets, supplies a digest of their exact names and bytes, and implements http.Handler for resource paths such as /js/Client.js. Mount it behind host authorization at a stable path containing assets.Digest(), stripping that prefix before serving. Use assets.RewriteHTML(document, "/client/"+assets.Digest()+"/") on each uncached, authenticated session document. Resources can then be reused across session URLs; the original graphics and protocol workers resolve their imports from the same resource version. Source directories and installed vendor files remain unchanged.

Only recognized public scripts, styles, images and fonts are included. HTML, configuration, credentials and session data are never served by this handler. The version includes the prepared input adapter and worker changes, not only the native package identity. Successful GET/HEAD responses use private immutable caching, representation-specific ETags and negotiated gzip; errors are uncached. Hosts own snapshot lifetime, permission checks and exact digest routing. A cached script grants no authority to view or control an application. Normal HTTPS/client trust and browser capability checks still govern video decoding; resource caching does not enable secure-context capabilities over an insecure connection.

Both authenticated hellos advertise floe-input: 1. Old clients cannot enter this input flow. Old sessions must be reopened explicitly without terminating unsaved applications. floe-input(sequence, window, text) accepts one nonempty, NUL-free commit up to 16,000 UTF-8 bytes. No commit is truncated or retried. XIM delivers bounded UTF-8 fragments to the same input context because legacy consumers have fixed lookup buffers. The scheduler holds later input until every fragment is acknowledged; cancellation discards unsent fragments and never replays a partially delivered operation. GTK/Qt receive one native text commit. Text, following keys, pointer/focus changes and clipboard claims share one scheduler. Toolkit acknowledgement occurs after committing in its native input filter; a D-Bus transport reply is not application delivery. XIM uses protocol synchronization. Invalid or timed-out contexts return an explicit error, revoke the attachment's pending input and release its held keys. Reattachment does not replay input.

Input bodies and document histories are not logged. Pending text exists only until delivery or revocation. onError(code) exposes stable error codes without user text. See CONTRIBUTING.md for native qualification and THIRD_PARTY_NOTICES.md for licenses and module provenance.

Documentation

Overview

Package nativeapps prepares a private native graphical stack without changing system packages. Callers own user consent, authorization, and application launch.

Index

• Constants
• Variables
• func CursorClientSource() []byte
• func DialDesktop(context.Context, DesktopEndpoint) (*DesktopConnection, DesktopState, error)
• func PrepareInputClient(source, destination string) error
• func SelfTest(context.Context, string) error
• func SystemClientInputPython(ctx context.Context, xpra string, environment []string) (string, error)
• func WriteApplicationLauncher(directory string) (string, error)
• func WriteBundle(ctx context.Context, pkg Package, cacheRoot string, output io.Writer, ...) error
• func WriteBundleWithOptions(ctx context.Context, pkg Package, cacheRoot string, output io.Writer, ...) error
• func WriteTransferBundle(ctx context.Context, pkg Package, plan TransferPlan, cacheRoot string, ...) error
• func WriteTransferBundleWithOptions(ctx context.Context, pkg Package, plan TransferPlan, cacheRoot string, ...) error
• func XpraApplicationLifetimeArgs() []string
• func XpraNoAudioArgs() []string
• type ApplicationLaunchPlan
  • func PlanApplication(ctx context.Context, options ApplicationPlanOptions) (ApplicationLaunchPlan, error)
  • func (p ApplicationLaunchPlan) Description() ApplicationPlanDescription
  • func (p ApplicationLaunchPlan) Revalidate(ctx context.Context, options ApplicationPlanOptions) error
  • func (p ApplicationLaunchPlan) Write(directory string) (string, error)
• type ApplicationPackage
• type ApplicationPlanDescription
• type ApplicationPlanOptions
• type Artifact
• type BackendCapability
• type BundleOptions
• type BundleProgress
• type ClientAssets
  • func OpenClientAssets(directory string) (*ClientAssets, error)
  • func (a *ClientAssets) Digest() string
  • func (a *ClientAssets) RewriteHTML(document []byte, basePath string) ([]byte, error)
  • func (a *ClientAssets) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ClientInput
  • func PrepareClientInput(directory, architecture string) (ClientInput, error)
  • func (input ClientInput) XpraArgs(baseEnvironment []string) []string
• type ClientInputCapability
  • func ProbeClientInput(ctx context.Context, python string, environment []string) (ClientInputCapability, error)
• type DesktopConnection
  • func (c *DesktopConnection) Close() error
  • func (c *DesktopConnection) Connection() uint64
  • func (c *DesktopConnection) Read(ctx context.Context) (DesktopEvent, error)
  • func (c *DesktopConnection) Send(ctx context.Context, request DesktopRequest) (uint64, error)
• type DesktopCursor
• type DesktopEndpoint
• type DesktopEvent
• type DesktopFrame
• type DesktopRequest
• type DesktopState
• type DesktopWindow
• type Installation
• type LaunchUnavailable
  • func (e *LaunchUnavailable) Error() string
• type Manager
  • func New(root string, pkg Package, validate func(context.Context, string) error) (*Manager, error)
  • func (m *Manager) Cancel(owner, id string) (Status, error)
  • func (m *Manager) Close()
  • func (m *Manager) CompleteUpload(owner, id string) (Status, error)
  • func (m *Manager) Directory() (string, error)
  • func (m *Manager) DirectoryFor(digest string) (string, error)
  • func (m *Manager) InstallationForProcess(process ProcessIdentity) (*Installation, error)
  • func (m *Manager) Package() Package
  • func (m *Manager) Plan(ctx context.Context) (TransferPlan, error)
  • func (m *Manager) Snapshot(owner string) Status
  • func (m *Manager) Start(owner, requestID, source string, uploadSize int64) (Status, error)
  • func (m *Manager) Watch() (<-chan struct{}, func())
  • func (m *Manager) WriteChunk(owner, id string, offset int64, data []byte) (Status, error)
• type Package
  • func ForPlatform(platform, architecture string) (Package, error)
  • func NativePackage() (Package, error)
  • func (p Package) Digest() string
  • func (p Package) Validate() error
• type PreparedViewer
  • func PrepareViewer(source string) (*PreparedViewer, error)
  • func (v *PreparedViewer) Assets() *ClientAssets
  • func (v *PreparedViewer) Document(basePath string) ([]byte, error)
• type ProcessIdentity
  • func ObserveProcess(_ int) (ProcessIdentity, error)
  • func (p ProcessIdentity) Alive() bool
• type Status
  • func (s Status) Active() bool
• type Tools
  • func ResolveTools(root string) (Tools, error)
  • func (t Tools) Environment(base []string) []string
• type TransferPlan

Examples

• New

Constants

const ClientInputTextLimit = 16000

ClientInputTextLimit bounds one atomic text commit in UTF-8 bytes. Applications must report rejected commits; truncation and automatic retry are forbidden.

const ClientInputVersion = 1

ClientInputVersion is the confirmed-text protocol advertised on Xpra's authenticated connection. Consumers must reject sessions without this version.

Variables

var ErrBusy = errors.New("native preparation is already running")

var ErrDesktopProtocol = errors.New("invalid native desktop helper protocol")

ErrDesktopProtocol reports invalid helper framing or metadata, without including application content, input text, or authentication material.

var ErrForbidden = errors.New("native preparation belongs to another caller")

var ErrInvalid = errors.New("invalid native preparation request")

var ErrUnsupported = errors.New("native graphical components are unavailable for this platform")

Functions

func CursorClientSource

func CursorClientSource() []byte

CursorClientSource returns the shared standalone JavaScript cursor owner. Consumers build this released asset into their viewer instead of duplicating normalization. FloeRemoteCursor accepts an apply callback and PNG metadata. Its receive, hide, reset and dispose methods own decode/DPR resource lifetime.

func DialDesktop

func DialDesktop(context.Context, DesktopEndpoint) (*DesktopConnection, DesktopState, error)

DialDesktop attaches to the Linux graphical helper on its own host. Other platforms retain their existing native backends; no remote socket fallback or second authentication channel is introduced here.

func PrepareInputClient

func PrepareInputClient(source, destination string) error

PrepareInputClient prepares an Xpra HTML5 v20/v21 distribution with exactly one external keyboard owner and one external pointer owner. It retains the graphics, clipboard and pointer transport. The destination must not exist. Neither a failed preparation nor an unsupported source is usable as a client. Consumers serve this directory through the same authenticated Xpra endpoint.

func SelfTest

func SelfTest(context.Context, string) error

Only Linux executes graphical components. Other hosts can acquire bundles.

func SystemClientInputPython

func SystemClientInputPython(ctx context.Context, xpra string, environment []string) (string, error)

SystemClientInputPython resolves the interpreter selected by an installed Xpra script, then probes that exact interpreter. It never substitutes the host's unrelated desktop Python or installs missing system dependencies.

func WriteApplicationLauncher

func WriteApplicationLauncher(directory string) (string, error)

WriteApplicationLauncher installs the Linux GIO launcher in a consumer-owned private directory. Invoke it with the tools' Python, an absolute .desktop file and an absolute receipt path. The atomic receipt reports running, exited or failed. A running receipt confirms process launch, not window/pixel readiness. Spawn failures include phase and a stable error_code. Final receipts include the actual direct-launcher exit_code (negative for a signal), per-launcher statuses and termination_requested. These are process observations; the graphical backend determines whether launch or established execution ended. The supervisor retains a nonzero launcher result after reaping descendants. The launcher restores the host application environment and reaps descendants; closing a window or losing a viewer never terminates the application. A verified Snap plan additionally requires FLOE_NATIVE_HOST_BUS to identify the real user bus, separate from DBUS_SESSION_BUS_ADDRESS. Only the supervisor receives that handoff; it is removed from the final application's environment. The supervisor exposes only its admitted direct launcher's scope operation.

func WriteBundle

func WriteBundle(ctx context.Context, pkg Package, cacheRoot string, output io.Writer, progress func(int64)) error

WriteBundle acquires the exact catalog archives for an offline host. It neither extracts nor executes them; the destination host verifies every original byte. Callers must publish the output only after this function returns successfully.

func WriteBundleWithOptions

func WriteBundleWithOptions(ctx context.Context, pkg Package, cacheRoot string, output io.Writer, options BundleOptions) error

WriteBundleWithOptions keeps the cache lease through the final ZIP read and applies optional maintenance afterwards, including on cancellation or failure.

func WriteTransferBundle

func WriteTransferBundle(ctx context.Context, pkg Package, plan TransferPlan, cacheRoot string, output io.Writer, progress func(int64)) error

WriteTransferBundle accepts only a subset of the supplied trusted recipe. Consumer adapters must resolve pkg from their compiled catalog, not a client. An empty plan needs no bundle: use Manager.Start with source "cache" instead.

func WriteTransferBundleWithOptions

func WriteTransferBundleWithOptions(ctx context.Context, pkg Package, plan TransferPlan, cacheRoot string, output io.Writer, options BundleOptions) error

WriteTransferBundleWithOptions validates receiver identities before any cache access, then uses the same leased acquisition path as a complete bundle.

func XpraApplicationLifetimeArgs

func XpraApplicationLifetimeArgs() []string

XpraApplicationLifetimeArgs binds an Xpra server to a monitored application child, independently of its viewers and windows. Use a --start-child command that remains alive until the application and its descendants have exited. Consumers still own application authorization, persistence and session policy.

func XpraNoAudioArgs

func XpraNoAudioArgs() []string

XpraNoAudioArgs disables audio support for a silent Xpra 6.x graphics session. Muting the speaker and microphone with "off" still initializes audio codecs; a missing audio backend can then delay every server inventory request. Session ownership, transport, and all other feature choices remain with the host.

Types

type ApplicationLaunchPlan

type ApplicationLaunchPlan struct {
	// contains filtered or unexported fields
}

ApplicationLaunchPlan is an immutable, short-lived snapshot. It is not an authorization token, a persistent application record, or a backend fallback. Package updates require a fresh plan before executing the application.

func PlanApplication

func PlanApplication(ctx context.Context, options ApplicationPlanOptions) (ApplicationLaunchPlan, error)

PlanApplication observes the desktop entry and installed package metadata without starting an application. Unknown protocol metadata selects the combined Wayland/Xwayland backend; its absence is explicit, never an Xpra retry.

func (ApplicationLaunchPlan) Description

func (p ApplicationLaunchPlan) Description() ApplicationPlanDescription

func (ApplicationLaunchPlan) Revalidate

func (p ApplicationLaunchPlan) Revalidate(ctx context.Context, options ApplicationPlanOptions) error

Revalidate rereads the same desktop entry, executable and package revision. The supervisor must also revalidate at its execution boundary. Calling this method alone cannot authorize a later unchecked launch.

func (ApplicationLaunchPlan) Write

func (p ApplicationLaunchPlan) Write(directory string) (string, error)

Write places this plan in the new application's private directory. Invoke the installed application launcher as --plan PATH RECEIPT. It revalidates before GIO creates a child; graphical resources must already match Backend.Component. Do not overwrite a running instance's plan or change its backend identity.

type ApplicationPackage

type ApplicationPackage struct {
	Kind        string `json:"kind"`
	ID          string `json:"id"`
	Revision    string `json:"revision"`
	Version     string `json:"version,omitempty"`
	Confinement string `json:"confinement,omitempty"`
	Application string `json:"application,omitempty"`
	SecurityTag string `json:"security_tag,omitempty"`
	Ref         string `json:"ref,omitempty"`
	Deployment  string `json:"deployment,omitempty"`
	Format      int    `json:"format,omitempty"`
}

type ApplicationPlanDescription

type ApplicationPlanDescription struct {
	Version       int                `json:"version"`
	SHA256        string             `json:"sha256"`
	Backend       BackendCapability  `json:"backend"`
	Package       ApplicationPackage `json:"package"`
	Services      []string           `json:"services"`
	Desktop       string             `json:"desktop"`
	DesktopSHA256 string             `json:"desktop_sha256"`
}

ApplicationPlanDescription describes identity and required resources without granting readiness or input permission. Each call returns independent values.

type ApplicationPlanOptions

type ApplicationPlanOptions struct {
	Python      string
	Environment []string
	DesktopFile string
	Backends    []BackendCapability
}

ApplicationPlanOptions contains the already authorized host desktop entry. Python must provide GIO. Environment is the original host environment, or a Tools.Environment result whose saved overrides the planner restores.

type Artifact

type Artifact struct {
	Name    string `json:"name"`
	URL     string `json:"url"`
	SHA256  string `json:"sha256"`
	Size    int64  `json:"size_bytes"`
	Format  string `json:"format"`
	License string `json:"license"`
	Source  string `json:"source"`
}

type BackendCapability

type BackendCapability struct {
	ID        string   `json:"id"`
	Component string   `json:"component"`
	Protocols []string `json:"protocols"`
	Services  []string `json:"services,omitempty"`
}

BackendCapability describes one prepared backend. The trusted host obtains these values from its installed backend, never from a browser request. A capability describes available resources, not application readiness.

type BundleOptions

type BundleOptions struct {
	CachePolicy   artifactcache.Policy
	OnProgress    func(BundleProgress) error
	OnMaintenance func(artifactcache.Maintenance, error)
	// Client is a trusted network policy/test hook, never a renderer input.
	Client *http.Client
}

type BundleProgress

type BundleProgress struct {
	Phase           string `json:"phase"`
	ComponentBytes  int64  `json:"component_bytes"`
	CachedBytes     *int64 `json:"cached_bytes,omitempty"`
	DownloadBytes   *int64 `json:"download_bytes,omitempty"`
	DownloadedBytes int64  `json:"downloaded_bytes"`
}

BundleProgress distinguishes verified cache bytes from actual network bytes. Totals remain absent until every requested archive has been checked.

type ClientAssets

type ClientAssets struct {
	// contains filtered or unexported fields
}

ClientAssets is an immutable snapshot of public resources from a directory produced by PrepareInputClient. It excludes HTML, configuration and session files. Hosts own authorization, route placement and snapshot lifetime.

func OpenClientAssets

func OpenClientAssets(directory string) (*ClientAssets, error)

OpenClientAssets snapshots and precompresses a prepared Xpra HTML5 v20/v21 client. Worker URLs follow the script's resource directory, independently of the session document URL. The source and installed vendor files are unchanged. The digest covers the exact prepared resource names and bytes, including the input adapter and worker transformation, rather than only the native recipe.

func (*ClientAssets) Digest

func (a *ClientAssets) Digest() string

Digest is the content version to include in the host's resource route.

func (*ClientAssets) RewriteHTML

func (a *ClientAssets) RewriteHTML(document []byte, basePath string) ([]byte, error)

RewriteHTML relocates only references to resources in this snapshot. basePath must be an absolute same-origin directory path containing the content version. It leaves WebSocket addresses, session settings and inline startup code alone. The resulting session document must remain authenticated and uncached.

func (*ClientAssets) ServeHTTP

func (a *ClientAssets) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves a resource path (for example /js/Client.js). The host must first select this snapshot by its exact digest and strip the versioned prefix. Authorization belongs before this handler. Cached scripts never authorize a connection: hosts must continue authenticating session documents and traffic.

type ClientInput

type ClientInput struct {
	Launcher, GTKModules, QtPlugins string
	// GTKPath is a private module root. Only GTK4 scans its 4.0.0 ABI directory;
	// GTK3 uses GTKModules and must never load the GTK4 shared object.
	GTKPath string
}

ClientInput is prepared support for one private X11 application session. Launch Launcher with the probed Xpra Python interpreter, normal Xpra arguments and XpraArgs. Start a private session bus first and pass its address explicitly to the application's start environment. These paths contain first-party adapters, never a copied host toolkit or a second input method engine.

func PrepareClientInput

func PrepareClientInput(directory, architecture string) (ClientInput, error)

PrepareClientInput installs the complete input contract into a new absolute private directory. The architecture is the application host's Go architecture.

func (ClientInput) XpraArgs

func (input ClientInput) XpraArgs(baseEnvironment []string) []string

XpraArgs selects client-owned composition in the private application environment. No host desktop input configuration is inherited or modified.

type ClientInputCapability

type ClientInputCapability struct {
	Version     int    `json:"version"`
	XpraVersion string `json:"xpra_version"`
}

func ProbeClientInput

func ProbeClientInput(ctx context.Context, python string, environment []string) (ClientInputCapability, error)

ProbeClientInput checks the interpreter and original XIM library before any application is launched. It does not acquire components or require a display. A successful probe does not assert that a particular application has a focused editable input context; that boundary is checked for every submitted commit.

type DesktopConnection

type DesktopConnection struct {
	// contains filtered or unexported fields
}

DesktopConnection owns one authenticated helper attachment. It has no process owner, reconnect loop, frame queue, input scheduler, or implicit frame ack. One goroutine reads events while writers may send requests concurrently. Native validation and ordering remain authoritative in the helper.

func (*DesktopConnection) Close

func (c *DesktopConnection) Close() error

Close revokes this sharing attachment. It never terminates the helper, display or application. The helper releases input owned by the detached attachment.

func (*DesktopConnection) Connection

func (c *DesktopConnection) Connection() uint64

Connection returns the immutable attachment generation assigned by the helper. Reattachment creates another DesktopConnection and another generation.

func (*DesktopConnection) Read

func (c *DesktopConnection) Read(ctx context.Context) (DesktopEvent, error)

Read returns one complete event without buffering subsequent frames or acknowledging pixels. Only one reader may call Read at a time. Cancellation closes the attachment rather than retaining a partially consumed packet.

func (*DesktopConnection) Send

func (c *DesktopConnection) Send(ctx context.Context, request DesktopRequest) (uint64, error)

Send writes one bounded request and returns its sequence. The reply is read by Read. Cancellation during I/O closes this attachment; no request is replayed. A caller should use a separate continuous reader so frame delivery cannot prevent it from consuming replies. Input ordering belongs to the helper.

type DesktopCursor

type DesktopCursor struct {
	Mode          string  `json:"mode"`
	Sequence      uint64  `json:"sequence"`
	Connection    uint64  `json:"connection"`
	Window        uint64  `json:"window"`
	Generation    uint64  `json:"generation"`
	Encoding      string  `json:"encoding,omitempty"`
	Width         int     `json:"width,omitempty"`
	Height        int     `json:"height,omitempty"`
	LogicalWidth  int     `json:"logical_width,omitempty"`
	LogicalHeight int     `json:"logical_height,omitempty"`
	XHot          float64 `json:"xhot,omitempty"`
	YHot          float64 `json:"yhot,omitempty"`
}

DesktopCursor carries the current native pointer shape. Image dimensions describe PNG pixels; LogicalWidth/Height and the hotspot are surface units. The shared cursor client caps CSS size without applying buffer scale twice. Hidden and default modes contain no pixel payload. Sequence is compositor-wide.

type DesktopEndpoint

type DesktopEndpoint struct {
	SocketPath string
	Instance   string
	Token      string
}

DesktopEndpoint identifies an existing private helper. A trusted application instance supplies these values; they are never taken from viewer input.

type DesktopEvent

type DesktopEvent struct {
	Event      string          `json:"event,omitempty"`
	ID         uint64          `json:"id,omitempty"`
	Version    int             `json:"version,omitempty"`
	Connection uint64          `json:"connection,omitempty"`
	State      *DesktopState   `json:"state,omitempty"`
	Frame      *DesktopFrame   `json:"frame,omitempty"`
	Cursor     *DesktopCursor  `json:"cursor,omitempty"`
	Bytes      int             `json:"bytes,omitempty"`
	Code       string          `json:"code,omitempty"`
	Error      string          `json:"error,omitempty"`
	Result     json.RawMessage `json:"result,omitempty"`
	Pixels     []byte          `json:"-"`
}

DesktopEvent contains one complete helper event or request result. A frame event includes its bounded PNG payload. The caller owns those returned bytes. Result and Error preserve helper semantics: submitted is not a widget receipt.

type DesktopFrame

type DesktopFrame struct {
	Encoding   string `json:"encoding"`
	Width      int    `json:"width"`
	Height     int    `json:"height"`
	Sequence   uint64 `json:"sequence"`
	Connection uint64 `json:"connection"`
	Window     uint64 `json:"window"`
	Generation uint64 `json:"generation"`
}

DesktopFrame binds pixels to the native connection, window and geometry generation. Receiving or parsing it does not grant input permission: the viewer must decode and paint it before sending frame_ack for Sequence.

type DesktopRequest

type DesktopRequest struct {
	Method     string          `json:"method"`
	Connection uint64          `json:"connection,omitempty"`
	Window     uint64          `json:"window,omitempty"`
	Generation uint64          `json:"generation,omitempty"`
	Frame      uint64          `json:"frame,omitempty"`
	Operation  json.RawMessage `json:"operation,omitempty"`
}

DesktopRequest names a version-1 helper operation. Operation is the native input object for input requests; the helper validates it against the current acknowledged target. Other methods have no Operation. Target fields remain explicit so a stale callback cannot borrow the connection's current target.

type DesktopState

type DesktopState struct {
	State      string          `json:"state"`
	Window     uint64          `json:"window"`
	Generation uint64          `json:"generation"`
	Windows    []DesktopWindow `json:"windows"`
}

DesktopState is native observation, not application lifetime. In particular, waiting or unavailable must never be interpreted as application exit.

type DesktopWindow

type DesktopWindow struct {
	Window      uint64 `json:"window"`
	Parent      uint64 `json:"parent"`
	Protocol    string `json:"protocol"`
	Width       int    `json:"width"`
	Height      int    `json:"height"`
	Title       string `json:"title"`
	Maximized   bool   `json:"maximized"`
	Fullscreen  bool   `json:"fullscreen"`
	Minimized   bool   `json:"minimized"`
	Interacting bool   `json:"interacting"`
}

type Installation

type Installation struct {
	ID           string `json:"id"`
	Digest       string `json:"digest"`
	Architecture string `json:"architecture"`
	Contract     string `json:"contract"`
	Ready        bool   `json:"ready"`
}

Installation identifies an installed recipe independently of the SDK release. Ready is a lightweight check of its private marker and required tool layout.

type LaunchUnavailable

type LaunchUnavailable struct {
	Code  string `json:"code"`
	Stage string `json:"stage"`
}

LaunchUnavailable is safe for production diagnostics. It contains no child output, input text, environment values, or desktop file contents.

func (*LaunchUnavailable) Error

func (e *LaunchUnavailable) Error() string

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

func New

func New(root string, pkg Package, validate func(context.Context, string) error) (*Manager, error)

New requires a private state root. Creating a manager never downloads or starts native processes. The optional validator is useful for host-owned qualification; production callers use the built-in graphical self-check by passing nil.

Example

This example compiles in source checks but performs no network operations in tests. A service should retain its manager for the service's entire lifetime.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"path/filepath"
	"time"

	nativeapps "github.com/floegence/floe-native-apps"
)

func main() {
	prepare := func(ctx context.Context, stateRoot, owner, requestID string) (nativeapps.Tools, error) {
		pkg, err := nativeapps.NativePackage()
		if err != nil {
			return nativeapps.Tools{}, err
		}
		manager, err := nativeapps.New(stateRoot, pkg, nil)
		if err != nil {
			return nativeapps.Tools{}, err
		}
		defer manager.Close()
		changes, stop := manager.Watch()
		defer stop()
		if _, err := manager.Start(owner, requestID, "download", 0); err != nil {
			return nativeapps.Tools{}, err
		}
		for {
			status := manager.Snapshot(owner)
			if status.State == "ready" {
				root, err := manager.Directory()
				if err != nil {
					return nativeapps.Tools{}, err
				}
				return nativeapps.ResolveTools(root)
			}
			if !status.Active() {
				return nativeapps.Tools{}, fmt.Errorf("preparation %s: %s", status.State, status.ErrorCode)
			}
			select {
			case <-ctx.Done():
				return nativeapps.Tools{}, ctx.Err()
			case <-changes:
			}
		}
	}
	cache, err := os.UserCacheDir()
	if err != nil {
		log.Fatal(err)
	}
	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Minute)
	defer cancel()
	// A real product supplies an authenticated owner and a stable request ID.
	tools, err := prepare(ctx, filepath.Join(cache, "floe-native-apps"), "local-user", "prepare-1")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(tools.Xpra)
}

func (*Manager) Cancel

func (m *Manager) Cancel(owner, id string) (Status, error)

func (*Manager) Close

func (m *Manager) Close()

func (*Manager) CompleteUpload

func (m *Manager) CompleteUpload(owner, id string) (Status, error)

func (*Manager) Directory

func (m *Manager) Directory() (string, error)

func (*Manager) DirectoryFor

func (m *Manager) DirectoryFor(digest string) (string, error)

DirectoryFor resolves an exact supported installation for a surviving process. It never changes the current installation or prepares another version.

func (*Manager) InstallationForProcess

func (m *Manager) InstallationForProcess(process ProcessIdentity) (*Installation, error)

func (*Manager) Package

func (m *Manager) Package() Package

func (*Manager) Plan

func (m *Manager) Plan(ctx context.Context) (TransferPlan, error)

Plan verifies archives only on explicit preparation/inspection, never on the normal application-open or status path. It performs no network requests.

func (*Manager) Snapshot

func (m *Manager) Snapshot(owner string) Status

func (*Manager) Start

func (m *Manager) Start(owner, requestID, source string, uploadSize int64) (Status, error)

func (*Manager) Watch

func (m *Manager) Watch() (<-chan struct{}, func())

func (*Manager) WriteChunk

func (m *Manager) WriteChunk(owner, id string, offset int64, data []byte) (Status, error)

type Package

type Package struct {
	ID             string     `json:"id"`
	Architecture   string     `json:"architecture"`
	SizeBytes      int64      `json:"size_bytes"`
	InstalledBytes int64      `json:"installed_bytes"`
	Artifacts      []Artifact `json:"artifacts"`
}

func ForPlatform

func ForPlatform(platform, architecture string) (Package, error)

func NativePackage

func NativePackage() (Package, error)

func (Package) Digest

func (p Package) Digest() string

func (Package) Validate

func (p Package) Validate() error

type PreparedViewer

type PreparedViewer struct {
	// contains filtered or unexported fields
}

PreparedViewer is an immutable, matching document and resource snapshot made by this SDK from an original reviewed HTML5 distribution. It owns no backend, input module or application process. A host pins it for one sharing session.

func PrepareViewer

func PrepareViewer(source string) (*PreparedViewer, error)

PrepareViewer uses the same preparation as PrepareInputClient, independently of any application's old prepared directory. Failure never yields an older viewer. The source must be a trusted installed original v20/v21 distribution.

func (*PreparedViewer) Assets

func (v *PreparedViewer) Assets() *ClientAssets

Assets returns the immutable public resources. Hosts must authorize each request by owner, active sharing origin and exact content digest.

func (*PreparedViewer) Document

func (v *PreparedViewer) Document(basePath string) ([]byte, error)

Document returns this snapshot's entry point with versioned public references. The document, settings, credentials and transport must never be cached.

type ProcessIdentity

type ProcessIdentity struct {
	PID     int    `json:"pid"`
	Boot    string `json:"boot"`
	Started string `json:"started"`
}

ProcessIdentity is an observation of one Linux process generation. Persisting it allows a host to distinguish a surviving native backend from a reused PID after restart. It grants no authorization and must never be used alone to select an application or issue a signal.

func ObserveProcess

func ObserveProcess(_ int) (ProcessIdentity, error)

func (ProcessIdentity) Alive

func (p ProcessIdentity) Alive() bool

type Status

type Status struct {
	State                 string        `json:"state"`
	OperationID           string        `json:"operation_id,omitempty"`
	ReceivedBytes         int64         `json:"received_bytes"`
	ExpectedBytes         int64         `json:"expected_bytes"`
	ErrorCode             string        `json:"error_code,omitempty"`
	CanCancel             bool          `json:"can_cancel"`
	Installed             *Installation `json:"installed,omitempty"`
	UpdateAvailable       bool          `json:"update_available"`
	InstallationErrorCode string        `json:"installation_error_code,omitempty"`
}

func (Status) Active

func (s Status) Active() bool

type Tools

type Tools struct{ Root, Xpra, Python, Xvfb, Xauth, DBus, HTML string }

func ResolveTools

func ResolveTools(root string) (Tools, error)

func (Tools) Environment

func (t Tools) Environment(base []string) []string

Environment scopes support-tool overrides. The GIO launcher must restore this small saved map on its AppLaunchContext before starting the user's program. Display and D-Bus addresses are deliberately not restored: those belong to the caller's private graphical session.

type TransferPlan

type TransferPlan struct {
	PackageDigest    string   `json:"package_digest"`
	Architecture     string   `json:"architecture"`
	MissingArtifacts []string `json:"missing_artifacts"`
	MissingBytes     int64    `json:"missing_bytes"`
}

TransferPlan contains only identities from the receiver's trusted catalog. It is a cache observation, not an authorization or a reservation of cache files.