@specific.dev/spectest 0.62.0 → 0.64.0

package/src/harness/intercept.ts

@@ -0,0 +1,238 @@
+/**
+ * Request interceptors on the ingress — the mechanism behind `ctx.intercept`.
+ *
+ * An interceptor is middleware in the Hono/Koa sense: it sees a request
+ * that reached the daemon's ingress for a hostname it claims, and either
+ * answers it itself or calls `next()` to let the real upstream (a proxied
+ * service, or a fake) answer. That is what lets a test make its *own*
+ * backend misbehave for one case — force a 500 from an edge function, add
+ * latency, fail twice then pass — without redefining the service.
+ *
+ * ## Why this is a chain and not a replacement handler
+ *
+ * A replacement handler covers "answer instead of the upstream" and nothing
+ * else. Every other shape a test needs — observe and count, mutate a real
+ * response, delay it, fail N times — needs the real answer in hand, which is
+ * what `next()` gives. Registration order is the chain order, as in Hono
+ * or Koa: the first interceptor sees the request first, and each one
+ * decides whether the next runs.
+ *
+ * ## Scope
+ *
+ * The registry is module memory in the harness process, so like fake state
+ * and the route tables it forks with the environment. That alone would make
+ * a parent's interceptor leak into every `dependsOn` child through the
+ * post-state snapshot, so a test's interceptors are **scoped to the case**:
+ * {@link InterceptRegistry.beginScope} opens the case, and
+ * {@link InterceptRegistry.endScope} removes everything registered inside it
+ * — the harness calls both around the test body. An interceptor registered
+ * outside a case (`eval`, project `setup`) has no scope and lasts until
+ * `remove()`.
+ *
+ * Pure module: no Bun, no listener, no recorder — so it is testable with
+ * plain `Request`/`Response` objects.
+ */
+
+import { isWildcard, wildcardSuffix } from "./hostmatch";
+
+/** The continuation an interceptor calls to reach the upstream (or the next
+ *  interceptor in the chain). Passing a `Request` replaces the one that goes
+ *  on — the way to forward a modified request, since a fetch `Request` is
+ *  immutable. */
+export type InterceptNext = (req?: Request) => Promise<Response>;
+
+export type InterceptHandler = (
+  req: Request,
+  next: InterceptNext,
+) => Response | Promise<Response>;
+
+/** One observed request, as the handle reports it. */
+export interface InterceptedRequest {
+  method: string;
+  /** Path + query, as requested. */
+  path: string;
+  status: number;
+  /** Who produced the response: the interceptor itself (`handler`), the
+   *  upstream via `next()` untouched (`upstream`), or the upstream's answer
+   *  replaced by the interceptor after `next()` (`modified`). */
+  answeredBy: "handler" | "upstream" | "modified";
+}
+
+export interface Interceptor {
+  id: number;
+  hostname: string;
+  /** Mount path, like `app.use(path, fn)`: matches the path itself and
+   *  everything below it. `"/"` (the default) matches every path. */
+  path: string;
+  handler: InterceptHandler;
+  /** The case this interceptor belongs to, if registered inside one. */
+  scope?: string;
+  calls: number;
+  requests: InterceptedRequest[];
+}
+
+/** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
+ *  never `/apix`. `/` matches everything. Query strings do not take part. */
+export function pathMounts(mount: string, pathname: string): boolean {
+  if (mount === "/" || mount === "") return true;
+  const m = mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  return pathname === m || pathname.startsWith(`${m}/`);
+}
+
+/** Exact hostname, or a `*.suffix` pattern that covers the host at any
+ *  depth — the same rule the route tables use for a wildcard route. */
+export function hostnameMatches(pattern: string, host: string): boolean {
+  if (pattern === host) return true;
+  if (!isWildcard(pattern)) return false;
+  return host.endsWith(wildcardSuffix(pattern));
+}
+
+/** Normalise a mount path: must start with `/`, no query, no trailing
+ *  slash (except the root). */
+export function normalizeMount(path: string | undefined): string {
+  if (path === undefined || path === "" || path === "/") return "/";
+  if (!path.startsWith("/")) {
+    throw new Error(`intercept: path ${JSON.stringify(path)} must start with "/"`);
+  }
+  if (path.includes("?") || path.includes("#")) {
+    throw new Error(
+      `intercept: path ${JSON.stringify(path)} is a mount prefix and cannot carry a query or fragment`,
+    );
+  }
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+
+export class InterceptRegistry {
+  private list: Interceptor[] = [];
+  private nextId = 1;
+  private scope: string | undefined;
+
+  /** Every interceptor registered from now on belongs to `scope`, until
+   *  {@link endScope}. */
+  beginScope(scope: string): void {
+    this.scope = scope;
+  }
+
+  /** Close the current scope and remove every interceptor registered in it.
+   *  Returns how many were removed. */
+  endScope(): number {
+    const scope = this.scope;
+    this.scope = undefined;
+    if (scope === undefined) return 0;
+    const before = this.list.length;
+    this.list = this.list.filter((i) => i.scope !== scope);
+    return before - this.list.length;
+  }
+
+  register(hostname: string, path: string | undefined, handler: InterceptHandler): Interceptor {
+    if (typeof handler !== "function") {
+      throw new Error("intercept: the handler must be a function (req, next) => Response");
+    }
+    const it: Interceptor = {
+      id: this.nextId++,
+      hostname: hostname.toLowerCase(),
+      path: normalizeMount(path),
+      handler,
+      scope: this.scope,
+      calls: 0,
+      requests: [],
+    };
+    this.list.push(it);
+    return it;
+  }
+
+  /** Idempotent: removing twice, or after the scope ended, is a no-op. */
+  remove(id: number): void {
+    this.list = this.list.filter((i) => i.id !== id);
+  }
+
+  /** The interceptors that apply to a request, in registration order. */
+  chainFor(host: string, pathname: string): Interceptor[] {
+    return this.list.filter(
+      (i) => hostnameMatches(i.hostname, host) && pathMounts(i.path, pathname),
+    );
+  }
+
+  size(): number {
+    return this.list.length;
+  }
+
+  clear(): void {
+    this.list = [];
+    this.scope = undefined;
+  }
+}
+
+/** What `runChain` reports about one interceptor's part in a request. */
+export interface ChainObserver {
+  (interceptor: Interceptor, record: InterceptedRequest, durationMs: number): void;
+}
+
+/**
+ * Run `req` through `chain`, ending at `upstream`.
+ *
+ * Each interceptor's `next` runs the rest of the chain; an interceptor
+ * that returns without calling `next` answers the request itself. A thrown
+ * error becomes a 500 naming the interceptor — the same rule a fake handler
+ * gets — so a bug in test code is a visible failure of that request, not a
+ * hung browser.
+ *
+ * `observe` is called once per interceptor that saw the request, after it
+ * returned, with what it did.
+ */
+export async function runChain(
+  chain: readonly Interceptor[],
+  req: Request,
+  upstream: (req: Request) => Promise<Response>,
+  observe?: ChainObserver,
+): Promise<Response> {
+  const run = async (index: number, current: Request): Promise<Response> => {
+    const it = chain[index];
+    if (!it) return upstream(current);
+    let calledNext = false;
+    let fromUpstream: Response | undefined;
+    const next: InterceptNext = async (replacement?: Request) => {
+      calledNext = true;
+      fromUpstream = await run(index + 1, replacement ?? current);
+      return fromUpstream;
+    };
+    const started = Date.now();
+    const url = new URL(current.url);
+    const record: InterceptedRequest = {
+      method: current.method,
+      path: `${url.pathname}${url.search}`,
+      status: 0,
+      answeredBy: "handler",
+    };
+    let res: Response;
+    try {
+      res = await it.handler(current, next);
+      if (!(res instanceof Response)) {
+        throw new Error(
+          `interceptor for ${it.hostname}${it.path === "/" ? "" : it.path} returned ${
+            res === undefined ? "undefined" : typeof res
+          } — return a Response, or the result of next()`,
+        );
+      }
+    } catch (err) {
+      const e = err as Error;
+      res = new Response(
+        `spectest-daemon: interceptor for ${it.hostname} threw: ${e?.message ?? String(err)}\n`,
+        { status: 500, headers: { "content-type": "text/plain" } },
+      );
+      record.answeredBy = "handler";
+      record.status = 500;
+      it.calls++;
+      it.requests.push(record);
+      observe?.(it, record, Date.now() - started);
+      return res;
+    }
+    record.status = res.status;
+    record.answeredBy = !calledNext ? "handler" : res === fromUpstream ? "upstream" : "modified";
+    it.calls++;
+    it.requests.push(record);
+    observe?.(it, record, Date.now() - started);
+    return res;
+  };
+  return run(0, req);
+}

package/src/index.ts

@@ -168,6 +168,32 @@ export type {
   LoweredIngress,
 } from "./ingress.js";
 import type { DnsTarget } from "./ingress.js";
+import type {
+  InterceptHandler,
+  InterceptNext,
+  InterceptedRequest,
+} from "./harness/intercept.js";
+export type { InterceptHandler, InterceptNext, InterceptedRequest };
+
+/**
+ * The handle `ctx.intercept` returns: what the interceptor has seen so far,
+ * and the way to take it down early. A test's interceptors are removed
+ * when the test ends whether or not `remove()` was called.
+ */
+export interface Interception {
+  hostname: string;
+  /** The normalised mount path (`"/"` when none was given). */
+  path: string;
+  /** How many requests the interceptor has seen. Provenance-wrapped, so an
+   *  `expect(outage.calls)` nests under the intercept step; `.unwrap()` for
+   *  the raw number. */
+  readonly calls: Wrapped<number>;
+  /** Every request it saw, in order, with the status it got and who
+   *  answered it (`handler` | `upstream` | `modified`). */
+  readonly requests: Wrapped<InterceptedRequest[]>;
+  /** Stop intercepting now. Idempotent. */
+  remove(): void;
+}
 import { isWildcard as isWildcardHost } from "./ingress.js";
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -514,6 +540,40 @@ export interface SpectestContext<
    * ```
    */
   dnsName(hostname: string, target: DnsTarget): Promise<void>;
+  /**
+   * Put middleware in front of a hostname the ingress serves — the way to
+   * make your **own** backend misbehave for one test: force a 500 from an
+   * API route, add latency, fail twice then pass, or just count calls.
+   *
+   * Hono/Koa-style middleware: `(req, next)` where `next()` returns the real upstream's
+   * response (a proxied service, or a fake). Return a `Response` to answer
+   * yourself, `next()` to pass through, or change what `next()` returned.
+   * An optional mount `path` limits it to that path and everything below
+   * (`"/functions/v1/sync"`), like `app.use(path, fn)`. Interceptors run in
+   * registration order.
+   *
+   * Only traffic that reaches the daemon can be intercepted: the browser,
+   * `ctx.fetch`, and any container that calls the hostname — so the service
+   * needs a `tls`/`hostnames` entry (or `supabase({ hostname })`), or the
+   * target is a fake. A bare `http://<service>:<port>` call between
+   * containers never passes through here, and a hostname nothing claims is
+   * refused at registration.
+   *
+   * From a test, the interceptor lasts until the test ends (a `dependsOn`
+   * child never inherits it); from `eval` or `setup` it lasts until
+   * `remove()`. Every request it sees is recorded under the intercept step.
+   *
+   * ```ts
+   * const outage = ctx.intercept("api.test", "/functions/v1/sync", () =>
+   *   new Response("boom", { status: 500 }));
+   * await page.getByRole("button", { name: "Sync" }).click();
+   * await expect(page.getByText("Retry")).toBeVisible();
+   * expect(outage.calls).toBe(1);
+   * outage.remove();                           // the retry now reaches the real function
+   * ```
+   */
+  intercept(hostname: string, handler: InterceptHandler): Interception;
+  intercept(hostname: string, path: string, handler: InterceptHandler): Interception;
   /**
    * Mint a leaf certificate from the in-VM root CA and return the PEMs.
    *