@specific.dev/spectest 0.101.0 → 0.103.0

package/README.md

@@ -20,6 +20,52 @@ Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 Use a local service definition or `serviceGroup()` wrapper; the repository’s
 `examples/google-pubsub` demonstrates this using public SDK APIs.
 
+
+## Microphone fixtures and WebSocket fakes (0.103.0)
+
+Supply a 16-bit PCM mono/stereo WAV when creating a browser session:
+
+```ts
+const browser = await ctx.browser({
+  microphone: { path: "spectest/tests/fixtures/speech.wav" },
+});
+```
+
+The microphone uses Chromium's native capture pipeline. It plays once and then
+supplies silence; add `loop: true` to repeat. Paths are relative to the repository
+root. Set the fixture on the first call for that browser session; reattaching
+preserves its source. Fixture sessions use a dedicated Chromium process to keep
+named browsers' audio isolated.
+
+A fake can serve HTTP and WebSockets on the same hostname, sharing state and
+helpers:
+
+```ts
+const speech = defineFake({
+  name: "speech",
+  hostnames: ["speech.example.com"],
+  state: () => ({ messages: [] as string[] }),
+  handler: () => Response.json({ ready: true }),
+  websocket(req, state) {
+    if (new URL(req.url).pathname !== "/realtime") {
+      return new Response("Not found", { status: 404 });
+    }
+    return {
+      message(socket, message) {
+        if (typeof message === "string") state.messages.push(message);
+        socket.send(message);
+      },
+    };
+  },
+  helpers: ({ state }) => ({ messages: () => [...state.messages] }),
+});
+```
+
+The handshake returns a rejection `Response` or callbacks (`open`, `message`,
+`close`), with an optional selected `protocol`. Callbacks may be async and run
+in order per connection. WS and trusted WSS support text/binary messages;
+observe traffic through the fake's helpers.
+
 ## HTTP assertions
 
 `ctx.fetch()` returns a wrapped response. Status fields, header lookups, and

package/dist/browser.d.ts

@@ -1,3 +1,5 @@
+import { type MicrophoneFixture } from "./harness/microphone-fixture.js";
+export type { MicrophoneFixture } from "./harness/microphone-fixture.js";
 import type { DesktopChrome } from "./desktop.js";
 import type { Wrapped } from "./inspect.js";
 import type { UrlPattern } from "./url-match.js";
