@specific.dev/spectest 0.109.1 → 0.111.0

package/dist/replay-mode.js

@@ -0,0 +1,12 @@
+// Environment state: travels with memory snapshots, independently of the
+// per-case event recorder. Shared/warm baselines must never record upstream.
+// The control plane enables recording only on an interactive environment,
+// after capturing/restoring the shared baseline and before interactive setup.
+let mode = "test";
+export function setReplayEnvironmentMode(value) {
+    mode = value;
+}
+export function resolveReplayMode(requested = "auto") {
+    // Even an explicit record option cannot send test traffic to real providers.
+    return mode === "test" || requested === "replay" ? "replay" : "record";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.109.1",
+  "version": "0.111.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/index.ts

@@ -88,6 +88,11 @@ export {
   type ReplayFakeContext,
   type ReplayHandler,
   type ReplayKey,
+  type WebSocketKey,
+  type ReplayWebSocketMessage,
+  type CassetteWebSocket,
+  type CassetteWebSocketMessage,
+  type WebSocketTiming,
   type ReplayRequest,
   type MatchKey,
   type JsonValue,

package/src/components/replay-key.ts

@@ -34,7 +34,7 @@ export type ReplayKey = (request: ReplayRequest) => MatchKey;
 /** Stream a typed, length-delimited canonical representation into the hash.
  *  Never call toJSON: unsupported values must fail rather than silently lose
  *  identity fields. In particular, an async callback must not become `{}`. */
-function hashKey(key: MatchKey): string {
+export function hashKey(key: MatchKey): string {
   const hash = createHash("sha256");
   const ancestors = new Set<object>();
   const visit = (value: unknown): void => {

package/src/components/replay-websocket.ts

@@ -0,0 +1,387 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import type WS from "ws";
+import type { FakeWebSocket, FakeWebSocketHandlers } from "../fake-websocket.js";
+import type { CassetteRequest } from "./replayFake.js";
+import { FakeWebSocketLifetime, bindWebSocketLifetime } from "../harness/fake-websocket-lifetime.js";
+import { hashKey, type MatchKey } from "./replay-key.js";
+
+// Bun's built-in ws shim does not support the external-DNS lookup option.
+const require = createRequire(import.meta.url);
+const { WebSocket } = require(join(dirname(require.resolve("ws/package.json")), "index.js")) as typeof import("ws");
+const MAX_BUFFER = 16 * 1024 * 1024;
+const MAX_PENDING = 1024;
+export type ReplayWebSocketMessage = string | Uint8Array;
+export type WebSocketKey<S = unknown> =
+  | ((message: ReplayWebSocketMessage) => MatchKey)
+  | { initial: S; reduce(state: S, message: ReplayWebSocketMessage): { state: S; key: MatchKey } };
+
+export interface WebSocketTiming {
+  /** Number of emitted input keys required. Zero means connection opening. */
+  afterInput: number;
+  /** Milliseconds since that input key (or opening). */
+  delayMs: number;
+}
+export interface CassetteWebSocketMessage extends WebSocketTiming {
+  type: "text" | "binary";
+  /** UTF-8 text or base64 binary. */
+  data: string;
+}
+export interface CassetteWebSocket {
+  request: CassetteRequest;
+  protocol?: string;
+  inputs: string[];
+  messages: CassetteWebSocketMessage[];
+  /** Absent while recording a connection that is still open. */
+  close?: WebSocketTiming & { initiator: "client" | "server"; code: number; reason: string };
+}
+
+export function validateWebSocketKey<S>(key: WebSocketKey<S> | undefined): void {
+  if (key === undefined || typeof key === "function") return;
+  if (!key || typeof key !== "object" || !("initial" in key) || typeof key.reduce !== "function") {
+    throw new Error("websocketKey must be a synchronous function or { initial, reduce }");
+  }
+  structuredClone(key.initial);
+}
+
+/** Clone once per connection; never retain incoming payloads. */
+export function websocketMatcher<S>(key?: WebSocketKey<S>): (message: ReplayWebSocketMessage) => string | null {
+  let state = key && typeof key !== "function" ? structuredClone(key.initial) : undefined;
+  return message => {
+    if (!key) return createHash("sha256").update(typeof message === "string" ? "text:" : "binary:").update(message).digest("hex");
+    let value: MatchKey;
+    if (typeof key === "function") value = key(message);
+    else {
+      const next = key.reduce(state as S, message);
+      if (next instanceof Promise) {
+        void next.catch(() => {});
+        throw new Error("websocketKey reducer must be synchronous");
+      }
+      if (!next || typeof next !== "object" || !("state" in next) || !("key" in next)
+        || ("then" in next && typeof next.then === "function")) {
+        throw new Error("websocketKey reducer must return { state, key }");
+      }
+      value = next.key;
+      const signature = value === null ? null : hashKey(value);
+      state = next.state;
+      return signature;
+    }
+    return value === null ? null : hashKey(value);
+  };
+}
+
+export function validateWebSocketRecording(record: CassetteWebSocket): void {
+  if (!record || !record.request || !Array.isArray(record.inputs)
+    || !record.inputs.every(k => typeof k === "string" && /^[a-f0-9]{64}$/.test(k))
+    || !Array.isArray(record.messages)) {
+    throw new Error("invalid WebSocket recording: expected request, input hashes and messages");
+  }
+  for (const message of record.messages) {
+    if (!message || typeof message.data !== "string" || !["text", "binary"].includes(message.type)) {
+      throw new Error("invalid WebSocket output message");
+    }
+    if (message.type === "binary" && !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(message.data)) {
+      throw new Error("invalid base64 WebSocket output");
+    }
+    if (Buffer.byteLength(message.data, message.type === "binary" ? "base64" : "utf8") > MAX_BUFFER) {
+      throw new Error("WebSocket output buffer exceeded");
+    }
+  }
+  let lastBarrier = 0;
+  let lastDelay = 0;
+  for (const event of [...record.messages, ...(record.close ? [record.close] : [])]) {
+    if (!Number.isInteger(event.afterInput) || event.afterInput < lastBarrier
+      || event.afterInput > record.inputs.length || !Number.isFinite(event.delayMs)
+      || event.delayMs < 0 || event.delayMs > 2_147_483_647
+      || (event.afterInput === lastBarrier && event.delayMs < lastDelay)) {
+      throw new Error("invalid WebSocket playback timing or input dependency");
+    }
+    lastBarrier = event.afterInput;
+    lastDelay = event.delayMs;
+  }
+  if (record.protocol !== undefined && (typeof record.protocol !== "string"
+    || !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(record.protocol))) {
+    throw new Error("invalid WebSocket subprotocol");
+  }
+  if (record.close && (!["client", "server"].includes(record.close.initiator)
+    || !validCloseCode(record.close.code) || typeof record.close.reason !== "string"
+    || Buffer.byteLength(record.close.reason) > 123 || record.close.afterInput !== record.inputs.length)) {
+    throw new Error("invalid WebSocket closure");
+  }
+}
+
+function validCloseCode(code: number): boolean {
+  return Number.isInteger(code) && ((code >= 1000 && code <= 1014 && ![1004, 1005, 1006].includes(code)) || (code >= 3000 && code <= 4999) || code === 1005 || code === 1006);
+}
+function closeSocket(socket: FakeWebSocket | WS, code: number, reason: string): void {
+  // Reserved status codes describe transport closure and cannot go on the wire.
+  if (code === 1006 && socket.terminate) socket.terminate();
+  else if (code === 1005 || code === 1006) socket.close();
+  else socket.close(code, reason);
+}
+
+export interface WebSocketSession {
+  cancel(): void;
+}
+
+export function replayWebSocket(args: {
+  recording: CassetteWebSocket;
+  match: (message: ReplayWebSocketMessage) => string | null;
+  label: string;
+  timeoutMs: number;
+  lifetime?: FakeWebSocketLifetime;
+  finished(session: WebSocketSession, error?: Error): void;
+}): { handlers: FakeWebSocketHandlers; session: WebSocketSession } {
+  const { recording: record, label } = args;
+  const lifetime = args.lifetime ?? new FakeWebSocketLifetime();
+  let detach = () => {};
+  let socket: FakeWebSocket | undefined;
+  let position = 0;
+  let output = 0;
+  const barriers: number[] = [];
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let deadline: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+  let sentClose = false;
+  const diagnostic = (detail: string) => new Error(`${label}, input #${position + 1}: ${detail}`);
+  const clear = () => { clearTimeout(timer); clearTimeout(deadline); };
+  const finish = (error?: Error) => {
+    if (stopped) return;
+    stopped = true;
+    clear();
+    detach();
+    lifetime.end(error ? { kind: "failed", error } : { kind: "aborted" });
+    args.finished(session, error);
+  };
+  const fail = (error: Error) => {
+    finish(error);
+    socket?.close(1011, "WebSocket replay failed");
+  };
+  const missing = () => diagnostic(`required input never arrived; expected ${record.inputs[position]}`);
+  const armDeadline = () => {
+    clearTimeout(deadline);
+    if (position < record.inputs.length) deadline = setTimeout(() => fail(missing()), args.timeoutMs);
+  };
+  const schedule = () => {
+    if (stopped || !socket || sentClose) return;
+    clearTimeout(timer);
+    const event = (record.messages[output] as CassetteWebSocketMessage | undefined) ?? (record.close?.initiator === "server" ? record.close : undefined);
+    if (!event || barriers[event.afterInput] === undefined) return;
+    const delay = Math.max(0, barriers[event.afterInput] + event.delayMs - performance.now());
+    timer = setTimeout(() => {
+      if (stopped) return;
+      try {
+        if ("data" in event) {
+          socket!.send(event.type === "text" ? event.data : new Uint8Array(Buffer.from(event.data, "base64")));
+          output++;
+          schedule();
+        } else {
+          sentClose = true;
+          closeSocket(socket!, event.code, event.reason);
+        }
+      } catch (error) { fail(diagnostic(`playback failed: ${(error as Error).message}`)); }
+    }, Math.min(delay, 2_147_483_647));
+  };
+  const session: WebSocketSession = {
+    cancel() { finish(); socket?.close(1001, "replay cleanup"); },
+  };
+  deadline = setTimeout(() => fail(diagnostic("connection never opened")), args.timeoutMs);
+  const handlers: FakeWebSocketHandlers = {
+    protocol: record.protocol,
+    open(ws) {
+      socket = ws;
+      if (stopped) { ws.close(1001, "replay cancelled"); return; }
+      barriers[0] = performance.now(); armDeadline(); schedule();
+    },
+    message(_ws, message) {
+      if (stopped) return;
+      try {
+        const actual = args.match(message);
+        if (actual === null) return;
+        const expected = record.inputs[position];
+        if (expected !== actual) throw new Error(`expected ${expected ?? "<exhausted>"}, actual ${actual}`);
+        barriers[++position] = performance.now();
+        armDeadline();
+        schedule();
+      } catch (error) {
+        const failure = diagnostic(`matching failed: ${(error as Error).message}`);
+        fail(failure);
+        throw failure;
+      }
+    },
+    close(_ws, code, reason) {
+      if (stopped) return;
+      let error: Error | undefined;
+      if (position < record.inputs.length) error = missing();
+      else if (output < record.messages.length || (record.close?.initiator === "server" && !sentClose)) error = diagnostic("unexpected connection closure before playback completed");
+      // A peer acknowledging our close need not echo its reason (Node's native
+      // WebSocket omits it). Only match the reason for client-initiated closes.
+      else if (record.close && (code !== record.close.code || (record.close.initiator === "client" && reason !== record.close.reason))) error = diagnostic(`unexpected connection closure: expected code ${record.close.code}, actual ${code}${record.close.initiator === "client" ? `; expected reason ${JSON.stringify(record.close.reason)}, actual ${JSON.stringify(reason)}` : ""}`);
+      finish(error);
+    },
+  };
+  detach = lifetime.onEnd(event => {
+    if (event.kind === "closed" && socket) handlers.close!(socket, event.code, event.reason);
+    else session.cancel();
+  });
+  return { session, handlers: bindWebSocketLifetime(handlers, lifetime) };
+}
+
+/** Open upstream before accepting downstream, retaining only a bounded opening queue. */
+export async function recordWebSocket(args: {
+  url: string;
+  ip: string;
+  host: string;
+  headers: Record<string, string>;
+  protocols: string[];
+  request: CassetteRequest;
+  match: (message: ReplayWebSocketMessage) => string | null;
+  redact(value: string): string;
+  secrets: { ref: string; value: string }[];
+  label: string;
+  captured(record: CassetteWebSocket): void;
+  lifetime?: FakeWebSocketLifetime;
+  finished(session: WebSocketSession, error?: Error): void;
+}): Promise<{ handlers: FakeWebSocketHandlers; session: WebSocketSession }> {
+  const lifetime = args.lifetime ?? new FakeWebSocketLifetime();
+  if (lifetime.ended) throw new Error("WebSocket handshake aborted");
+  let detach = () => {};
+  const upstream = new WebSocket(args.url, args.protocols, {
+    headers: args.headers, maxPayload: MAX_BUFFER,
+    handshakeTimeout: 10_000,
+    lookup: ((_hostname: string, options: { all?: boolean }, callback: Function) => {
+      if (options.all) callback(null, [{ address: args.ip, family: 4 }]);
+      else callback(null, args.ip, 4);
+    }) as any,
+  });
+  const record: CassetteWebSocket = { request: args.request, inputs: [], messages: [] };
+  let socket: FakeWebSocket | undefined;
+  let anchor = performance.now();
+  let stopped = false;
+  let clientClosed = false;
+  let upstreamClosure: { code: number; reason: string } | undefined;
+  let queue: ReplayWebSocketMessage[] = [];
+  let queuedBytes = 0;
+  let openingTimer: ReturnType<typeof setTimeout> | undefined;
+  let opened = false;
+  let rejectOpen: (error: Error) => void = () => {};
+  const timing = () => ({ afterInput: record.inputs.length, delayMs: Math.max(0, performance.now() - anchor) });
+  const scrub = (value: string) => {
+    const result = args.redact(value);
+    for (const secret of args.secrets) if (secret.value && result.includes(secret.value)) throw new Error(`secret ${secret.ref} survived WebSocket redaction`);
+    return result;
+  };
+  const finish = (error?: Error) => {
+    if (stopped) return;
+    stopped = true;
+    clearTimeout(openingTimer);
+    detach();
+    queue = [];
+    upstream.terminate();
+    lifetime.end(error ? { kind: "failed", error } : { kind: "aborted" });
+    args.finished(session, error);
+  };
+  const fail = (error: unknown) => {
+    if (stopped) return;
+    const failure = new Error(`${args.label}: ${(error as Error).message}`);
+    rejectOpen(failure);
+    finish(failure);
+    socket?.close(1011, "WebSocket recording failed");
+  };
+  const session: WebSocketSession = {
+    cancel() { rejectOpen(new Error("WebSocket handshake aborted")); finish(); socket?.close(1001, "recording cleanup"); },
+  };
+  upstream.on("error", fail);
+  upstream.on("message", (data, binary) => {
+    if (stopped || clientClosed) return;
+    try {
+      const bytes = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data as ArrayBuffer);
+      const message = binary ? new Uint8Array(bytes) : bytes.toString();
+      // Redact bytes too: base64 encoding must not hide a brokered secret.
+      const redacted = binary ? redactBinary(bytes, args.redact, args.secrets) : scrub(bytes.toString());
+      record.messages.push({ ...timing(), type: binary ? "binary" : "text", data: redacted });
+      if (socket) socket.send(message);
+      else {
+        queuedBytes += bytes.length;
+        if (queue.length >= MAX_PENDING || queuedBytes > MAX_BUFFER) throw new Error("WebSocket opening buffer exceeded");
+        queue.push(message);
+      }
+    } catch (error) { fail(error); }
+  });
+  upstream.on("close", (code, reason) => {
+    if (stopped) return;
+    if (!opened) { fail(new Error("upstream closed before handshake completed")); return; }
+    try {
+      if (!clientClosed) {
+        upstreamClosure = { code, reason: reason.toString() };
+        record.close = { ...timing(), initiator: "server", code, reason: scrub(reason.toString()) };
+      }
+      if (socket) { closeSocket(socket, code, reason.toString()); finish(); }
+      // If the upstream closes before downstream open, open() flushes the queue.
+    } catch (error) { fail(error); }
+  });
+  const opening = new Promise<void>((resolve, reject) => {
+    rejectOpen = reject;
+    upstream.once("open", () => {
+      try {
+        opened = true;
+        anchor = performance.now();
+        if (upstream.protocol) record.protocol = scrub(upstream.protocol);
+        args.captured(record);
+        openingTimer = setTimeout(() => fail(new Error("downstream did not open")), 10_000);
+        resolve();
+      } catch (error) { fail(error); }
+    });
+  });
+  const handlers: FakeWebSocketHandlers = {
+    open(ws) {
+      socket = ws;
+      clearTimeout(openingTimer);
+      if (stopped) { ws.close(1011, "WebSocket recording failed"); return; }
+      try {
+        for (const message of queue) ws.send(message);
+        queue = []; queuedBytes = 0;
+        if (upstreamClosure) { closeSocket(ws, upstreamClosure.code, upstreamClosure.reason); finish(); }
+      } catch (error) { fail(error); }
+    },
+    message(_ws, message) {
+      if (stopped) return;
+      try {
+        const signature = args.match(typeof message === "string" ? message : Uint8Array.from(message));
+        if (signature !== null) { record.inputs.push(signature); anchor = performance.now(); }
+        const size = typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
+        if (size + upstream.bufferedAmount > MAX_BUFFER) throw new Error("WebSocket upstream buffer exceeded");
+        if (upstream.readyState !== WebSocket.OPEN) throw new Error("upstream is not open");
+        upstream.send(message);
+      } catch (error) { fail(error); throw error; }
+    },
+    close(_ws, code, reason) {
+      if (stopped || clientClosed) return;
+      try {
+        clientClosed = true;
+        record.close = { ...timing(), initiator: "client", code, reason: scrub(reason) };
+        closeSocket(upstream, code, reason);
+        openingTimer = setTimeout(() => finish(), 1_000);
+      } catch (error) { fail(error); }
+    },
+  };
+  detach = lifetime.onEnd(event => {
+    if (event.kind === "closed" && socket) handlers.close!(socket, event.code, event.reason);
+    else session.cancel();
+  });
+  await opening;
+  handlers.protocol = upstream.protocol || undefined;
+  return { session, handlers: bindWebSocketLifetime(handlers, lifetime) };
+}
+
+function redactBinary(bytes: Buffer, redact: (text: string) => string, secrets: { ref: string; value: string }[]): string {
+  // Preserve arbitrary bytes; textual patterns can only safely apply to valid UTF-8.
+  let output = bytes;
+  try {
+    const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    output = Buffer.from(redact(text));
+  } catch { /* Binary payload; fail closed for embedded credentials below. */ }
+  for (const { ref, value } of secrets) if (value && output.includes(Buffer.from(value))) throw new Error(`secret ${ref} survived binary WebSocket redaction`);
+  return output.toString("base64");
+}

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

@@ -163,9 +163,10 @@ describe("scripted behavior on replay fakes", () => {
         extends: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
         compilerOptions: {
           noEmit: true,
+          rootDir: fileURLToPath(new URL("../../../", import.meta.url)),
           typeRoots: [fileURLToPath(new URL("../../node_modules/@types", import.meta.url))],
         },
-        include: [fileURLToPath(import.meta.url)],
+        include: [fileURLToPath(import.meta.url), fileURLToPath(new URL("./replayFake-websocket.test.ts", import.meta.url))],
         exclude: [],
       }));
       const child = Bun.spawn([process.execPath, fileURLToPath(import.meta.resolve("typescript/bin/tsc")), "-p", config], {

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

@@ -44,6 +44,8 @@ test("recorded bodies and redaction survive; replay uses default order or an exp
     } }));
 
     const { replayFake } = await import(${moduleUrl("./replayFake.ts")});
+    const { setReplayEnvironmentMode } = await import(${moduleUrl("../replay-mode.ts")});
+    setReplayEnvironmentMode("interactive");
     const { setRecordSecrets } = await import(${moduleUrl("../record-secrets.ts")});
     setRecordSecrets({ API_KEY: "recording-secret" });
     const options = {
@@ -126,7 +128,8 @@ test("recorded bodies and redaction survive; replay uses default order or an exp
     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.
+    setReplayEnvironmentMode("test");
+    startRecording();
     try {
       assert.equal(await (await send("scripted")).text(), "scripted response");
       assert.equal(await (await send("delegated")).text(), "response");
@@ -137,6 +140,9 @@ test("recorded bodies and redaction survive; replay uses default order or an exp
     } finally {
       stopRecording();
     }
+    // Background work after the case must still fail closed.
+    assert.equal((await send("delegated")).status, 599);
+    assert.equal(upstreamHeaders.length, 4);
     });
   `;
   const dir = await mkdtemp(join(tmpdir(), "spectest-replay-record-"));

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

@@ -0,0 +1,110 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// A real TLS upstream and real ingress; only external DNS is replaced. Run in
+// a child so both the resolver mock and local CA stay isolated from other tests.
+test("record/replay through real WSS and ingress brokers credentials, retains subprotocol and client close", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "spectest-ws-record-"));
+  const module = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
+  try {
+    const key = join(dir, "key.pem"), cert = join(dir, "cert.pem");
+    execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", key, "-out", cert,
+      "-days", "1", "-subj", "/CN=voice.test", "-addext", "subjectAltName=DNS:voice.test"], { stdio: "ignore" });
+    const script = `
+      import { test, mock, expect } from "bun:test";
+      import { EventEmitter, once } from "node:events";
+      import { createServer } from "node:https";
+      import { readFileSync } from "node:fs";
+      import * as dnsPacket from ${JSON.stringify(import.meta.resolve("dns-packet"))};
+      import WS from ${JSON.stringify(import.meta.resolve("ws").replace(/wrapper\.mjs$/, "index.js"))};
+      test("round trip", async () => {
+        mock.module("node:dgram", () => ({ createSocket() {
+          const socket = new EventEmitter(); socket.close = () => {};
+          socket.send = (_query, _port, _host, done) => { done(); queueMicrotask(() => socket.emit("message", dnsPacket.encode({
+            type: "response", id: 1, answers: [{ type: "A", name: "voice.test", ttl: 60, data: "127.0.0.1" }],
+          }))); }; return socket;
+        } }));
+        const { replayFake } = await import(${module("./replayFake.ts")});
+        const { setReplayEnvironmentMode } = await import(${module("../replay-mode.ts")});
+        setReplayEnvironmentMode("interactive");
+        const { setRecordSecrets } = await import(${module("../record-secrets.ts")});
+        const { startIngressServer } = await import(${module("../harness/ingress-server.ts")});
+        const { dispatchFake } = await import(${module("../harness/fake-websocket.ts")});
+        const upstream = createServer({ key: readFileSync(${JSON.stringify(key)}), cert: readFileSync(${JSON.stringify(cert)}) });
+        const wss = new WS.WebSocketServer({ server: upstream, handleProtocols: () => "voice" });
+        upstream.listen(0, "127.0.0.1"); await once(upstream, "listening");
+        let connections = 0;
+        wss.on("connection", (socket, req) => {
+          connections++;
+          expect(req.headers.authorization).toBe("Bearer test-secret");
+          socket.send("greeting test-secret");
+          if (req.url === "/drop") setTimeout(() => socket.terminate(), 5);
+          socket.on("message", (data, binary) => socket.send(data, { binary }));
+        });
+        setRecordSecrets({ TOKEN: "test-secret" });
+        const options = { name: "voice", host: "voice.test:" + upstream.address().port,
+          inject: [{ headers: { authorization: "Bearer {{secret:TOKEN}}" } }],
+          key: request => ({ path: request.path, tenant: request.headers["x-tenant"] }),
+        };
+        const recorder = replayFake({ ...options, mode: "record" });
+        const state = await recorder.state();
+        const helpers = await recorder.helpers({ name: "voice", state, ctx: {} });
+        let active = recorder, activeState = state;
+        const ingress = await startIngressServer({ port: 0, hostname: "127.0.0.1", fetch: (req, server) => dispatchFake(req, server, active, activeState, {}) });
+        try {
+          async function conversation(expectedGreeting) {
+            const client = new WS("ws://127.0.0.1:" + ingress.port + "/live", ["other", "voice"], { headers: { authorization: "Bearer dummy", "x-tenant": "one" } });
+            const messages = []; client.on("message", (data, binary) => messages.push({ data: data.toString(), binary }));
+            await once(client, "open"); expect(client.protocol).toBe("voice");
+            client.send("text"); client.send(new Uint8Array([1, 2]));
+            for (let i = 0; messages.length < 3 && i < 200; i++) await Bun.sleep(5);
+            expect(messages).toEqual([{ data: expectedGreeting, binary: false }, { data: "text", binary: false }, { data: "\\x01\\x02", binary: true }]);
+            client.close(4002, "client-done"); await once(client, "close");
+            await Bun.sleep(20);
+          }
+          await conversation("greeting test-secret");
+          const cassette = JSON.parse(JSON.stringify(helpers.dump()));
+          expect(cassette.websockets).toHaveLength(1);
+          expect(cassette.websockets[0].close).toMatchObject({ initiator: "client", code: 4002, reason: "client-done" });
+          expect(cassette.websockets[0].inputs).toHaveLength(2);
+          expect(JSON.stringify(cassette)).not.toContain("test-secret");
+          expect(JSON.stringify(cassette)).not.toContain("Bearer dummy");
+          active = replayFake({ ...options, mode: "replay" }); activeState = await active.state();
+          const replay = await active.helpers({ name: "voice", state: activeState, ctx: {} });
+          replay.replay(cassette);
+          await conversation("greeting <REDACTED:TOKEN>"); expect(activeState.websocketErrors).toEqual([]);
+          expect(connections).toBe(1);
+          async function disconnect() {
+            const client = new WS("ws://127.0.0.1:" + ingress.port + "/drop", ["voice"], { headers: { "x-tenant": "one" } });
+            const closed = once(client, "close");
+            await once(client, "open");
+            expect((await closed)[0]).toBe(1006);
+            await Bun.sleep(20);
+          }
+          active = recorder; activeState = state;
+          await disconnect();
+          const abnormal = helpers.dump();
+          expect(abnormal.websockets[1].close).toMatchObject({ code: 1006, initiator: "server" });
+          active = replayFake({ ...options, mode: "replay" }); activeState = await active.state();
+          const abnormalReplay = await active.helpers({ name: "voice", state: activeState, ctx: {} });
+          abnormalReplay.replay(abnormal);
+          await disconnect(); expect(activeState.websocketErrors).toEqual([]);
+          expect(connections).toBe(2);
+        } finally {
+          ingress.stop(true);
+          for (const socket of wss.clients) socket.terminate(); wss.close(); upstream.close();
+        }
+      });
+    `;
+    const file = join(dir, "record.test.ts");
+    await writeFile(file, script);
+    const child = Bun.spawn([process.execPath, "test", file], {
+      env: { ...process.env, NODE_EXTRA_CA_CERTS: cert }, 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 }); }
+}, 15_000);