@specific.dev/spectest 0.99.0 → 0.101.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
@@ -65,6 +67,8 @@ import * as dnsPacket from "dns-packet";
 import type { FakeContext, FakeDefinition } from "../index.js";
 import { isRecording } from "../recorder.js";
 import { getRecordSecret } from "../record-secrets.js";
+import { replaySignature, type ReplayKey } from "./replay-key.js";
+export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 import {
   inferSigV4Scope,
   signAwsV4Request,
@@ -75,21 +79,6 @@ import {
 // Options + cassette format
 // ────────────────────────────────────────────────────────────────────────
 
-/** Which parts of a request define a match against the cassette. */
-export interface ReplayMatch {
-  /** Match on HTTP method. Default `true`. */
-  method?: boolean;
-  /** Match on path (no query). Default `true`. */
-  path?: boolean;
-  /** Match on normalized query string. Default `true`. */
-  query?: boolean;
-  /** Match on body: `true` = exact decoded body, `"hash"` = sha256 only.
-   *  Default off. */
-  body?: boolean | "hash";
-  /** Header names (lowercase) to include in the match. Default none. */
-  headers?: string[];
-}
-
 /** Match one request dimension. A bare string is an exact match; the
  *  object forms cover prefix and regex matching. */
 export type StringMatch =
@@ -146,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
@@ -155,8 +161,12 @@ export interface ReplayFakeOptions {
    *  resolved via an external DNS server — see the module header). Your
    *  app points at this real host directly; no separate stand-in. */
   host: string;
-  /** What defines a request match. Default `{ method, path, query }`. */
-  match?: ReplayMatch;
+  /** Complete request identity. Default: method, path, normalized query,
+   *  and exact body bytes. The same synchronous, deterministic callback runs
+   *  on recorded and incoming requests. Return JSON values and/or Uint8Array
+   *  bytes; objects compare independently of property order. No implicit
+   *  matching dimensions or fallback apply when a key is supplied. */
+  key?: ReplayKey;
   /** Per-fake credential brokering. Rules are evaluated in
    *  order; the first whose `match` matches wins (a rule without `match`
    *  matches everything and shadows later rules). Applied at the
@@ -175,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 {
@@ -182,7 +201,8 @@ export interface CassetteRequest {
   path: string;
   /** Normalized: keys + repeated values sorted, so matching is order-free. */
   query: Record<string, string[]>;
-  /** Matched/readable header subset only — never `authorization`/`cookie`. */
+  /** Captured non-sensitive headers — never `authorization`/`cookie`.
+   *  Older cassettes may contain only content-type and selected headers. */
   headers: Record<string, string>;
   bodyHash?: string;
   /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
@@ -216,6 +236,8 @@ export interface Cassette {
 /** Forked-per-test state for one replay fake. */
 export interface CassetteState {
   cassette: Cassette;
+  /** Complete signature → cassette interaction indexes, in cassette order. */
+  index: Map<string, number[]>;
   /** Per-match-signature replay cursor (call-order sequencing). */
   cursor: Map<string, number>;
   /** Interactions captured this record session. */
@@ -236,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
@@ -263,7 +286,9 @@ const SENSITIVE_HEADERS = new Set([
   "cookie",
   "set-cookie",
   "proxy-authorization",
+  "api-key",
   "x-api-key",
+  "x-goog-api-key",
   "x-amz-security-token",
 ]);
 
@@ -292,17 +317,6 @@ const STRIP_FORWARD_HEADERS = new Set([
 const EXTERNAL_DNS = process.env.SPECTEST_UPSTREAM_DNS ?? "1.1.1.1";
 const EXTERNAL_DNS_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
 
-function defaultMatch(m: ReplayMatch | undefined): Required<Omit<ReplayMatch, "body" | "headers">> &
-  Pick<ReplayMatch, "body" | "headers"> {
-  return {
-    method: m?.method ?? true,
-    path: m?.path ?? true,
-    query: m?.query ?? true,
-    body: m?.body,
-    headers: m?.headers,
-  };
-}
-
 /** SigV4 puts per-request signing params (`X-Amz-Signature`, `X-Amz-Date`, …)
  *  in the query for presigned URLs — they change every call and would poison
  *  query matching, so they're dropped from both the match key and the forward
@@ -341,27 +355,6 @@ function recordable(headers: Headers, want: string[]): Record<string, string> {
   return out;
 }
 
-/** Canonical match signature for an interaction's request, used as both
- *  the replay-cursor key and the equality basis (two requests match iff
- *  their signatures are equal). Computed identically for an incoming
- *  request and a stored `CassetteRequest`. */
-function signature(req: CassetteRequest, match: ReturnType<typeof defaultMatch>): string {
-  const sig: Record<string, unknown> = {};
-  if (match.method) sig.method = req.method.toUpperCase();
-  if (match.path) sig.path = req.path;
-  if (match.query) sig.query = req.query;
-  if (match.body === true) sig.body = req.body ?? "";
-  else if (match.body === "hash") sig.bodyHash = req.bodyHash ?? "";
-  if (match.headers && match.headers.length > 0) {
-    const h: Record<string, string> = {};
-    for (const name of match.headers.map((n) => n.toLowerCase()).sort()) {
-      h[name] = req.headers[name] ?? "";
-    }
-    sig.headers = h;
-  }
-  return JSON.stringify(sig);
-}
-
 /** The project's `spectest/tests/` dir — cassettes live alongside the
  *  tests, and a `replay(path)` argument is a path relative to here. Keeping
  *  them under `tests/` means re-recording is picked up on the next run with
@@ -386,7 +379,7 @@ function coerceCassette(parsed: Cassette, name: string, host: string): Cassette
     version: 1,
     fake: parsed.fake ?? name,
     host: parsed.host ?? host,
-    interactions: parsed.interactions,
+    interactions: structuredClone(parsed.interactions),
   };
 }
 
@@ -421,7 +414,7 @@ function readCassetteFile(name: string, file: string, host: string): Cassette {
 /** Decode response bytes to a string, falling back to base64 for binary. */
 function decodeBody(bytes: Uint8Array): { body: string; bodyEncoding: "utf8" | "base64" } {
   try {
-    const text = new TextDecoder("utf8", { fatal: true }).decode(bytes);
+    const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
     return { body: text, bodyEncoding: "utf8" };
   } catch {
     return { body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" };
@@ -663,15 +656,20 @@ 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`);
   }
   const host = opts.host.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-  const match = defaultMatch(opts.match);
+  if ("match" in opts) {
+    throw new Error(`replayFake(${opts.name}): \`match\` has been replaced by \`key(request)\`, which defines the complete request identity`);
+  }
+  if (opts.key !== undefined && typeof opts.key !== "function") {
+    throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
+  }
   const injectRules = opts.inject ?? [];
   // Refs every header template references — the control plane resolves these
   // server-side and pushes them for the environment lifetime (see the daemon's
@@ -685,19 +683,33 @@ export function replayFake(
   };
 
   // ── REPLAY ──────────────────────────────────────────────────────────
+  function signature(request: CassetteRequest, location: string): string {
+    try {
+      return replaySignature(request, opts.key);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`replayFake(${opts.name}): invalid replay key for ${location}: ${message}`);
+    }
+  }
+
   function replay(reqLike: CassetteRequest, state: CassetteState): Response {
-    const sig = signature(reqLike, match);
-    const matches: CassetteInteraction[] = [];
-    for (const it of state.cassette.interactions) {
-      if (signature(it.request, match) === sig) matches.push(it);
+    let sig: string;
+    try {
+      sig = signature(reqLike, "incoming request");
+    } catch (error) {
+      return new Response((error as Error).message + "\n", {
+        status: 599, headers: { "content-type": "text/plain" },
+      });
     }
+    const matches = state.index.get(sig) ?? [];
     const idx = state.cursor.get(sig) ?? 0;
-    const hit = matches[idx];
+    const interactionIndex = matches[idx];
+    const hit = interactionIndex === undefined ? undefined : state.cassette.interactions[interactionIndex];
     if (!hit) {
       const body =
         `replayFake(${opts.name}): no cassette interaction for ` +
-        `${reqLike.method} ${reqLike.path} (matched ${matches.length}, wanted #${idx + 1}). ` +
-        `Re-record the cassette, or relax \`match\`.\n`;
+        `${reqLike.method} ${reqLike.path} (${matches.length === 0 ? "unknown key" : "exhausted key"}; matched ${matches.length}, wanted #${idx + 1}). ` +
+        `Check \`key\` or re-record the cassette.\n`;
       return new Response(body, {
         status: 599,
         headers: { "content-type": "text/plain" },
@@ -883,7 +895,7 @@ export function replayFake(
         method: reqLike.method,
         path: reqLike.path,
         query: redactedQuery,
-        headers: reqLike.headers,
+        headers: Object.fromEntries(Object.entries(reqLike.headers).map(([k, v]) => [k, redact(v)])),
         ...(reqLike.body !== undefined
           ? {
               bodyHash: reqLike.bodyHash,
@@ -931,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"
@@ -943,7 +958,7 @@ export function replayFake(
       // Strip SigV4 `x-amz-*` query params from the match key when signing —
       // presigned URLs carry a per-request signature there.
       query: normalizeQuery(url.searchParams, opts.sign !== undefined),
-      headers: recordable(req.headers, ["content-type", ...(match.headers ?? [])]),
+      headers: recordable(req.headers, [...req.headers.keys()]),
       ...(decodedBody
         ? {
             bodyHash: sha256Bytes(bodyBytes),
@@ -957,58 +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),
-      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").`,
-          );
+    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.cursor = new Map();
-        return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
-      },
-      dump(): Cassette {
-        return {
-          version: 1,
-          fake: opts.name,
-          host,
-          interactions: [...state.cassette.interactions, ...state.recorded],
-        };
-      },
-      recorded(): CassetteInteraction[] {
-        return state.recorded.slice();
-      },
-      count(): number {
-        return state.recorded.length;
-      },
-    }),
+        return { ...custom, ...builtins };
+      });
+    },
   };
   return def;
 }