@specific.dev/spectest 0.89.0 → 0.89.1

package/dist/daemon.js

@@ -51,6 +51,7 @@ import { bindInstrumentationScope, createInstrumentationScope, runInstrumented,
 import { encodeRegistry } from "./harness/names-registry.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
+import { WS_BRIDGE_HANDLERS, 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 { startTlsTerminator } from "./harness/tls-terminator.js";
@@ -1977,8 +1978,8 @@ async function unbindRuntimeTls(hostname) {
  * 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 exports a `websocket`
- * handler so reverse-proxy targets can transparently bridge WS
+ * 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
@@ -2016,81 +2017,9 @@ serve = { proto: "http" }) {
         idleTimeout: 0,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto),
-        websocket: {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            async open(ws) {
-                const data = ws.data;
-                try {
-                    const upstream = new WebSocket(data.upstreamUrl);
-                    // ArrayBuffer so binary frames can be ws.send()'d to the
-                    // downstream client verbatim — Blob would need an extra
-                    // .arrayBuffer() round-trip on every message.
-                    upstream.binaryType = "arraybuffer";
-                    data.upstream = upstream;
-                    upstream.addEventListener("open", () => {
-                        for (const m of data.pending)
-                            upstream.send(m);
-                        data.pending = [];
-                    });
-                    upstream.addEventListener("message", (ev) => {
-                        try {
-                            ws.send(ev.data);
-                        }
-                        catch {
-                            /* client gone */
-                        }
-                    });
-                    upstream.addEventListener("close", (ev) => {
-                        try {
-                            ws.close(ev.code, ev.reason);
-                        }
-                        catch {
-                            /* already closed */
-                        }
-                    });
-                    upstream.addEventListener("error", () => {
-                        try {
-                            ws.close(1011, "upstream error");
-                        }
-                        catch {
-                            /* already closed */
-                        }
-                    });
-                }
-                catch (err) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`[ingress] ws upstream open failed for ${data.upstreamUrl}:`, err);
-                    try {
-                        ws.close(1011, "upstream open failed");
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                }
-            },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            message(ws, message) {
-                const data = ws.data;
-                const payload = typeof message === "string" ? message : new Uint8Array(message);
-                if (data.upstream && data.upstream.readyState === WebSocket.OPEN) {
-                    data.upstream.send(payload);
-                }
-                else {
-                    // Buffer until the upstream finishes its handshake.
-                    data.pending.push(payload);
-                }
-            },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            close(ws, code, reason) {
-                const data = ws.data;
-                try {
-                    data.upstream?.close(code, reason);
-                }
-                catch {
-                    /* ignore */
-                }
-            },
-        },
+        // 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);
 }
