@specific.dev/spectest 0.62.0 → 0.64.0

package/src/components/supabase.ts

@@ -1043,12 +1043,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);
@@ -1063,14 +1111,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
@@ -1917,7 +1958,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
 
       // ── functions (edge runtime) ────────────────────────────────────
       if (withFunctions) {
-        parts.functions = {
+        const functionsDef: ServiceDefinition = {
           // Built rather than pulled, so the functions' remote imports are
           // fetched by the host builder and cached into the image — see
           // `functionsDockerfile`.
@@ -1976,7 +2017,27 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             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()) as { warmed: string[]; failed: Record<string, string> };
+            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

package/src/daemon.ts

@@ -98,6 +98,11 @@ import {
   parseContentLength,
 } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
+import {
+  InterceptRegistry,
+  runChain,
+  type Interceptor,
+} from "./harness/intercept.js";
 import {
   HOP_BY_HOP_HEADERS,
   augmentCorsResponse,
@@ -151,6 +156,7 @@ import { openMcp } from "./mcp.js";
 import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation, type RenderAnnotation } from "./annotate.js";
 import {
+  isRecording,
   pauseRecording,
   recordEmail,
   recordEnv,
@@ -191,6 +197,9 @@ import type {
   FakeContext,
   FakeDefinition,
   FileMount,
+  InterceptHandler,
+  Interception,
+  InterceptedRequest,
   Project,
   ProjectSetupContext,
   ReadyCheck,
@@ -2449,26 +2458,30 @@ async function dispatchIngress(
   // Cache-Control, Pragma, … — isn't rejected by whatever the upstream happens
   // 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 as Error;
-      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: Request): Promise<Response> => {
+    if (route.kind === "fake") {
+      try {
+        return await route.fake.def.handler(current, route.fake.state, FAKE_CTX);
+      } catch (err) {
+        const e = err as Error;
+        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);
 }
 
@@ -2755,6 +2768,137 @@ async function seedNamesRegistry(opts: { servicesUp: boolean }): Promise<void> {
   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<number, number>();
+
+/** What every port's route table together claims — the hostnames a request
+ *  can reach the ingress under at all. */
+function ingressClaimsHostname(hostname: string): boolean {
+  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: Interceptor,
+  rec: { method: string; path: string; status: number; answeredBy: string },
+  durationMs: number,
+): void {
+  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: string,
+  pathOrHandler: string | InterceptHandler,
+  maybeHandler?: InterceptHandler,
+): Interception {
+  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(): Wrapped<number> {
+      return wrap(it.calls, seq) as unknown as Wrapped<number>;
+    },
+    get requests(): Wrapped<InterceptedRequest[]> {
+      return wrap(it.requests.map((r) => ({ ...r })), seq) as unknown as Wrapped<
+        InterceptedRequest[]
+      >;
+    },
+    remove(): void {
+      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
@@ -4303,6 +4447,7 @@ async function spectestContext(scope: ContextScope = {}): Promise<SpectestContex
     certificate: mintCertificate,
     startService: startRuntimeService,
     stopService: stopRuntimeService,
+    intercept: registerInterceptor as SpectestContext["intercept"],
   };
 }
 
@@ -5253,6 +5398,9 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   // 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: NodeJS.Timeout | undefined;
@@ -5284,6 +5432,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   } finally {
     if (timer) clearTimeout(timer);
     RECORDING_EXEC = undefined;
+    INTERCEPTORS.endScope();
     restoreFetch();
     restoreConsole();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/harness/intercept.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test";
+import {
+  InterceptRegistry,
+  hostnameMatches,
+  normalizeMount,
+  pathMounts,
+  runChain,
+  type Interceptor,
+} from "./intercept";
+
+const upstream = async (_req: Request) => new Response("real", { status: 200 });
+
+function req(path = "/", init?: RequestInit): Request {
+  return new Request(`https://api.test${path}`, init);
+}
+
+describe("pathMounts", () => {
+  test("root matches everything", () => {
+    expect(pathMounts("/", "/")).toBe(true);
+    expect(pathMounts("/", "/a/b")).toBe(true);
+  });
+  test("a mount matches itself and below, on a segment boundary", () => {
+    expect(pathMounts("/api", "/api")).toBe(true);
+    expect(pathMounts("/api", "/api/")).toBe(true);
+    expect(pathMounts("/api", "/api/x")).toBe(true);
+    expect(pathMounts("/api", "/apix")).toBe(false);
+    expect(pathMounts("/api", "/")).toBe(false);
+  });
+});
+
+describe("normalizeMount", () => {
+  test("defaults and trims", () => {
+    expect(normalizeMount(undefined)).toBe("/");
+    expect(normalizeMount("/api/")).toBe("/api");
+  });
+  test("rejects a relative path or a query", () => {
+    expect(() => normalizeMount("api")).toThrow(/must start with/);
+    expect(() => normalizeMount("/api?x=1")).toThrow(/mount prefix/);
+  });
+});
+
+describe("hostnameMatches", () => {
+  test("exact and wildcard", () => {
+    expect(hostnameMatches("api.test", "api.test")).toBe(true);
+    expect(hostnameMatches("api.test", "www.api.test")).toBe(false);
+    expect(hostnameMatches("*.api.test", "www.api.test")).toBe(true);
+    expect(hostnameMatches("*.api.test", "a.b.api.test")).toBe(true);
+    expect(hostnameMatches("*.api.test", "api.test")).toBe(false);
+  });
+});
+
+describe("runChain", () => {
+  test("no interceptors reaches the upstream", async () => {
+    const res = await runChain([], req(), upstream);
+    expect(await res.text()).toBe("real");
+  });
+
+  test("a handler that answers stops the chain", async () => {
+    const reg = new InterceptRegistry();
+    reg.register("api.test", undefined, () => new Response("boom", { status: 500 }));
+    let upstreamHit = 0;
+    const res = await runChain(reg.chainFor("api.test", "/x"), req("/x"), async (r) => {
+      upstreamHit++;
+      return upstream(r);
+    });
+    expect(res.status).toBe(500);
+    expect(upstreamHit).toBe(0);
+    const it = reg.chainFor("api.test", "/x")[0]!;
+    expect(it.calls).toBe(1);
+    expect(it.requests[0]).toEqual({ method: "GET", path: "/x", status: 500, answeredBy: "handler" });
+  });
+
+  test("next() reaches the upstream and reports it", async () => {
+    const reg = new InterceptRegistry();
+    const it = reg.register("api.test", undefined, (_r, next) => next());
+    const res = await runChain([it], req("/x?y=1"), upstream);
+    expect(res.status).toBe(200);
+    expect(it.requests[0]).toEqual({ method: "GET", path: "/x?y=1", status: 200, answeredBy: "upstream" });
+  });
+
+  test("a replaced upstream answer reports modified", async () => {
+    const it: Interceptor = new InterceptRegistry().register("api.test", undefined, async (_r, next) => {
+      const real = await next();
+      return new Response(await real.text(), { status: 503 });
+    });
+    const res = await runChain([it], req(), upstream);
+    expect(res.status).toBe(503);
+    expect(it.requests[0]!.answeredBy).toBe("modified");
+  });
+
+  test("next(request) forwards the replacement", async () => {
+    const it = new InterceptRegistry().register("api.test", undefined, (r, next) =>
+      next(new Request(r.url, { method: "POST", headers: { "x-added": "1" } })),
+    );
+    let seen: Request | undefined;
+    await runChain([it], req(), async (r) => {
+      seen = r;
+      return upstream(r);
+    });
+    expect(seen!.method).toBe("POST");
+    expect(seen!.headers.get("x-added")).toBe("1");
+  });
+
+  test("chains run in registration order, each deciding on the next", async () => {
+    const reg = new InterceptRegistry();
+    const order: string[] = [];
+    reg.register("api.test", undefined, (_r, next) => {
+      order.push("first");
+      return next();
+    });
+    reg.register("api.test", "/api", () => {
+      order.push("second");
+      return new Response("second", { status: 418 });
+    });
+    reg.register("api.test", undefined, () => {
+      order.push("third");
+      return new Response("third");
+    });
+    const res = await runChain(reg.chainFor("api.test", "/api/x"), req("/api/x"), upstream);
+    expect(res.status).toBe(418);
+    expect(order).toEqual(["first", "second"]);
+    // A path outside the second mount skips it.
+    order.length = 0;
+    const res2 = await runChain(reg.chainFor("api.test", "/other"), req("/other"), upstream);
+    expect(await res2.text()).toBe("third");
+    expect(order).toEqual(["first", "third"]);
+  });
+
+  test("a throwing handler becomes a 500 naming the host", async () => {
+    const it = new InterceptRegistry().register("api.test", undefined, () => {
+      throw new Error("kaput");
+    });
+    const res = await runChain([it], req(), upstream);
+    expect(res.status).toBe(500);
+    expect(await res.text()).toContain("kaput");
+    expect(it.requests[0]!.answeredBy).toBe("handler");
+  });
+
+  test("a handler that returns nothing is a 500, not a hang", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const it = new InterceptRegistry().register("api.test", undefined, (() => undefined) as any);
+    const res = await runChain([it], req(), upstream);
+    expect(res.status).toBe(500);
+    expect(await res.text()).toContain("returned undefined");
+  });
+
+  test("the observer sees every interceptor that ran", async () => {
+    const reg = new InterceptRegistry();
+    reg.register("api.test", undefined, (_r, next) => next());
+    reg.register("api.test", undefined, () => new Response("x", { status: 404 }));
+    const seen: string[] = [];
+    await runChain(reg.chainFor("api.test", "/"), req(), upstream, (it, rec) => {
+      seen.push(`${it.id}:${rec.status}:${rec.answeredBy}`);
+    });
+    // Inner finishes first (its observer fires as the stack unwinds).
+    expect(seen).toEqual(["2:404:handler", "1:404:upstream"]);
+  });
+});
+
+describe("InterceptRegistry scopes", () => {
+  test("endScope removes what the scope registered and nothing else", () => {
+    const reg = new InterceptRegistry();
+    const global = reg.register("api.test", undefined, (_r, n) => n());
+    reg.beginScope("case-1");
+    reg.register("api.test", "/a", (_r, n) => n());
+    reg.register("api.test", "/b", (_r, n) => n());
+    expect(reg.size()).toBe(3);
+    expect(reg.endScope()).toBe(2);
+    expect(reg.size()).toBe(1);
+    expect(reg.chainFor("api.test", "/a")[0]!.id).toBe(global.id);
+    // Closing again is a no-op.
+    expect(reg.endScope()).toBe(0);
+  });
+
+  test("remove is idempotent", () => {
+    const reg = new InterceptRegistry();
+    const it = reg.register("api.test", undefined, (_r, n) => n());
+    reg.remove(it.id);
+    reg.remove(it.id);
+    expect(reg.size()).toBe(0);
+  });
+});