@specific.dev/spectest 0.61.0 → 0.63.0

package/dist/daemon.js

@@ -21,7 +21,7 @@ import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, resolveServiceImage, proxy as makeProxyDecl, } from "./index.js";
 import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import { applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, nodeCoverageToolsAvailable, nodeCoverageToolsDir, NODE_COVERAGE_TOOLS_CONTAINER_DIR, } from "./coverage.js";
@@ -32,7 +32,7 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
 // exact-then-longest-suffix rule and the one-label certificate rule are
 // each easy to restate subtly differently.
-import { buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
+import { buildArgFlags, buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.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";
@@ -831,7 +832,7 @@ async function prepareServiceImage(svc, opts) {
     // (/workspace) is an input too — a runtime service started mid-test
     // after setup/test code mutated /workspace must rebuild, not share a
     // pre-mutation image.
-    const image = svc.image;
+    const image = dockerfileContent(svc);
     if (opts?.dedup) {
         const key = buildContentKey(image);
         const inflight = BUILD_DEDUP.get(key);
@@ -922,6 +923,16 @@ RUN P='[spectest-ca]'; \\
     fi
 `;
 }
+/** The built form of a dockerfile image. `resolveServiceImage` read a
+ *  `path` into `content` at config time, so a service that still carries
+ *  `path` here skipped that step — a programming error, not user input. */
+function dockerfileContent(svc) {
+    const image = svc.image;
+    if (image.type !== "dockerfile" || typeof image.content !== "string") {
+        throw new Error(`service "${svc.name}" image was not resolved to Dockerfile contents`);
+    }
+    return image;
+}
 /**
  * Build a dockerfile service's image.
  *
@@ -997,6 +1008,9 @@ async function runServiceBuild(name, image, tag, caSuffix) {
         const useBuildKit = useRemote || (await hasBuildx());
         const buildEnv = {};
         let buildArgs;
+        // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
+        // so every builder — host buildkitd, in-VM BuildKit, legacy — takes it.
+        const argFlags = buildArgFlags(image.buildArgs);
         if (useRemote) {
             // Build on the host-side shared buildkitd (persistent cross-VM cache);
             // `--load` brings the finished image back into the in-VM dockerd so
@@ -1007,15 +1021,16 @@ async function runServiceBuild(name, image, tag, caSuffix) {
                 "--builder", REMOTE_BUILDER_NAME,
                 "--load",
                 "--progress=plain",
+                ...argFlags,
                 "-t", tag, "-f", dfPath, WORKSPACE,
             ];
         }
         else if (useBuildKit) {
-            buildArgs = ["build", "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
+            buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
             buildEnv.DOCKER_BUILDKIT = "1";
         }
         else {
-            buildArgs = ["build", "-t", tag, "-f", dfPath, WORKSPACE];
+            buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, WORKSPACE];
         }
         progressService(name, { status: "building", detail: "starting build" });
         const build = await shxStream("docker", buildArgs, 1_800_000, buildEnv, (line) => {
@@ -1979,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);
 }
 /**
@@ -2249,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
@@ -2323,9 +2462,11 @@ const RUNTIME_SERVICES = new Map();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec) {
     const { name, ...rest } = spec;
-    // A runtime spec skipped `defineEnvironment`, so its coverage adapters
-    // get their config-time pass here.
-    return { name, ...applyCoverageAdapters(name, rest) };
+    // A runtime spec skipped `defineEnvironment`, so its config-time passes
+    // run here: a `path` Dockerfile is read into `content`, and coverage
+    // adapters get their configure step.
+    const svc = { ...rest, image: resolveServiceImage(name, rest.image) };
+    return { name, ...applyCoverageAdapters(name, svc) };
 }
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
  *  Prepares the image (pulling on first use through the host cache), runs
@@ -3475,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
@@ -4290,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) => {
@@ -4319,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/build-context.d.ts

@@ -79,4 +79,7 @@ export interface Hasher {
 export declare function buildContentKey(createHasher: () => Hasher, image: {
     content: string;
     exclude?: readonly string[];
+    buildArgs?: Readonly<Record<string, string>>;
 }): string;
+/** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
+export declare function buildArgFlags(buildArgs: Readonly<Record<string, string>> | undefined): string[];

package/dist/harness/build-context.js

@@ -109,5 +109,17 @@ export function buildContentKey(createHasher, image) {
         // genuinely different builds would collapse into one.
         .update("\0")
         .update(JSON.stringify(image.exclude ?? []))
+        // Build args are an input to the image (an ARG picks the base image,
+        // the NODE_ENV of an install step…), so two services on one
+        // Dockerfile with different args must not share a build. Sorted, so
+        // key order in the user's object doesn't split identical builds.
+        .update("\0")
+        .update(JSON.stringify(buildArgFlags(image.buildArgs)))
         .digest("hex"));
 }
+/** `--build-arg NAME=value` pairs, in a stable (sorted) order. */
+export function buildArgFlags(buildArgs) {
+    return Object.entries(buildArgs ?? {})
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .flatMap(([k, v]) => ["--build-arg", `${k}=${v}`]);
+}

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);
+}