@specific.dev/spectest 0.115.1 → 0.116.1

package/dist/harness/sticky-consumer.js

@@ -3,6 +3,7 @@ import { execFile } from "node:child_process";
 import { mkdir, readFile, statfs, writeFile } from "node:fs/promises";
 import { STICKY_RUNTIME } from "./sticky-paths.js";
 import { openKubernetesCacheMaintenance } from "./sticky-kubernetes.js";
+import { recordStickyImageUse } from "./sticky-image-retention.js";
 export const STICKY_CAPABILITY = "sticky-disks-v1";
 export const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
 export { STICKY_RUNTIME } from "./sticky-paths.js";
@@ -35,15 +36,40 @@ export function validateStickyConfig(config) {
     if (config.path !== "/var/lib/spectest-sticky" || config.compatibility !== STICKY_COMPATIBILITY ||
         !Number.isSafeInteger(config.capacityBytes) || config.capacityBytes <= 0 ||
         !Number.isSafeInteger(config.headroomBytes) || config.headroomBytes < 16 * 1024 * 1024 ||
-        !Number.isSafeInteger(config.cacheTargetBytes) || config.cacheTargetBytes <= 0 ||
-        !Number.isSafeInteger(config.buildkitTargetBytes) || config.buildkitTargetBytes <= 0 ||
-        config.buildkitTargetBytes > config.cacheTargetBytes ||
-        config.cacheTargetBytes + config.headroomBytes >= config.capacityBytes) {
+        config.headroomBytes >= config.capacityBytes) {
         throw new Error("unsupported sticky consumer profile or budget");
     }
 }
