@specific.dev/spectest 0.100.0 → 0.102.0

package/dist/harness/ingress-server.js

@@ -0,0 +1,166 @@
+import http from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { WS_BRIDGE_HANDLERS } from "./ws-bridge.js";
+// Load the installed implementation, not Bun's built-in `ws` replacement.
+// On Bun 1.4.0 that replacement cannot upgrade node:http sockets after the
+// asynchronous upstream handshake. The package uses the ordinary socket API.
+const require = createRequire(import.meta.url);
+const { WebSocketServer } = require(join(dirname(require.resolve("ws/package.json")), "index.js"));
+/**
+ * Serve the ingress's Fetch handlers through node:http. Bun.serve discards
+ * Content-Length on a still-streaming Response, even when its bytes are
+ * unchanged. ServerResponse preserves the declared length while pipeline
+ * propagates backpressure and cancellation without buffering the whole body.
+ * This is also the HTTP/1 listener behind the TLS terminator.
+ */
+export async function startIngressServer(options) {
+    const peers = new WeakMap();
+    const upgrades = new WeakMap();
+    const protocols = new WeakMap();
+    const sockets = new Set();
+    const websockets = new WebSocketServer({
+        noServer: true,
+        // The upstream handshake has already selected a protocol. Never select
+        // the client's first offer on its behalf.
+        handleProtocols: (_offered, req) => protocols.get(req) || false,
+    });
+    const server = http.createServer({ requestTimeout: 0 }, (req, res) => {
+        void dispatch(req, res);
+    });
+    server.on("connection", socket => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+    });
+    server.on("upgrade", (req, socket, head) => {
+        void dispatch(req, undefined, { req, socket: socket, head, upgraded: false });
+    });
+    const facade = {
+        port: 0,
+        stop(force = false) {
+            if (force) {
+                for (const ws of websockets.clients)
+                    ws.terminate();
+                for (const socket of sockets)
+                    socket.destroy();
+                server.closeAllConnections();
+            }
+            websockets.close();
+            server.close();
+        },
+        requestIP(req) {
+            const socket = peers.get(req);
+            return socket?.remoteAddress && socket.remotePort
+                ? { address: socket.remoteAddress, port: socket.remotePort } : undefined;
+        },
+        upgrade(req, opts) {
+            const pending = upgrades.get(req);
+            if (!pending || pending.upgraded || pending.socket.destroyed)
+                return false;
+            protocols.set(pending.req, opts.headers?.["sec-websocket-protocol"]);
+            websockets.handleUpgrade(pending.req, pending.socket, pending.head, ws => {
+                pending.upgraded = true;
+                const client = {
+                    data: opts.data,
+                    send: (data) => ws.send(data),
+                    close: (code, reason) => ws.close(code, reason),
+                };
+                ws.on("message", (data, binary) => WS_BRIDGE_HANDLERS.message(client, binary ? Buffer.from(data) : data.toString()));
+                ws.on("close", (code, reason) => WS_BRIDGE_HANDLERS.close(client, code, reason.toString()));
+                ws.on("error", () => opts.data.upstream.close());
+                WS_BRIDGE_HANDLERS.open(client);
+            });
+            return pending.upgraded;
+        },
+    };
+    async function dispatch(incoming, outgoing, upgrade) {
+        const abort = new AbortController();
+        const onClose = () => {
+            if (!outgoing?.writableFinished && !upgrade?.upgraded)
+                abort.abort();
+        };
+        const connection = outgoing ?? upgrade.socket;
+        connection.once("close", onClose);
+        const responseWriter = () => {
+            if (!outgoing) {
+                // Only attach an HTTP response after a refused upgrade. Attaching
+                // one before handleUpgrade conflicts with Bun's native handshake.
+                outgoing = new http.ServerResponse(incoming);
+                outgoing.assignSocket(upgrade.socket);
+                outgoing.once("finish", () => upgrade.socket.end());
+            }
+            return outgoing;
+        };
+        let response;
+        try {
+            const headers = new Headers();
+            for (let i = 0; i < incoming.rawHeaders.length; i += 2) {
+                headers.append(incoming.rawHeaders[i], incoming.rawHeaders[i + 1]);
+            }
+            const method = incoming.method ?? "GET";
+            const req = new Request(new URL(incoming.url ?? "/", `http://${headers.get("host") ?? "localhost"}`), {
+                method, headers, signal: abort.signal,
+                body: method === "GET" || method === "HEAD" ? undefined : Readable.toWeb(incoming),
+                duplex: "half",
+            });
+            peers.set(req, incoming.socket);
+            if (upgrade)
+                upgrades.set(req, upgrade);
+            response = await options.fetch(req, facade);
+            if (upgrade?.upgraded)
+                return;
+            if (!response)
+                throw new Error("Ingress handler returned no response");
+            if (abort.signal.aborted) {
+                await response.body?.cancel();
+                return;
+            }
+            const writer = responseWriter();
+            writer.statusCode = response.status;
+            writer.statusMessage = response.statusText;
+            response.headers.forEach((value, key) => {
+                if (key !== "set-cookie")
+                    writer.setHeader(key, value);
+            });
+            const cookies = response.headers.getSetCookie();
+            if (cookies.length)
+                writer.setHeader("set-cookie", cookies);
+            // Flush even for a body already buffered by fetch. An upstream with
+            // no length must not acquire an invented Content-Length from end().
+            writer.flushHeaders();
+            if (method === "HEAD" || response.status === 204 || response.status === 304 || !response.body) {
+                await response.body?.cancel();
+                writer.end();
+            }
+            else {
+                await pipeline(Readable.fromWeb(response.body), writer);
+            }
+        }
+        catch (error) {
+            if (upgrade?.upgraded)
+                return;
+            outgoing = responseWriter();
+            if (!outgoing.headersSent && !outgoing.destroyed) {
+                outgoing.writeHead(500, { "content-type": "text/plain" });
+                outgoing.end("spectest-daemon: ingress response failed\n");
+            }
+            else {
+                outgoing.destroy(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        finally {
+            connection.off("close", onClose);
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen({ port: options.port, host: options.hostname ?? "0.0.0.0", reusePort: options.reusePort }, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    facade.port = server.address().port;
+    return facade;
+}

package/dist/harness/tls-terminator.js

@@ -33,15 +33,11 @@
  * ## The shape, and why it is a byte pipe
  *
  * The terminator does TLS and *nothing else*: it accepts on :443, picks a
- * leaf by SNI, and pipes the decrypted stream to a plaintext `Bun.serve`
- * bound on loopback. Opted-in HTTP/2 routes select a separate stream router
- * by ALPN; HTTP/1.1 and WebSockets retain the existing listener. Everything downstream — routing, fakes,
- * interceptors, reverse-proxying, and `server.upgrade()` WebSocket
- * bridging — is the same `Bun.serve` code that already serves :80, run
- * unchanged. Terminating HTTP here instead (`node:https`, `(req, res)`)
- * would have meant reimplementing the WebSocket bridge against a
- * different API, which is exactly the kind of trade this change exists to
- * avoid: one flake removed, another introduced somewhere subtler.
+ * leaf by SNI, and pipes the decrypted stream to the plaintext ingress
+ * server bound on loopback. Opted-in HTTP/2 routes select a separate stream
+ * router by ALPN; HTTP/1.1 and WebSockets use the shared ingress listener.
+ * Routing, fakes, interceptors and reverse-proxying stay in that listener;
+ * this layer never parses or rewrites HTTP response framing.
  *
  * Measured cost of the extra hop on this host (Bun 1.4.0, undici client,
  * 50 MB bodies): ~11 % fewer small requests per second, download

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.100.0",
+  "version": "0.102.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,11 +56,13 @@
     "@kubernetes/client-node": "^1.0.0",
     "@xterm/headless": "^5.5.0",
     "dns-packet": "^5.6.1",
-    "playwright-core": "^1.61.1"
+    "playwright-core": "^1.61.1",
+    "ws": "^8.20.1"
   },
   "devDependencies": {
     "@types/dns-packet": "^5.6.5",
     "@types/bun": "^1.3.0",
+    "@types/ws": "^8",
     "typescript": "^5.6.3"
   },
   "spectestCapabilities": [

package/src/components/index.ts

@@ -85,6 +85,8 @@ export { okta, type OktaOptions } from "./okta.js";
 export {
   replayFake,
   type ReplayFakeOptions,
+  type ReplayFakeContext,
+  type ReplayHandler,
   type ReplayKey,
   type ReplayRequest,
   type MatchKey,

package/src/components/replayFake-handler.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineEnvironment, type FakeContext } from "../index.js";
+import { replayFake, type Cassette, type ReplayFakeContext, type ReplayHandler } from "./index.js";
+
+const host = "api.example.test";
+const context = {} as FakeContext;
+const fixture: Cassette = {
+  version: 1, fake: "mixed", host,
+  interactions: ["one", "two"].map((task) => ({
+    request: {
+      method: "POST", path: "/messages", query: {}, headers: {},
+      body: JSON.stringify({ task }), bodyEncoding: "utf8",
+    },
+    response: { status: 200, headers: {}, body: `recorded-${task}`, bodyEncoding: "utf8" },
+  })),
+};
+const request = (task = "one", path = "/messages") => new Request(`https://${host}${path}`, {
+  method: "POST", body: JSON.stringify({ task }),
+});
+
+function mixedFake() {
+  return replayFake({
+    name: "mixed", host, mode: "replay",
+    state: () => ({ useRecordings: false, reply: "scripted", seen: [] as string[] }),
+    helpers: ({ state }) => ({
+      useRecordings(enabled = true) { state.useRecordings = enabled; },
+      reply(text: string) { state.reply = text; },
+      seen() { return [...state.seen]; },
+    }),
+    async handler(req, state, ctx) {
+      const body = await req.clone().json() as { task: string };
+      state.seen.push(body.task);
+      if (state.useRecordings && new URL(req.url).pathname === "/messages") {
+        return ctx.replay(req);
+      }
+      return new Response(state.reply);
+    },
+  });
+}
+
+describe("scripted behavior on replay fakes", () => {
+  test("loading only loads; custom helpers select behavior and misses never fall back", async () => {
+    const fake = mixedFake();
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    const send = (task?: string, path?: string) => fake.handler(request(task, path), state, context);
+
+    expect(await (await send()).text()).toBe("scripted");
+    helpers.reply("configured");
+    helpers.replay(fixture);
+    expect(await (await send()).text()).toBe("configured");
+    helpers.useRecordings();
+    expect((await send("missing")).status).toBe(599);
+    // The same fake mixes scripted and replayed endpoints concurrently.
+    expect(await Promise.all([
+      send("two"), send("one", "/transcription"), send("one"),
+    ].map(async (response) => (await response).text()))).toEqual([
+      "recorded-two", "configured", "recorded-one",
+    ]);
+    expect((await send()).status).toBe(599);
+    helpers.useRecordings(false);
+    expect(await (await send()).text()).toBe("configured");
+    expect(helpers.count()).toBe(0);
+    expect(helpers.recorded()).toEqual([]);
+    expect(helpers.seen()).toHaveLength(8);
+  });
+
+  test("delegating without a cassette fails even when scripted responses are available", async () => {
+    const fake = mixedFake();
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    helpers.useRecordings();
+    expect((await fake.handler(request(), state, context)).status).toBe(599);
+  });
+
+  test("custom state and cassette cursors survive cloning and siblings remain independent", async () => {
+    const fake = mixedFake();
+    const parent = await fake.state!();
+    const parentHelpers = await fake.helpers!({ name: "mixed", state: parent, ctx: context });
+    parentHelpers.replay(fixture);
+    parentHelpers.useRecordings();
+    await fake.handler(request("one"), parent, context);
+    // Model the state inherited by forks, including custom state and cursors.
+    const left = structuredClone(parent);
+    const right = structuredClone(parent);
+    const leftHelpers = await fake.helpers!({ name: "mixed", state: left, ctx: context });
+    leftHelpers.reply("left only");
+    expect((await fake.handler(request("one"), right, context)).status).toBe(599);
+    expect(await (await fake.handler(request("two"), left, context)).text()).toBe("recorded-two");
+    expect(await (await fake.handler(request("two"), right, context)).text()).toBe("recorded-two");
+    leftHelpers.useRecordings(false);
+    expect(right.custom.useRecordings).toBe(true);
+    expect(right.custom.reply).toBe("scripted");
+    expect(parent.cursor.size).toBe(1);
+  });
+
+  test("async factories receive custom state and the normal fake context", async () => {
+    const ctx = { dnsName: async () => {} } as unknown as FakeContext;
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      state: async () => ({ reply: "async" }),
+      helpers: async ({ state, name, ctx: received }) => {
+        expect(name).toBe("mixed");
+        expect(received).toBe(ctx);
+        return { reply: (text: string) => { state.reply = text; } };
+      },
+      handler: (_req, state, received) => {
+        expect(received.dnsName).toBe(ctx.dnsName);
+        expect(typeof received.replay).toBe("function");
+        expect("replay" in ctx).toBe(false);
+        return new Response(state.reply);
+      },
+    });
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx });
+    helpers.reply("updated");
+    expect(await (await fake.handler(request(), state, ctx)).text()).toBe("updated");
+  });
+
+  test.each(["replay", "dump", "recorded", "count"])("rejects reserved helper name %s", async (name) => {
+    const fake = replayFake({ name: "mixed", host, helpers: () => ({ [name]: () => {} }) });
+    const state = await fake.state!();
+    await expect(Promise.resolve().then(() => fake.helpers!({ name: "mixed", state, ctx: context })))
+      .rejects.toThrow(`custom helper "${name}" is reserved`);
+  });
+
+  test("handler-only customization needs no state or helpers", async () => {
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      handler(req, state, ctx) {
+        expect(state).toBeUndefined();
+        return ctx.replay(req);
+      },
+    });
+    const state = await fake.state!();
+    const helpers = await fake.helpers!({ name: "mixed", state, ctx: context });
+    helpers.replay(fixture);
+    expect(await (await fake.handler(request(), state, context)).text()).toBe("recorded-one");
+  });
+
+  test("a consumed body reports how to inspect safely before delegation", async () => {
+    const fake = replayFake({
+      name: "mixed", host, mode: "replay",
+      async handler(req, _state, ctx) {
+        await req.json();
+        return ctx.replay(req);
+      },
+    });
+    const state = await fake.state!();
+    await expect(fake.handler(request(), state, context)).rejects.toThrow("inspect request.clone()");
+  });
+
+  test("public state, context, and helper types stay inferred through defineEnvironment", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spectest-replay-types-"));
+    try {
+      const config = join(dir, "tsconfig.json");
+      await writeFile(config, JSON.stringify({
+        extends: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
+        compilerOptions: {
+          noEmit: true,
+          typeRoots: [fileURLToPath(new URL("../../node_modules/@types", import.meta.url))],
+        },
+        include: [fileURLToPath(import.meta.url)],
+        exclude: [],
+      }));
+      const child = Bun.spawn([process.execPath, fileURLToPath(import.meta.resolve("typescript/bin/tsc")), "-p", config], {
+        stdout: "pipe", stderr: "pipe",
+      });
+      const [exit, stdout, stderr] = await Promise.all([
+        child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+      ]);
+      expect(exit, stdout + stderr).toBe(0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }, 30_000);
+});
+
+// Checked with tsc as well as the runtime tests: inference must survive the
+// public components export and defineEnvironment's wrapped helper surface.
+function checkPublicTypes() {
+  const fake = replayFake({
+    name: "typed", host,
+    state: () => ({ enabled: false }),
+    helpers: ({ state }) => ({
+      enable(value: boolean) {
+        state.enabled = value;
+        // @ts-expect-error custom state is inferred, not any
+        state.missing;
+      },
+    }),
+    handler(req, state, ctx) {
+      const enabled: boolean = state.enabled;
+      const typedContext: ReplayFakeContext = ctx;
+      // @ts-expect-error internal cassette state is not exposed to the handler
+      state.cassette;
+      return enabled ? typedContext.replay(req) : new Response("scripted");
+    },
+  });
+  const env = defineEnvironment({ name: "typed", services: {}, fakes: { typed: fake } });
+  env.test("types", (ctx) => {
+    ctx.fakes.typed.enable(true);
+    ctx.fakes.typed.replay(fixture);
+    ctx.fakes.typed.dump();
+    // @ts-expect-error helper arguments retain their inferred types
+    ctx.fakes.typed.enable("yes");
+    // @ts-expect-error unknown helpers are not callable
+    ctx.fakes.typed.missing();
+  });
+  const handler: ReplayHandler<{ enabled: boolean }> = (req, state, ctx) =>
+    state.enabled ? ctx.replay(req) : new Response("scripted");
+  return handler;
+}

