@specific.dev/spectest 0.4.0

package/src/components/replayFake.ts

@@ -0,0 +1,515 @@
+// Record/replay fake — a VCR-style cassette fake.
+//
+// `replayFake({...})` returns a plain `FakeDefinition`, so it drops
+// straight into `fakes: { stripe: replayFake({...}) }` and inherits all
+// the existing fakes machinery: ingress lowering mints the TLS leaf cert
+// and registers the hostname, dispatch routes by `Host` header to the
+// generated `handler`, and `state` forks per test like any fake.
+//
+// The only new behaviour lives inside the generated `handler`/`state`:
+//
+//   - REPLAY (hermetic): the request is matched against a committed
+//     cassette and the recorded response is returned. No network. This is
+//     what runs under `spectest test`.
+//   - RECORD: the request is forwarded to the real upstream, the
+//     request/response pair is captured (decoded, redacted), and the real
+//     response is returned to the app so a manual session behaves like
+//     production. This runs under `spectest_eval` / a manual env.
+//
+// Mode is chosen by `isRecording()`: it is true only inside an active
+// recorder (a `spectest test` case), false in eval/manual. So `auto`
+// (the default) replays under test and records under eval — no new
+// control-plane mode flag. `mode: "record" | "replay"` overrides it.
+//
+// Secrets are injected at the egress boundary (the forwarder): the app
+// only ever holds a placeholder; the real value — pushed eval-scoped from
+// the control plane via {@link getRecordSecret} — is swapped in on the
+// forward to upstream and never persists into a cassette (redacted,
+// fail-closed) or any snapshot a hermetic run could fork.
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import type { FakeContext, FakeDefinition } from "../index.js";
+import { isRecording } from "../recorder.js";
+import { getRecordSecret } from "../record-secrets.js";
+
+// Pristine `fetch`, captured at module load (project import time, before
+// any per-test / per-eval fetch wrapper monkey-patches `globalThis.fetch`).
+// The forwarder uses this so its outbound call isn't intercepted by the
+// recorder — same reason the daemon's reverse-proxy keeps its own
+// `NATIVE_FETCH`.
+const NATIVE_FETCH: typeof fetch = globalThis.fetch.bind(globalThis);
+
+// ────────────────────────────────────────────────────────────────────────
+// 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[];
+}
+
+export interface ReplaySecretInjection {
+  /** Platform secret reference, e.g. `"STRIPE_API_KEY"`. The control plane
+   *  resolves it (default: `SPECTEST_SECRET_STRIPE_API_KEY` in the server
+   *  env) and pushes the value on the eval path only. */
+  ref: string;
+  /** Build the headers to set on the forward to upstream from the real
+   *  secret value, *replacing* whatever placeholder the app sent. Default:
+   *  `{ authorization: "Bearer <value>" }`. */
+  inject?: (req: Request, value: string) => Record<string, string>;
+  /** Extra substrings/patterns to scrub from stored request/response
+   *  bodies and queries (the secret value itself is always scrubbed). */
+  redactPatterns?: (string | RegExp)[];
+}
+
+export interface ReplayFakeOptions {
+  /** Stable name — the `ctx.fakes` key. */
+  name: string;
+  /** Hostnames the fake answers to (e.g. `["api.stripe.test"]`). Keep
+   *  these distinct from the real `upstream` host so the record-mode
+   *  forward doesn't resolve back into the daemon (see the loopback
+   *  guard). */
+  hostnames: string[];
+  /** Real upstream base URL to forward to in record mode (e.g.
+   *  `"https://api.stripe.com"`). */
+  upstream: string;
+  /** TCP port the fake listens on. Default `80`. */
+  port?: number;
+  /** Cassette filename under `spectest/recordings/`. Default `<name>.json`. */
+  cassette?: string;
+  /** What defines a request match. Default `{ method, path, query }`. */
+  match?: ReplayMatch;
+  /** Record-time secret injection at the egress boundary. */
+  secret?: ReplaySecretInjection;
+  /** `"auto"` (default) records under eval and replays under test;
+   *  `"record"` / `"replay"` force a mode. */
+  mode?: "auto" | "record" | "replay";
+}
+
+export interface CassetteRequest {
+  method: string;
+  path: string;
+  /** Normalized: keys + repeated values sorted, so matching is order-free. */
+  query: Record<string, string[]>;
+  /** Matched/readable header subset only — never `authorization`/`cookie`. */
+  headers: Record<string, string>;
+  bodyHash?: string;
+  /** Decoded + redacted request body (omitted when empty). */
+  body?: string;
+}
+
+export interface CassetteResponse {
+  status: number;
+  headers: Record<string, string>;
+  /** Decoded + redacted response body. */
+  body: string;
+  bodyEncoding: "utf8" | "base64";
+}
+
+export interface CassetteInteraction {
+  request: CassetteRequest;
+  response: CassetteResponse;
+}
+
+export interface Cassette {
+  version: 1;
+  fake: string;
+  upstream: string;
+  interactions: CassetteInteraction[];
+}
+
+/** Forked-per-test state for one replay fake. */
+export interface CassetteState {
+  cassette: Cassette;
+  /** Per-match-signature replay cursor (call-order sequencing). */
+  cursor: Map<string, number>;
+  /** Interactions captured this record session. */
+  recorded: CassetteInteraction[];
+  dirty: boolean;
+}
+
+export interface ReplayHelpers extends Record<string, unknown> {
+  /** Full cassette JSON (committed interactions + newly recorded, redacted)
+   *  — the MVP delivery channel: `export default ctx.fakes.<name>.dump()`,
+   *  then write the result to `spectest/recordings/<name>.json`. */
+  dump(): Cassette;
+  /** Interactions captured this record session. */
+  recorded(): CassetteInteraction[];
+  /** Count of interactions captured this record session. */
+  count(): number;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────
+
+const SENSITIVE_HEADERS = new Set([
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "proxy-authorization",
+  "x-api-key",
+  "x-amz-security-token",
+]);
+
+/** Hop-by-hop + body-framing headers never forwarded / never replayed
+ *  (Bun's fetch already decompresses, so the encoding/length no longer
+ *  describe the bytes). */
+const STRIP_FORWARD_HEADERS = new Set([
+  "host",
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+  "content-length",
+  "content-encoding",
+]);
+
+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,
+  };
+}
+
+function normalizeQuery(search: URLSearchParams): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const key of [...search.keys()].sort()) {
+    out[key] = search.getAll(key).slice().sort();
+  }
+  return out;
+}
+
+function sha256(s: string): string {
+  return "sha256:" + createHash("sha256").update(s).digest("hex");
+}
+
+function recordable(headers: Headers, want: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of want) {
+    const lower = name.toLowerCase();
+    if (SENSITIVE_HEADERS.has(lower)) continue;
+    const v = headers.get(lower);
+    if (v !== null) out[lower] = v;
+  }
+  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);
+}
+
+function recordingsDir(): string {
+  const dir =
+    process.env.SPECTEST_PROJECT_DIR ??
+    path.join(process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app", "spectest");
+  return path.join(dir, "recordings");
+}
+
+function emptyCassette(name: string, upstream: string): Cassette {
+  return { version: 1, fake: name, upstream, interactions: [] };
+}
+
+function loadCassette(name: string, file: string, upstream: string): Cassette {
+  const p = path.join(recordingsDir(), file);
+  if (!existsSync(p)) return emptyCassette(name, upstream);
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf8")) as Cassette;
+    if (!Array.isArray(parsed.interactions)) {
+      throw new Error("cassette has no `interactions` array");
+    }
+    return {
+      version: 1,
+      fake: parsed.fake ?? name,
+      upstream: parsed.upstream ?? upstream,
+      interactions: parsed.interactions,
+    };
+  } catch (err) {
+    throw new Error(
+      `replayFake(${name}): failed to read cassette ${p}: ${(err as Error).message}`,
+    );
+  }
+}
+
+/** Decode response bytes to a string, falling back to base64 for binary. */
+function decodeBody(buf: ArrayBuffer): { body: string; bodyEncoding: "utf8" | "base64" } {
+  const bytes = new Uint8Array(buf);
+  try {
+    const text = new TextDecoder("utf8", { fatal: true }).decode(bytes);
+    return { body: text, bodyEncoding: "utf8" };
+  } catch {
+    return { body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" };
+  }
+}
+
+function makeRedactor(
+  secretValue: string | undefined,
+  patterns: (string | RegExp)[] | undefined,
+  ref: string | undefined,
+): (s: string) => string {
+  return (s: string): string => {
+    let out = s;
+    if (secretValue && secretValue.length > 0) {
+      out = out.split(secretValue).join(`<REDACTED:${ref ?? "SECRET"}>`);
+    }
+    for (const p of patterns ?? []) {
+      if (typeof p === "string") {
+        if (p.length > 0) out = out.split(p).join("<REDACTED>");
+      } else {
+        const g = p.flags.includes("g") ? p : new RegExp(p.source, p.flags + "g");
+        out = out.replace(g, "<REDACTED>");
+      }
+    }
+    return out;
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// replayFake
+// ────────────────────────────────────────────────────────────────────────
+
+export function replayFake(
+  opts: ReplayFakeOptions,
+): FakeDefinition<CassetteState, ReplayHelpers> {
+  if (!opts.name) throw new Error("replayFake: `name` is required");
+  if (!Array.isArray(opts.hostnames) || opts.hostnames.length === 0) {
+    throw new Error(`replayFake(${opts.name}): at least one hostname is required`);
+  }
+  if (!opts.upstream) {
+    throw new Error(`replayFake(${opts.name}): "upstream" is required`);
+  }
+  const cassetteFile = opts.cassette ?? `${opts.name}.json`;
+  const upstream = opts.upstream.replace(/\/+$/, "");
+  const match = defaultMatch(opts.match);
+  const fakeHosts = new Set(opts.hostnames.map((h) => h.toLowerCase()));
+  const inject =
+    opts.secret?.inject ??
+    ((_req: Request, value: string): Record<string, string> => ({
+      authorization: `Bearer ${value}`,
+    }));
+
+  const resolveMode = (): "record" | "replay" => {
+    if (opts.mode === "record") return "record";
+    if (opts.mode === "replay") return "replay";
+    return isRecording() ? "replay" : "record";
+  };
+
+  // ── REPLAY ──────────────────────────────────────────────────────────
+  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);
+    }
+    const idx = state.cursor.get(sig) ?? 0;
+    const hit = matches[idx];
+    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`;
+      return new Response(body, {
+        status: 599,
+        headers: { "content-type": "text/plain" },
+      });
+    }
+    state.cursor.set(sig, idx + 1);
+    const headers = new Headers(hit.response.headers);
+    const payload =
+      hit.response.bodyEncoding === "base64"
+        ? Buffer.from(hit.response.body, "base64")
+        : hit.response.body;
+    return new Response(payload, { status: hit.response.status, headers });
+  }
+
+  // ── RECORD ──────────────────────────────────────────────────────────
+  async function record(
+    req: Request,
+    reqLike: CassetteRequest,
+    rawBody: string,
+    state: CassetteState,
+  ): Promise<Response> {
+    const secretValue = opts.secret ? getRecordSecret(opts.secret.ref) : undefined;
+    if (opts.secret && secretValue === undefined) {
+      return new Response(
+        `replayFake(${opts.name}): secret ${JSON.stringify(opts.secret.ref)} was not supplied ` +
+          `(set SPECTEST_SECRET_${opts.secret.ref} in the server env and record via spectest_eval).\n`,
+        { status: 599, headers: { "content-type": "text/plain" } },
+      );
+    }
+
+    // Build the upstream URL and guard against forwarding back into the
+    // daemon (which would happen if the upstream host is itself one of
+    // this fake's hostnames — the in-VM resolver points those at us).
+    const target = new URL(reqLike.path, upstream + "/");
+    const incomingUrl = new URL(req.url);
+    incomingUrl.searchParams.forEach((v, k) => target.searchParams.append(k, v));
+    if (fakeHosts.has(target.hostname.toLowerCase())) {
+      throw new Error(
+        `replayFake(${opts.name}): upstream host ${target.hostname} is also a fake hostname — ` +
+          `forwarding would loop back into the daemon. Use a distinct fake hostname ` +
+          `(e.g. "api.${opts.name}.test") pointed at upstream ${upstream}.`,
+      );
+    }
+
+    // Forward headers: drop hop-by-hop, then apply secret injection
+    // (replacing whatever placeholder the app sent — the real key only
+    // ever appears on this outbound wire).
+    const fwdHeaders = new Headers();
+    req.headers.forEach((v, k) => {
+      if (!STRIP_FORWARD_HEADERS.has(k.toLowerCase())) fwdHeaders.set(k, v);
+    });
+    if (opts.secret && secretValue !== undefined) {
+      for (const [k, v] of Object.entries(inject(req, secretValue))) {
+        fwdHeaders.set(k, v);
+      }
+    }
+
+    const upstreamRes = await NATIVE_FETCH(target.toString(), {
+      method: reqLike.method,
+      headers: fwdHeaders,
+      body: rawBody.length > 0 ? rawBody : undefined,
+      redirect: "manual",
+    });
+    const resBuf = await upstreamRes.arrayBuffer();
+
+    // Decode + redact for storage; return the real (un-redacted) bytes to
+    // the app so the manual session behaves like production.
+    const redact = makeRedactor(secretValue, opts.secret?.redactPatterns, opts.secret?.ref);
+    const decoded = decodeBody(resBuf);
+    const respHeaders: Record<string, string> = {};
+    upstreamRes.headers.forEach((v, k) => {
+      const lower = k.toLowerCase();
+      if (SENSITIVE_HEADERS.has(lower) || STRIP_FORWARD_HEADERS.has(lower)) return;
+      respHeaders[lower] = v;
+    });
+
+    const redactedQuery: Record<string, string[]> = {};
+    for (const [k, vs] of Object.entries(reqLike.query)) {
+      redactedQuery[k] = vs.map(redact);
+    }
+    const interaction: CassetteInteraction = {
+      request: {
+        method: reqLike.method,
+        path: reqLike.path,
+        query: redactedQuery,
+        headers: reqLike.headers,
+        ...(rawBody.length > 0
+          ? { bodyHash: reqLike.bodyHash, body: redact(rawBody) }
+          : {}),
+      },
+      response: {
+        status: upstreamRes.status,
+        headers: respHeaders,
+        body: decoded.bodyEncoding === "utf8" ? redact(decoded.body) : decoded.body,
+        bodyEncoding: decoded.bodyEncoding,
+      },
+    };
+
+    // Fail-closed: never persist a cassette that still carries the raw
+    // secret (a missed redaction is a leak, not a warning).
+    if (secretValue && secretValue.length > 0) {
+      if (JSON.stringify(interaction).includes(secretValue)) {
+        throw new Error(
+          `replayFake(${opts.name}): refusing to record — the secret value survived redaction ` +
+            `into the interaction for ${reqLike.method} ${reqLike.path}. Add a redactPatterns entry.`,
+        );
+      }
+    }
+
+    state.recorded.push(interaction);
+    state.dirty = true;
+
+    const outHeaders = new Headers(respHeaders);
+    return new Response(resBuf, { status: upstreamRes.status, headers: outHeaders });
+  }
+
+  // ── handler ─────────────────────────────────────────────────────────
+  const handler = async (
+    req: Request,
+    state: CassetteState,
+    _ctx: FakeContext,
+  ): Promise<Response> => {
+    const url = new URL(req.url);
+    const rawBody = req.method === "GET" || req.method === "HEAD" ? "" : await req.text();
+    const reqLike: CassetteRequest = {
+      method: req.method.toUpperCase(),
+      path: url.pathname,
+      query: normalizeQuery(url.searchParams),
+      headers: recordable(req.headers, ["content-type", ...(match.headers ?? [])]),
+      ...(rawBody.length > 0 ? { bodyHash: sha256(rawBody) } : {}),
+    };
+
+    if (resolveMode() === "replay") return replay(reqLike, state);
+    return record(req, reqLike, rawBody, state);
+  };
+
+  const def: FakeDefinition<CassetteState, ReplayHelpers> = {
+    name: opts.name,
+    hostnames: opts.hostnames,
+    port: opts.port,
+    secretRefs: opts.secret ? [opts.secret.ref] : [],
+    state: (): CassetteState => ({
+      cassette: loadCassette(opts.name, cassetteFile, upstream),
+      cursor: new Map(),
+      recorded: [],
+      dirty: false,
+    }),
+    handler,
+    helpers: ({ state }): ReplayHelpers => ({
+      dump(): Cassette {
+        return {
+          version: 1,
+          fake: opts.name,
+          upstream,
+          interactions: [...state.cassette.interactions, ...state.recorded],
+        };
+      },
+      recorded(): CassetteInteraction[] {
+        return state.recorded.slice();
+      },
+      count(): number {
+        return state.recorded.length;
+      },
+    }),
+  };
+  return def;
+}