@braedonsaunders/appkit-desk 0.6.0 → 0.8.0

package/index.d.ts

@@ -7,4 +7,7 @@ export * from './host.js';
 export * from './frames.js';
 export * from './portable-home.js';
 export * from './conformance.js';
+export * from './network.js';
+export * from './virtualization.js';
+export * from './port-relay.js';
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AAEzB,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA"}

package/index.js

@@ -7,4 +7,7 @@ export * from './host.js';
 export * from './frames.js';
 export * from './portable-home.js';
 export * from './conformance.js';
+export * from './network.js';
+export * from './virtualization.js';
+export * from './port-relay.js';
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA","sourcesContent":["export * from './events'\nexport * from './protocol'\nexport * from './plan'\nexport * from './guest-agent'\nexport * from './backend'\nexport * from './host'\nexport * from './frames'\nexport * from './portable-home'\nexport * from './conformance'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AAEzB,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA","sourcesContent":["export * from './events'\nexport * from './protocol'\nexport * from './plan'\nexport * from './guest-agent'\nexport * from './backend'\nexport * from './host'\nexport * from './frames'\nexport * from './portable-home'\nexport * from './conformance'\nexport * from './network'\n\nexport * from './virtualization'\nexport * from './port-relay'\n"]}

package/machine.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The guest channel every backend shares: the hybrid-vsock handshake, the
+ * proof that a guest is really behind it, the reconnecting machine, and the
+ * child-process plumbing around a VMM. Cloud Hypervisor and the
+ * Virtualization.framework helper both expose the guest agent through a host
+ * Unix socket with the same `CONNECT <port>` preamble, so everything from the
+ * socket inwards is one implementation. Internal to the package.
+ */
+import { type ChildProcess } from 'node:child_process';
+import type { Duplex } from 'node:stream';
+import { type DeskMachine } from './backend.js';
+import { type DeskLauncherIdentity } from './plan.js';
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 20000;
+export declare const DEFAULT_CONNECT_RETRY_DELAY_MS = 100;
+export declare const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+export declare const DEFAULT_RECONNECT_WINDOW_MS = 30000;
+export declare const DEFAULT_RECONNECT_RETRY_DELAY_MS = 250;
+/**
+ * How far the reconnect delay is allowed to double. A guest agent that systemd
+ * is restarting is not helped by being hammered four times a second for the
+ * whole window, and an unbounded doubling would spend most of the window
+ * asleep after two failures.
+ */
+export declare const RECONNECT_BACKOFF_CEILING = 8;
+export declare const DEFAULT_KILL_GRACE_MS = 2000;
+/**
+ * The machine, and the small state machine that keeps it connected.
+ *
+ * A vsock channel is not a fact the host learns once at boot — the transport
+ * can lie about being connected, and it can go away mid-lease for reasons that
+ * have nothing to do with the desk being unusable: the guest agent restarts,
+ * the socat bridge drops, a transient vsock error, the guest wedges for a
+ * moment. Treating any of those as terminal stranded the desk for the rest of
+ * its lease with a perfectly healthy guest behind it, answering every call
+ * with "no longer connected". So a live connection is something this machine
+ * RE-ESTABLISHES:
+ *
+ *   live ──unexpected drop──▶ reconnecting ──confirmed guest──▶ live
+ *     │                            │
+ *     │                            └──window exhausted / VMM exited──▶ closed
+ *     └──shutdown(), VMM already exited, protocol violation───────────▶ closed
+ *
+ * `closed` is terminal. Nothing reconnects out of it, which is what makes
+ * `shutdown()` and a dead VMM final rather than the start of a retry loop.
+ *
+ * What differs between hypervisors is only how the VM stops, parks, and
+ * reaches guest ports, and those arrive as functions.
+ */
+export declare function createGuestMachine(options: {
+    deskId: string;
+    exit: ExitWatcher;
+    stream: Duplex;
+    /** Re-establishes the channel; resolves only once a guest has answered. */
+    reconnect: (abandoned: () => boolean) => Promise<Duplex>;
+    reconnectWindowMs: number;
+    now: () => number;
+    idFactory: () => string;
+    requestTimeoutMs: number;
+    /** Stop the VMM; resolves once its process has exited. */
+    stop: () => Promise<void>;
+    /**
+     * Pause, snapshot into `snapshotDir`, and stop the VMM. Called after the
+     * guest channel has been closed. Must leave the VMM stopped on failure too.
+     */
+    park?: (snapshotDir: string) => Promise<void>;
+    /** Open a host-to-guest TCP stream, for backends with no routable guest. */
+    connect?: (port: number) => Promise<Duplex>;
+}): DeskMachine;
+export interface ExitWatcher {
+    done: boolean;
+    promise: Promise<void>;
+}
+/**
+ * Read a child's output and keep only the last few kilobytes.
+ *
+ * This is not for logging — it is load-bearing. A child spawned with its
+ * streams as PIPES blocks once a pipe nobody reads fills, after about 64KB.
+ * Cloud Hypervisor logs while it runs, so an unread pipe freezes the guest
+ * partway through boot: the process is alive, the disk is untouched, and the
+ * guest agent never reaches vsock. Every symptom points at the image and none
+ * of them are its fault.
+ *
+ * Draining costs nothing and buys the tail of what the process said, which is
+ * the difference between "the VMM exited" and knowing why. `streams` names the
+ * pipes to drain: a helper that speaks a protocol on stdout drains only stderr.
+ */
+export declare function drainOutput(child: ChildProcess, limit?: number, streams?: readonly ('stdout' | 'stderr')[]): {
+    tail: () => string;
+};
+export declare function watchExit(child: ChildProcess): ExitWatcher;
+export declare function terminate(child: ChildProcess, exit: ExitWatcher, killGraceMs: number): Promise<void>;
+export declare function runToCompletion(child: ChildProcess, label: string): Promise<void>;
+/**
+ * Cloud Hypervisor exposes guest vsock ports through a host Unix socket with
+ * a line-oriented preamble: the client writes `CONNECT <port>\n` and the VMM
+ * answers `OK <assigned>\n` before the byte stream becomes the guest
+ * connection. The VMM creates the socket during boot, so connection attempts
+ * retry until the deadline. The Virtualization.framework helper speaks the
+ * same preamble on its own socket.
+ *
+ * The same loop serves the first connection and every later reconnect, so a
+ * reconnect gets `confirmGuest` too — a mid-lease reconnect that trusted the
+ * banner would re-adopt exactly the hollow stream the boot path learned not to.
+ */
+export declare function connectWithRetry(options: {
+    connect: (socketPath: string) => Duplex;
+    now: () => number;
+    socketPath: string;
+    port: number;
+    timeoutMs: number;
+    retryDelayMs: number;
+    /** Ceiling the delay doubles toward; omitted keeps the delay constant. */
+    maxRetryDelayMs?: number;
+    attemptTimeoutMs: number;
+    exited: ExitWatcher;
+    /** A dead VMM means something different at boot than it does mid-lease. */
+    exitedMessage?: string;
+    /** Stops the loop early when the caller no longer wants the connection. */
+    abandoned?: () => boolean;
+}): Promise<Duplex>;
+/**
+ * One handshake attempt, which MUST settle.
+ *
+ * Cloud Hypervisor accepts a connection on the vsock socket whether or not
+ * anything in the guest is listening on the port, and when nothing is it may
+ * answer nothing at all: no reply, no error, no close. Without a deadline of
+ * its own this promise then never settles — and because the caller awaits it
+ * inside the retry loop, the loop stops iterating, the overall deadline is
+ * never re-checked, and the boot hangs forever rather than failing. That is
+ * indistinguishable from a wedged host and it is why every attempt is bounded
+ * here as well as in aggregate.
+ *
+ * A close before the reply line is a refusal: that is how a port with nothing
+ * listening presents through Cloud Hypervisor, and the Virtualization.framework
+ * helper presents a refused vsock or TCP port the same way.
+ */
+export declare function attemptHandshake(connect: (socketPath: string) => Duplex, socketPath: string, port: number, attemptTimeoutMs: number): Promise<Duplex>;
+export declare function defaultLauncher(command: string, args: readonly string[], options: {
+    identity?: DeskLauncherIdentity;
+}): ChildProcess;
+export declare function defaultConnect(socketPath: string): Duplex;
+export declare function delay(ms: number): Promise<void>;
+export declare function errorMessage(error: unknown): string;
+//# sourceMappingURL=machine.d.ts.map

package/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"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"}