@specific.dev/spectest 0.101.0 → 0.103.0

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

@@ -0,0 +1,250 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import http from "node:http";
+import https from "node:https";
+import { once } from "node:events";
+import { createHash, randomBytes } from "node:crypto";
+import { gzipSync } from "node:zlib";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { forwardableHeaders, withIngressCors } from "./http-proxy";
+import { startIngressServer, type IngressServer } from "./ingress-server";
+import { startTlsTerminator, type TlsTerminator } from "./tls-terminator";
+
+const object = randomBytes(65536);
+const compressed = gzipSync(object);
+const digest = (body: Uint8Array) => createHash("sha256").update(body).digest("hex");
+let upstream: http.Server;
+let upstreamPort: number;
+let ingress: IngressServer;
+let tls: TlsTerminator;
+let dir: string;
+let release: (() => void) | undefined;
+let upstreamClosed: Promise<unknown>;
+
+beforeAll(async () => {
+  upstream = http.createServer((req, res) => {
+    const path = req.url!;
+    let body = path === "/8960" ? object.subarray(0, 8960) : path === "/gzip" ? compressed : object;
+    res.setHeader("content-type", "application/octet-stream");
+    res.setHeader("etag", '"original"');
+    res.setHeader("set-cookie", ["a=1", "b=2"]);
+    if (path === "/empty") body = Buffer.alloc(0);
+    if (path === "/gzip") res.setHeader("content-encoding", "gzip");
+    if (req.headers.range) {
+      body = body.subarray(512, 8704);
+      res.statusCode = 206;
+      res.setHeader("content-range", `bytes 512-8703/${object.length}`);
+    }
+    if (path !== "/unknown" && path !== "/unknown-small") res.setHeader("content-length", body.length);
+    if (path === "/large") res.setHeader("content-length", 1024 ** 3);
+    if (path === "/not-modified") res.statusCode = 304;
+    if (path === "/no-content") { res.statusCode = 204; res.removeHeader("content-length"); }
+    if (req.method === "HEAD" || [204, 304].includes(res.statusCode) || body.length === 0) { res.end(); return; }
+    if (path === "/unknown-small") { res.write("small"); res.end(); return; }
+    // Force multiple reads by sending the tail after headers + first chunk.
+    res.write(body.subarray(0, 1024));
+    if (path === "/gated" || path === "/large" || path === "/unknown") {
+      upstreamClosed = once(res, "close");
+      release = () => res.end(body.subarray(1024));
+    } else {
+      setTimeout(() => res.end(body.subarray(1024)), 5);
+    }
+  });
+  upstream.listen(0, "127.0.0.1");
+  await once(upstream, "listening");
+  upstreamPort = (upstream.address() as { port: number }).port;
+  ingress = await startIngressServer({
+    port: 0, hostname: "127.0.0.1",
+    fetch: req => withIngressCors(req, "permissive", async current => {
+      const res = await fetch(`http://127.0.0.1:${upstreamPort}${new URL(current.url).pathname}`, {
+        method: current.method, headers: current.headers, signal: current.signal,
+        decompress: false, keepalive: false,
+      });
+      return new Response(res.body, {
+        status: res.status, statusText: res.statusText, headers: forwardableHeaders(res.headers),
+      });
+    }),
+  });
+  dir = mkdtempSync(join(tmpdir(), "spectest-length-"));
+  execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "2",
+    "-subj", "/CN=bucket.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") };
+  tls = await startTlsTerminator({ port: 0, hostname: "127.0.0.1", upstreamPort: ingress.port, certFor: () => leaf });
+});
+
+afterAll(() => {
+  release?.();
+  tls?.close();
+  ingress?.stop(true);
+  upstream?.closeAllConnections();
+  upstream?.close();
+  if (dir) rmSync(dir, { recursive: true, force: true });
+});
+
+function request(path: string, options: { boundary?: "storage" | "http" | "https"; method?: string; headers?: Record<string, string> } = {}) {
+  const boundary = options.boundary ?? "https";
+  return new Promise<http.IncomingMessage>((resolve, reject) => {
+    const req = (boundary === "https" ? https : http).request({
+      host: "127.0.0.1", port: boundary === "https" ? tls.port : boundary === "http" ? ingress.port : upstreamPort,
+      path, method: options.method ?? "GET", headers: { host: "bucket.test", ...options.headers },
+      agent: false, rejectUnauthorized: false,
+    }, resolve);
+    req.once("error", reject);
+    req.setTimeout(2000, () => req.destroy(new Error("ingress request timed out")));
+    req.end();
+  });
+}
+
+async function bytes(res: http.IncomingMessage) {
+  const chunks: Buffer[] = [];
+  for await (const chunk of res) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks);
+}
+
+describe("ingress response framing", () => {
+  for (const boundary of ["storage", "http", "https"] as const) {
+    test(`${boundary}: repeated multi-chunk GETs keep length and digest`, async () => {
+      for (const size of [8960, 65536]) {
+        for (let n = 0; n < 20; n++) {
+          const res = await request(`/${size}`, { boundary });
+          const body = await bytes(res);
+          expect(res.statusCode).toBe(200);
+          expect(res.headers["content-length"]).toBe(String(size));
+          expect(res.headers["transfer-encoding"]).toBeUndefined();
+          expect(body.length).toBe(size);
+          expect(digest(body)).toBe(digest(object.subarray(0, size)));
+        }
+      }
+    });
+  }
+
+  test("HEAD, empty objects, ranges, cookies and CORS preserve their metadata", async () => {
+    const head = await request("/65536", { method: "HEAD" });
+    expect(head.headers["content-length"]).toBe("65536");
+    expect((await bytes(head)).length).toBe(0);
+    const empty = await request("/empty");
+    expect(empty.headers["content-length"]).toBe("0");
+    expect((await bytes(empty)).length).toBe(0);
+    const range = await request("/65536", { headers: { range: "bytes=512-8703", origin: "https://app.test" } });
+    expect(range.statusCode).toBe(206);
+    expect(range.headers["content-length"]).toBe("8192");
+    expect(range.headers["content-range"]).toBe("bytes 512-8703/65536");
+    expect(range.headers.etag).toBe('"original"');
+    expect(range.headers["set-cookie"]).toEqual(["a=1", "b=2"]);
+    expect(range.headers["access-control-allow-origin"]).toBe("https://app.test");
+    expect(digest(await bytes(range))).toBe(digest(object.subarray(512, 8704)));
+  });
+
+  test("compressed bytes and their encoded length remain unchanged", async () => {
+    const res = await request("/gzip", { headers: { "accept-encoding": "gzip" } });
+    expect(res.headers["content-length"]).toBe(String(compressed.length));
+    expect(res.headers["content-encoding"]).toBe("gzip");
+    expect(digest(await bytes(res))).toBe(digest(compressed));
+  });
+
+  test("no length is invented for an already-complete unknown-length body", async () => {
+    const res = await request("/unknown-small");
+    expect(res.headers["content-length"]).toBeUndefined();
+    expect((await bytes(res)).toString()).toBe("small");
+  });
+
+  test("bodyless statuses stay bodyless", async () => {
+    for (const [path, status] of [["/not-modified", 304], ["/no-content", 204]] as const) {
+      const res = await request(path);
+      expect(res.statusCode).toBe(status);
+      expect(res.headers["transfer-encoding"]).toBeUndefined();
+      if (status === 304) expect(res.headers["content-length"]).toBe("65536");
+      expect((await bytes(res)).length).toBe(0);
+    }
+  });
+
+  for (const path of ["/gated", "/unknown", "/large"]) {
+    test(`${path}: first bytes arrive before upstream finishes; disconnect cancels`, async () => {
+      // The source cannot finish until the test releases it. This fails if
+      // ingress waits for an entire body, regardless of any buffering cap.
+      const res = await request(path);
+      const first = await once(res, "data");
+      expect(Buffer.from(first[0])).toEqual(object.subarray(0, 1024));
+      expect(res.headers["content-length"]).toBe(path === "/unknown" ? undefined : path === "/large" ? String(1024 ** 3) : "65536");
+      if (path === "/large") {
+        res.destroy();
+        await upstreamClosed;
+      } else {
+        const rest = bytes(res);
+        release!();
+        expect(digest(Buffer.concat([first[0], await rest]))).toBe(digest(object));
+      }
+    });
+  }
+});
+
+describe("ingress request lifecycle", () => {
+  test("streams uploads and preserves the request URL, headers and peer", async () => {
+    const server = await startIngressServer({
+      port: 0, hostname: "127.0.0.1",
+      async fetch(req, ingress) {
+        const body = await req.arrayBuffer();
+        return Response.json({ method: req.method, url: req.url, digest: digest(new Uint8Array(body)),
+          authorization: req.headers.get("authorization"), peer: ingress.requestIP(req)?.address });
+      },
+    });
+    try {
+      for (const chunked of [false, true]) {
+        const result = new Promise<http.IncomingMessage>((resolve, reject) => {
+          const req = http.request({ host: "127.0.0.1", port: server.port, path: "/upload?part=2", method: "PUT",
+            headers: { host: "bucket.test:8443", authorization: "signed", ...(chunked ? {} : { "content-length": object.length }) },
+          }, resolve);
+          req.on("error", reject);
+          req.write(object.subarray(0, 1024));
+          setTimeout(() => req.end(object.subarray(1024)), 5);
+        });
+        expect(JSON.parse((await bytes(await result)).toString())).toEqual({ method: "PUT",
+          url: "http://bucket.test:8443/upload?part=2", digest: digest(object), authorization: "signed", peer: "127.0.0.1" });
+      }
+    } finally { server.stop(true); }
+  });
+
+  test("disconnect before response headers aborts the handler", async () => {
+    let entered!: () => void;
+    const started = new Promise<void>(resolve => { entered = resolve; });
+    let cancelled!: () => void;
+    const aborted = new Promise<void>(resolve => { cancelled = resolve; });
+    const server = await startIngressServer({
+      port: 0, hostname: "127.0.0.1",
+      async fetch(req) {
+        req.signal.addEventListener("abort", cancelled, { once: true });
+        entered();
+        await aborted;
+        return new Response("cancelled");
+      },
+    });
+    try {
+      const req = http.get(`http://127.0.0.1:${server.port}/`);
+      req.on("error", () => {});
+      await started;
+      req.destroy();
+      await aborted;
+    } finally { server.stop(true); }
+  });
+
+  test("an error after headers closes the stream instead of appending a success or error body", async () => {
+    const server = await startIngressServer({
+      port: 0, hostname: "127.0.0.1",
+      fetch: () => new Response(new ReadableStream({
+        start(controller) {
+          controller.enqueue(object.subarray(0, 1024));
+          setTimeout(() => controller.error(new Error("upstream truncated")), 20);
+        },
+      }), { headers: { "content-length": String(object.length) } }),
+    });
+    try {
+      const res = await new Promise<http.IncomingMessage>((resolve, reject) => {
+        http.get(`http://127.0.0.1:${server.port}/`, resolve).on("error", reject);
+      });
+      expect(res.headers["content-length"]).toBe(String(object.length));
+      await expect(bytes(res)).rejects.toThrow();
+    } finally { server.stop(true); }
+  });
+});

