@namzu/sandbox 1.1.0

package/dist/backends/firecracker/transport.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Host-side vsock transport + dialer for the Firecracker in-VM agent.
+ *
+ * This is the NEW code the §2.2 decision calls for. The docker/ACI
+ * backends reach the agent over HTTP with `fetch`; **Node `fetch`
+ * cannot dial `AF_VSOCK`**, and across an FC snapshot resume a TCP
+ * control channel is dead-on-arrival (FC `snapshot-support.md`: TCP
+ * connection state does not survive a resume; the **vsock LISTEN
+ * socket** does). So the FC control channel is a framed stream over
+ * vsock, and that framing + the resume-survival hardening live here.
+ *
+ * ## One wire, two transports
+ * The message FORMAT (NDJSON exec events + base64 file-IO) is shared
+ * with the HTTP backends via `protocol.ts`. This module owns only the
+ * TRANSPORT: how a request crosses the wire and how a response is
+ * framed back.
+ *
+ * Framing: a length-prefixed envelope per message —
+ *   `<8-hex-digit big-endian byte length>\n<utf8 JSON payload>`
+ * The newline after the hex length lets a reader find the boundary
+ * without a fixed header struct, and the explicit length means a
+ * payload that itself contains newlines (NDJSON exec output) is read
+ * whole, not split. Exec replies are a SEQUENCE of framed NDJSON
+ * lines terminated by a zero-length frame; file-IO replies are a
+ * single framed JSON object.
+ *
+ * ## How vsock is actually dialed from Node
+ * Node has no `AF_VSOCK` socket family. The production path therefore
+ * follows exactly what the in-situ bench already proved: the guest
+ * agent's vsock stream is bridged to a **host-side unix-domain
+ * socket** (the bench relays guest `AF_VSOCK` → host CID:port → a host
+ * unix socket; FC's own vsock device exposes a host-side unix socket
+ * rendezvous, `UDS + "CONNECT <port>"`). So the host dialer ALWAYS
+ * terminates on a `net.connect({ path })` unix socket:
+ *   - `kind: 'unix'`   — connect directly to `path` (local/dev + tests).
+ *   - `kind: 'vsock'`  — connect to the FC vsock device's host unix
+ *     socket `udsPath`, then send the firecracker hybrid-vsock
+ *     handshake line `CONNECT <port>\n` and await the `OK <hostport>`
+ *     ack before framing application traffic.
+ * Both land on the same `net.Socket`, so the unix-socket stand-in in
+ * the tests exercises the identical framing/heartbeat/reconnect code
+ * the vsock path runs — the only delta is the one-line CONNECT
+ * handshake, which is covered by its own assertion.
+ *
+ * ## Resume survival (the hard invariant, FC #4713 / loopholelabs)
+ * On resume the guest vsock driver closes all existing connections and
+ * the `TRANSPORT_RESET` event may NOT be delivered, so a host read can
+ * hang. The agent re-LISTENs after every resume; the host dialer
+ * carries a per-attempt connect/handshake **timeout + retry budget**
+ * so a dropped reset cannot wedge first-exec — the dialer simply
+ * re-dials. Every request opens a fresh connection (no long-lived
+ * socket to be silently severed by a resume), which makes the
+ * transport resume-survivable by construction.
+ */
+import type { SandboxExecResult } from '@namzu/sdk';
+import { type ExecRequest, type ReadFileRequest, type WriteFileRequest } from './protocol.js';
+/**
+ * An addressable agent endpoint. The orchestrator hands one of these
+ * back per sandbox (`create()` response → `vsock endpoint`).
+ *
+ *  - `unix`  — a host unix-domain socket the agent (or a relay) is
+ *    listening on. The local/dev path and the test stand-in.
+ *  - `vsock` — a Firecracker hybrid-vsock device exposed as a host
+ *    unix socket at `udsPath`; `port` is the guest AF_VSOCK port the
+ *    agent listens on (the fixed contract port baked into the golden
+ *    rootfs). The dialer connects to `udsPath` then issues the
+ *    `CONNECT <port>` handshake.
+ *  - `mtls`  — a per-FC-host mTLS RELAY daemon reachable over the
+ *    network at `host:port` (the owning host's private VNet IP + the
+ *    bridge port). The dialer `tls.connect`s the relay presenting the
+ *    fleet client cert, verifies the relay's server cert
+ *    (`rejectUnauthorized: true`), then writes a single routing
+ *    preamble line `SANDBOX <sandboxId>\n`. The relay terminates mTLS,
+ *    resolves `sandboxId` to the host-local jailed `v.sock`, dials it,
+ *    and issues the guest `CONNECT 1024` handshake ITSELF — so the
+ *    caller does NOT write the `CONNECT` line. After the preamble the
+ *    relay is a verbatim byte pump, so the IDENTICAL 8-hex/NDJSON
+ *    framing + heartbeat + retry runs unchanged over the TLS socket
+ *    (`tls.TLSSocket` is a `net.Socket`). The container-app NEVER sees
+ *    a host-local `udsPath`; the cert material is injected by the
+ *    Vandal host layer, never returned by the orchestrator.
+ */
+export type SandboxAgentHandle = {
+    readonly kind: 'unix';
+    readonly path: string;
+} | {
+    readonly kind: 'vsock';
+    readonly udsPath: string;
+    readonly port: number;
+} | {
+    readonly kind: 'mtls';
+    readonly host: string;
+    readonly port: number;
+    readonly sandboxId: string;
+    readonly tls: {
+        readonly ca: string | Buffer;
+        readonly cert: string | Buffer;
+        readonly key: string | Buffer;
+        readonly servername?: string;
+    };
+};
+/**
+ * The mTLS cert material the consumer injects onto a wire `mtls` handle (the
+ * `tls` block of the transport handle). Read from the consumer's runtime (the
+ * Vandal host layer's `VANDAL_SANDBOX_FC_TLS_*`), NEVER returned by the
+ * orchestrator — the leak-prevention boundary.
+ */
+export interface MtlsClientMaterial {
+    readonly ca: string | Buffer;
+    readonly cert: string | Buffer;
+    readonly key: string | Buffer;
+    readonly servername?: string;
+}
+/**
+ * The WIRE shape of an agent handle as the orchestrator returns it. Identical
+ * to {@link SandboxAgentHandle} EXCEPT the `mtls` arm omits the `tls` cert
+ * block: the orchestrator returns only host/port/sandboxId, and the consumer
+ * (Vandal host layer) merges the cert material in (see `normalizeHandle`)
+ * before constructing the transport. The `unix`/`vsock` arms are unchanged
+ * (they carry no cert material).
+ */
+export type WireSandboxAgentHandle = {
+    readonly kind: 'unix';
+    readonly path: string;
+} | {
+    readonly kind: 'vsock';
+    readonly udsPath: string;
+    readonly port: number;
+} | {
+    readonly kind: 'mtls';
+    readonly host: string;
+    readonly port: number;
+    readonly sandboxId: string;
+};
+/**
+ * A framed request. `op` selects the agent handler; the HTTP worker
+ * used the URL path (`/execute`, `/read-file`, `/write-file`,
+ * `/healthz`) — over vsock the same selector rides in the framed JSON.
+ */
+export type AgentRequest = {
+    readonly op: 'execute';
+    readonly body: ExecRequest;
+} | {
+    readonly op: 'read-file';
+    readonly body: ReadFileRequest;
+} | {
+    readonly op: 'write-file';
+    readonly body: WriteFileRequest;
+} | {
+    readonly op: 'healthz';
+};
+export interface VsockTransportOptions {
+    /** Per-attempt connect + handshake timeout. Default 5000ms. */
+    readonly connectTimeoutMs?: number;
+    /** Total time budget for connect retries (resume survival). Default 30000ms. */
+    readonly connectRetryBudgetMs?: number;
+    /** Backoff between connect retries. Default 100ms. */
+    readonly connectRetryIntervalMs?: number;
+    /**
+     * Idle read timeout once connected and the request is sent. Guards
+     * the FC #4713 "read hangs because TRANSPORT_RESET was not
+     * delivered" case: if no byte arrives within this window the
+     * transport tears the socket down and the caller's retry re-dials
+     * against the agent's fresh listen socket. Default 60000ms.
+     */
+    readonly readIdleTimeoutMs?: number;
+}
+declare function frame(payload: string): Buffer;
+/**
+ * Incremental frame reader. Feed it socket chunks; it yields complete
+ * payloads. A zero-length frame is the exec stream terminator and is
+ * surfaced as an empty string so the caller can stop.
+ */
+declare class FrameReader {
+    private buf;
+    push(chunk: Buffer): string[];
+}
+/**
+ * The transport. One instance per sandbox handle; every request opens
+ * a fresh connection (resume-survivable — no socket lingers across a
+ * resume to be silently severed). All four ops + the heartbeat go
+ * through {@link request} / {@link execute}.
+ */
+export declare class VsockAgentTransport {
+    private readonly handle;
+    private readonly connectTimeoutMs;
+    private readonly connectRetryBudgetMs;
+    private readonly connectRetryIntervalMs;
+    private readonly readIdleTimeoutMs;
+    constructor(handle: SandboxAgentHandle, options?: VsockTransportOptions);
+    /**
+     * Dial the agent with the resume-survival retry budget. Resolves a
+     * connected, post-handshake socket. Retries connect/handshake
+     * failures (ECONNREFUSED while the agent re-listens after a resume,
+     * a dropped CONNECT ack) until the budget is exhausted.
+     */
+    private dial;
+    private connectOnce;
+    /**
+     * Dial the per-FC-host mTLS relay for an `mtls` handle.
+     *
+     * This is a pure TRANSPORT substitution for the `net.connect` arms:
+     * it `tls.connect`s the relay (presenting the fleet client cert and
+     * verifying the relay's server cert, `rejectUnauthorized: true`),
+     * asserts `socket.authorized`, then writes the single routing
+     * preamble line `SANDBOX <sandboxId>\n`. It does NOT write the guest
+     * `CONNECT 1024` line — the relay issues that host-side toward the
+     * jailed `v.sock`. The relay does NOT send an ack line: after the
+     * preamble it is a verbatim byte pump, so the caller hands the
+     * post-preamble socket straight up to the IDENTICAL framing loop the
+     * unix/vsock arms use (a `tls.TLSSocket` IS a `net.Socket`). The
+     * connect-retry budget, idle timeout, and the "fresh connection per
+     * request" resume-survival invariant are inherited unchanged.
+     *
+     * INTEGRATE CONTRACT (must match the relay, Track B): NO ack line.
+     * The relay reads `SANDBOX <id>\n`, then bridges; it writes nothing
+     * back until the agent does. If the relay is ever changed to emit an
+     * `OK` ack first, this arm must await that line (mirroring the vsock
+     * CONNECT-ack path) before resolving — today it does not.
+     */
+    private connectOnceMtls;
+    /**
+     * Send one framed request and read one framed JSON reply (file-IO +
+     * healthz). Applies the read-idle timeout so a post-resume hung read
+     * is torn down rather than wedging the caller.
+     */
+    request<T>(req: AgentRequest): Promise<T>;
+    /**
+     * Send an `/execute` and accumulate the streamed NDJSON frames into a
+     * {@link SandboxExecResult} via the shared {@link ExecResultAccumulator}.
+     * The agent terminates the stream with a zero-length frame.
+     */
+    execute(body: ExecRequest): Promise<SandboxExecResult>;
+    /** Liveness probe. Returns true on an `{ ok: true }` healthz reply. */
+    healthz(): Promise<boolean>;
+    /**
+     * Poll the agent until a healthz succeeds or the timeout elapses.
+     * Mirrors the HTTP `waitForWorkerReady`, but over the vsock dialer
+     * (which already carries connect retry) — used by the backend's
+     * post-create readiness fence.
+     */
+    waitForReady(timeoutMs: number, pollIntervalMs: number): Promise<void>;
+    writeFile(path: string, content: Buffer): Promise<void>;
+    readFile(path: string): Promise<Buffer>;
+}
+export declare const __framing: {
+    frame: typeof frame;
+    FrameReader: typeof FrameReader;
+};
+export {};
+//# sourceMappingURL=transport.d.ts.map

package/dist/backends/firecracker/transport.d.ts.map

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