@@ -20,6 +22,10 @@ export interface BrowserOptions {
     frame?: "browser" | "mobile";
     /** Initial URL to navigate to before the constructor returns. */
     url?: string;
+    /** Feed a WAV fixture through Chromium's native microphone capture.
+     * Set on the session's first creation; inherited sessions keep their source.
+     * Fixture sessions use a dedicated Chromium process for audio isolation. */
+    microphone?: MicrophoneFixture;
     /**
      * Script installed (before the session's first navigation) to run in every
      * document loaded from now on, BEFORE the document's own scripts — the

package/dist/browser.js

@@ -33,6 +33,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
 import { rawFetch } from "./harness/raw-fetch.js";
+import { prepareMicrophoneFixture } from "./harness/microphone-fixture.js";
 import { DESKTOP_INPUT_SYNC_SCRIPT } from "./desktop-recorder.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
@@ -74,8 +75,8 @@ function base64ByteLength(b64) {
 // What the app gets is Chromium's own synthetic devices: the microphone is a
 // generated beep pattern (a live, real MediaStreamTrack — MediaRecorder,
 // WebRTC and AudioContext analysis all work on it), the camera a rolling
-// test pattern at 640x480. There is deliberately NO way to feed a recording
-// in; this is device availability, not audio fixtures.
+// test pattern at 640x480. A microphone fixture adds Chromium's file-capture
+// flag in a dedicated process; getUserMedia and track behavior stay native.
 //
 // --use-fake-device-for-media-stream: the synthetic camera + microphone.
 //   Also what makes `enumerateDevices()` return anything at all.
@@ -106,14 +107,16 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // ────────────────────────────────────────────────────────────────────────
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
-// One Chromium per daemon, launched lazily on first view creation and kept
-// for the daemon's lifetime. It rides snapshots: the process, playwright's
+// Default sessions share one Chromium per daemon, launched lazily and kept
+// for the daemon's lifetime. Fixture sessions own a process because the audio
+// source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
 // and resume in each fork (like dockerd and the daemon itself). Profile
 // state — cookies, localStorage — is per-Chromium, and the in-VM CA trust
 // comes from the HOME-scoped NSS user DB, so neither cares that playwright
 // runs a temp --user-data-dir.
 let PW_BROWSER = null;
+const VIEW_CLEANUPS = new WeakMap();
 // Every view gets its OWN context, desktop included. A context is the cookie
 // jar + storage, so one-context-per-view is what makes `close()` mean what
 // the docs promise: the browsing session is destroyed and the next
@@ -157,18 +160,56 @@ function deviceContextOptions(d) {
 }
 /** Create the context one view lives in — device emulation when the view is
  *  phone-emulated, a plain viewport otherwise. */
-async function newViewContext(width, height, device) {
-    const browser = await ensurePlaywrightBrowser();
-    const context = await browser.newContext(device
-        ? deviceContextOptions(device)
-        : {
-            viewport: { width, height },
-            // Reduced-motion for replay fidelity — see deviceContextOptions.
-            reducedMotion: "reduce",
-        });
-    context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
-    context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
-    return context;
+async function newViewContext(width, height, device, microphone) {
+    const fixture = microphone === undefined ? undefined : await prepareMicrophoneFixture(microphone);
+    let browser;
+    try {
+        browser = fixture ? await chromium.launch({
+            executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
+        }) : await ensurePlaywrightBrowser();
+        const context = await browser.newContext(device
+            ? deviceContextOptions(device)
+            : {
+                viewport: { width, height },
+                // Reduced-motion for replay fidelity — see deviceContextOptions.
+                reducedMotion: "reduce",
+            });
+        context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
+        context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+        if (fixture) {
+            const owned = browser;
+            VIEW_CLEANUPS.set(context, async () => {
+                try {
+                    await owned.close();
+                }
+                finally {
+                    await fixture.cleanup();
+                }
+            });
+        }
+        return context;
+    }
+    catch (err) {
+        if (fixture) {
+            try {
+                await browser?.close();
+            }
+            finally {
+                await fixture.cleanup();
+            }
+        }
+        throw err;
+    }
+}
+async function closeViewContext(context) {
+    try {
+        await context.close();
+    }
+    finally {
+        const cleanup = VIEW_CLEANUPS.get(context);
+        VIEW_CLEANUPS.delete(context);
+        await cleanup?.();
+    }
 }
 /**
  * Make a user script evaluable by the page: Bun's `view.evaluate` accepts a
@@ -872,7 +913,7 @@ export async function openMobileBackend(opts = {}) {
     // Mobile views are never pooled — the pool holds only default-desktop
     // views (in the shared desktop context), and a mobile view needs its own
     // emulated context anyway.
-    const pooled = !device && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    const pooled = !device && opts.microphone === undefined && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
     let holder;
     if (pooled) {
         holder = {
@@ -889,7 +930,7 @@ export async function openMobileBackend(opts = {}) {
         };
     }
     else {
-        holder = await newHolder(wantW, wantH, device);
+        holder = await newHolder(wantW, wantH, device, opts.microphone);
     }
     const { backend } = buildBackend(holder, opts.recorder ?? null, {
         persistent: false,
@@ -897,12 +938,17 @@ export async function openMobileBackend(opts = {}) {
     // We deliberately don't forward `opts.url` to the constructor — going
     // through our own `navigate()` keeps the recorder log uniform (one
     // event per navigation, with timing) and drains rrweb after the load.
-    if (opts.initScript !== undefined)
-        await installInitScript(holder, opts.initScript);
-    if (opts.url !== undefined) {
-        await backend.goto(opts.url);
+    try {
+        if (opts.initScript !== undefined)
+            await installInitScript(holder, opts.initScript);
+        if (opts.url !== undefined)
+            await backend.goto(opts.url);
+        return backend;
+    }
+    catch (err) {
+        await backend.close();
+        throw err;
     }
-    return backend;
 }
 // ────────────────────────────────────────────────────────────────────────
 // Persistent sessions (the default behind ctx.browser / ctx.mobile)
@@ -946,9 +992,16 @@ function checkSessionCap(kind, live, name) {
         `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
         `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`);
 }
-async function newHolder(width, height, device) {
-    const context = await newViewContext(width, height, device);
-    const spawned = await spawnPage(context);
+async function newHolder(width, height, device, microphone) {
+    const context = await newViewContext(width, height, device, microphone);
+    let spawned;
+    try {
+        spawned = await spawnPage(context);
+    }
+    catch (err) {
+        await closeViewContext(context);
+        throw err;
+    }
     const holder = {
         context,
         page: spawned.page,
@@ -1020,7 +1073,7 @@ export async function acquirePersistentBrowser(name = "", opts = {}) {
     }
     else {
         checkSessionCap("browser", SHARED_BROWSERS.size, name);
-        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device);
+        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device, opts.microphone);
         SHARED_BROWSERS.set(name, holder);
     }
     const view = holder;
@@ -1617,7 +1670,7 @@ function buildBackend(holder, recorder, buildOpts) {
             // only the page would leave the next session signed in as this one.
             try {
                 if (buildOpts.ownsContext !== false)
-                    await holder.context.close();
+                    await closeViewContext(holder.context);
             }
             catch {
                 /* context already gone (browser died) */

package/dist/daemon.js

@@ -41,6 +41,7 @@ import { isDesktopApp } from "./desktop.js";
 // each easy to restate subtly differently.
 import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { startServices } from "./harness/service-graph.js";
+import { dispatchFake } from "./harness/fake-websocket.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
@@ -57,9 +58,10 @@ import { bindInstrumentationScope, createInstrumentationScope, runInstrumented,
 import { encodeRegistry } from "./harness/names-registry.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, withIngressCors, upstreamRequestHeaders, } from "./harness/http-proxy.js";
-import { WS_BRIDGE_HANDLERS, openUpstreamWebSocket, parseSubprotocols, upstreamHandshakeHeaders, } from "./harness/ws-bridge.js";
+import { openUpstreamWebSocket, parseSubprotocols, upstreamHandshakeHeaders, } from "./harness/ws-bridge.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectCertName, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
+import { startIngressServer } from "./harness/ingress-server.js";
 import { startHttp2Proxy } from "./harness/http2-proxy.js";
 import { startTlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
@@ -1495,11 +1497,10 @@ let LOWERED = {
     aliasesByService: {},
     wildcards: [],
 };
-/** Running HTTP servers per port (Bun.Server). Rebuilt on /load. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+/** Running HTTP servers per port. Rebuilt on /load. */
 const INGRESS_HTTP_SERVERS = new Map();
+const INGRESS_HTTP_STARTING = new Map();
 /** Running HTTPS servers per port (currently always {INGRESS_HTTPS_PORT}). */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INGRESS_HTTPS_SERVERS = new Map();
 /**
  * The :443 TLS terminator, once per harness process.
@@ -1564,6 +1565,7 @@ function stopIngressServers() {
         }
     }
     INGRESS_HTTP_SERVERS.clear();
+    INGRESS_HTTP_STARTING.clear();
     for (const [port, srv] of INGRESS_HTTPS_SERVERS) {
         try {
             srv.stop?.(true);
@@ -1691,7 +1693,7 @@ async function startIngress() {
         // eslint-disable-next-line no-console
         console.warn(`[ingress] root CA missing at ${CA_PATH}; skipping HTTPS bind (fakes/proxies will be HTTP-only)`);
     }
-    const Bun = requireBun();
+    requireBun();
     // Resolve every ingress hostname to its handler into the live per-port
     // route tables (module scope, so runtime `tls` can extend them later).
     // Fakes run an in-daemon handler on their declared port; proxies
@@ -1732,13 +1734,13 @@ async function startIngress() {
     for (const [port, byHost] of INGRESS.routesByPort) {
         if (port === INGRESS_HTTPS_PORT)
             continue;
-        INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, `port ${port}`));
+        await ensureHttpIngress(port, byHost);
         // eslint-disable-next-line no-console
         console.log(`[ingress] http :${port} for ${[...byHost.keys()].join(", ")}`);
     }
     // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
     if (INGRESS.certByHost.size > 0)
-        await ensureHttpsIngress(Bun);
+        await ensureHttpsIngress();
     // Seed the resolver's names registry: ingress hostnames (fakes, TLS
     // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
     // wildcards. Service-targeted wildcards wait for the post-container pass
@@ -1750,17 +1752,17 @@ function requireBun() {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const Bun = globalThis.Bun;
     if (!Bun?.serve) {
-        throw new Error("ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)");
+        throw new Error("ingress requires Bun; the daemon must run under Bun (it does in-VM)");
     }
     return Bun;
 }
 /**
  * Bring :443 up, once.
  *
- * Two pieces: a plaintext `Bun.serve` on an ephemeral loopback port that
+ * Two pieces: a plaintext HTTP server on an ephemeral loopback port that
  * carries the HTTPS route table (and therefore all the routing, fake
- * dispatch, interception, reverse-proxying and `server.upgrade()`
- * WebSocket bridging that :80 already gets, unchanged), and the TLS
+ * dispatch, interception, reverse-proxying and WebSocket
+ * bridging that :80 already gets, unchanged), and the TLS
  * terminator in front of it on :443.
  *
  * **This is idempotent, and that is the feature.** Adding a certificate
@@ -1781,27 +1783,25 @@ function requireBun() {
  * container can reach (containers arrive at the bridge gateway), so the
  * only way in is through the terminator.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function ensureHttpsIngress(Bun) {
+async function ensureHttpsIngress() {
     if (INGRESS_HTTPS_SERVERS.has(INGRESS_HTTPS_PORT))
         return;
     if (!HTTPS_INGRESS_STARTING) {
         // Cleared on both outcomes: once bound, the check above short-circuits
         // every later caller, and a failed bind must be retryable rather than
         // remembered as a rejection for the life of the project.
-        HTTPS_INGRESS_STARTING = startHttpsIngress(Bun).finally(() => {
+        HTTPS_INGRESS_STARTING = startHttpsIngress().finally(() => {
             HTTPS_INGRESS_STARTING = undefined;
         });
     }
     return HTTPS_INGRESS_STARTING;
 }
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function startHttpsIngress(Bun) {
+async function startHttpsIngress() {
     const routes = routesFor(INGRESS, INGRESS_HTTPS_PORT);
     // `proto` is passed rather than inferred: this listener speaks plain
     // HTTP, but everything reaching it arrived over TLS, so X-Forwarded-Proto
     // must say https.
-    const plain = bindIngressServer(Bun, 0, routes, `https :${INGRESS_HTTPS_PORT}`, {
+    const plain = await bindIngressServer(0, routes, `https :${INGRESS_HTTPS_PORT}`, {
         proto: "https",
         hostname: "127.0.0.1",
     });
@@ -1884,7 +1884,7 @@ async function bindRuntimeTls(hostname, service, port, http2, cors) {
     if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
         throw new Error(`runtime tls for ${JSON.stringify(host)} requires the in-VM root CA at ${CA_PATH}`);
     }
-    const Bun = requireBun();
+    requireBun();
     const route = { kind: "proxy", service, port, http2, cors };
     // Decide the cost before mutating anything: an already-covered hostname
     // (an exact duplicate, or one under a boot wildcard) needs only a route.
@@ -1899,9 +1899,7 @@ async function bindRuntimeTls(hostname, service, port, http2, cors) {
     // the route is only reachable once the hostname resolves, which is the
     // registry write at the end.
     bindRoute(INGRESS, host, route);
-    if (!INGRESS_HTTP_SERVERS.has(INGRESS_HTTP_PORT)) {
-        INGRESS_HTTP_SERVERS.set(INGRESS_HTTP_PORT, bindIngressServer(Bun, INGRESS_HTTP_PORT, routesFor(INGRESS, INGRESS_HTTP_PORT), `port ${INGRESS_HTTP_PORT}`));
-    }
+    await ensureHttpIngress(INGRESS_HTTP_PORT, routesFor(INGRESS, INGRESS_HTTP_PORT));
     if (plan.needsCert) {
         // The terminator reads this table on every handshake, so the leaf is
         // live the moment it lands — no listener is touched, and no connection
@@ -1909,7 +1907,7 @@ async function bindRuntimeTls(hostname, service, port, http2, cors) {
         INGRESS.certByHost.set(host, await generateHostCert(host, [host]));
     }
     if (plan.needsHttpsListener)
-        await ensureHttpsIngress(Bun);
+        await ensureHttpsIngress();
     // Resolve the hostname to the daemon gateway (where :443/:80 listen).
     // A wildcard can only live in the resolver's suffix table.
     const gw = await bridgeGatewayIp();
@@ -1946,57 +1944,27 @@ async function unbindRuntimeTls(hostname) {
         await writeRegistry();
     }
 }
-/**
- * Spin up one Bun.serve listener bound to (port, optional TLS) that
- * dispatches every request to the matching Route by Host header.
- *
- * Shared by the HTTP and HTTPS branches. Also carries the `websocket`
- * handler set so reverse-proxy targets can transparently bridge WS
- * upgrades through to their upstream service.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function bindIngressServer(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-Bun, port, byHost, listenerLabel, 
-// Every ingress listener speaks plain HTTP now — the one behind :443
-// sits under the TLS terminator. So the scheme a client actually used
-// can no longer be inferred from the socket and is declared instead; it
-// stamps X-Forwarded-Proto, which upstreams that build absolute URLs or
-// redirect depend on.
-serve = { proto: "http" }) {
-    const proto = serve.proto;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const opts = {
+/** Concurrent runtime routes must share the asynchronous first bind. */
+async function ensureHttpIngress(port, byHost) {
+    if (INGRESS_HTTP_SERVERS.has(port))
+        return;
+    let starting = INGRESS_HTTP_STARTING.get(port);
+    if (!starting) {
+        starting = bindIngressServer(port, byHost, `port ${port}`).then(server => {
+            INGRESS_HTTP_SERVERS.set(port, server);
+        }).finally(() => INGRESS_HTTP_STARTING.delete(port));
+        INGRESS_HTTP_STARTING.set(port, starting);
+    }
+    await starting;
+}
+/** Bind the shared HTTP/1 ingress handler, including the listener behind TLS. */
+async function bindIngressServer(port, byHost, listenerLabel, serve = { proto: "http" }) {
+    return startIngressServer({
         port,
         hostname: serve.hostname ?? "0.0.0.0",
-        // SO_REUSEPORT on every ingress listener. It was introduced so a
-        // replacement :443 could overlap the original during a certificate
-        // swap; the terminator removed that swap, and this stays for the
-        // remaining case — the `/load` teardown force-closes and rebinds, and
-        // a socket the kernel has not finished releasing would otherwise fail
-        // the next bind with "Is port 443 in use?". Note the flip side, which
-        // {@link stopIngressServers} depends on: a half-alive listener shares
-        // the port silently instead of colliding loudly.
         reusePort: true,
-        // OCI layer uploads can exceed Bun's default 128 MiB request limit.
-        // Large proxy bodies stream through; this limit does not allocate a buffer.
-        maxRequestBodySize: 1024 ** 4,
-        // Bun.serve defaults to a 10s idleTimeout, which kills any proxied
-        // request whose upstream takes >10s to produce bytes — under parallel
-        // test load that surfaced as "fetch failed"/"other side closed" on
-        // deploy-archive uploads and ERR_EMPTY_RESPONSE in browser tests
-        // ([Bun.serve]: request timed out after 10 seconds). Ingress fronts
-        // arbitrarily slow app endpoints (deploys can legitimately take
-        // minutes), so disable the idle timeout entirely; forked test VMs are
-        // short-lived, leaked-connection risk is bounded by the fork.
-        idleTimeout: 0,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto),
-        // The frame relay for bridged WebSocket upgrades; `proxyToService`
-        // opens the upstream before it upgrades the client (harness/ws-bridge.ts).
-        websocket: WS_BRIDGE_HANDLERS,
-    };
-    return Bun.serve(opts);
+        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, serve.proto),
+    });
 }
 /**
  * Resolve a Host header to a route: an exact entry first, then the longest
@@ -2033,13 +2001,7 @@ server, byHost, listenerLabel, proto) {
     // The real answer — a fake handled in-process, or the proxied container.
     const upstream = async (current) => {
         if (route.kind === "fake") {
-            try {
-                return await runUninstrumented(() => route.fake.def.handler(current, route.fake.state, FAKE_CTX));
-            }
-            catch (err) {
-                const e = err;
-                return new Response(`spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
-            }
+            return dispatchFake(current, server, route.fake.def, route.fake.state, FAKE_CTX);
         }
         return proxyToService(current, server, route.service, route.port, listenerLabel, proto);
     };
@@ -2128,7 +2090,7 @@ server, service, port, listenerLabel, proto) {
             headers: selected ? { "sec-websocket-protocol": selected } : undefined,
         });
         if (ok) {
-            // Bun has already taken over the response — return a stub.
+            // The WebSocket has already taken over the response — return a stub.
             return new Response(null, { status: 101 });
         }
         try {
@@ -2189,6 +2151,7 @@ server, service, port, listenerLabel, proto) {
                 headers: fwdHeaders,
                 body: hasBody ? (bufferedBody ?? req.body) : undefined,
                 redirect: "manual",
+                signal: req.signal,
             });
             // decompress:false → forward the encoded body untouched (see fn doc).
             // keepalive:false → fresh connection per request (see fwdHeaders above).
@@ -2198,7 +2161,7 @@ server, service, port, listenerLabel, proto) {
                 keepalive: false,
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
             });
-            // Strip hop-by-hop response headers; let Bun set content-length / TE.
+            // Strip connection framing while preserving the unchanged body's length.
             const respHeaders = new Headers();
             for (const [k, v] of upstreamRes.headers) {
                 if (HOP_BY_HOP_HEADERS.has(k.toLowerCase()))

package/dist/fake-websocket.d.ts

@@ -0,0 +1,16 @@
+/** A connection accepted by a fake. Text and binary messages retain their type. */
+export interface FakeWebSocket {
+    readonly readyState: number;
+    send(message: string | Uint8Array | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+}
+/** Returned by a fake's websocket handshake callback to accept a connection.
+ * Callbacks run in order per connection, including async callbacks. Capture
+ * fake state and connection-local state in the handshake callback's closure. */
+export interface FakeWebSocketHandlers {
+    /** An offered Sec-WebSocket-Protocol to select, if the client requires one. */
+    protocol?: string;
+    open?(socket: FakeWebSocket): void | Promise<void>;
+    message?(socket: FakeWebSocket, message: string | Uint8Array): void | Promise<void>;
+    close?(socket: FakeWebSocket, code: number, reason: string): void | Promise<void>;
+}

package/dist/fake-websocket.js

@@ -0,0 +1 @@
+export {};

package/dist/harness/fake-websocket-connection.d.ts

@@ -0,0 +1,5 @@
+import type WebSocket from "ws";
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
+/** Serialize async fake callbacks without allowing a slow handler or peer to
+ * retain unbounded audio. A handler failure closes just this connection. */
+export declare function attachFakeWebSocket(ws: WebSocket, handlers: FakeWebSocketHandlers): void;

package/dist/harness/fake-websocket-connection.js

@@ -0,0 +1,58 @@
+const MAX_BUFFER = 16 * 1024 * 1024;
+const MAX_PENDING = 1024;
+/** Serialize async fake callbacks without allowing a slow handler or peer to
+ * retain unbounded audio. A handler failure closes just this connection. */
+export function attachFakeWebSocket(ws, handlers) {
+    let tail = Promise.resolve();
+    let pending = 0;
+    let bytes = 0;
+    let failed = false;
+    const socket = {
+        get readyState() { return ws.readyState; },
+        send(message) {
+            if (ws.readyState !== 1)
+                throw new Error("WebSocket is not open");
+            const size = typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
+            if (ws.bufferedAmount + size > MAX_BUFFER) {
+                failed = true;
+                ws.close(1009, "fake output buffer exceeded");
+                throw new Error("fake WebSocket output buffer exceeded");
+            }
+            ws.send(message);
+        },
+        close: (code, reason) => ws.close(code, reason),
+    };
+    const fail = (err) => {
+        failed = true;
+        console.error("[spectest] fake WebSocket callback failed:", err);
+        try {
+            ws.close(1011, "fake handler failed");
+        }
+        catch {
+            ws.terminate();
+        }
+    };
+    const enqueue = (fn, size = 0, closing = false) => {
+        if (failed && !closing)
+            return;
+        if (!closing && (pending >= MAX_PENDING || bytes + size > MAX_BUFFER)) {
+            failed = true;
+            ws.close(1009, "fake input buffer exceeded");
+            return;
+        }
+        pending++;
+        bytes += size;
+        tail = tail.then(async () => {
+            if (!failed || closing)
+                await fn();
+        }).catch(fail).finally(() => { pending--; bytes -= size; });
+    };
+    ws.on("message", (data, binary) => {
+        const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+        const message = binary ? new Uint8Array(buffer) : buffer.toString();
+        enqueue(() => handlers.message?.(socket, message), buffer.length);
+    });
+    ws.on("close", (code, reason) => enqueue(() => handlers.close?.(socket, code, reason.toString()), 0, true));
+    ws.on("error", fail);
+    enqueue(() => handlers.open?.(socket));
+}

package/dist/harness/fake-websocket.d.ts

@@ -0,0 +1,4 @@
+import type { FakeContext, FakeDefinition } from "../index.js";
+import type { IngressServer } from "./ingress-server.js";
+/** HTTP and WebSocket dispatch share fake state, helpers, and execution scope. */
+export declare function dispatchFake<S>(req: Request, server: IngressServer, def: FakeDefinition<S, any>, state: S, ctx: FakeContext): Promise<Response>;

package/dist/harness/fake-websocket.js

@@ -0,0 +1,32 @@
+import { runUninstrumented } from "./instrumentation-scope.js";
+import { parseSubprotocols } from "./ws-bridge.js";
+/** HTTP and WebSocket dispatch share fake state, helpers, and execution scope. */
+export async function dispatchFake(req, server, def, state, ctx) {
+    try {
+        if (req.headers.get("upgrade")?.toLowerCase() !== "websocket" || !def.websocket) {
+            return await runUninstrumented(() => def.handler(req, state, ctx));
+        }
+        const accepted = await runUninstrumented(() => def.websocket(req, state, ctx));
+        if (accepted instanceof Response)
+            return accepted;
+        if (!accepted || typeof accepted !== "object")
+            throw new Error("websocket must return handlers or a Response");
+        if (accepted.protocol !== undefined && !parseSubprotocols(req.headers.get("sec-websocket-protocol")).includes(accepted.protocol)) {
+            throw new Error("websocket selected a protocol the client did not offer");
+        }
+        const handlers = {
+            open: socket => runUninstrumented(() => accepted.open?.(socket)),
+            message: (socket, message) => runUninstrumented(() => accepted.message?.(socket, message)),
+            close: (socket, code, reason) => runUninstrumented(() => accepted.close?.(socket, code, reason)),
+        };
+        return server.upgrade(req, {
+            handlers,
+            headers: accepted.protocol ? { "sec-websocket-protocol": accepted.protocol } : undefined,
+        }) ? new Response(null, { status: 101 }) : new Response("WebSocket upgrade refused", { status: 426 });
+    }
+    catch (err) {
+        return new Response(`spectest-daemon: fake ${def.name} threw: ${err instanceof Error ? err.message : String(err)}\n`, {
+            status: 500, headers: { "content-type": "text/plain" },
+        });
+    }
+}