+/** Explicit policy avoids BuildKit's default size caps (including its separate
+ * cache-mount/source cap). Use physical capacity as the nonbinding max: with
+ * only minFreeSpace, BuildKit 0.32.2 sets keepBytes == totalSize when healthy,
+ * and pruneOnce's strict '<' check can still evict a record on every GC pass.
+ * Actual filesystem capacity is smaller than the device due to metadata. */
+export function stickyBuildkitConfig(config) {
+    validateStickyConfig(config);
+    return `root = "${config.path}/buildkit"
+[grpc]
+  address = ["tcp://127.0.0.1:1234"]
+[worker.oci]
+  enabled = false
+[worker.containerd]
+  enabled = true
+  address = "/run/containerd/containerd.sock"
+  namespace = "moby"
+  snapshotter = "overlayfs"
+  gc = true
+[[worker.containerd.gcpolicy]]
+  all = true
+  maxUsedSpace = ${config.capacityBytes}
+  minFreeSpace = ${config.headroomBytes}
+`;
+}
 export async function initializeStickyConsumer(config) {
     validateStickyConfig(config);
+    // Do not persist obsolete caps supplied by an older controller. Maintenance
+    // also ignores them when restoring a snapshot written by an older SDK.
+    config = { path: config.path, capacityBytes: config.capacityBytes,
+        headroomBytes: config.headroomBytes, compatibility: config.compatibility };
     await exec("mountpoint", ["-q", config.path]);
     // The base must have stopped these before its RAM was captured. Refuse an
     // unexpected writer rather than racing it for the standard daemon sockets.
@@ -72,21 +98,7 @@ disabled_plugins = ["io.containerd.grpc.v1.cri"]
     dockerConfig.features = { "containerd-snapshotter": true };
     dockerConfig["storage-driver"] = "overlayfs";
     await writeFile(`${STICKY_RUNTIME}/docker.json`, JSON.stringify(dockerConfig));
-    await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, `root = "${config.path}/buildkit"
-[grpc]
-  address = ["tcp://127.0.0.1:1234"]
-[worker.oci]
-  enabled = false
-[worker.containerd]
-  enabled = true
-  address = "/run/containerd/containerd.sock"
-  namespace = "moby"
-  snapshotter = "overlayfs"
-  gc = true
-  reservedSpace = "1GB"
-  maxUsedSpace = ${config.buildkitTargetBytes}
-  minFreeSpace = ${config.headroomBytes}
-`);
+    await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, stickyBuildkitConfig(config));
     const start = async (unit, program, args) => {
         await exec("systemd-run", ["--quiet", "--unit", unit, "-p", "TimeoutStopSec=30",
             // Pinned BuildKit 0.32.2 returns 1 after its normal first-SIGTERM
@@ -109,22 +121,33 @@ disabled_plugins = ["io.containerd.grpc.v1.cri"]
  * Only called after runtime containers/volumes have been removed on the
  * isolated publication clone. Never removes files behind the daemons' backs.
  */
-export async function collectStickyCache(config, run = exec, usage = async () => {
+export async function collectStickyCache(config, retention, run = exec, usage = async () => {
     const fs = await statfs(config.path);
     return { freeBytes: fs.bavail * fs.bsize, totalBytes: fs.blocks * fs.bsize };
 }, kubernetes) {
     validateStickyConfig(config);
     const buildctl = ["--addr", "tcp://127.0.0.1:1234", "prune"];
     await run("buildctl", [...buildctl, "--keep-duration", "168h"], 120_000);
-    await run("docker", ["image", "prune", "-af", "--filter", "until=168h"], 120_000);
-    const withinTarget = (fs) => fs.freeBytes >= config.headroomBytes && fs.totalBytes - fs.freeBytes <= config.cacheTargetBytes;
+    // Docker's until filter and Created field refer to the publisher's build
+    // date, not our use. Never prune a just-used image merely because it is old.
+    const protectedImage = (id) => retention.protectedImages.has(id) || kubernetes?.protectedImages.has(id);
+    const images = [...retention.images].sort((a, b) => a.lastUsed - b.lastUsed || a.id.localeCompare(b.id));
+    const expired = new Set();
+    for (const image of images) {
+        if (protectedImage(image.id) || image.lastUsed >= retention.observedAt - 7 * 24 * 60 * 60 * 1000)
+            continue;
+        await run("docker", ["image", "rm", "-f", image.id], 120_000);
+        expired.add(image.id);
+    }
+    const withinTarget = (fs) => fs.freeBytes >= config.headroomBytes;
     let fs = await usage();
-    // Always enforce the independent BuildKit target. Its accounting alone
-    // cannot bound shared images/content, so also request real filesystem space.
+    if (withinTarget(fs))
+        return;
+    // All consumers share this filesystem. Reclaim only the missing headroom;
+    // a per-consumer cap evicts useful cache even when the disk is mostly empty.
     const pruneBuildkit = async () => {
-        await run("buildctl", [...buildctl, "--all", "--keep-storage",
-            String(Math.floor(config.buildkitTargetBytes / 1e6)), "--free-storage",
-            String(Math.ceil(Math.max(config.headroomBytes, fs.totalBytes - config.cacheTargetBytes) / 1e6))], 120_000);
+        await run("buildctl", [...buildctl, "--all", "--free-storage",
+            String(Math.ceil(config.headroomBytes / 1e6))], 120_000);
         fs = await usage();
     };
     await pruneBuildkit();
@@ -135,16 +158,15 @@ export async function collectStickyCache(config, run = exec, usage = async () =>
         if (withinTarget(fs))
             return;
     }
-    // Pressure can be entirely in recent Docker images. Drop oldest images
-    // first, even within the age window, until the whole filesystem fits.
-    const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"])).split(/\s+/).filter(Boolean))];
-    const images = ids.length
-        ? JSON.parse(await run("docker", ["image", "inspect", ...ids])) : [];
-    images.sort((a, b) => a.Created.localeCompare(b.Created) || a.Id.localeCompare(b.Id));
+    // Under pressure, evict least recently used images, including within the
+    // age window, but preserve this environment's images for the next build.
     for (const image of images) {
-        if (kubernetes?.protectedImages.has(image.Id))
+        if (expired.has(image.id) || protectedImage(image.id))
             continue;
-        await run("docker", ["image", "rm", "-f", image.Id], 120_000);
+        await run("docker", ["image", "rm", "-f", image.id], 120_000);
+        fs = await usage();
+        if (withinTarget(fs))
+            return;
         await pruneBuildkit();
         if (withinTarget(fs))
             return;
@@ -153,14 +175,15 @@ export async function collectStickyCache(config, run = exec, usage = async () =>
     for (let pass = 0; pass < 3 && !withinTarget(fs); pass++)
         await pruneBuildkit();
     if (!withinTarget(fs))
-        throw new Error("sticky cache cannot meet filesystem retention target and write headroom");
+        throw new Error("sticky cache cannot reclaim required write headroom");
 }
 /** Only on an isolated maintenance clone; never on the live ready environment. */
 export async function prepareStickyConsumer(artifact = false) {
     const config = JSON.parse(await readFile(`${STICKY_RUNTIME}/consumer.json`, "utf8"));
     validateStickyConfig(config);
     if (!artifact) {
-        const containers = (await exec("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+        const retention = await recordStickyImageUse(config.path, exec);
+        const { containers } = retention;
         if (containers.length)
             await exec("docker", ["rm", "-f", ...containers]);
         const volumes = (await exec("docker", ["volume", "ls", "-q"])).split(/\s+/).filter(Boolean);
@@ -168,7 +191,7 @@ export async function prepareStickyConsumer(artifact = false) {
             await exec("docker", ["volume", "rm", ...volumes]);
         const kubernetes = await openKubernetesCacheMaintenance(exec);
         try {
-            await collectStickyCache(config, exec, undefined, kubernetes);
+            await collectStickyCache(config, retention, exec, undefined, kubernetes);
         }
         finally {
             await kubernetes.close();

package/dist/harness/sticky-image-retention.d.ts

@@ -0,0 +1,15 @@
+import type { CacheCommand } from "./sticky-kubernetes.js";
+export interface StickyImageRetention {
+    images: {
+        id: string;
+        lastUsed: number;
+    }[];
+    protectedImages: Set<string>;
+    containers: string[];
+    observedAt: number;
+}
+/** Call before removing containers from the isolated publication clone.
+ * New/legacy images get a first observation; inherited unused images retain
+ * their previous timestamp. Rewriting from the inventory drops stale IDs.
+ */
+export declare function recordStickyImageUse(root: string, run: CacheCommand, now?: number): Promise<StickyImageRetention>;

package/dist/harness/sticky-image-retention.js

@@ -0,0 +1,32 @@
+/** Image use belongs to the cache lineage, not the publisher's image clock. */
+import { randomUUID } from "node:crypto";
+import { readFile, rename, writeFile } from "node:fs/promises";
+/** Call before removing containers from the isolated publication clone.
+ * New/legacy images get a first observation; inherited unused images retain
+ * their previous timestamp. Rewriting from the inventory drops stale IDs.
+ */
+export async function recordStickyImageUse(root, run, now = Date.now()) {
+    const path = `${root}/.spectest-image-use.json`;
+    const saved = await readFile(path, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    const previous = saved === undefined ? { schema: 1, images: {} } : JSON.parse(saved);
+    if (previous.schema !== 1 || !previous.images || typeof previous.images !== "object" ||
+        Array.isArray(previous.images) || Object.values(previous.images).some(value => typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) {
+        throw new Error("invalid sticky image-use ledger");
+    }
+    const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"]))
+            .split(/\s+/).filter(Boolean))];
+    const containers = (await run("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+    const protectedImages = new Set(containers.length
+        ? (await run("docker", ["container", "inspect", "--format", "{{.Image}}", ...containers]))
+            .split(/\s+/).filter(Boolean) : []);
+    const images = ids.map(id => ({ id, lastUsed: protectedImages.has(id) ? now : previous.images[id] ?? now }));
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify({ schema: 1,
+        images: Object.fromEntries(images.map(({ id, lastUsed }) => [id, lastUsed])) }));
+    await rename(temporary, path);
+    return { images, protectedImages, containers, observedAt: now };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { InjectRule, SignConfig } from "./fake-upstream.js";
+export type { InjectRule, InjectMatch, StringMatch, SignConfig, AwsSigV4Sign } from "./fake-upstream.js";
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
 import type { Android, AndroidApp } from "./android.js";
@@ -1456,6 +1458,14 @@ export interface ExecOpts {
 export interface TestSuite<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     tests: TestCase<unknown, S, F>[];
 }
+/** Forward the entire fake to real HTTPS/WSS upstreams in interactive environments.
+ * Tests and shared baselines always use the scripted handlers. No traffic is recorded. */
+export interface FakeLiveOptions {
+    /** Same header injection rules as replayFake, applied to HTTP and WebSocket handshakes. */
+    inject?: InjectRule[];
+    /** Re-sign HTTP requests using brokered AWS credentials. Not supported for WebSockets. */
+    sign?: SignConfig;
+}
 /**
  * A fake server hosted in the harness. Use this to stand in for
  * external HTTP APIs (auth providers, payment gateways, …) that you can't
@@ -1489,6 +1499,10 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * other fakes.
      */
     hostnames: readonly string[];
+    /** Opt in to forwarding all HTTP/WebSocket traffic to the declared real hosts
+     * over HTTPS/WSS (port 443) in interactive environments. Errors never fall back
+     * to scripted handlers. Omit to keep the fake scripted in every environment. */
+    live?: FakeLiveOptions;
     /** TCP port the fake listens on. Default `80`. */
     port?: number;
     /** Preserve handler/interceptor CORS policy by default. "permissive"
@@ -1546,7 +1560,7 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
         ctx: FakeContext;
     }) => H | Promise<H>;
     /**
-     * Internal. Platform secret references this fake needs at *record* time
+     * Internal. Platform secret references this fake needs for upstream access
      * (set by {@link replayFake}). The daemon reports the union of these to
      * the control plane, which resolves each via its `SecretResolver` and
      * supplies them for the environment lifetime, including snapshots. Values

package/dist/index.js

@@ -407,6 +407,9 @@ export function defineFake(opts) {
             throw new Error(`defineFake(${opts.name}): hostname ${JSON.stringify(h)} ends in reserved ".internal" TLD`);
         }
     }
+    if (opts.live !== undefined && (!opts.live || typeof opts.live !== "object" || Array.isArray(opts.live))) {
+        throw new Error(`defineFake(${opts.name}): \`live\` must be an options object`);
+    }
     validateCorsMode(opts.cors);
     if (typeof opts.handler !== "function") {
         throw new Error(`defineFake(${opts.name}): \`handler\` is required`);

package/dist/record-secrets.d.ts

@@ -1,4 +1,4 @@
 /** Replace the complete environment secret set, including removing stale refs. */
 export declare function setRecordSecrets(secrets: Record<string, string>): void;
-/** Resolve a declared project secret for an outbound recording request. */
+/** Resolve a declared project secret for an outbound live or recording request. */
 export declare function getRecordSecret(ref: string): string | undefined;

package/dist/record-secrets.js

@@ -1,9 +1,9 @@
-// Environment-lifetime credentials for record-mode fakes. The control plane
+// Environment-lifetime credentials for live and record-mode fakes. The control plane
 // resolves declared references from the owning project's Secrets store before
 // service startup and refreshes them on warm starts and interactive forks.
 // They persist across evals, background requests and memory snapshots, just
 // like other environment state. Test forks inherit their parent's credentials;
-// replay mode still uses cassettes and never forwards upstream.
+// test mode still uses scripted handlers or cassettes and never forwards upstream.
 // Values stay out of project files, config hashes and recorded cassettes.
 const SECRETS = new Map();
 /** Replace the complete environment secret set, including removing stale refs. */
@@ -12,7 +12,7 @@ export function setRecordSecrets(secrets) {
     for (const [ref, value] of Object.entries(secrets))
         SECRETS.set(ref, value);
 }
-/** Resolve a declared project secret for an outbound recording request. */
+/** Resolve a declared project secret for an outbound live or recording request. */
 export function getRecordSecret(ref) {
     return SECRETS.get(ref);
 }

package/dist/replay-mode.d.ts

@@ -1,2 +1,4 @@
 export declare function setReplayEnvironmentMode(value: "test" | "interactive"): void;
 export declare function resolveReplayMode(requested?: "auto" | "record" | "replay"): "record" | "replay";
+/** Shared gate for live and replay fakes. Credentials never enable upstream access. */
+export declare function isInteractiveEnvironment(): boolean;

package/dist/replay-mode.js

@@ -1,6 +1,6 @@
 // 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,
+// per-case event recorder. Shared/warm baselines must never forward upstream.
+// The control plane enables upstream access only on an interactive environment,
 // after capturing/restoring the shared baseline and before interactive setup.
 let mode = "test";
 export function setReplayEnvironmentMode(value) {
@@ -10,3 +10,7 @@ export function resolveReplayMode(requested = "auto") {
     // Even an explicit record option cannot send test traffic to real providers.
     return mode === "test" || requested === "replay" ? "replay" : "record";
 }
+/** Shared gate for live and replay fakes. Credentials never enable upstream access. */
+export function isInteractiveEnvironment() {
+    return mode === "interactive";
+}

package/package.json

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

package/src/components/replay-websocket.ts

@@ -1,16 +1,11 @@
 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;
+import { MAX_BUFFER, closeSocket, forwardWebSocket, type WebSocketSession } from "../fake-upstream-websocket.js";
+export type { WebSocketSession } from "../fake-upstream-websocket.js";
 const MAX_PENDING = 1024;
 export type ReplayWebSocketMessage = string | Uint8Array;
 export type WebSocketKey<S = unknown> =
@@ -181,17 +176,6 @@ export function validateWebSocketRecording(record: CassetteWebSocket): void {
 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: WebSocketMatcher;
@@ -352,24 +336,12 @@ export async function recordWebSocket(args: {
   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: [],
     ...(args.match.candidates ? { inputMode: "anchors" as const, inputOccurrences: [] } : {}),
   };
   const occurrences = new Map<string, number>();
   let candidate: { key: string; count: number; at: number; index: number } | undefined;
   let candidateIndex = 0, selectedIndex = 0;
-  let socket: FakeWebSocket | undefined;
   let anchor = performance.now();
   const selectCandidate = () => {
     if (!candidate || candidate.index === selectedIndex) return;
@@ -378,131 +350,39 @@ export async function recordWebSocket(args: {
     anchor = candidate.at;
     selectedIndex = candidate.index;
   };
-  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());
-      // Apply the same redacted output reducer that replay will see.
-      if (args.match.output?.(binary ? new Uint8Array(Buffer.from(redacted, "base64")) : redacted)) selectCandidate();
-      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) {
-        selectCandidate();
-        upstreamClosure = { code, reason: reason.toString() };
-        record.close = { ...timing(), initiator: "server", code, reason: scrub(reason.toString()) };
+  return forwardWebSocket({ ...args, observe: {
+    open(protocol) {
+      anchor = performance.now();
+      if (protocol) record.protocol = scrub(protocol);
+      args.captured(record);
+    },
+    input(message) {
+      const input = typeof message === "string" ? message : Uint8Array.from(message);
+      if (args.match.candidates) {
+        const at = performance.now();
+        for (const key of args.match.candidates(input)) candidate = { key, count: occurrence(occurrences, key), at, index: ++candidateIndex };
+      } else {
+        const signature = args.match(input);
+        if (signature !== null) { record.inputs.push(signature); anchor = performance.now(); }
       }
-      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 input = typeof message === "string" ? message : Uint8Array.from(message);
-        if (args.match.candidates) {
-          const at = performance.now();
-          for (const key of args.match.candidates(input)) candidate = { key, count: occurrence(occurrences, key), at, index: ++candidateIndex };
-        } else {
-          const signature = args.match(input);
-          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; }
+    output(message) {
+      const binary = typeof message !== "string";
+      const redacted = binary ? redactBinary(Buffer.from(message), args.redact, args.secrets) : scrub(message);
+      if (args.match.output?.(binary ? new Uint8Array(Buffer.from(redacted, "base64")) : redacted)) selectCandidate();
+      record.messages.push({ ...timing(), type: binary ? "binary" : "text", data: redacted });
     },
-    close(_ws, code, reason) {
-      if (stopped || clientClosed) return;
-      try {
-        clientClosed = true;
-        selectCandidate();
-        record.close = { ...timing(), initiator: "client", code, reason: scrub(reason) };
-        closeSocket(upstream, code, reason);
-        openingTimer = setTimeout(() => finish(), 1_000);
-      } catch (error) { fail(error); }
+    close(code, reason, initiator) {
+      selectCandidate();
+      record.close = { ...timing(), initiator, code, reason: scrub(reason) };
     },
-  };
-  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 {