package/src/components/replayFake-record.test.ts

@@ -95,6 +95,48 @@ test("recorded headers, redaction, and exact body bytes survive record → repla
       }
     }
     assert.equal(upstreamHeaders.length, 3); // Replay never forwards.
+
+    // The custom handler delegates through the same auto-mode pipeline.
+    // Scripted requests must neither forward nor enter the cassette.
+    const { startRecording, stopRecording } = await import(${moduleUrl("../recorder.ts")});
+    const mixed = replayFake({
+      ...options,
+      state: () => ({ useRecordings: false }),
+      helpers: ({ state }) => ({ useRecordings() { state.useRecordings = true; } }),
+      async handler(request, state, ctx) {
+        const body = await request.clone().text();
+        return state.useRecordings && body !== "scripted"
+          ? ctx.replay(request)
+          : new Response("scripted response");
+      },
+    });
+    const mixedState = await mixed.state();
+    const mixedHelpers = await mixed.helpers({ name: "test", state: mixedState, ctx: {} });
+    const send = (body) => mixed.handler(new Request("https://api.example.test/messages", {
+      method: "POST", body,
+    }), mixedState, {});
+    assert.equal(await (await send("delegated")).text(), "scripted response");
+    assert.equal(upstreamHeaders.length, 3);
+    mixedHelpers.useRecordings();
+    assert.equal(await (await send("scripted")).text(), "scripted response");
+    assert.equal(await (await send("delegated")).text(), "response");
+    assert.equal(upstreamHeaders.length, 4);
+    assert.equal(upstreamHeaders[3].authorization, "Bearer recording-secret");
+    assert.equal(mixedHelpers.count(), 1);
+    const mixedCassette = mixedHelpers.dump();
+    assert.equal(mixedCassette.interactions[0].request.body, "delegated");
+    mixedHelpers.replay(mixedCassette);
+    startRecording(); // Enter a test: auto now replays instead of forwarding.
+    try {
+      assert.equal(await (await send("scripted")).text(), "scripted response");
+      assert.equal(await (await send("delegated")).text(), "response");
+      assert.equal((await send("delegated")).status, 599);
+      assert.equal((await send("unrecorded")).status, 599);
+      assert.equal(mixedHelpers.count(), 1);
+      assert.equal(upstreamHeaders.length, 4);
+    } finally {
+      stopRecording();
+    }
     });
   `;
   const dir = await mkdtemp(join(tmpdir(), "spectest-replay-record-"));