@@ -2181,8 +2110,12 @@ function ingressClientIp(server, req, proto) {
  * Reverse-proxy a request to `http://<service>:<port>` on
  * `spectest-net`. Handles plain HTTP/1.1 + 2 and WebSocket upgrades:
  *
- *   - WS upgrade requests get routed through `server.upgrade()`, with
- *     the upstream URL stashed on `ws.data`. The shared `websocket`
+ *   - WS upgrade requests open the upstream WebSocket first, with the
+ *     client's full `Sec-WebSocket-Protocol` list and its forwardable
+ *     headers (cookies, authorization, origin, x-forwarded-*). Only after
+ *     that handshake succeeds is the client upgraded, with the protocol
+ *     the upstream selected; a refused upstream handshake is a 502, not a
+ *     101 followed by a close. The open upstream rides on `ws.data`; the shared `websocket`
  *     handler opens the upstream and bridges frames both ways.
  *   - Plain requests pass through via `fetch()` with hop-by-hop
  *     headers stripped; the response body is a ReadableStream returned
@@ -2205,16 +2138,38 @@ server, service, port, listenerLabel, proto) {
     const upgrade = req.headers.get("upgrade")?.toLowerCase() ?? "";
     if (upgrade === "websocket") {
         const upstreamUrl = `ws://${await proxyUpstreamHost(service)}:${port}${upstreamPath}`;
-        const wsData = {
-            upstreamUrl,
-            upstream: null,
-            pending: [],
-        };
-        const ok = server.upgrade(req, { data: wsData });
+        // The upstream handshake carries what the client's did: the whole
+        // subprotocol list (a console ticket often rides as the second entry)
+        // and the forwardable headers. Same provenance stamps as the HTTP path.
+        const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+        const headers = upstreamHandshakeHeaders(req.headers, {
+            service,
+            port,
+            proto,
+            clientIp: ingressClientIp(server, req, proto),
+        });
+        const opened = await openUpstreamWebSocket(upstreamUrl, { protocols, headers });
+        if (!opened.ok) {
+            return new Response(`spectest-daemon: ${opened.reason} (${upstreamUrl}) on ${listenerLabel}\n`, { status: 502, headers: { "content-type": "text/plain" } });
+        }
+        const wsData = { upstreamUrl, upstream: opened.socket };
+        // Echo the protocol the upstream selected; Bun would otherwise pick
+        // the client's first entry by itself, which can differ.
+        const selected = opened.socket.protocol;
+        const ok = server.upgrade(req, {
+            data: wsData,
+            headers: selected ? { "sec-websocket-protocol": selected } : undefined,
+        });
         if (ok) {
             // Bun has already taken over the response — return a stub.
             return new Response(null, { status: 101 });
         }
+        try {
+            opened.socket.close(1011, "client upgrade refused");
+        }
+        catch {
+            /* ignore */
+        }
         return new Response(`spectest-daemon: ws upgrade refused on ${listenerLabel}\n`, { status: 426, headers: { "content-type": "text/plain" } });
     }
     const fwdHeaders = new Headers();

package/dist/harness/ws-bridge.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The ingress WebSocket bridge: one client WebSocket on an ingress
+ * listener, one upstream WebSocket to the service, frames copied in both
+ * directions.
+ *
+ * The handshake is the part that matters. A client that sends
+ * `Sec-WebSocket-Protocol: console, <ticket>` expects the upstream to see
+ * the full list, and expects to get back the one the upstream selected.
+ * The first version of this bridge opened the upstream with no protocols
+ * and no headers, so a ticket or a cookie that rode on the handshake never
+ * reached the service, and the service refused the connection after the
+ * client already saw a 101. So the bridge now opens the upstream FIRST,
+ * with the client's protocol list and forwardable headers, waits for the
+ * upstream handshake, and only then upgrades the client with the protocol
+ * the upstream selected. An upstream that refuses the handshake becomes a
+ * 502 to the client, the same as the HTTP proxy path.
+ *
+ * `daemon.ts` owns the listener and the route lookup; this module owns
+ * the handshake and the frame relay so the two can be tested on loopback
+ * without a VM.
+ */
+/** Per-bridge context stored on `ws.data` of the client socket. */
+export interface WsBridgeData {
+    upstreamUrl: string;
+    /** Open by the time the client socket exists: the handshake awaited it. */
+    upstream: WebSocket;
+}
+/** `Sec-WebSocket-Protocol` is a comma-separated list; each token is
+ *  trimmed, empty tokens are dropped, order is kept (RFC 6455 §4.1 lets
+ *  the server pick from the list, so order is the client's preference). */
+export declare function parseSubprotocols(header: string | null | undefined): string[];
+/**
+ * The headers the upstream handshake carries: everything forwardable from
+ * the client's request (cookies, authorization, origin, user-agent …),
+ * minus the client's own handshake fields, plus the proxy provenance
+ * headers and a Host that names the service.
+ */
+export declare function upstreamHandshakeHeaders(req: Headers, opts: {
+    service: string;
+    port: number;
+    proto: string;
+    clientIp?: string;
+}): Record<string, string>;
+export type UpstreamOpen = {
+    ok: true;
+    socket: WebSocket;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Open the upstream WebSocket and wait for its handshake. Resolves once
+ * the socket is open, or once it failed; the handshake listeners are
+ * removed either way so a later close does not fire them again.
+ */
+export declare function openUpstreamWebSocket(url: string, opts: {
+    protocols: string[];
+    headers: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<UpstreamOpen>;
+/** The minimum of Bun's ServerWebSocket that the relay uses. */
+interface ClientSocket {
+    data: WsBridgeData;
+    send(data: string | ArrayBuffer | Uint8Array): unknown;
+    close(code?: number, reason?: string): unknown;
+}
+/**
+ * The `websocket` handler set for `Bun.serve`. The upstream is already
+ * open when `open()` runs, so frames go straight through in both
+ * directions, and a close on either side closes the other with the same
+ * code and reason.
+ */
+export declare const WS_BRIDGE_HANDLERS: {
+    open(ws: ClientSocket): void;
+    message(ws: ClientSocket, message: string | Buffer): void;
+    close(ws: ClientSocket, code: number, reason: string): void;
+};
+export {};

package/dist/harness/ws-bridge.js

@@ -0,0 +1,180 @@
+/**
+ * The ingress WebSocket bridge: one client WebSocket on an ingress
+ * listener, one upstream WebSocket to the service, frames copied in both
+ * directions.
+ *
+ * The handshake is the part that matters. A client that sends
+ * `Sec-WebSocket-Protocol: console, <ticket>` expects the upstream to see
+ * the full list, and expects to get back the one the upstream selected.
+ * The first version of this bridge opened the upstream with no protocols
+ * and no headers, so a ticket or a cookie that rode on the handshake never
+ * reached the service, and the service refused the connection after the
+ * client already saw a 101. So the bridge now opens the upstream FIRST,
+ * with the client's protocol list and forwardable headers, waits for the
+ * upstream handshake, and only then upgrades the client with the protocol
+ * the upstream selected. An upstream that refuses the handshake becomes a
+ * 502 to the client, the same as the HTTP proxy path.
+ *
+ * `daemon.ts` owns the listener and the route lookup; this module owns
+ * the handshake and the frame relay so the two can be tested on loopback
+ * without a VM.
+ */
+import { forwardableHeaders } from "./http-proxy.js";
+/** Headers that belong to the client's own WebSocket handshake. Bun's
+ *  WebSocket client mints its own key and version, and the protocol list
+ *  goes through the constructor option, so these never travel as plain
+ *  headers. */
+const HANDSHAKE_HEADERS = new Set([
+    "sec-websocket-key",
+    "sec-websocket-version",
+    "sec-websocket-protocol",
+    "sec-websocket-extensions",
+    "sec-websocket-accept",
+]);
+/** `Sec-WebSocket-Protocol` is a comma-separated list; each token is
+ *  trimmed, empty tokens are dropped, order is kept (RFC 6455 §4.1 lets
+ *  the server pick from the list, so order is the client's preference). */
+export function parseSubprotocols(header) {
+    if (!header)
+        return [];
+    return header
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * The headers the upstream handshake carries: everything forwardable from
+ * the client's request (cookies, authorization, origin, user-agent …),
+ * minus the client's own handshake fields, plus the proxy provenance
+ * headers and a Host that names the service.
+ */
+export function upstreamHandshakeHeaders(req, opts) {
+    const out = {};
+    forwardableHeaders(req).forEach((value, key) => {
+        if (HANDSHAKE_HEADERS.has(key))
+            return;
+        out[key] = value;
+    });
+    const priorXff = req.get("x-forwarded-for");
+    const xff = opts.clientIp
+        ? priorXff
+            ? `${priorXff}, ${opts.clientIp}`
+            : opts.clientIp
+        : priorXff;
+    if (xff)
+        out["x-forwarded-for"] = xff;
+    out["x-forwarded-proto"] = opts.proto;
+    const publicHost = req.get("host");
+    if (publicHost)
+        out["x-forwarded-host"] = publicHost;
+    out["host"] = `${opts.service}:${opts.port}`;
+    return out;
+}
+/**
+ * Open the upstream WebSocket and wait for its handshake. Resolves once
+ * the socket is open, or once it failed; the handshake listeners are
+ * removed either way so a later close does not fire them again.
+ */
+export function openUpstreamWebSocket(url, opts) {
+    const Ctor = WebSocket;
+    let socket;
+    try {
+        socket = new Ctor(url, { protocols: opts.protocols, headers: opts.headers });
+    }
+    catch (err) {
+        return Promise.resolve({ ok: false, reason: String(err) });
+    }
+    // ArrayBuffer so binary frames can be sent to the client verbatim.
+    socket.binaryType = "arraybuffer";
+    return new Promise((resolve) => {
+        let settled = false;
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        const timer = setTimeout(() => finish({ ok: false, reason: "upstream handshake timed out" }), timeoutMs);
+        const onOpen = () => finish({ ok: true, socket });
+        const onError = (ev) => {
+            const msg = ev.message;
+            finish({ ok: false, reason: msg ? `upstream handshake failed: ${msg}` : "upstream handshake failed" });
+        };
+        const onClose = (ev) => finish({ ok: false, reason: `upstream closed during handshake (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})` });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeEventListener("open", onOpen);
+            socket.removeEventListener("error", onError);
+            socket.removeEventListener("close", onClose);
+            if (!result.ok) {
+                try {
+                    socket.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+            resolve(result);
+        };
+        socket.addEventListener("open", onOpen);
+        socket.addEventListener("error", onError);
+        socket.addEventListener("close", onClose);
+    });
+}
+/**
+ * The `websocket` handler set for `Bun.serve`. The upstream is already
+ * open when `open()` runs, so frames go straight through in both
+ * directions, and a close on either side closes the other with the same
+ * code and reason.
+ */
+export const WS_BRIDGE_HANDLERS = {
+    open(ws) {
+        const { upstream } = ws.data;
+        upstream.addEventListener("message", (ev) => {
+            try {
+                ws.send(ev.data);
+            }
+            catch {
+                /* client gone */
+            }
+        });
+        upstream.addEventListener("close", (ev) => {
+            try {
+                ws.close(ev.code, ev.reason);
+            }
+            catch {
+                /* already closed */
+            }
+        });
+        upstream.addEventListener("error", () => {
+            try {
+                ws.close(1011, "upstream error");
+            }
+            catch {
+                /* already closed */
+            }
+        });
+        // The upstream can have closed between the handshake and this
+        // callback; the close listener above was not attached yet then.
+        if (upstream.readyState !== WebSocket.OPEN) {
+            try {
+                ws.close(1011, "upstream closed");
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    },
+    message(ws, message) {
+        const { upstream } = ws.data;
+        const payload = typeof message === "string" ? message : new Uint8Array(message);
+        if (upstream.readyState === WebSocket.OPEN)
+            upstream.send(payload);
+    },
+    close(ws, code, reason) {
+        try {
+            ws.data.upstream.close(code, reason);
+        }
+        catch {
+            /* ignore */
+        }
+    },
+};

package/package.json

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

package/src/daemon.ts

@@ -124,6 +124,13 @@ import {
   corsPreflightResponse,
   isCorsPreflight,
 } from "./harness/http-proxy.js";
+import {
+  WS_BRIDGE_HANDLERS,
+  openUpstreamWebSocket,
+  parseSubprotocols,
+  upstreamHandshakeHeaders,
+  type WsBridgeData,
+} from "./harness/ws-bridge.js";
 import {
   certCovers as hostmatchCertCovers,
   hostWithoutPort,
@@ -2112,14 +2119,6 @@ async function bridgeGatewayIp(): Promise<string> {
  *  The shape is `harness/ingress-table.ts`'s, generic over that record. */
 type Route = IngressRoute<FakeRuntime>;
 
-/** Per-WS-upgrade context: the upstream URL we'll open in `open()` and
- * keep the bridge in `message()`/`close()`. Stored on `ws.data`. */
-interface WsBridgeData {
-  upstreamUrl: string;
-  upstream: WebSocket | null;
-  pending: Array<string | ArrayBuffer | Uint8Array>;
-}
-
 /**
  * Pristine `fetch` captured at module load, before any test-scoped
  * fetch wrapper can monkey-patch `globalThis.fetch`. The reverse-proxy
@@ -2440,8 +2439,8 @@ 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 exports a `websocket`
- * handler so reverse-proxy targets can transparently bridge WS
+ * 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
@@ -2485,74 +2484,9 @@ function bindIngressServer(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     fetch: (req: Request, server: any): Response | Promise<Response> =>
       dispatchIngress(req, server, byHost, listenerLabel, proto),
-    websocket: {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      async open(ws: any) {
-        const data = ws.data as WsBridgeData;
-        try {
-          const upstream = new WebSocket(data.upstreamUrl);
-          // ArrayBuffer so binary frames can be ws.send()'d to the
-          // downstream client verbatim — Blob would need an extra
-          // .arrayBuffer() round-trip on every message.
-          upstream.binaryType = "arraybuffer";
-          data.upstream = upstream;
-          upstream.addEventListener("open", () => {
-            for (const m of data.pending) upstream.send(m);
-            data.pending = [];
-          });
-          upstream.addEventListener("message", (ev: MessageEvent) => {
-            try {
-              ws.send(ev.data);
-            } catch {
-              /* client gone */
-            }
-          });
-          upstream.addEventListener("close", (ev: CloseEvent) => {
-            try {
-              ws.close(ev.code, ev.reason);
-            } catch {
-              /* already closed */
-            }
-          });
-          upstream.addEventListener("error", () => {
-            try {
-              ws.close(1011, "upstream error");
-            } catch {
-              /* already closed */
-            }
-          });
-        } catch (err) {
-          // eslint-disable-next-line no-console
-          console.warn(`[ingress] ws upstream open failed for ${data.upstreamUrl}:`, err);
-          try {
-            ws.close(1011, "upstream open failed");
-          } catch {
-            /* ignore */
-          }
-        }
-      },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      message(ws: any, message: string | Buffer) {
-        const data = ws.data as WsBridgeData;
-        const payload =
-          typeof message === "string" ? message : new Uint8Array(message);
-        if (data.upstream && data.upstream.readyState === WebSocket.OPEN) {
-          data.upstream.send(payload);
-        } else {
-          // Buffer until the upstream finishes its handshake.
-          data.pending.push(payload);
-        }
-      },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      close(ws: any, code: number, reason: string) {
-        const data = ws.data as WsBridgeData;
-        try {
-          data.upstream?.close(code, reason);
-        } catch {
-          /* ignore */
-        }
-      },
-    },
+    // 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);
 }
@@ -2657,8 +2591,12 @@ function ingressClientIp(server: any, req: Request, proto: string): string | und
  * Reverse-proxy a request to `http://<service>:<port>` on
  * `spectest-net`. Handles plain HTTP/1.1 + 2 and WebSocket upgrades:
  *
- *   - WS upgrade requests get routed through `server.upgrade()`, with
- *     the upstream URL stashed on `ws.data`. The shared `websocket`
+ *   - WS upgrade requests open the upstream WebSocket first, with the
+ *     client's full `Sec-WebSocket-Protocol` list and its forwardable
+ *     headers (cookies, authorization, origin, x-forwarded-*). Only after
+ *     that handshake succeeds is the client upgraded, with the protocol
+ *     the upstream selected; a refused upstream handshake is a 502, not a
+ *     101 followed by a close. The open upstream rides on `ws.data`; the shared `websocket`
  *     handler opens the upstream and bridges frames both ways.
  *   - Plain requests pass through via `fetch()` with hop-by-hop
  *     headers stripped; the response body is a ReadableStream returned
@@ -2688,16 +2626,40 @@ async function proxyToService(
   const upgrade = req.headers.get("upgrade")?.toLowerCase() ?? "";
   if (upgrade === "websocket") {
     const upstreamUrl = `ws://${await proxyUpstreamHost(service)}:${port}${upstreamPath}`;
-    const wsData: WsBridgeData = {
-      upstreamUrl,
-      upstream: null,
-      pending: [],
-    };
-    const ok = server.upgrade(req, { data: wsData });
+    // The upstream handshake carries what the client's did: the whole
+    // subprotocol list (a console ticket often rides as the second entry)
+    // and the forwardable headers. Same provenance stamps as the HTTP path.
+    const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+    const headers = upstreamHandshakeHeaders(req.headers, {
+      service,
+      port,
+      proto,
+      clientIp: ingressClientIp(server, req, proto),
+    });
+    const opened = await openUpstreamWebSocket(upstreamUrl, { protocols, headers });
+    if (!opened.ok) {
+      return new Response(
+        `spectest-daemon: ${opened.reason} (${upstreamUrl}) on ${listenerLabel}\n`,
+        { status: 502, headers: { "content-type": "text/plain" } },
+      );
+    }
+    const wsData: WsBridgeData = { upstreamUrl, upstream: opened.socket };
+    // Echo the protocol the upstream selected; Bun would otherwise pick
+    // the client's first entry by itself, which can differ.
+    const selected = opened.socket.protocol;
+    const ok = server.upgrade(req, {
+      data: wsData,
+      headers: selected ? { "sec-websocket-protocol": selected } : undefined,
+    });
     if (ok) {
       // Bun has already taken over the response — return a stub.
       return new Response(null, { status: 101 });
     }
+    try {
+      opened.socket.close(1011, "client upgrade refused");
+    } catch {
+      /* ignore */
+    }
     return new Response(
       `spectest-daemon: ws upgrade refused on ${listenerLabel}\n`,
       { status: 426, headers: { "content-type": "text/plain" } },

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

@@ -0,0 +1,224 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+
+import {
+  WS_BRIDGE_HANDLERS,
+  openUpstreamWebSocket,
+  parseSubprotocols,
+  upstreamHandshakeHeaders,
+  type WsBridgeData,
+} from "./ws-bridge";
+
+describe("parseSubprotocols", () => {
+  test("splits, trims, drops empty tokens, keeps order", () => {
+    expect(parseSubprotocols("console, ticket-abc")).toEqual(["console", "ticket-abc"]);
+    expect(parseSubprotocols(" a ,, b ,")).toEqual(["a", "b"]);
+    expect(parseSubprotocols(null)).toEqual([]);
+    expect(parseSubprotocols("")).toEqual([]);
+  });
+});
+
+describe("upstreamHandshakeHeaders", () => {
+  test("forwards cookies and origin, drops the client's handshake fields, stamps provenance", () => {
+    const req = new Headers({
+      host: "api.prod.specific.dev",
+      connection: "Upgrade",
+      upgrade: "websocket",
+      "sec-websocket-key": "abc==",
+      "sec-websocket-version": "13",
+      "sec-websocket-protocol": "console, ticket",
+      "sec-websocket-extensions": "permessage-deflate",
+      cookie: "sid=1",
+      origin: "https://app.test",
+      authorization: "Bearer t",
+    });
+    const out = upstreamHandshakeHeaders(req, {
+      service: "api",
+      port: 4000,
+      proto: "https",
+      clientIp: "10.0.0.7",
+    });
+    expect(out["cookie"]).toBe("sid=1");
+    expect(out["origin"]).toBe("https://app.test");
+    expect(out["authorization"]).toBe("Bearer t");
+    expect(out["host"]).toBe("api:4000");
+    expect(out["x-forwarded-host"]).toBe("api.prod.specific.dev");
+    expect(out["x-forwarded-proto"]).toBe("https");
+    expect(out["x-forwarded-for"]).toBe("10.0.0.7");
+    for (const k of Object.keys(out)) {
+      expect(k.startsWith("sec-websocket-")).toBe(false);
+      expect(["connection", "upgrade"]).not.toContain(k);
+    }
+  });
+
+  test("appends the client to an existing x-forwarded-for", () => {
+    const out = upstreamHandshakeHeaders(new Headers({ "x-forwarded-for": "1.2.3.4" }), {
+      service: "api",
+      port: 1,
+      proto: "http",
+      clientIp: "10.0.0.7",
+    });
+    expect(out["x-forwarded-for"]).toBe("1.2.3.4, 10.0.0.7");
+  });
+});
+
+/**
+ * A loopback copy of the daemon's arrangement: an upstream that admits a
+ * connection only when the SECOND subprotocol is the ticket (the shape of
+ * Specific's console API), a bridge listener in front of it that does what
+ * `proxyToService` does, and a client through the bridge.
+ */
+describe("the bridge on loopback", () => {
+  let upstream: ReturnType<typeof Bun.serve>;
+  let bridge: ReturnType<typeof Bun.serve>;
+  /** What the upstream saw on its last handshake. */
+  let seen: { protocols: string[]; cookie: string | null; xfh: string | null } | null = null;
+
+  beforeAll(() => {
+    upstream = Bun.serve({
+      port: 0,
+      fetch(req, server) {
+        const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+        seen = {
+          protocols,
+          cookie: req.headers.get("cookie"),
+          xfh: req.headers.get("x-forwarded-host"),
+        };
+        if (protocols[1] !== "ticket-ok") return new Response("Unauthorized", { status: 401 });
+        const ok = server.upgrade(req, {
+          headers: { "sec-websocket-protocol": protocols[0] },
+          data: { admitted: protocols[1] },
+        });
+        return ok ? undefined : new Response("refused", { status: 426 });
+      },
+      websocket: {
+        open(ws) {
+          ws.send("ready");
+        },
+        message(ws, m) {
+          if (typeof m === "string") {
+            if (m === "close-me") ws.close(4402, "app said so");
+            else ws.send(`echo:${m}`);
+          } else {
+            ws.send(new Uint8Array(m).reverse());
+          }
+        },
+      },
+    });
+
+    bridge = Bun.serve({
+      port: 0,
+      async fetch(req, server) {
+        const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+        const headers = upstreamHandshakeHeaders(req.headers, {
+          service: "api",
+          port: upstream.port!,
+          proto: "https",
+        });
+        const url = new URL(req.url);
+        const opened = await openUpstreamWebSocket(
+          `ws://127.0.0.1:${upstream.port}${url.pathname}${url.search}`,
+          { protocols, headers },
+        );
+        if (!opened.ok) return new Response(opened.reason, { status: 502 });
+        const data: WsBridgeData = { upstreamUrl: "", upstream: opened.socket };
+        const ok = server.upgrade(req, {
+          headers: opened.socket.protocol
+            ? { "sec-websocket-protocol": opened.socket.protocol }
+            : undefined,
+          data,
+        });
+        if (!ok) {
+          opened.socket.close();
+          return new Response("refused", { status: 426 });
+        }
+        return undefined;
+      },
+      websocket: WS_BRIDGE_HANDLERS,
+    });
+  });
+
+  afterAll(() => {
+    upstream.stop(true);
+    bridge.stop(true);
+  });
+
+  function connect(protocols: string[]): Promise<{
+    ws: WebSocket;
+    events: Array<{ kind: "open" | "message" | "close" | "error"; value?: unknown }>;
+    done: Promise<void>;
+  }> {
+    const Ctor = WebSocket as unknown as new (
+      url: string,
+      opts: { protocols?: string[]; headers?: Record<string, string> },
+    ) => WebSocket;
+    const ws = new Ctor(`ws://127.0.0.1:${bridge.port}/console?x=1`, {
+      protocols,
+      headers: { cookie: "sid=abc", host: "api.prod.specific.dev" },
+    });
+    ws.binaryType = "arraybuffer";
+    const events: Array<{ kind: "open" | "message" | "close" | "error"; value?: unknown }> = [];
+    const done = new Promise<void>((resolve) => {
+      ws.addEventListener("close", (ev) => {
+        events.push({ kind: "close", value: { code: ev.code, reason: ev.reason } });
+        resolve();
+      });
+    });
+    ws.addEventListener("error", (ev) => events.push({ kind: "error", value: (ev as { message?: string }).message }));
+    ws.addEventListener("message", (ev) => events.push({ kind: "message", value: ev.data }));
+    return new Promise((resolve, reject) => {
+      ws.addEventListener("open", () => {
+        events.push({ kind: "open" });
+        resolve({ ws, events, done });
+      });
+      done.then(() => reject(new Error(`closed before open: ${JSON.stringify(events)}`)));
+    });
+  }
+
+  test("the full protocol list and the headers reach the upstream; the selected protocol comes back", async () => {
+    const { ws, events, done } = await connect(["console", "ticket-ok"]);
+    expect(ws.protocol).toBe("console");
+    expect(seen).toEqual({
+      protocols: ["console", "ticket-ok"],
+      cookie: "sid=abc",
+      xfh: "api.prod.specific.dev",
+    });
+    await Bun.sleep(20);
+    ws.send("hi");
+    ws.send(new Uint8Array([1, 2, 3]));
+    await Bun.sleep(50);
+    ws.close(1000, "bye");
+    await done;
+    const messages = events.filter((e) => e.kind === "message").map((e) => e.value);
+    expect(messages[0]).toBe("ready");
+    expect(messages[1]).toBe("echo:hi");
+    expect(Array.from(new Uint8Array(messages[2] as ArrayBuffer))).toEqual([3, 2, 1]);
+  });
+
+  test("an upstream close code after the handshake is relayed to the client", async () => {
+    const { ws, events, done } = await connect(["console", "ticket-ok"]);
+    await Bun.sleep(20);
+    ws.send("close-me");
+    await done;
+    const close = events.find((e) => e.kind === "close")?.value as { code: number; reason: string };
+    expect(close.code).toBe(4402);
+    expect(close.reason).toBe("app said so");
+  });
+
+  test("an upstream that refuses the handshake never gives the client a 101", async () => {
+    // A plain fetch with the upgrade headers shows the status the bridge
+    // answers with; a WebSocket client only reports a failed handshake.
+    const res = await fetch(`http://127.0.0.1:${bridge.port}/console`, {
+      headers: {
+        connection: "Upgrade",
+        upgrade: "websocket",
+        "sec-websocket-version": "13",
+        "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==",
+        "sec-websocket-protocol": "console, ticket-bad",
+      },
+    });
+    expect(res.status).toBe(502);
+    expect(await res.text()).toContain("upstream handshake failed");
+    expect(seen?.protocols).toEqual(["console", "ticket-bad"]);
+    await expect(connect(["console", "ticket-bad"])).rejects.toThrow(/closed before open/);
+  });
+});

package/src/harness/ws-bridge.ts

@@ -0,0 +1,210 @@
+/**
+ * The ingress WebSocket bridge: one client WebSocket on an ingress
+ * listener, one upstream WebSocket to the service, frames copied in both
+ * directions.
+ *
+ * The handshake is the part that matters. A client that sends
+ * `Sec-WebSocket-Protocol: console, <ticket>` expects the upstream to see
+ * the full list, and expects to get back the one the upstream selected.
+ * The first version of this bridge opened the upstream with no protocols
+ * and no headers, so a ticket or a cookie that rode on the handshake never
+ * reached the service, and the service refused the connection after the
+ * client already saw a 101. So the bridge now opens the upstream FIRST,
+ * with the client's protocol list and forwardable headers, waits for the
+ * upstream handshake, and only then upgrades the client with the protocol
+ * the upstream selected. An upstream that refuses the handshake becomes a
+ * 502 to the client, the same as the HTTP proxy path.
+ *
+ * `daemon.ts` owns the listener and the route lookup; this module owns
+ * the handshake and the frame relay so the two can be tested on loopback
+ * without a VM.
+ */
+
+import { forwardableHeaders } from "./http-proxy.js";
+
+/** Headers that belong to the client's own WebSocket handshake. Bun's
+ *  WebSocket client mints its own key and version, and the protocol list
+ *  goes through the constructor option, so these never travel as plain
+ *  headers. */
+const HANDSHAKE_HEADERS: ReadonlySet<string> = new Set([
+  "sec-websocket-key",
+  "sec-websocket-version",
+  "sec-websocket-protocol",
+  "sec-websocket-extensions",
+  "sec-websocket-accept",
+]);
+
+/** Per-bridge context stored on `ws.data` of the client socket. */
+export interface WsBridgeData {
+  upstreamUrl: string;
+  /** Open by the time the client socket exists: the handshake awaited it. */
+  upstream: WebSocket;
+}
+
+/** `Sec-WebSocket-Protocol` is a comma-separated list; each token is
+ *  trimmed, empty tokens are dropped, order is kept (RFC 6455 §4.1 lets
+ *  the server pick from the list, so order is the client's preference). */
+export function parseSubprotocols(header: string | null | undefined): string[] {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * The headers the upstream handshake carries: everything forwardable from
+ * the client's request (cookies, authorization, origin, user-agent …),
+ * minus the client's own handshake fields, plus the proxy provenance
+ * headers and a Host that names the service.
+ */
+export function upstreamHandshakeHeaders(
+  req: Headers,
+  opts: {
+    service: string;
+    port: number;
+    proto: string;
+    clientIp?: string;
+  },
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  forwardableHeaders(req).forEach((value, key) => {
+    if (HANDSHAKE_HEADERS.has(key)) return;
+    out[key] = value;
+  });
+  const priorXff = req.get("x-forwarded-for");
+  const xff = opts.clientIp
+    ? priorXff
+      ? `${priorXff}, ${opts.clientIp}`
+      : opts.clientIp
+    : priorXff;
+  if (xff) out["x-forwarded-for"] = xff;
+  out["x-forwarded-proto"] = opts.proto;
+  const publicHost = req.get("host");
+  if (publicHost) out["x-forwarded-host"] = publicHost;
+  out["host"] = `${opts.service}:${opts.port}`;
+  return out;
+}
+
+/** Bun's WebSocket constructor takes an options object with `headers`;
+ *  the bundled types only declare the WHATWG `protocols` form. */
+type BunWebSocketCtor = new (
+  url: string,
+  opts: { protocols?: string[]; headers?: Record<string, string> },
+) => WebSocket;
+
+export type UpstreamOpen =
+  | { ok: true; socket: WebSocket }
+  | { ok: false; reason: string };
+
+/**
+ * Open the upstream WebSocket and wait for its handshake. Resolves once
+ * the socket is open, or once it failed; the handshake listeners are
+ * removed either way so a later close does not fire them again.
+ */
+export function openUpstreamWebSocket(
+  url: string,
+  opts: { protocols: string[]; headers: Record<string, string>; timeoutMs?: number },
+): Promise<UpstreamOpen> {
+  const Ctor = WebSocket as unknown as BunWebSocketCtor;
+  let socket: WebSocket;
+  try {
+    socket = new Ctor(url, { protocols: opts.protocols, headers: opts.headers });
+  } catch (err) {
+    return Promise.resolve({ ok: false, reason: String(err) });
+  }
+  // ArrayBuffer so binary frames can be sent to the client verbatim.
+  socket.binaryType = "arraybuffer";
+  return new Promise<UpstreamOpen>((resolve) => {
+    let settled = false;
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const timer = setTimeout(() => finish({ ok: false, reason: "upstream handshake timed out" }), timeoutMs);
+    const onOpen = (): void => finish({ ok: true, socket });
+    const onError = (ev: Event): void => {
+      const msg = (ev as { message?: string }).message;
+      finish({ ok: false, reason: msg ? `upstream handshake failed: ${msg}` : "upstream handshake failed" });
+    };
+    const onClose = (ev: CloseEvent): void =>
+      finish({ ok: false, reason: `upstream closed during handshake (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})` });
+    const finish = (result: UpstreamOpen): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeEventListener("open", onOpen);
+      socket.removeEventListener("error", onError);
+      socket.removeEventListener("close", onClose);
+      if (!result.ok) {
+        try {
+          socket.close();
+        } catch {
+          /* already closed */
+        }
+      }
+      resolve(result);
+    };
+    socket.addEventListener("open", onOpen);
+    socket.addEventListener("error", onError);
+    socket.addEventListener("close", onClose);
+  });
+}
+
+/** The minimum of Bun's ServerWebSocket that the relay uses. */
+interface ClientSocket {
+  data: WsBridgeData;
+  send(data: string | ArrayBuffer | Uint8Array): unknown;
+  close(code?: number, reason?: string): unknown;
+}
+
+/**
+ * The `websocket` handler set for `Bun.serve`. The upstream is already
+ * open when `open()` runs, so frames go straight through in both
+ * directions, and a close on either side closes the other with the same
+ * code and reason.
+ */
+export const WS_BRIDGE_HANDLERS = {
+  open(ws: ClientSocket): void {
+    const { upstream } = ws.data;
+    upstream.addEventListener("message", (ev: MessageEvent) => {
+      try {
+        ws.send(ev.data);
+      } catch {
+        /* client gone */
+      }
+    });
+    upstream.addEventListener("close", (ev: CloseEvent) => {
+      try {
+        ws.close(ev.code, ev.reason);
+      } catch {
+        /* already closed */
+      }
+    });
+    upstream.addEventListener("error", () => {
+      try {
+        ws.close(1011, "upstream error");
+      } catch {
+        /* already closed */
+      }
+    });
+    // The upstream can have closed between the handshake and this
+    // callback; the close listener above was not attached yet then.
+    if (upstream.readyState !== WebSocket.OPEN) {
+      try {
+        ws.close(1011, "upstream closed");
+      } catch {
+        /* already closed */
+      }
+    }
+  },
+  message(ws: ClientSocket, message: string | Buffer): void {
+    const { upstream } = ws.data;
+    const payload = typeof message === "string" ? message : new Uint8Array(message);
+    if (upstream.readyState === WebSocket.OPEN) upstream.send(payload);
+  },
+  close(ws: ClientSocket, code: number, reason: string): void {
+    try {
+      ws.data.upstream.close(code, reason);
+    } catch {
+      /* ignore */
+    }
+  },
+};