nativeapps

package module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 23, 2026 License: MIT Imports: 31 Imported by: 1

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.

Source checks CodeQL Go Reference

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 use independent temporary files and may repeat a download; cancellation removes only the current call's staging file. The host owns cache retention and must not remove entries while readers use them. 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 adapters require glibc 2.31 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. GTK4 and incompatible/private toolkit loaders are not claimed as supported adapters.

PrepareInputClient prepares Xpra HTML5 v20/v21 with external input ownership. 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

Examples

Constants

View Source 
const ClientInputTextLimit = 16000

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

View Source 
const ClientInputVersion = 1

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

Variables

View Source 
var ErrBusy = errors.New("native preparation is already running")
View Source 
var ErrForbidden = errors.New("native preparation belongs to another caller")
View Source 
var ErrInvalid = errors.New("invalid native preparation request")
View Source 
var ErrUnsupported = errors.New("native graphical components are unavailable for this platform")

Functions

func PrepareInputClient added in v0.5.0 

func PrepareInputClient(source, destination string) error

PrepareInputClient prepares an Xpra HTML5 v20/v21 distribution with exactly one external keyboard owner. It retains the original graphics, pointer and clipboard protocol implementations. 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(parent context.Context, root string) (result error)

SelfTest creates only its own virtual display and transient GTK fixture. A successful check proves actual window discovery, rendered pixels, and input; importing a module or starting a process alone is not readiness evidence.

func SystemClientInputPython added in v0.5.0 

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 added in v0.3.0 

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. The launcher restores the host application environment and reaps descendants; closing a window or losing a viewer never terminates the application.

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 WriteTransferBundle added in v0.4.0 

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 XpraApplicationLifetimeArgs added in v0.3.0 

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 added in v0.2.1 

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 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 ClientAssets added in v0.6.0 

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 added in v0.6.0 

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 added in v0.6.0 

func (a *ClientAssets) Digest() string

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

func (*ClientAssets) RewriteHTML added in v0.6.0 

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 added in v0.6.0 

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 added in v0.5.0 

type ClientInput struct{ Launcher, GTKModules, QtPlugins 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 added in v0.5.0 

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 added in v0.5.0 

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 added in v0.5.0 

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

func ProbeClientInput added in v0.5.0 

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 Installation added in v0.4.0 

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 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 added in v0.4.0 

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 added in v0.4.0 

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

InstallationForProcess identifies a legacy backend's private loader using kernel evidence. Nil means a system installation outside this manager's root. The caller still owns application authorization and backend identity checks.

func (*Manager) Package 

func (m *Manager) Package() Package

func (*Manager) Plan added in v0.4.0 

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 ProcessIdentity added in v0.3.0 

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 added in v0.3.0 

func ObserveProcess(pid int) (ProcessIdentity, error)

ObserveProcess reads the kernel's boot and start identity for a live process.

func (ProcessIdentity) Alive added in v0.3.0 

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 added in v0.4.0 

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.

Source Files

View all Source files

Directories

Path Synopsis
Package artifactcache acquires pinned publisher archives into a private, content-addressed cache.
 Package artifactcache acquires pinned publisher archives into a private, content-addressed cache.
cmd
floe-native-apps command
floe-native-apps is an explicit qualification and offline acquisition tool.
 floe-native-apps is an explicit qualification and offline acquisition tool.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.