@namzu/sandbox 1.1.0

package/dist/backends/firecracker/index.js

@@ -0,0 +1,334 @@
+/**
+ * `microvm:self-hosted` (Firecracker) backend.
+ *
+ * Sibling of `docker/` and `aci-standby-pool/`: same
+ * {@link SandboxBackend} surface, same NDJSON exec-stream + base64
+ * file-IO **wire contract**, different transport and shipping
+ * mechanism.
+ *
+ *  - docker `docker run`s a container and reaches an HTTP worker on a
+ *    host loopback port.
+ *  - aci PUTs an ACI container group and reaches the same HTTP worker
+ *    over the group's IP.
+ *  - firecracker POSTs the owned Azure **orchestrator** to CoW-resume a
+ *    microVM off the golden snapshot, then reaches a **custom vsock
+ *    agent** baked into the golden rootfs over the **vsock transport**
+ *    (`transport.ts`). The wire FORMAT is identical (see `protocol.ts`);
+ *    only the transport differs — HTTP for docker/aci, framed-over-vsock
+ *    for FC, because across an FC snapshot resume a TCP control channel
+ *    is dead-on-arrival while the vsock LISTEN socket survives
+ *    (FC `snapshot-support.md`).
+ *
+ * ## Why this is a remote-copy backend (no host bind-mounts)
+ * A sibling process on the FC host cannot see the microVM's
+ * filesystem, so — exactly like ACI — the workspace is seeded by
+ * archive-sync over the control channel (tar.gz `writeFile` +
+ * in-sandbox `tar -xzf` via `exec`), driven by the Vandal-side
+ * lifecycle (`workspace-sync.ts`). This backend therefore exposes no
+ * `layout` mount rendering; it only needs the `outputs` container path
+ * as the workspace root, which the orchestrator returns as `rootDir`.
+ *
+ * ## Trust model
+ * The microVM is a hardware-virtualization (KVM) trust boundary —
+ * stronger than docker namespaces or ACI's managed isolation. The
+ * vsock control channel never traverses the guest's egress netns; the
+ * agent listens on a fixed AF_VSOCK port captured warm in the golden
+ * snapshot. Auth to the orchestrator rides a caller-supplied
+ * `getToken()` closure (the ACI `getArmToken` pattern) so
+ * `@namzu/sandbox` keeps zero Azure-SDK dependencies.
+ *
+ * ## Auth / SDK-dependency boundary
+ * `getToken()` mirrors ACI's `getArmToken`: the consumer's runtime
+ * owns Managed-Identity / federated-credential picking; this package
+ * only calls the closure on every orchestrator HTTP call so a
+ * long-running sandbox survives token rotation.
+ */
+import https from 'node:https';
+import { VsockAgentTransport } from './transport.js';
+const DEFAULT_AGENT_VSOCK_PORT = 1024;
+const DEFAULT_READY_TIMEOUT_MS = 60_000;
+const DEFAULT_READY_POLL_MS = 250;
+/**
+ * Build a {@link SandboxBackend} backed by the owned Firecracker
+ * platform. Construction is synchronous; the orchestrator POST happens
+ * on the first `create()`.
+ */
+export function buildFirecrackerBackend(config) {
+    return {
+        tier: 'microvm',
+        name: 'firecracker',
+        async create(options) {
+            return await spawnFirecrackerSandbox(config, options);
+        },
+    };
+}
+async function orchestratorCall(endpoint, pathSuffix, method, getToken, body, mtls) {
+    const token = await getToken();
+    const url = `${endpoint.replace(/\/+$/, '')}${pathSuffix}`;
+    const payload = body !== undefined ? JSON.stringify(body) : undefined;
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        'content-type': 'application/json',
+    };
+    let res;
+    try {
+        // When CONTROL-plane mTLS material is injected the call dials over a
+        // node:https request presenting the client cert + pinning the server CA
+        // (the public-internet hop). Without it the EXISTING plain `fetch` path
+        // runs unchanged (the single-host default). node:https is used rather
+        // than fetch+undici-dispatcher because the package declares no undici
+        // dependency — node:https is always importable and needs nothing added.
+        res = mtls
+            ? await httpsOrchestratorRequest(url, method, headers, payload, mtls)
+            : await fetchOrchestratorRequest(url, method, headers, payload);
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.cause : undefined;
+        throw new Error(`firecracker orchestrator ${method} ${url} failed: ${err instanceof Error ? err.message : String(err)}${cause ? ` — cause: ${cause instanceof Error ? cause.message : String(cause)}` : ''}`, { cause: err });
+    }
+    if (res.status < 200 || res.status >= 300) {
+        throw new Error(`firecracker orchestrator ${method} ${url} → ${res.status}: ${await res.text()}`);
+    }
+    if (res.status === 204)
+        return undefined;
+    if (res.contentType.includes('application/json'))
+        return JSON.parse(await res.text());
+    return undefined;
+}
+/** The plain-`fetch` control-plane path — the single-host DEFAULT, unchanged. */
+async function fetchOrchestratorRequest(url, method, headers, payload) {
+    const init = { method, headers };
+    if (payload !== undefined)
+        init.body = payload;
+    const res = await fetch(url, init);
+    return {
+        status: res.status,
+        contentType: res.headers.get('content-type') ?? '',
+        text: () => res.text(),
+    };
+}
+/**
+ * The mTLS control-plane path: a node:https request presenting the injected
+ * client cert and verifying the orchestrator's server cert against the injected
+ * CA (`rejectUnauthorized: true`). Used only when `controlPlaneMtls` is present;
+ * the plain-`fetch` path above stays the default for single-host.
+ */
+function httpsOrchestratorRequest(url, method, headers, payload, mtls) {
+    const target = new URL(url);
+    return new Promise((resolve, reject) => {
+        const req = https.request({
+            protocol: target.protocol,
+            hostname: target.hostname,
+            port: target.port !== '' ? Number(target.port) : 443,
+            path: `${target.pathname}${target.search}`,
+            method,
+            headers,
+            ca: mtls.ca,
+            cert: mtls.cert,
+            key: mtls.key,
+            rejectUnauthorized: true,
+            minVersion: 'TLSv1.3',
+            ...(mtls.servername !== undefined ? { servername: mtls.servername } : {}),
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const ct = res.headers['content-type'];
+                resolve({
+                    status: res.statusCode ?? 0,
+                    contentType: Array.isArray(ct) ? (ct[0] ?? '') : (ct ?? ''),
+                    text: async () => Buffer.concat(chunks).toString('utf8'),
+                });
+            });
+            res.on('error', reject);
+        });
+        req.on('error', reject);
+        if (payload !== undefined)
+            req.write(payload);
+        req.end();
+    });
+}
+// ---------------------------------------------------------------------------
+// create()
+// ---------------------------------------------------------------------------
+async function spawnFirecrackerSandbox(config, options) {
+    const endpoint = config.orchestratorEndpoint;
+    const createBody = {
+        ...(config.template !== undefined ? { template: config.template } : {}),
+        ...(config.agentSnapshot !== undefined ? { agentSnapshot: config.agentSnapshot } : {}),
+        ...(options.memoryLimitMb !== undefined ? { memoryLimitMb: options.memoryLimitMb } : {}),
+        ...(options.maxProcesses !== undefined ? { maxProcesses: options.maxProcesses } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(resolveEgressAllowlist(options) !== undefined
+            ? { egressAllowlist: resolveEgressAllowlist(options) }
+            : {}),
+    };
+    let created;
+    try {
+        created = await orchestratorCall(endpoint, '/sandboxes', 'POST', config.getToken, createBody, config.controlPlaneMtls);
+    }
+    catch (err) {
+        throw new Error(`firecracker: failed to create microVM sandbox — ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (!created || !created.sandboxId || !created.agent) {
+        throw new Error('firecracker: orchestrator create returned no sandboxId / agent handle');
+    }
+    const id = created.sandboxId;
+    const rootDir = created.rootDir;
+    // Normalise the orchestrator handle: fill the contract vsock port when a
+    // vsock handle omits it, and MERGE the consumer-injected mTLS material onto
+    // a network (`mtls`) handle so the transport can dial the relay. The
+    // orchestrator returns an `mtls` handle WITHOUT cert material (host/port/
+    // sandboxId only); the certs are injected here from `config.mtls`, never
+    // shipped by the control plane.
+    const handle = normalizeHandle(created.agent, config.agentVsockPort ?? DEFAULT_AGENT_VSOCK_PORT, config.mtls);
+    const transport = new VsockAgentTransport(handle, config.transport ?? {});
+    const destroy = async () => {
+        await orchestratorCall(endpoint, `/sandboxes/${encodeURIComponent(id)}:delete`, 'DELETE', config.getToken, undefined, config.controlPlaneMtls);
+    };
+    try {
+        // Readiness fence: the orchestrator's resume returns BEFORE the
+        // guest agent has reseeded entropy and re-listened on vsock. Stop
+        // the clock on the agent's healthz, exactly as the HTTP backends
+        // wait on `/healthz` — never on the orchestrator's 2xx, which
+        // fires before the guest runs (§5 clock semantics).
+        await transport.waitForReady(config.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS, config.readyPollIntervalMs ?? DEFAULT_READY_POLL_MS);
+    }
+    catch (err) {
+        // Best-effort orchestrator teardown so a readiness failure does not
+        // orphan a microVM/netns/UFFD handler (the reaper backstops, but
+        // surfacing the delete failure keeps the leak observable).
+        try {
+            await destroy();
+        }
+        catch {
+            // Preserve the readiness error as primary.
+        }
+        throw err;
+    }
+    let status = 'ready';
+    return {
+        id,
+        get status() {
+            return status;
+        },
+        rootDir,
+        environment: detectEnvironment(),
+        async exec(command, argv, opts) {
+            status = 'busy';
+            try {
+                return await transport.execute({
+                    command,
+                    args: argv ?? [],
+                    ...(opts?.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                    ...(opts?.env !== undefined ? { env: opts.env } : {}),
+                    ...(opts?.timeout !== undefined ? { timeoutMs: opts.timeout } : {}),
+                });
+            }
+            finally {
+                status = 'ready';
+            }
+        },
+        async writeFile(path, content) {
+            const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+            await transport.writeFile(path, buf);
+        },
+        async readFile(path) {
+            return await transport.readFile(path);
+        },
+        async listFiles(rootPath) {
+            // Same wire as docker/aci: `find -printf '%p\t%s\n'`, parse
+            // line-by-line, map a non-zero exit (missing root) to "empty".
+            const result = await transport.execute({
+                command: 'find',
+                args: [rootPath, '-type', 'f', '-printf', '%p\t%s\n'],
+            });
+            if (result.exitCode !== 0)
+                return [];
+            const entries = [];
+            for (const rawLine of result.stdout.split('\n')) {
+                if (!rawLine)
+                    continue;
+                const tab = rawLine.indexOf('\t');
+                if (tab < 0)
+                    continue;
+                const filePath = rawLine.slice(0, tab);
+                const size = Number.parseInt(rawLine.slice(tab + 1), 10);
+                if (!filePath || !Number.isFinite(size))
+                    continue;
+                entries.push({ path: filePath, size });
+            }
+            return entries;
+        },
+        async destroy() {
+            status = 'destroyed';
+            // Let the orchestrator DELETE failure propagate — the
+            // Vandal-side lifecycle wraps this with logging, and a
+            // swallowed error here means orphaned microVMs (and their
+            // netns / UFFD handlers) pile up with no observability handle.
+            await destroy();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveEgressAllowlist(options) {
+    const egress = options.egress;
+    if (!egress)
+        return undefined;
+    if (egress.kind === 'static')
+        return egress.allowedHosts;
+    // `deny-all` → empty allowlist (explicit). `allow-all` / `resolver`
+    // are resolved by the host before create when they apply; the
+    // backend forwards only the static, already-resolved shape. A
+    // resolver-shaped policy is the Vandal lifecycle's job to resolve
+    // upstream and pass as `static`.
+    if (egress.kind === 'deny-all')
+        return [];
+    return undefined;
+}
+/**
+ * Turn the orchestrator's WIRE handle into the transport handle the dialer
+ * uses. Two transforms:
+ *
+ *  - `vsock` with a missing/<=0 port → fill the contract port.
+ *  - `mtls` → MERGE the consumer-injected `mtls` cert material onto the
+ *    wire handle (which carries only host/port/sandboxId). The orchestrator
+ *    never ships cert material; without an injected `mtls` block a network
+ *    handle cannot dial, so this throws loud rather than constructing a
+ *    transport that would fail at connect time.
+ *
+ * `unix` + already-correct `vsock` handles pass through untouched.
+ */
+export function normalizeHandle(handle, contractPort, mtls) {
+    if (handle.kind === 'mtls') {
+        if (!mtls) {
+            throw new Error('firecracker: orchestrator returned an mtls agent handle but no client cert material was injected ' +
+                '(the Vandal host layer must supply VANDAL_SANDBOX_FC_TLS_CA/_CERT/_KEY in network mode)');
+        }
+        return {
+            kind: 'mtls',
+            host: handle.host,
+            port: handle.port,
+            sandboxId: handle.sandboxId,
+            tls: {
+                ca: mtls.ca,
+                cert: mtls.cert,
+                key: mtls.key,
+                ...(mtls.servername !== undefined ? { servername: mtls.servername } : {}),
+            },
+        };
+    }
+    if (handle.kind === 'vsock' && (!handle.port || handle.port <= 0)) {
+        return { kind: 'vsock', udsPath: handle.udsPath, port: contractPort };
+    }
+    return handle;
+}
+function detectEnvironment() {
+    // Firecracker guests run Linux; the agent is a Linux-namespace-style
+    // worker from the SDK's perspective (the enum is host-shape, not
+    // guest internals).
+    return 'linux-namespace';
+}
+//# sourceMappingURL=index.js.map

package/dist/backends/firecracker/index.js.map

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

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

@@ -0,0 +1,132 @@
+/**
+ * The ONE wire contract, shared across both transports.
+ *
+ * The docker (`backends/docker/`) and ACI (`backends/aci-standby-pool/`)
+ * backends speak this contract over **HTTP**: a streaming NDJSON
+ * `/execute` response and base64-bodied `/read-file` / `/write-file`
+ * JSON requests, served by `worker/server.js`. The Firecracker
+ * backend speaks the **same NDJSON shapes and the same base64 file-IO
+ * shapes** — only the transport changes from HTTP-over-TCP to
+ * framed-over-vsock (see `transport.ts`).
+ *
+ * This module is the single source of truth for the message shapes
+ * and the streaming exec-line parser, so the two transports cannot
+ * drift. It deliberately carries NO transport concern (no `fetch`, no
+ * socket) — it is pure codec. The HTTP backends keep their own inline
+ * copies (they predate this module and stay UNTOUCHED per the P0
+ * scope); this module mirrors those shapes verbatim and is the
+ * canonical definition the vsock path consumes.
+ *
+ * Why mirror rather than refactor docker/aci onto it: the P0 scope is
+ * "do NOT touch docker or aci". Centralising the shapes here, with the
+ * inline docker copy pinned by `backends/docker/__tests__` and this
+ * module pinned by `backends/firecracker/__tests__`, keeps both honest
+ * without editing the frozen HTTP path. A later cleanup pass can fold
+ * docker/aci onto this module once it is no longer release-frozen.
+ */
+import type { SandboxExecResult } from '@namzu/sdk';
+/**
+ * `/execute` request body. Identical field set to the HTTP worker's
+ * `handleExecute` body (`command`, `args`, `cwd`, `env`, `stdin`,
+ * `timeoutMs`, `maxOutputBytes`). `timeoutMs` maps from the SDK's
+ * `SandboxExecOptions.timeout`.
+ */
+export interface ExecRequest {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+    readonly stdin?: string;
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+}
+/**
+ * One NDJSON event the agent emits while streaming an `/execute`. The
+ * exact union the HTTP worker writes via `writeEvent`:
+ *   { type: 'stdout_delta', data }
+ *   { type: 'stderr_delta', data }
+ *   { type: 'result', exitCode, timedOut, durationMs, stdoutTruncated?, stderrTruncated? }
+ *   { type: 'error', error }
+ */
+export type ExecEvent = {
+    readonly type: 'stdout_delta';
+    readonly data: string;
+} | {
+    readonly type: 'stderr_delta';
+    readonly data: string;
+} | {
+    readonly type: 'result';
+    readonly exitCode: number;
+    readonly timedOut: boolean;
+    readonly durationMs?: number;
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+} | {
+    readonly type: 'error';
+    readonly error: string;
+};
+/** `/write-file` request body. `content` is base64. */
+export interface WriteFileRequest {
+    readonly path: string;
+    readonly content: string;
+    readonly encoding: 'base64';
+}
+/** `/write-file` success response. */
+export interface WriteFileResponse {
+    readonly ok: boolean;
+    readonly bytesWritten?: number;
+    readonly error?: string;
+}
+/** `/read-file` request body. */
+export interface ReadFileRequest {
+    readonly path: string;
+    readonly encoding: 'base64';
+}
+/** `/read-file` response. `content` is base64 on success. */
+export interface ReadFileResponse {
+    readonly ok: boolean;
+    readonly content?: string;
+    readonly sizeBytes?: number;
+    readonly encoding?: string;
+    readonly error?: string;
+}
+/**
+ * Accumulates the streamed `/execute` NDJSON into a single
+ * {@link SandboxExecResult}, exactly as the docker/aci `execViaWorker`
+ * loops do: concatenate `stdout_delta` / `stderr_delta`, capture the
+ * terminal `result`, and **throw** on an `error` event.
+ *
+ * Transport-agnostic: feed it whole parsed {@link ExecEvent}s (the
+ * transport owns newline-framing → JSON.parse → here). Malformed lines
+ * are dropped by the transport's `JSON.parse` guard before they reach
+ * this accumulator, matching the docker loop's `SyntaxError` swallow.
+ */
+export declare class ExecResultAccumulator {
+    private stdout;
+    private stderr;
+    private exitCode;
+    private timedOut;
+    private signal;
+    private settled;
+    private readonly start;
+    constructor(start?: number);
+    /**
+     * Apply one event. Returns `true` once a terminal `result` has been
+     * seen (so the transport can stop reading early if it wants).
+     * Throws if the event is an `error` — the same control flow the
+     * docker loop uses (`throw new Error(event.error)`).
+     */
+    push(event: ExecEvent): boolean;
+    get done(): boolean;
+    /** Build the SDK-shaped result. `durationMs` measured host-side. */
+    finish(): SandboxExecResult;
+}
+/**
+ * Parse a single NDJSON line into an {@link ExecEvent}, or `undefined`
+ * if the line is blank or not valid JSON (the docker loop's
+ * `SyntaxError` swallow). Non-`SyntaxError` problems are impossible
+ * here because we only `JSON.parse`; structural validation is by the
+ * `type` discriminator at the call site.
+ */
+export declare function parseExecLine(line: string): ExecEvent | undefined;
+//# sourceMappingURL=protocol.d.ts.map

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

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

package/dist/backends/firecracker/protocol.js

@@ -0,0 +1,112 @@
+/**
+ * The ONE wire contract, shared across both transports.
+ *
+ * The docker (`backends/docker/`) and ACI (`backends/aci-standby-pool/`)
+ * backends speak this contract over **HTTP**: a streaming NDJSON
+ * `/execute` response and base64-bodied `/read-file` / `/write-file`
+ * JSON requests, served by `worker/server.js`. The Firecracker
+ * backend speaks the **same NDJSON shapes and the same base64 file-IO
+ * shapes** — only the transport changes from HTTP-over-TCP to
+ * framed-over-vsock (see `transport.ts`).
+ *
+ * This module is the single source of truth for the message shapes
+ * and the streaming exec-line parser, so the two transports cannot
+ * drift. It deliberately carries NO transport concern (no `fetch`, no
+ * socket) — it is pure codec. The HTTP backends keep their own inline
+ * copies (they predate this module and stay UNTOUCHED per the P0
+ * scope); this module mirrors those shapes verbatim and is the
+ * canonical definition the vsock path consumes.
+ *
+ * Why mirror rather than refactor docker/aci onto it: the P0 scope is
+ * "do NOT touch docker or aci". Centralising the shapes here, with the
+ * inline docker copy pinned by `backends/docker/__tests__` and this
+ * module pinned by `backends/firecracker/__tests__`, keeps both honest
+ * without editing the frozen HTTP path. A later cleanup pass can fold
+ * docker/aci onto this module once it is no longer release-frozen.
+ */
+// ---------------------------------------------------------------------------
+// Streaming exec-line accumulator — the parser docker/aci inline today,
+// lifted out so the vsock transport reuses it byte-for-byte.
+// ---------------------------------------------------------------------------
+/**
+ * Accumulates the streamed `/execute` NDJSON into a single
+ * {@link SandboxExecResult}, exactly as the docker/aci `execViaWorker`
+ * loops do: concatenate `stdout_delta` / `stderr_delta`, capture the
+ * terminal `result`, and **throw** on an `error` event.
+ *
+ * Transport-agnostic: feed it whole parsed {@link ExecEvent}s (the
+ * transport owns newline-framing → JSON.parse → here). Malformed lines
+ * are dropped by the transport's `JSON.parse` guard before they reach
+ * this accumulator, matching the docker loop's `SyntaxError` swallow.
+ */
+export class ExecResultAccumulator {
+    stdout = '';
+    stderr = '';
+    exitCode = -1;
+    timedOut = false;
+    signal;
+    settled = false;
+    start;
+    constructor(start = Date.now()) {
+        this.start = start;
+    }
+    /**
+     * Apply one event. Returns `true` once a terminal `result` has been
+     * seen (so the transport can stop reading early if it wants).
+     * Throws if the event is an `error` — the same control flow the
+     * docker loop uses (`throw new Error(event.error)`).
+     */
+    push(event) {
+        if (event.type === 'stdout_delta') {
+            this.stdout += event.data;
+            return false;
+        }
+        if (event.type === 'stderr_delta') {
+            this.stderr += event.data;
+            return false;
+        }
+        if (event.type === 'result') {
+            this.exitCode = event.exitCode;
+            this.timedOut = event.timedOut;
+            this.settled = true;
+            return true;
+        }
+        // event.type === 'error'
+        throw new Error(event.error);
+    }
+    get done() {
+        return this.settled;
+    }
+    /** Build the SDK-shaped result. `durationMs` measured host-side. */
+    finish() {
+        return {
+            exitCode: this.exitCode,
+            stdout: this.stdout,
+            stderr: this.stderr,
+            ...(this.signal ? { signal: this.signal } : {}),
+            timedOut: this.timedOut,
+            durationMs: Date.now() - this.start,
+        };
+    }
+}
+/**
+ * Parse a single NDJSON line into an {@link ExecEvent}, or `undefined`
+ * if the line is blank or not valid JSON (the docker loop's
+ * `SyntaxError` swallow). Non-`SyntaxError` problems are impossible
+ * here because we only `JSON.parse`; structural validation is by the
+ * `type` discriminator at the call site.
+ */
+export function parseExecLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return undefined;
+        throw err;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/backends/firecracker/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/backends/firecracker/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA8EH,8EAA8E;AAC9E,wEAAwE;AACxE,6DAA6D;AAC7D,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,qBAAqB;IACzB,MAAM,GAAG,EAAE,CAAA;IACX,MAAM,GAAG,EAAE,CAAA;IACX,QAAQ,GAAG,CAAC,CAAC,CAAA;IACb,QAAQ,GAAG,KAAK,CAAA;IAChB,MAAM,CAAoB;IAC1B,OAAO,GAAG,KAAK,CAAA;IACN,KAAK,CAAQ;IAE9B,YAAY,QAAgB,IAAI,CAAC,GAAG,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAgB;QACpB,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAA;YACzB,OAAO,KAAK,CAAA;QACb,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAA;YACzB,OAAO,KAAK,CAAA;QACb,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;YAC9B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;YAC9B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;YACnB,OAAO,IAAI,CAAA;QACZ,CAAC;QACD,yBAAyB;QACzB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;IAED,IAAI,IAAI;QACP,OAAO,IAAI,CAAC,OAAO,CAAA;IACpB,CAAC;IAED,oEAAoE;IACpE,MAAM;QACL,OAAO;YACN,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;SACnC,CAAA;IACF,CAAC;CACD;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IAC9B,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAc,CAAA;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,GAAG,YAAY,WAAW;YAAE,OAAO,SAAS,CAAA;QAChD,MAAM,GAAG,CAAA;IACV,CAAC;AACF,CAAC"}