package/src/harness/ingress-server.ts

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

package/src/harness/microphone-fixture.ts

@@ -0,0 +1,71 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveExistingProjectPath } from "../project-files.js";
+
+export interface MicrophoneFixture {
+  /** WAV file relative to the repository root (absolute paths also work).
+   * Use 16-bit PCM mono or stereo audio. */
+  path: string;
+  /** Repeat the recording. Default false: play once, then supply silence. */
+  loop?: boolean;
+}
+
+/** Stage immutable bytes under a safe filename: Chromium interprets a `%`
+ * suffix as playback options, so a project filename cannot be passed verbatim. */
+export async function prepareMicrophoneFixture(fixture: MicrophoneFixture): Promise<{
+  arg: string;
+  cleanup(): Promise<void>;
+}> {
+  if (!fixture || typeof fixture.path !== "string" || !fixture.path.trim()) {
+    throw new Error("microphone.path must name a WAV fixture");
+  }
+  if (fixture.loop !== undefined && typeof fixture.loop !== "boolean") throw new Error("microphone.loop must be a boolean");
+  const source = resolveExistingProjectPath(fixture.path, "microphone fixture");
+  const bytes = await readFile(source);
+  let pcm = false;
+  let audio = false;
+  let dataAt = 0;
+  let dataSize = 0;
+  let bytesPerFrame = 0;
+  let sampleRate = 0;
+  if (bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WAVE") {
+    for (let at = 12; at + 8 <= bytes.length;) {
+      const size = bytes.readUInt32LE(at + 4);
+      const end = at + 8 + size;
+      if (end > bytes.length) break;
+      const chunk = bytes.toString("ascii", at, at + 4);
+      if (chunk === "fmt " && size >= 16) {
+        sampleRate = bytes.readUInt32LE(at + 12);
+        bytesPerFrame = bytes.readUInt16LE(at + 10) * 2;
+        pcm = bytes.readUInt16LE(at + 8) === 1 && [1, 2].includes(bytes.readUInt16LE(at + 10)) &&
+          sampleRate >= 8000 && sampleRate <= 192000 && bytes.readUInt16LE(at + 22) === 16 &&
+          bytes.readUInt16LE(at + 20) === bytesPerFrame;
+      }
+      if (chunk === "data" && size > 0) { audio = true; dataAt = at; dataSize = size; }
+      at = end + (size % 2);
+    }
+  }
+  if (!pcm || !audio || dataSize % bytesPerFrame !== 0) throw new Error(`microphone fixture "${fixture.path}" must be a non-empty 16-bit PCM mono or stereo WAV (8–192 kHz)`);
+  // Chromium's FileSource returns zero at EOF without clearing the previous
+  // capture buffer. Finish with silence so single playback cannot repeat the
+  // final speech fragment indefinitely. Leave looping recordings untouched.
+  let staged = bytes;
+  if (!fixture.loop) {
+    const silence = Buffer.alloc(Math.ceil(sampleRate / 4) * bytesPerFrame);
+    const end = dataAt + 8 + dataSize;
+    staged = Buffer.concat([bytes.subarray(0, end), silence, bytes.subarray(end)]);
+    staged.writeUInt32LE(staged.length - 8, 4);
+    staged.writeUInt32LE(dataSize + silence.length, dataAt + 4);
+  }
+  const dir = await mkdtemp(join(tmpdir(), "spectest-microphone-"));
+  const cleanup = () => rm(dir, { recursive: true, force: true });
+  try {
+    const file = join(dir, "audio.wav");
+    await writeFile(file, staged);
+    return { arg: `--use-file-for-fake-audio-capture=${file}${fixture.loop ? "" : "%noloop"}`, cleanup };
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+}

package/src/harness/tls-terminator.test.ts

@@ -28,6 +28,7 @@ import tls from "node:tls";
 import type { Leaf } from "./ingress-table";
 import { selectCertName } from "./hostmatch";
 import { startTlsTerminator, type TlsTerminator } from "./tls-terminator";
+import { startIngressServer } from "./ingress-server";
 
 // ── a throwaway CA and leaves, so the client can verify for real ──────────
 let dir: string;
@@ -80,10 +81,9 @@ let seenClientIp: string | undefined;
 
 beforeAll(async () => {
   certByHost = new Map([["app.test", leaves.get("app.test")!]]);
-  plain = Bun.serve({
+  plain = await startIngressServer({
     port: 0,
     hostname: "127.0.0.1",
-    idleTimeout: 0,
     fetch(req, server) {
       const peer = server.requestIP(req);
       seenClientIp = term.clientIpFor(peer?.port) ?? peer?.address;

package/src/harness/tls-terminator.ts

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

package/src/harness/ws-bridge.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { startIngressServer, type IngressServer } from "./ingress-server";
 
 import {
-  WS_BRIDGE_HANDLERS,
   openUpstreamWebSocket,
   parseSubprotocols,
   upstreamHandshakeHeaders,
@@ -65,11 +65,11 @@ describe("upstreamHandshakeHeaders", () => {
  */
 describe("the bridge on loopback", () => {
   let upstream: ReturnType<typeof Bun.serve>;
-  let bridge: ReturnType<typeof Bun.serve>;
+  let bridge: IngressServer;
   /** What the upstream saw on its last handshake. */
   let seen: { protocols: string[]; cookie: string | null; host: string | null; xfh: string | null } | null = null;
 
-  beforeAll(() => {
+  beforeAll(async () => {
     upstream = Bun.serve({
       port: 0,
       fetch(req, server) {
@@ -102,7 +102,7 @@ describe("the bridge on loopback", () => {
       },
     });
 
-    bridge = Bun.serve({
+    bridge = await startIngressServer({
       port: 0,
       async fetch(req, server) {
         const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
@@ -128,7 +128,6 @@ describe("the bridge on loopback", () => {
         }
         return undefined;
       },
-      websocket: WS_BRIDGE_HANDLERS,
     });
   });
 

package/src/index.ts

@@ -78,6 +78,9 @@ export { RedisClient, type RedisClientLike, type RedisOptions } from "./redis.js
 export { S3Client, type S3ClientLike, type S3File, type S3ClientOptions } from "./s3.js";
 
 export type { Browser, BrowserOptions, Keyboard, Mouse, Touchscreen } from "./browser.js";
+export type { MicrophoneFixture } from "./harness/microphone-fixture.js";
+export type { FakeWebSocket, FakeWebSocketHandlers } from "./fake-websocket.js";
+import type { FakeWebSocketHandlers } from "./fake-websocket.js";
 
 import type { Browser, BrowserOptions } from "./browser.js";
 
@@ -2171,6 +2174,11 @@ export interface FakeDefinition<
    * also applies to state/helper factories and helper implementations.
    */
   handler: (req: Request, state: S, ctx: FakeContext) => Response | Promise<Response>;
+  /** Optional WebSocket handshake on the same hostnames as HTTP. Return a
+   * Response to reject, or connection callbacks to accept. Callbacks share
+   * this fake's state and run uninstrumented, in order per connection. */
+  websocket?: (req: Request, state: S, ctx: FakeContext) =>
+    FakeWebSocketHandlers | Response | Promise<FakeWebSocketHandlers | Response>;
   /**
    * Build the helpers exposed at `ctx.fakes.<name>` — a record of
    * **functions** that read or mutate the fake's `state` (received here)
@@ -2239,6 +2247,9 @@ export function defineFake<
   if (typeof opts.handler !== "function") {
     throw new Error(`defineFake(${opts.name}): \`handler\` is required`);
   }
+  if (opts.websocket !== undefined && typeof opts.websocket !== "function") {
+    throw new Error(`defineFake(${opts.name}): \`websocket\` must be a function`);
+  }
   return opts;
 }