@specific.dev/spectest 0.62.0 → 0.64.0

package/dist/components/supabase.js

@@ -698,12 +698,60 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
+/** One isolate per function, reused across requests (the runtime pools by
+ *  servicePath). The idle timeout is a day, not upstream's five minutes: a
+ *  test environment is a snapshot lineage whose forks inherit these
+ *  isolates, and an isolate reaped for idleness is rebooted by the next
+ *  test that calls the function — a boot's worth of dirtied memory in that
+ *  test's own snapshot diff. */
+function workerFor(name: string) {
+  return EdgeRuntime.userWorkers.create({
+    servicePath: FUNCTIONS_DIR + "/" + name,
+    memoryLimitMb: 256,
+    workerTimeoutMs: 24 * 60 * 60 * 1000,
+    noModuleCache: false,
+    importMapPath: null,
+    envVars: Object.entries(Deno.env.toObject()),
+  });
+}
+
+/** Boot every function's isolate now, without calling it. Creating the
+ *  worker loads the module graph and runs the module's top level — for a
+ *  function that is its \`Deno.serve(handler)\` registration, no business
+ *  logic. Called once at environment setup, before the warm snapshot, so
+ *  the isolates are shared, clean pages of the snapshot rather than a boot
+ *  in every test that first touches a function. */
+async function warmAll(): Promise<{ warmed: string[]; failed: Record<string, string> }> {
+  const names: string[] = [];
+  for await (const entry of Deno.readDir(FUNCTIONS_DIR)) {
+    if (!entry.isDirectory || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    try {
+      await Deno.stat(FUNCTIONS_DIR + "/" + entry.name + "/index.ts");
+      names.push(entry.name);
+    } catch {
+      // not a function directory
+    }
+  }
+  // All at once: a project can have dozens of functions, and each boot is
+  // mostly module loading — the isolates come up concurrently.
+  const results = await Promise.allSettled(names.map((name) => workerFor(name)));
+  const warmed: string[] = [];
+  const failed: Record<string, string> = {};
+  results.forEach((r, i) => {
+    if (r.status === "fulfilled") warmed.push(names[i]);
+    else failed[names[i]] = String(r.reason);
+  });
+  return { warmed: warmed.sort(), failed };
+}
+
 Deno.serve(async (req: Request) => {
   const { pathname } = new URL(req.url);
 
   // Ready probe — answered before any auth check, so bring-up never needs a
   // token, and never treated as a function name.
   if (pathname === "/_spectest/health") return new Response("ok");
+  // Setup-time warm-up (see warmAll); never treated as a function name.
+  if (pathname === "/_spectest/warm") return json(await warmAll());
 
   const name = pathname.split("/")[1] ?? "";
   if (name === "") return json({ msg: "missing function name in request" }, 400);
@@ -718,14 +766,7 @@ Deno.serve(async (req: Request) => {
 
   const servicePath = FUNCTIONS_DIR + "/" + name;
   try {
-    const worker = await EdgeRuntime.userWorkers.create({
-      servicePath,
-      memoryLimitMb: 256,
-      workerTimeoutMs: 5 * 60 * 1000,
-      noModuleCache: false,
-      importMapPath: null,
-      envVars: Object.entries(Deno.env.toObject()),
-    });
+    const worker = await workerFor(name);
     return await worker.fetch(req);
   } catch (e) {
     // A missing directory lands here too, so say which function was asked
@@ -1416,7 +1457,7 @@ export function supabase(opts = {}) {
             }
             // ── functions (edge runtime) ────────────────────────────────────
             if (withFunctions) {
-                parts.functions = {
+                const functionsDef = {
                     // Built rather than pulled, so the functions' remote imports are
                     // fetched by the host builder and cached into the image — see
                     // `functionsDockerfile`.
@@ -1472,7 +1513,27 @@ export function supabase(opts = {}) {
                         path: "/_spectest/health",
                         timeoutSecs: 120,
                     },
+                    // Boot every function's isolate before the warm snapshot is
+                    // taken (see warmAll in the router). Measured on a real project
+                    // (Harmony, 2026-08-28): a test that first touched a few
+                    // functions dirtied ~1 GB booting them — memory that then had to
+                    // be written into that test's snapshot diff and paid for by every
+                    // fork of it. Warm, the isolates are clean shared pages of the
+                    // snapshot and a test's diff is what its requests mutate.
+                    setup: async () => {
+                        const res = await fetch(`http://${g.key("functions")}:9000/_spectest/warm`);
+                        if (!res.ok) {
+                            console.warn(`supabase(): edge functions warm-up answered ${res.status}; functions boot on first call instead.`);
+                            return;
+                        }
+                        const { warmed, failed } = (await res.json());
+                        console.log(`supabase(): warmed ${warmed.length} edge function${warmed.length === 1 ? "" : "s"}${warmed.length ? ` (${warmed.join(", ")})` : ""}.`);
+                        for (const [name, err] of Object.entries(failed)) {
+                            console.warn(`supabase(): edge function "${name}" failed to boot at warm-up — it will be retried on first call: ${err}`);
+                        }
+                    },
                 };
+                parts.functions = functionsDef;
             }
             // ── kong (gateway / primary) — no explicit dependsOn: the group
             // expansion makes the primary depend on every member ──────────────

package/dist/daemon.js

@@ -42,6 +42,7 @@ import { pollUntilReady } from "./harness/ready-poll.js";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
+import { InterceptRegistry, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, certEntries, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
@@ -54,7 +55,7 @@ import { openTerminal } from "./terminal.js";
 import { openMcp } from "./mcp.js";
 import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation } from "./annotate.js";
-import { pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
+import { isRecording, pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
 import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
@@ -1993,17 +1994,27 @@ server, byHost, listenerLabel, proto) {
     // to list in Access-Control-Allow-Headers.
     if (isCorsPreflight(req))
         return corsPreflightResponse(req);
-    if (route.kind === "fake") {
-        try {
-            const res = await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
-            return augmentCorsResponse(req, res);
-        }
-        catch (err) {
-            const e = err;
-            return new Response(`spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
+    // The real answer — a fake handled in-process, or the proxied container.
+    const upstream = async (current) => {
+        if (route.kind === "fake") {
+            try {
+                return await route.fake.def.handler(current, route.fake.state, FAKE_CTX);
+            }
+            catch (err) {
+                const e = err;
+                return new Response(`spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
+            }
         }
-    }
-    const res = await proxyToService(req, server, route.service, route.port, listenerLabel, proto);
+        return proxyToService(current, server, route.service, route.port, listenerLabel, proto);
+    };
+    // `ctx.intercept` middleware runs first, in registration order, and reaches
+    // the upstream through `next()`. The CORS headers go on *after* the chain,
+    // so a forced 500 reaches the browser as a 500 and not as a CORS error —
+    // the trap `page.route`-style interception falls into.
+    const chain = INTERCEPTORS.chainFor(host, new URL(req.url).pathname);
+    const res = chain.length === 0
+        ? await upstream(req)
+        : await runChain(chain, req, upstream, recordInterceptedRequest);
     return augmentCorsResponse(req, res);
 }
 /**
@@ -2263,6 +2274,120 @@ async function seedNamesRegistry(opts) {
     }
     await writeRegistry();
 }
+/**
+ * The live interceptors (`ctx.intercept`). Module memory, so they fork with
+ * the environment like the route tables; a test's own are removed when its
+ * case ends (`runOne` opens and closes the scope), so a `dependsOn` child
+ * never inherits a parent's forced outage.
+ */
+const INTERCEPTORS = new InterceptRegistry();
+/** The recorder seq of the `intercept` step each interceptor was registered
+ *  under, so every request it sees can nest below that step. */
+const INTERCEPT_STEP_SEQ = new Map();
+/** What every port's route table together claims — the hostnames a request
+ *  can reach the ingress under at all. */
+function ingressClaimsHostname(hostname) {
+    for (const byHost of INGRESS.routesByPort.values()) {
+        if (matchRoute(byHost, hostname))
+            return true;
+        if (isWildcard(hostname)) {
+            // A wildcard interceptor is fine when any route sits under it.
+            const suffix = wildcardSuffix(hostname);
+            for (const key of byHost.keys()) {
+                if (key === hostname || key.endsWith(suffix))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** Record one request an interceptor saw, nested under its `intercept` step. */
+function recordInterceptedRequest(it, rec, durationMs) {
+    const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
+    if (parentSeq === undefined || !isRecording())
+        return;
+    const by = rec.answeredBy === "handler"
+        ? "answered by the interceptor"
+        : rec.answeredBy === "modified"
+            ? "upstream answer replaced by the interceptor"
+            : "passed through to the upstream";
+    recordStep({
+        kind: "intercept-request",
+        parentSeq,
+        title: `${rec.method} ${rec.path} → ${rec.status}`,
+        status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+        blocks: [
+            {
+                type: "kv",
+                rows: [
+                    { label: "Host", value: it.hostname },
+                    { label: "Request", value: `${rec.method} ${rec.path}` },
+                    { label: "Status", value: String(rec.status) },
+                    { label: "Answered", value: by },
+                ],
+            },
+        ],
+        durationMs,
+    });
+}
+/**
+ * Put middleware in front of a hostname the ingress serves — the
+ * implementation behind `ctx.intercept`.
+ *
+ * Refuses a hostname no route claims: a request for it would never reach
+ * the daemon (DNS does not point here), so the interceptor could only be
+ * silent — and silence is the failure mode this whole layer is designed
+ * against. The message names the two ways to get a route.
+ */
+function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
+    const path = typeof pathOrHandler === "string" ? pathOrHandler : undefined;
+    const handler = typeof pathOrHandler === "function" ? pathOrHandler : maybeHandler;
+    if (typeof hostname !== "string" || hostname.length === 0) {
+        throw new Error("ctx.intercept: a hostname is required");
+    }
+    const host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    if (!handler) {
+        throw new Error("ctx.intercept: a handler (req, next) => Response is required");
+    }
+    if (!ingressClaimsHostname(host)) {
+        throw new Error(`ctx.intercept(${JSON.stringify(host)}): no request can reach the ingress under that hostname. ` +
+            `Only traffic that passes through the daemon can be intercepted: give the service a \`tls\`/\`hostnames\` ` +
+            `entry (or \`supabase({ hostname })\`), or target a fake's hostname. A bare service name ` +
+            `(\`http://<service>:<port>\`) is container-to-container traffic and never passes through here.`);
+    }
+    const resv = reserveEvent();
+    const it = INTERCEPTORS.register(host, path, handler);
+    const seq = recordStep({
+        kind: "intercept",
+        title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+        blocks: [
+            {
+                type: "kv",
+                rows: [
+                    { label: "Host", value: host },
+                    { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+                ],
+            },
+        ],
+        durationMs: 0,
+    }, resv);
+    if (seq !== undefined)
+        INTERCEPT_STEP_SEQ.set(it.id, seq);
+    return {
+        hostname: host,
+        path: it.path,
+        get calls() {
+            return wrap(it.calls, seq);
+        },
+        get requests() {
+            return wrap(it.requests.map((r) => ({ ...r })), seq);
+        },
+        remove() {
+            INTERCEPTORS.remove(it.id);
+            INTERCEPT_STEP_SEQ.delete(it.id);
+        },
+    };
+}
 /**
  * Register a hostname at runtime — the implementation behind `ctx.dnsName`.
  * Validates via the same `dnsName` primitive the static path uses, resolves
@@ -3491,6 +3616,7 @@ async function spectestContext(scope = {}) {
         certificate: mintCertificate,
         startService: startRuntimeService,
         stopService: stopRuntimeService,
+        intercept: registerInterceptor,
     };
 }
 /** Handles for a service hook: its dependencies (always up by the time the
@@ -4306,6 +4432,9 @@ async function runOne(testCase) {
     // time — so from here on a service helper's `docker exec` lands on the
     // timeline (and in the cast) exactly like the test's own `ctx.exec`.
     RECORDING_EXEC = recordedExec;
+    // Interceptors this case registers die with it (see harness/intercept.ts
+    // — the post-state snapshot must not carry a forced outage into children).
+    INTERCEPTORS.beginScope(testCase.id);
     const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
     let timer;
     const timedOut = new Promise((_, reject) => {
@@ -4335,6 +4464,7 @@ async function runOne(testCase) {
         if (timer)
             clearTimeout(timer);
         RECORDING_EXEC = undefined;
+        INTERCEPTORS.endScope();
         restoreFetch();
         restoreConsole();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/harness/intercept.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+/** 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 declare function pathMounts(mount: string, pathname: string): boolean;
+/** 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 declare function hostnameMatches(pattern: string, host: string): boolean;
+/** Normalise a mount path: must start with `/`, no query, no trailing
+ *  slash (except the root). */
+export declare function normalizeMount(path: string | undefined): string;
+export declare class InterceptRegistry {
+    private list;
+    private nextId;
+    private scope;
+    /** Every interceptor registered from now on belongs to `scope`, until
+     *  {@link endScope}. */
+    beginScope(scope: string): void;
+    /** Close the current scope and remove every interceptor registered in it.
+     *  Returns how many were removed. */
+    endScope(): number;
+    register(hostname: string, path: string | undefined, handler: InterceptHandler): Interceptor;
+    /** Idempotent: removing twice, or after the scope ended, is a no-op. */
+    remove(id: number): void;
+    /** The interceptors that apply to a request, in registration order. */
+    chainFor(host: string, pathname: string): Interceptor[];
+    size(): number;
+    clear(): void;
+}
+/** 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 declare function runChain(chain: readonly Interceptor[], req: Request, upstream: (req: Request) => Promise<Response>, observe?: ChainObserver): Promise<Response>;

package/dist/harness/intercept.js

@@ -0,0 +1,175 @@
+/**
+ * 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";
+/** 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, pathname) {
+    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, host) {
+    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) {
+    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 {
+    list = [];
+    nextId = 1;
+    scope;
+    /** Every interceptor registered from now on belongs to `scope`, until
+     *  {@link endScope}. */
+    beginScope(scope) {
+        this.scope = scope;
+    }
+    /** Close the current scope and remove every interceptor registered in it.
+     *  Returns how many were removed. */
+    endScope() {
+        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, path, handler) {
+        if (typeof handler !== "function") {
+            throw new Error("intercept: the handler must be a function (req, next) => Response");
+        }
+        const it = {
+            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) {
+        this.list = this.list.filter((i) => i.id !== id);
+    }
+    /** The interceptors that apply to a request, in registration order. */
+    chainFor(host, pathname) {
+        return this.list.filter((i) => hostnameMatches(i.hostname, host) && pathMounts(i.path, pathname));
+    }
+    size() {
+        return this.list.length;
+    }
+    clear() {
+        this.list = [];
+        this.scope = undefined;
+    }
+}
+/**
+ * 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, req, upstream, observe) {
+    const run = async (index, current) => {
+        const it = chain[index];
+        if (!it)
+            return upstream(current);
+        let calledNext = false;
+        let fromUpstream;
+        const next = async (replacement) => {
+            calledNext = true;
+            fromUpstream = await run(index + 1, replacement ?? current);
+            return fromUpstream;
+        };
+        const started = Date.now();
+        const url = new URL(current.url);
+        const record = {
+            method: current.method,
+            path: `${url.pathname}${url.search}`,
+            status: 0,
+            answeredBy: "handler",
+        };
+        let res;
+        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;
+            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/dist/index.d.ts

@@ -25,6 +25,27 @@ import { type ServiceCoverage } from "./coverage.js";
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
 export type { CertificateDecl, DnsDecl, ProxyDecl, IngressDecl, DnsTarget, 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;
+}
 export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
     /** Human-friendly name for the environment, e.g. "my-app". */
     name: string;
@@ -355,6 +376,40 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * ```
      */
     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.
      *

package/package.json

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