@namzu/sandbox 13.0.0 → 15.0.0

package/dist/testing/sandbox-conformance.d.ts

@@ -0,0 +1,227 @@
+/**
+ * The {@link Sandbox} contract, as a suite a backend author runs against
+ * their own implementation.
+ *
+ * ## Why this exists
+ *
+ * `@namzu/sdk`'s `Sandbox` interface is the one thing every backend in this
+ * package promises to implement the same way — `exec`'s exit codes, the
+ * `AbortSignal` contract, a `writeFile`/`readFile` round trip, terminal
+ * ownership on `destroy()` — and until now nothing PROVED that two backends
+ * agreed on any of it. Each backend carried its own bespoke test file
+ * (`sandbox-surface.test.ts`, `backend.test.ts`, …), written by whoever
+ * built that backend, checking whatever that author thought to check. A
+ * shared contract can be silently narrower than either file: this suite is
+ * the thing that would have caught it.
+ *
+ * ## Why it takes its runner as an argument
+ *
+ * The same shape as `@namzu/sdk/testing`'s checkpoint-store and provider
+ * driver suites, and for the same two reasons: `@namzu/sandbox` gains no
+ * test dependency from publishing it, and a caller can pass a RECORDING
+ * `describe`/`it` and run the whole contract as ordinary code — which is
+ * how `testing/__tests__/conformance-fails-a-broken-sandbox.test.ts`
+ * proves a deliberately wrong `Sandbox` fails it.
+ *
+ * ## What is asserted, and what deliberately is not
+ *
+ * Contract behaviour only — never a backend-specific object, field or
+ * error string. A case never inspects `sandbox.constructor.name`, never
+ * matches an error message, and never assumes a particular
+ * {@link SandboxEnvironment}. `openTerminal`, `openTcpConnection` and
+ * `walkFiles` are OPTIONAL on {@link Sandbox} by the SDK's own contract — a
+ * backend that cannot honour one must omit it rather than accept and ignore
+ * it — so a factory whose sandbox omits any of them skips that section rather
+ * than failing it. Every other section runs against every sandbox.
+ *
+ * ## Where it runs today
+ *
+ * Both `backends/kubernetes/__tests__/conformance.test.ts` and
+ * `backends/firecracker/__tests__/conformance.test.ts` call this against a
+ * real `agent/agent.cjs` on a loopback socket — proving the suite is
+ * backend-agnostic rather than one backend's tests wearing a new name.
+ * `packages/sandbox/k8s/scripts/contract-suite.mjs` runs it a third time,
+ * against a live cluster.
+ *
+ * ## Not published from `@namzu/sandbox`'s entry point
+ *
+ * The package has no `testing` subpath today (unlike `@namzu/sdk`), and
+ * this batch does not add one — promoting this to a public import path is
+ * a deliberate, separate decision. Within the monorepo a caller imports it
+ * by relative path, exactly as the two files above do:
+ *
+ * ```ts sketch
+ * import { defineSandboxConformance } from '../../../testing/sandbox-conformance.js'
+ *
+ * defineSandboxConformance({
+ *   describe, it, expect,
+ *   label: 'my-backend',
+ *   makeSandbox: async () => ({ sandbox: await myBackend.create(), dispose: async () => {} }),
+ * })
+ * ```
+ */
+import type { OpenTerminalOptions, Sandbox, TerminalSession } from '@namzu/sdk';
+import type { ConformanceAssertion, ConformanceDescribe, ConformanceExpect, ConformanceIt } from '@namzu/sdk/testing';
+/**
+ * The contract revision these assertions express. Carried on the describe
+ * label so a failure is legible on sight as "the sandbox contract", the
+ * same convention `PROVIDER_DRIVER_CONTRACT_VERSION` uses — raised only
+ * when a case is ADDED or TIGHTENED, never on a rewording.
+ *
+ * 3 is the `walkFiles`, concurrent-`exec` and `exec`-timeout sections, none
+ * of which needs a guest feature that did not already exist.
+ *
+ * **The ranged and streamed read cases deliberately did NOT raise it
+ * further.** Raising it for them would assert that every backend this suite
+ * runs against implements them, and one does not: the Firecracker tier's
+ * guest lives in a golden rootfs image that is NOT built from this
+ * repository — nothing here builds one, `packages/sandbox/package.json#files`
+ * does not even ship `agent/`, and `README.md` documents the image as
+ * something the operator builds and canaries on their own schedule. A
+ * deployment therefore runs whatever agent its last image build baked in,
+ * and a contract version that claimed otherwise would be a claim about
+ * images this repository cannot see. Those two cases are gated on
+ * {@link SandboxConformanceOptions.supportsRangedAndStreamedReads}
+ * instead, and skip by name when a backend does not declare them.
+ */
+export declare const SANDBOX_CONTRACT_VERSION = 3;
+/** A sandbox to test, plus whatever teardown building it required. */
+export interface SandboxConformanceHandle {
+    readonly sandbox: Sandbox;
+    /**
+     * Called after each case, pass or fail — closes fixture servers, restores
+     * environment variables, removes temp directories. Distinct from
+     * `sandbox.destroy()`, which the suite calls itself (idempotently) as
+     * part of every case's teardown; `dispose` is for what `makeSandbox`
+     * itself stood up, not for the sandbox's own lifecycle.
+     */
+    dispose?(): void | Promise<void>;
+}
+/**
+ * Build one fresh {@link Sandbox}. Called once per case, so no case can be
+ * affected by another's writes, aborts or destroys — the suite never
+ * assumes a shared instance and never reuses one across cases.
+ */
+export type MakeSandbox = () => SandboxConformanceHandle | Promise<SandboxConformanceHandle>;
+export interface SandboxConformanceOptions {
+    readonly describe: ConformanceDescribe;
+    readonly it: ConformanceIt;
+    readonly expect: ConformanceExpect;
+    readonly makeSandbox: MakeSandbox;
+    /** Names the backend in test output. Defaults to `sandbox`. */
+    readonly label?: string;
+    /**
+     * Whether this backend's guest can run the `openTcpConnection` positive
+     * case's listener at all — by default {@link nodeGuestListener}, `node
+     * -e`. Defaults to `true`: every backend this suite ships against runs
+     * `agent/agent.cjs` in the guest, and that agent IS node, so node on the
+     * guest's own `PATH` is a precondition of the agent existing rather than
+     * an extra capability this suite demands.
+     *
+     * Set `false` for a guest that cannot run a listener this way at all
+     * (no `openTerminal`, or an image with neither node nor a substitute) —
+     * the case then SKIPS, its own title stating why, rather than failing a
+     * backend for a capability its contract never promised. A backend that
+     * can run *some* listener, just not node, keeps this `true` (or omits
+     * it) and supplies {@link SandboxConformanceOptions.guestListenerCommand}
+     * instead.
+     */
+    readonly guestCanRunNode?: boolean;
+    /**
+     * Overrides the program the `openTcpConnection` positive case starts
+     * inside the guest. Defaults to {@link nodeGuestListener}. A guest
+     * without node but with, say, busybox `nc` can supply its own command as
+     * long as it reports the bound port the way
+     * {@link GuestListenerCommand.parsePort} expects.
+     */
+    readonly guestListenerCommand?: () => GuestListenerCommand;
+    /**
+     * Whether this backend's guest honours `readFile`'s `offset`/`length`
+     * and implements {@link Sandbox.readFileStream}.
+     *
+     * **Defaults to `false`, and the default is the honest one.** These
+     * cases are not in {@link SANDBOX_CONTRACT_VERSION} — see the comment
+     * on that constant for why — so the suite cannot assume a backend has
+     * them. A backend whose guest is built from this repository sets it
+     * `true`; every other backend gets the cases as named skips, counted in
+     * the runner's own totals and titled with the reason, rather than as
+     * failures for a contract it never agreed to.
+     *
+     * A backend that sets this `true` while its guest ignores
+     * `offset`/`length` FAILS, and that is the point: returning the whole
+     * file where a slice was asked for is a wrong answer, not a missing
+     * capability.
+     */
+    readonly supportsRangedAndStreamedReads?: boolean;
+}
+/**
+ * A program the `openTcpConnection` positive case can start INSIDE a guest
+ * through {@link Sandbox.openTerminal}, and dial back into over
+ * `openTcpConnection` itself.
+ *
+ * Starting the listener in the guest — rather than in the orchestrator/test
+ * process, which is what this case used to do — is the whole point: a
+ * listener on the HOST'S loopback only ever proves anything for a backend
+ * whose "guest" happens to share that loopback (a Firecracker fixture over a
+ * local socket, a fake-agent-in-this-process kubernetes test). It never
+ * proves anything for a real remote guest, which cannot dial the
+ * orchestrator's loopback at all — that gap is exactly what let the case
+ * pass in every colocated fixture and fail the one time it ran against a
+ * live cluster.
+ */
+export interface GuestListenerCommand {
+    /** The program `openTerminal` runs as the session's top-level process. */
+    readonly command: string;
+    readonly args: readonly string[];
+    /**
+     * Reads the port the listener bound out of everything it has printed to
+     * its terminal so far. Returns `undefined` until the listener has
+     * reported one — the suite polls this as output arrives rather than
+     * parsing a single chunk, because a pty may deliver the report split
+     * across reads.
+     */
+    parsePort(output: string): number | undefined;
+}
+/**
+ * The default {@link GuestListenerCommand}: `node -e` binding an ephemeral
+ * port on the GUEST's own loopback, echoing `conformance-reply:<payload>`
+ * back for the first chunk of the one connection it accepts, then reporting
+ * the bound port on its own stdout — the only way the host, which cannot
+ * inspect a real remote guest's open ports any other way, learns which port
+ * to dial.
+ *
+ * Every backend this suite ships against runs `agent/agent.cjs` in the
+ * guest, which is itself node — so node on the guest's `PATH` is not an
+ * extra requirement this suite invents, it is a precondition of the agent
+ * existing at all. A backend whose guest genuinely cannot run node (or
+ * cannot run `openTerminal`) declares that through
+ * {@link SandboxConformanceOptions.guestCanRunNode} or supplies its own
+ * command via {@link SandboxConformanceOptions.guestListenerCommand}.
+ */
+export declare function nodeGuestListener(): GuestListenerCommand;
+/**
+ * Start `listener` through `openTerminal`, and resolve once it has reported
+ * the port it bound.
+ *
+ * The returned `stop()` kills the terminal's owned process tree — the exact
+ * ownership guarantee the `openTerminal` section above already proves
+ * `destroy()` gets for free, used here to tear the listener down without
+ * waiting for the whole sandbox to go away.
+ *
+ * Takes `openTerminal` as a plain function rather than a `Sandbox`, so a
+ * unit test can exercise the port-parsing and exit-races above without a
+ * `Sandbox` fixture — see `__tests__/guest-listener.test.ts`.
+ */
+export declare function startGuestListener(openTerminal: (options: OpenTerminalOptions) => Promise<TerminalSession>, listener: GuestListenerCommand): Promise<{
+    readonly port: number;
+    stop(): Promise<void>;
+}>;
+/**
+ * Register the {@link Sandbox} contract against one backend.
+ *
+ * Call it once per backend. It registers cases through the supplied
+ * `describe`/`it`; it does not run them.
+ */
+export declare function defineSandboxConformance(options: SandboxConformanceOptions): void;
+export type { ConformanceAssertion, ConformanceDescribe, ConformanceExpect, ConformanceIt };
+//# sourceMappingURL=sandbox-conformance.d.ts.map

package/dist/testing/sandbox-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/sandbox-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAGH,OAAO,KAAK,EACX,mBAAmB,EACnB,OAAO,EAIP,eAAe,EACf,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EACX,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,MAAM,oBAAoB,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC,sEAAsE;AACtE,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAA;AAE5F,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;IACtC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,oBAAoB,CAAA;IAC1D;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,OAAO,CAAA;CACjD;AAgED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC7C;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,IAAI,oBAAoB,CAsBxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACvC,YAAY,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,eAAe,CAAC,EACxE,QAAQ,EAAE,oBAAoB,GAC5B,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CA0C3D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAozBjF;AAKD,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,aAAa,EAAE,CAAA"}