@specific.dev/spectest 0.100.0 → 0.102.0

package/src/components/replayFake.ts

@@ -14,7 +14,7 @@
 //   - REPLAY (hermetic): the request is matched against the cassette the
 //     test EXPLICITLY loaded (`ctx.fakes.<name>.replay(file)`) and the
 //     recorded response is returned. No network. Nothing is auto-loaded:
-//     a test that loads no cassette gets a fail-loud 599 on every request.
+//     a test that loads no cassette gets a fail-loud 599 on every delegated request.
 //     This is what runs under `spectest test`.
 //   - RECORD (MITM): the request is forwarded to the REAL host and the
 //     request/response pair is captured (decoded, redacted), and the real
@@ -35,6 +35,8 @@
 // recorder (a `spectest test` case), false in eval/manual. So `auto`
 // (the default) replays under test and records during manual use — no new
 // control-plane mode flag. `mode: "record" | "replay"` overrides it.
+// An optional custom handler can return scripted responses or explicitly
+// delegate with ctx.replay(request). Only delegated traffic uses this engine.
 //
 // Credential brokering (per-fake): `inject` rules set
 // headers on the egress forward — overwriting whatever the app sent — so
@@ -133,7 +135,24 @@ export interface AwsSigV4Sign {
 
 export type SignConfig = AwsSigV4Sign;
 
-export interface ReplayFakeOptions {
+/** A normal fake context with explicit delegation to recording/replay. */
+export interface ReplayFakeContext extends FakeContext {
+  /** Record against the real upstream in record mode, or consume a matching
+   *  cassette interaction in replay mode. A replay miss returns 599; there
+   *  is no fallback to scripted logic. Inspect a body's clone before calling. */
+  replay(request: Request): Promise<Response>;
+}
+
+export type ReplayHandler<S> = (
+  request: Request,
+  state: S,
+  ctx: ReplayFakeContext,
+) => Response | Promise<Response>;
+
+export interface ReplayFakeOptions<
+  S = undefined,
+  H extends Record<string, unknown> = {},
+> {
   /** Stable name — the `ctx.fakes` key. */
   name: string;
   /** The REAL host to fake, e.g. `"api.stripe.com"`. The fake answers for
@@ -166,6 +185,15 @@ export interface ReplayFakeOptions {
   /** `"auto"` (default) records under eval and replays under test;
    *  `"record"` / `"replay"` force a mode. */
   mode?: "auto" | "record" | "replay";
+  /** Custom state, with the same lifecycle as a normal fake's state. Kept
+   *  separate from cassette internals; helpers and handler see only S. */
+  state?: () => S | Promise<S>;
+  /** Custom helpers exposed alongside replay/dump/recorded/count. Those
+   *  names are reserved. Loading a cassette does not change custom state. */
+  helpers?: (args: { name: string; state: S; ctx: FakeContext }) => H | Promise<H>;
+  /** Decide whether to answer in code or call ctx.replay(request). Without
+   *  a handler, every request delegates. Only delegated requests record. */
+  handler?: ReplayHandler<S>;
 }
 
 export interface CassetteRequest {
@@ -230,8 +258,9 @@ export interface ReplaySummary {
 }
 
 export interface ReplayHelpers extends Record<string, unknown> {
-  /** Load a cassette into THIS fork's replay set and replay from it,
+  /** Load a cassette into THIS fork's replay set for delegated requests,
    *  replacing whatever was loaded before and resetting the replay cursor.
+   *  Does not change custom state or bypass a custom handler.
    *  Cassettes are NOT auto-loaded — call this at the top of a test. Pass a
    *  path relative to `spectest/tests/` (e.g. `"recordings/stripe.json"`; it
    *  must stay under `spectest/tests/`) or a cassette object; a missing file
@@ -627,9 +656,9 @@ function forwardToRealUpstream(args: {
 // replayFake
 // ────────────────────────────────────────────────────────────────────────
 
-export function replayFake(
-  opts: ReplayFakeOptions,
-): FakeDefinition<CassetteState, ReplayHelpers> {
+export function replayFake<S = undefined, H extends Record<string, unknown> = {}>(
+  opts: ReplayFakeOptions<S, H>,
+): FakeDefinition<CassetteState & { custom: S }, ReplayHelpers & H> {
   if (!opts.name) throw new Error("replayFake: `name` is required");
   if (!opts.host || typeof opts.host !== "string") {
     throw new Error(`replayFake(${opts.name}): "host" (the real hostname) is required`);
@@ -914,6 +943,9 @@ export function replayFake(
     state: CassetteState,
     _ctx: FakeContext,
   ): Promise<Response> => {
+    if (req.bodyUsed) {
+      throw new Error(`replayFake(${opts.name}): cannot delegate a consumed request body; inspect request.clone() before calling ctx.replay(request)`);
+    }
     const url = new URL(req.url);
     const bodyBytes =
       req.method === "GET" || req.method === "HEAD"
@@ -940,69 +972,88 @@ export function replayFake(
     return record(req, url, reqLike, bodyBytes, state);
   };
 
-  const def: FakeDefinition<CassetteState, ReplayHelpers> = {
+  const replayHelpers = (state: CassetteState): ReplayHelpers => ({
+    replay(file: string | Cassette): ReplaySummary {
+      let loaded: Cassette;
+      let label: string;
+      if (file && typeof file === "object") {
+        loaded = coerceCassette(file, opts.name, host);
+        label = file.fake || "(inline)";
+      } else if (typeof file === "string" && file.length > 0) {
+        label = file;
+        loaded = readCassetteFile(opts.name, file, host);
+      } else {
+        throw new Error(
+          `replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
+            `(e.g. "recordings/${opts.name}.json").`,
+        );
+      }
+      // Build/validate before replacing live state: a bad key/cassette
+      // must leave the previous cassette and consumption cursors intact.
+      const index = new Map<string, number[]>();
+      for (const [i, interaction] of loaded.interactions.entries()) {
+        const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+        const queue = index.get(sig);
+        if (queue) queue.push(i);
+        else index.set(sig, [i]);
+      }
+      // Mutate the live state object (the handler reads the same
+      // reference); reset the cursor so replay starts from the top.
+      state.cassette = loaded;
+      state.index = index;
+      state.cursor = new Map();
+      return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
+    },
+    dump(): Cassette {
+      return structuredClone({
+        version: 1,
+        fake: opts.name,
+        host,
+        interactions: [...state.cassette.interactions, ...state.recorded],
+      });
+    },
+    recorded(): CassetteInteraction[] {
+      return structuredClone(state.recorded);
+    },
+    count(): number {
+      return state.recorded.length;
+    },
+  });
+
+  const initialState = (custom: S): CassetteState & { custom: S } => ({
+    cassette: emptyCassette(opts.name, host),
+    index: new Map(),
+    cursor: new Map(),
+    recorded: [],
+    dirty: false,
+    custom,
+  });
+
+  const def: FakeDefinition<CassetteState & { custom: S }, ReplayHelpers & H> = {
     name: opts.name,
-    // Fake = real: we answer for the real host on :80 and :443.
     hostnames: [host],
     secretRefs,
-    // Cassettes are NOT auto-loaded — a fork starts with an empty replay
-    // set, so a test that loads nothing fails loud (599). Tests call
-    // `replay(...)` to populate it.
-    state: (): CassetteState => ({
-      cassette: emptyCassette(opts.name, host),
-      index: new Map(),
-      cursor: new Map(),
-      recorded: [],
-      dirty: false,
-    }),
-    handler,
-    helpers: ({ state }): ReplayHelpers => ({
-      replay(file: string | Cassette): ReplaySummary {
-        let loaded: Cassette;
-        let label: string;
-        if (file && typeof file === "object") {
-          loaded = coerceCassette(file, opts.name, host);
-          label = file.fake || "(inline)";
-        } else if (typeof file === "string" && file.length > 0) {
-          label = file;
-          loaded = readCassetteFile(opts.name, file, host);
-        } else {
-          throw new Error(
-            `replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
-              `(e.g. "recordings/${opts.name}.json").`,
-          );
-        }
-        // Build/validate before replacing live state: a bad key/cassette
-        // must leave the previous cassette and consumption cursors intact.
-        const index = new Map<string, number[]>();
-        for (const [i, interaction] of loaded.interactions.entries()) {
-          const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
-          const queue = index.get(sig);
-          if (queue) queue.push(i);
-          else index.set(sig, [i]);
+    state: () => opts.state
+      ? Promise.resolve(opts.state()).then(initialState)
+      : initialState(undefined as S),
+    handler: (request, state, ctx) => opts.handler
+      ? opts.handler(request, state.custom, {
+          ...ctx,
+          replay: (delegated) => handler(delegated, state, ctx),
+        })
+      : handler(request, state, ctx),
+    helpers: ({ name, state, ctx }) => {
+      const builtins = replayHelpers(state);
+      if (!opts.helpers) return builtins as ReplayHelpers & H;
+      return Promise.resolve(opts.helpers({ name, state: state.custom, ctx })).then((custom) => {
+        for (const key of Object.keys(builtins)) {
+          if (key in custom) {
+            throw new Error(`replayFake(${opts.name}): custom helper ${JSON.stringify(key)} is reserved for recording/replay; choose another name`);
+          }
         }
-        // Mutate the live state object (the handler reads the same
-        // reference); reset the cursor so replay starts from the top.
-        state.cassette = loaded;
-        state.index = index;
-        state.cursor = new Map();
-        return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
-      },
-      dump(): Cassette {
-        return structuredClone({
-          version: 1,
-          fake: opts.name,
-          host,
-          interactions: [...state.cassette.interactions, ...state.recorded],
-        });
-      },
-      recorded(): CassetteInteraction[] {
-        return structuredClone(state.recorded);
-      },
-      count(): number {
-        return state.recorded.length;
-      },
-    }),
+        return { ...custom, ...builtins };
+      });
+    },
   };
   return def;
 }

package/src/daemon.ts

@@ -131,7 +131,6 @@ import {
   upstreamRequestHeaders,
 } from "./harness/http-proxy.js";
 import {
-  WS_BRIDGE_HANDLERS,
   openUpstreamWebSocket,
   parseSubprotocols,
   upstreamHandshakeHeaders,
@@ -157,6 +156,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 +1920,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 +1988,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 +2129,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 +2168,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 +2188,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 +2198,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 +2222,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 +2325,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 +2342,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 +2386,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),
+  });
 }
 
 /**
@@ -2610,7 +2567,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 +2633,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 +2643,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/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);