@specific.dev/spectest 0.101.0 → 0.103.0

package/src/daemon.ts

@@ -91,6 +91,7 @@ import {
   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,
@@ -131,7 +132,6 @@ import {
   upstreamRequestHeaders,
 } from "./harness/http-proxy.js";
 import {
-  WS_BRIDGE_HANDLERS,
   openUpstreamWebSocket,
   parseSubprotocols,
   upstreamHandshakeHeaders,
@@ -157,6 +157,7 @@ import {
   unbindRoute,
   type Route as IngressRoute,
 } from "./harness/ingress-table.js";
+import { startIngressServer, type IngressServer } from "./harness/ingress-server.js";
 import { startHttp2Proxy } from "./harness/http2-proxy.js";
 import { startTlsTerminator, type TlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
@@ -1920,12 +1921,11 @@ let LOWERED: LoweredIngress = {
   aliasesByService: {},
   wildcards: [],
 };
-/** Running HTTP servers per port (Bun.Server). Rebuilt on /load. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const INGRESS_HTTP_SERVERS = new Map<number, any>();
+/** Running HTTP servers per port. Rebuilt on /load. */
+const INGRESS_HTTP_SERVERS = new Map<number, IngressServer>();
+const INGRESS_HTTP_STARTING = new Map<number, Promise<void>>();
 /** 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<number, any>();
+const INGRESS_HTTPS_SERVERS = new Map<number, IngressServer>();
 /**
  * The :443 TLS terminator, once per harness process.
  *
@@ -1989,6 +1989,7 @@ function stopIngressServers(): void {
     }
   }
   INGRESS_HTTP_SERVERS.clear();
+  INGRESS_HTTP_STARTING.clear();
   for (const [port, srv] of INGRESS_HTTPS_SERVERS) {
     try {
       srv.stop?.(true);
@@ -2129,7 +2130,7 @@ async function startIngress(): Promise<void> {
     );
   }
 
-  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).
@@ -2168,12 +2169,12 @@ async function startIngress(): Promise<void> {
   // ── HTTP listeners (one per non-443 port).
   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);
+  if (INGRESS.certByHost.size > 0) await ensureHttpsIngress();
 
   // Seed the resolver's names registry: ingress hostnames (fakes, TLS
   // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
@@ -2188,7 +2189,7 @@ function requireBun(): any {
   const Bun = (globalThis as any).Bun;
   if (!Bun?.serve) {
     throw new Error(
-      "ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)",
+      "ingress requires Bun; the daemon must run under Bun (it does in-VM)",
     );
   }
   return Bun;
@@ -2198,10 +2199,10 @@ function requireBun(): any {
 /**
  * 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
@@ -2222,27 +2223,25 @@ function requireBun(): any {
  * 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: any): Promise<void> {
+async function ensureHttpsIngress(): Promise<void> {
   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: any): Promise<void> {
+async function startHttpsIngress(): Promise<void> {
   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",
   });
@@ -2327,7 +2326,7 @@ async function bindRuntimeTls(hostname: string, service: string, port: number, h
       `runtime tls for ${JSON.stringify(host)} requires the in-VM root CA at ${CA_PATH}`,
     );
   }
-  const Bun = requireBun();
+  requireBun();
   const route: Route = { kind: "proxy", service, port, http2, cors };
 
   // Decide the cost before mutating anything: an already-covered hostname
@@ -2344,24 +2343,14 @@ async function bindRuntimeTls(hostname: string, service: string, port: number, h
   // 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
     // already on :443 notices.
     INGRESS.certByHost.set(host, await generateHostCert(host, [host]));
   }
-  if (plan.needsHttpsListener) await ensureHttpsIngress(Bun);
+  if (plan.needsHttpsListener) await ensureHttpsIngress();
 
   // Resolve the hostname to the daemon gateway (where :443/:80 listen).
   // A wildcard can only live in the resolver's suffix table.
@@ -2398,63 +2387,32 @@ async function unbindRuntimeTls(hostname: string): Promise<void> {
   }
 }
 
-/**
- * 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: any,
+/** Concurrent runtime routes must share the asynchronous first bind. */
+async function ensureHttpIngress(port: number, byHost: Map<string, Route>): Promise<void> {
+  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: number,
   byHost: Map<string, Route>,
   listenerLabel: string,
-  // 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" | "https"; hostname?: string } = { proto: "http" },
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-): any {
-  const proto = serve.proto;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const opts: Record<string, any> = {
+): Promise<IngressServer> {
+  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: Request, server: any): Response | Promise<Response> =>
-      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),
+  });
 }
 
 /**
@@ -2501,17 +2459,7 @@ async function dispatchIngress(
   // The real answer — a fake handled in-process, or the proxied container.
   const upstream = async (current: Request): Promise<Response> => {
     if (route.kind === "fake") {
-      try {
-        return await runUninstrumented(() =>
-          route.fake.def.handler(current, route.fake.state, FAKE_CTX),
-        );
-      } catch (err) {
-        const e = err as Error;
-        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);
   };
@@ -2610,7 +2558,7 @@ async function proxyToService(
       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 {
@@ -2676,6 +2624,7 @@ async function proxyToService(
         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).
@@ -2685,7 +2634,7 @@ async function proxyToService(
         keepalive: false,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
       } as 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())) continue;

package/src/fake-websocket.ts

@@ -0,0 +1,17 @@
+/** 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/src/harness/fake-websocket-connection.ts

@@ -0,0 +1,54 @@
+import type WebSocket from "ws";
+import type { FakeWebSocket, FakeWebSocketHandlers } from "../fake-websocket.js";
+
+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: WebSocket, handlers: FakeWebSocketHandlers): void {
+  let tail = Promise.resolve();
+  let pending = 0;
+  let bytes = 0;
+  let failed = false;
+  const socket: FakeWebSocket = {
+    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: unknown) => {
+    failed = true;
+    console.error("[spectest] fake WebSocket callback failed:", err);
+    try { ws.close(1011, "fake handler failed"); } catch { ws.terminate(); }
+  };
+  const enqueue = (fn: () => void | Promise<void>, 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 as ArrayBuffer);
+    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/src/harness/fake-websocket.test.ts

@@ -0,0 +1,219 @@
+import { afterEach, expect, test, spyOn } from "bun:test";
+import { once } from "node:events";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { defineFake, type FakeContext, type FakeDefinition } from "../index.js";
+import { dispatchFake } from "./fake-websocket.js";
+import { startIngressServer, type IngressServer } from "./ingress-server.js";
+import { currentInstrumentationScope } from "./instrumentation-scope.js";
+import { startTlsTerminator } from "./tls-terminator.js";
+
+const require = createRequire(import.meta.url);
+const WS = require(join(dirname(require.resolve("ws/package.json")), "index.js")) as typeof import("ws");
+const servers: IngressServer[] = [];
+afterEach(() => { for (const s of servers.splice(0)) s.stop(true); });
+
+async function serve<S>(def: FakeDefinition<S, any>, state: S) {
+  const server = await startIngressServer({ port: 0, hostname: "127.0.0.1",
+    fetch: (req, server) => dispatchFake(req, server, def, state, {} as FakeContext),
+  });
+  servers.push(server);
+  return `127.0.0.1:${server.port}`;
+}
+
+function client(url: string, protocols?: string[], options?: import("ws").ClientOptions) {
+  const ws = new WS(url.startsWith("wss://") ? url : `ws://${url}`, protocols, options);
+  const messages: { data: Buffer; binary: boolean }[] = [];
+  const waiting: ((value: { data: Buffer; binary: boolean }) => void)[] = [];
+  ws.on("message", (data, binary) => {
+    const value = { data: Buffer.from(data as Buffer), binary };
+    const next = waiting.shift();
+    if (next) next(value); else messages.push(value);
+  });
+  const open = once(ws, "open");
+  const closed = once(ws, "close");
+  return { ws, open, closed, next: () => messages.length ? Promise.resolve(messages.shift()!) :
+    new Promise<{ data: Buffer; binary: boolean }>(resolve => waiting.push(resolve)) };
+}
+
+test("HTTP and WebSocket share state, helpers, ordered async callbacks and binary frames", async () => {
+  const state = { events: [] as string[], closed: "" };
+  const def = defineFake({
+    name: "speech", hostnames: ["speech.test"],
+    state: () => state,
+    handler: (_req, state) => Response.json(state.events),
+    helpers: ({ state }) => ({ events: () => [...state.events] }),
+    websocket: async (req, state) => {
+      expect(new URL(req.url).pathname).toBe("/realtime");
+      expect(currentInstrumentationScope()).toBeNull();
+      return {
+        protocol: "audio",
+        async open(ws) {
+          await Bun.sleep(10);
+          state.events.push("open");
+          ws.send("ready");
+        },
+        async message(ws, message) {
+          await Bun.sleep(5);
+          expect(currentInstrumentationScope()).toBeNull();
+          state.events.push(typeof message === "string" ? message : "binary");
+          ws.send(message);
+        },
+        close(_ws, code, reason) { state.closed = `${code}:${reason}`; },
+      };
+    },
+  });
+  const addr = await serve(def, state);
+  const c = client(`${addr}/realtime`, ["other", "audio"]);
+  await c.open;
+  expect(c.ws.protocol).toBe("audio");
+  c.ws.send("first");
+  c.ws.send(new Uint8Array([0, 128, 255]));
+  expect((await c.next()).data.toString()).toBe("ready");
+  expect((await c.next()).data.toString()).toBe("first");
+  expect(await c.next()).toEqual({ data: Buffer.from([0, 128, 255]), binary: true });
+  expect(await (await fetch(`http://${addr}/events`)).json()).toEqual(["open", "first", "binary"]);
+  const helpers = await def.helpers!({ name: "speech", state, ctx: {} as FakeContext });
+  expect(helpers.events()).toEqual(["open", "first", "binary"]);
+  c.ws.close(4001, "finished");
+  await c.closed;
+  for (let i = 0; !state.closed && i < 50; i++) await Bun.sleep(2);
+  expect(state.closed).toBe("4001:finished");
+});
+
+test("handshake can reject before upgrade with an HTTP status and body", async () => {
+  const addr = await serve(defineFake({ name: "auth", hostnames: ["auth.test"],
+    handler: () => new Response("http"),
+    websocket: req => req.headers.get("authorization") === "Bearer valid"
+      ? {} : new Response("token required", { status: 401 }),
+  }), undefined);
+  const ws = new WS(`ws://${addr}/realtime`);
+  const [req, response] = await once(ws, "unexpected-response");
+  const chunks: Buffer[] = [];
+  for await (const chunk of response) chunks.push(Buffer.from(chunk));
+  expect(response.statusCode).toBe(401);
+  expect(Buffer.concat(chunks).toString()).toBe("token required");
+  req.destroy();
+});
+
+test("an unoffered protocol fails the handshake", async () => {
+  const addr = await serve(defineFake({ name: "bad", hostnames: ["bad.test"],
+    handler: () => new Response("http"), websocket: () => ({ protocol: "unoffered" }),
+  }), undefined);
+  const ws = new WS(`ws://${addr}`, ["offered"]);
+  const [req, response] = await once(ws, "unexpected-response");
+  expect(response.statusCode).toBe(500);
+  response.resume();
+  req.destroy();
+});
+
+test("a throwing async callback closes its connection and later connections still work", async () => {
+  const errors = spyOn(console, "error").mockImplementation(() => {});
+  try {
+  const addr = await serve(defineFake({ name: "errors", hostnames: ["errors.test"],
+    handler: () => new Response("healthy"),
+    websocket: () => ({ async message(ws, message) {
+      if (message === "fail") throw new Error("intentional failure");
+      ws.send(message);
+    } }),
+  }), undefined);
+  const c = client(addr);
+  await c.open;
+  c.ws.send("fail");
+  const [code] = await c.closed;
+  expect(code).toBe(1011);
+  const next = client(addr);
+  await next.open;
+  next.ws.send("works");
+  expect((await next.next()).data.toString()).toBe("works");
+  next.ws.close();
+  await next.closed;
+  expect(errors).toHaveBeenCalled();
+  } finally { errors.mockRestore(); }
+});
+
+test("HTTP-only fakes retain their existing handling of upgrade requests", async () => {
+  const addr = await serve(defineFake({ name: "http", hostnames: ["http.test"],
+    handler: () => new Response("no realtime", { status: 404 }),
+  }), undefined);
+  const ws = new WS(`ws://${addr}`);
+  const [req, response] = await once(ws, "unexpected-response");
+  expect(response.statusCode).toBe(404);
+  response.resume();
+  req.destroy();
+});
+
+test("WSS uses the shared TLS terminator with real certificate verification", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-fake-wss-"));
+  let tls: Awaited<ReturnType<typeof startTlsTerminator>> | undefined;
+  try {
+    execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "1",
+      "-subj", "/CN=speech.test", "-addext", "subjectAltName=DNS:speech.test",
+      "-keyout", join(dir, "key.pem"), "-out", join(dir, "cert.pem")], { stdio: "ignore" });
+    const leaf = { key: readFileSync(join(dir, "key.pem"), "utf8"), cert: readFileSync(join(dir, "cert.pem"), "utf8") };
+    const addr = await serve(defineFake({ name: "tls", hostnames: ["speech.test"],
+      handler: () => new Response("http"),
+      websocket: req => {
+        expect(req.headers.get("host")).toBe("speech.test");
+        expect(req.headers.get("cookie")).toBe("session=valid");
+        return { open(ws) { ws.send("secure"); }, message(ws, message) { ws.send(message); } };
+      },
+    }), undefined);
+    tls = await startTlsTerminator({ port: 0, hostname: "127.0.0.1", upstreamPort: Number(addr.split(":")[1]), certFor: () => leaf });
+    const c = client(`wss://127.0.0.1:${tls.port}`, undefined, {
+      servername: "speech.test", ca: leaf.cert, headers: { host: "speech.test", cookie: "session=valid" },
+    });
+    await c.open;
+    expect((await c.next()).data.toString()).toBe("secure");
+    c.ws.send(new Uint8Array([1, 2, 3]));
+    expect(await c.next()).toEqual({ data: Buffer.from([1, 2, 3]), binary: true });
+    c.ws.close(); await c.closed;
+  } finally { tls?.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("each handshake owns separate connection-local state", async () => {
+  const addr = await serve(defineFake({ name: "sessions", hostnames: ["speech.test"],
+    handler: () => new Response("http"), websocket: () => {
+      let sequence = 0;
+      return { message(ws) { ws.send(String(++sequence)); } };
+    },
+  }), undefined);
+  const a = client(addr), b = client(addr);
+  await Promise.all([a.open, b.open]);
+  a.ws.send("next"); a.ws.send("next"); b.ws.send("next");
+  expect((await a.next()).data.toString()).toBe("1");
+  expect((await a.next()).data.toString()).toBe("2");
+  expect((await b.next()).data.toString()).toBe("1");
+  a.ws.close(); b.ws.close(); await Promise.all([a.closed, b.closed]);
+});
+
+test("oversized fake output closes with 1009 instead of buffering it", async () => {
+  const errors = spyOn(console, "error").mockImplementation(() => {});
+  try {
+    const addr = await serve(defineFake({ name: "bounded", hostnames: ["bounded.test"],
+      handler: () => new Response("http"),
+      websocket: () => ({ message(ws) { ws.send(new Uint8Array(16 * 1024 * 1024 + 1)); } }),
+    }), undefined);
+    const c = client(addr);
+    await c.open;
+    c.ws.send("start");
+    expect((await c.closed)[0]).toBe(1009);
+  } finally { errors.mockRestore(); }
+});
+
+test("a slow callback cannot accumulate unlimited pending messages", async () => {
+  let release!: () => void;
+  const blocked = new Promise<void>(resolve => { release = resolve; });
+  try {
+    const addr = await serve(defineFake({ name: "slow", hostnames: ["slow.test"],
+      handler: () => new Response("http"), websocket: () => ({ open: () => blocked }),
+    }), undefined);
+    const c = client(addr);
+    await c.open;
+    for (let i = 0; i < 1100; i++) c.ws.send("queued");
+    expect((await c.closed)[0]).toBe(1009);
+  } finally { release(); }
+});

package/src/harness/fake-websocket.ts

@@ -0,0 +1,39 @@
+import type { FakeWebSocketHandlers } from "../fake-websocket.js";
+import type { FakeContext, FakeDefinition } from "../index.js";
+import type { IngressServer } from "./ingress-server.js";
+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<S>(
+  req: Request,
+  server: IngressServer,
+  def: FakeDefinition<S, any>,
+  state: S,
+  ctx: FakeContext,
+): Promise<Response> {
+  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: FakeWebSocketHandlers = {
+      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" },
+    });
+  }
+}

package/src/harness/ingress-cors.test.ts

@@ -3,6 +3,7 @@ import { defineEnvironment, defineFake, lowerIngress, provides, proxy, type Cors
 import { supabase } from "../components/supabase.js";
 import { withIngressCors, upstreamRequestHeaders } from "./http-proxy.js";
 import { InterceptRegistry, runChain } from "./intercept.js";
+import { startIngressServer } from "./ingress-server.js";
 
 const allowed = "https://app.tangent.test";
 const denied = "https://untrusted.test";
@@ -56,12 +57,12 @@ for (const kind of ["fake", "service"] as const) {
             method: req.method, headers: upstreamRequestHeaders(req.headers, { proto: "https" }),
             body: req.body, redirect: "manual",
           });
-        const ingress = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: req =>
+        const ingress = await startIngressServer({ port: 0, hostname: "127.0.0.1", fetch: req =>
           withIngressCors(req, mode, current => runChain(
             interceptors.chainFor("bucket.test", new URL(current.url).pathname), current, forward)),
         });
         try {
-          const send = (path: string, init: RequestInit) => fetch(new URL(path, ingress.url), init);
+          const send = (path: string, init: RequestInit) => fetch(new URL(path, `http://127.0.0.1:${ingress.port}`), init);
           const ok = await send("/probe", preflight(allowed));
           expect(ok.status).toBe(204);
           expect(ok.headers.get("access-control-allow-origin")).toBe(allowed);