@schmock/core 2.2.3 → 2.3.1

package/dist/builder.js

@@ -1,11 +1,130 @@
-import { normalizePath, toHttpMethod } from "./constants.js";
+import { awaitWithAbort, throwIfAborted } from "./abort.js";
+import { isBinaryBody } from "./binary.js";
+import { canonicalizePath, markResponseException, markRouteNotFound, normalizePath, toHttpMethod, } from "./constants.js";
 import { errorMessage, RouteDefinitionError, RouteNotFoundError, SchmockError, } from "./errors.js";
-import { collectBody, parseNodeHeaders, parseNodeQuery, writeSchmockResponse, } from "./http-helpers.js";
+import { collectBody, HttpIngressError, parseNodeHeaders, parseNodeQuery, writeRejectedSchmockResponse, writeSchmockResponse, } from "./http-helpers.js";
 import { createFetchInterceptor } from "./interceptor.js";
 import { parseRouteKey } from "./parser.js";
-import { runPluginPipeline } from "./plugin-pipeline.js";
+import { recoverGeneratorError, runPluginBeforeRequest, runPluginPipeline, } from "./plugin-pipeline.js";
+import { normalizeResponse } from "./response-normalizer.js";
 import { parseResponse } from "./response-parser.js";
 import { extractParams, findRoute, isGeneratorFunction, } from "./route-matcher.js";
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "then" in value &&
+        typeof value.then === "function");
+}
+function unavailableHistoryValue(value) {
+    let type = typeof value;
+    if (typeof value === "object" && value !== null) {
+        try {
+            type = Object.prototype.toString.call(value);
+        }
+        catch {
+            type = "object";
+        }
+    }
+    return {
+        kind: "unavailable",
+        reason: "not-structured-cloneable",
+        type,
+    };
+}
+function removeSharedMemory(value, seen = new WeakMap()) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    const existing = seen.get(value);
+    if (existing !== undefined)
+        return existing;
+    if (typeof SharedArrayBuffer !== "undefined" &&
+        value instanceof SharedArrayBuffer) {
+        const copy = Uint8Array.from(new Uint8Array(value)).buffer;
+        seen.set(value, copy);
+        return copy;
+    }
+    if (ArrayBuffer.isView(value) &&
+        typeof SharedArrayBuffer !== "undefined" &&
+        value.buffer instanceof SharedArrayBuffer) {
+        const copy = Uint8Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+        seen.set(value, copy);
+        return copy;
+    }
+    seen.set(value, value);
+    if (value instanceof Map) {
+        const entries = [...value.entries()];
+        value.clear();
+        for (const [key, entryValue] of entries) {
+            value.set(removeSharedMemory(key, seen), removeSharedMemory(entryValue, seen));
+        }
+        return value;
+    }
+    if (value instanceof Set) {
+        const entries = [...value.values()];
+        value.clear();
+        for (const entryValue of entries) {
+            value.add(removeSharedMemory(entryValue, seen));
+        }
+        return value;
+    }
+    for (const key of Reflect.ownKeys(value)) {
+        Reflect.set(value, key, removeSharedMemory(Reflect.get(value, key), seen));
+    }
+    return value;
+}
+/**
+ * Reject a history limit that cannot bound anything.
+ *
+ * A negative limit used to read as "unbounded" and a fractional one evicted a
+ * fractional number of records, so a typo silently disabled the cap instead of
+ * failing. `Number.isInteger` also rejects NaN and Infinity. `0` stays valid
+ * and keeps meaning "history disabled".
+ */
+function assertValidHistoryLimit(limit) {
+    if (limit === undefined)
+        return;
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new SchmockError(`Invalid maxHistorySize: ${String(limit)}. Expected a non-negative integer (0 disables history).`, "INVALID_CONFIG", { maxHistorySize: limit });
+    }
+}
+/**
+ * Header names whose VALUE is replaced in debug logs. The name is kept so a log
+ * still shows the header was present; only the credential is hidden. Matches
+ * the set the CLI already masks.
+ */
+const REDACTED_HEADER_NAMES = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-auth-token",
+    "x-schmock-admin-token",
+]);
+const REDACTED_HEADER_VALUE = "[redacted]";
+/**
+ * Copy-on-write redaction: the input record is handed on to plugins, history
+ * and transports, so it must never be mutated. When nothing is sensitive the
+ * original object is returned unchanged.
+ */
+function redactSensitiveHeaders(headers) {
+    let redacted;
+    for (const name of Object.keys(headers)) {
+        if (!REDACTED_HEADER_NAMES.has(name.toLowerCase()))
+            continue;
+        redacted ??= { ...headers };
+        redacted[name] = REDACTED_HEADER_VALUE;
+    }
+    return redacted ?? headers;
+}
+function snapshotHistoryValue(value) {
+    try {
+        return removeSharedMemory(structuredClone(value));
+    }
+    catch {
+        return unavailableHistoryValue(value);
+    }
+}
 /**
  * Debug logger that respects debug mode configuration
  */
@@ -43,7 +162,6 @@ class DebugLogger {
  * @internal
  */
 export class CallableMockInstance {
-    globalConfig;
     routes = [];
     staticRoutes = new Map();
     plugins = [];
@@ -51,12 +169,21 @@ export class CallableMockInstance {
     requestHistory = [];
     callableRef;
     server;
-    serverInfo;
-    interceptHandle = null;
+    pendingServerStart;
+    serverCloseBarrier;
+    interceptHandles = new Set();
+    requestGeneration = { activeAdmissions: 0 };
+    historyGeneration = Symbol("schmock.history.generation");
+    interceptOwner = Symbol("schmock.intercept.owner");
+    globalConfig;
     // biome-ignore lint/complexity/noBannedTypes: internal storage for event listeners with varying signatures
     listeners = new Map();
     constructor(globalConfig = {}) {
-        this.globalConfig = globalConfig;
+        assertValidHistoryLimit(globalConfig.maxHistorySize);
+        this.globalConfig = {
+            ...globalConfig,
+            state: globalConfig.state ?? {},
+        };
         this.logger = new DebugLogger(globalConfig.debug || false);
         if (globalConfig.debug) {
             this.logger.log("config", "Debug mode enabled");
@@ -83,8 +210,8 @@ export class CallableMockInstance {
                 // Default to plain text for primitives
                 routeConfig.contentType = "text/plain";
             }
-            else if (Buffer.isBuffer(generator)) {
-                // Default to octet-stream for buffers
+            else if (isBinaryBody(generator)) {
+                // Default to octet-stream for browser and Node binary values
                 routeConfig.contentType = "application/octet-stream";
             }
             else {
@@ -139,6 +266,82 @@ export class CallableMockInstance {
         this.callableRef = ref;
     }
     pipe(plugin) {
+        if (plugin.install && this.callableRef) {
+            const previousRoutes = this.routes;
+            const previousStaticRoutes = this.staticRoutes;
+            this.routes = previousRoutes.slice();
+            this.staticRoutes = new Map(previousStaticRoutes);
+            let installActive = true;
+            let installFacade;
+            const requireInstallScope = () => {
+                if (installActive)
+                    return;
+                throw new SchmockError(`Plugin "${plugin.name}" used its install instance outside install()`, "PLUGIN_INSTALL_SCOPE_EXPIRED", { plugin: plugin.name });
+            };
+            const rejectInstallOperation = (operation) => {
+                requireInstallScope();
+                throw new SchmockError(`Plugin "${plugin.name}" cannot call ${operation} during install()`, "PLUGIN_INSTALL_OPERATION_UNSUPPORTED", { operation, plugin: plugin.name });
+            };
+            const registerRoute = (route, generator, config = {}) => {
+                requireInstallScope();
+                this.defineRoute(route, generator, config);
+                return installFacade;
+            };
+            installFacade = Object.assign(registerRoute, {
+                pipe: () => rejectInstallOperation("pipe()"),
+                handle: () => rejectInstallOperation("handle()"),
+                history: (method, path) => {
+                    requireInstallScope();
+                    return this.history(method, path);
+                },
+                called: (method, path) => {
+                    requireInstallScope();
+                    return this.called(method, path);
+                },
+                callCount: (method, path) => {
+                    requireInstallScope();
+                    return this.callCount(method, path);
+                },
+                lastRequest: (method, path) => {
+                    requireInstallScope();
+                    return this.lastRequest(method, path);
+                },
+                reset: () => rejectInstallOperation("reset()"),
+                resetHistory: () => rejectInstallOperation("resetHistory()"),
+                resetState: () => rejectInstallOperation("resetState()"),
+                on: () => rejectInstallOperation("on()"),
+                off: () => rejectInstallOperation("off()"),
+                getRoutes: () => {
+                    requireInstallScope();
+                    return this.getRoutes();
+                },
+                getState: () => {
+                    requireInstallScope();
+                    return this.getState();
+                },
+                listen: () => rejectInstallOperation("listen()"),
+                close: () => rejectInstallOperation("close()"),
+                intercept: () => rejectInstallOperation("intercept()"),
+            });
+            try {
+                const installResult = plugin.install(installFacade);
+                installActive = false;
+                if (isThenable(installResult)) {
+                    void Promise.resolve(installResult).catch((error) => {
+                        this.logger.log("plugin", `Rejected async install for ${plugin.name}: ${errorMessage(error)}`);
+                    });
+                    throw new SchmockError(`Plugin "${plugin.name}" returned a Promise from install()`, "PLUGIN_ASYNC_INSTALL_UNSUPPORTED", { plugin: plugin.name });
+                }
+            }
+            catch (error) {
+                this.routes = previousRoutes;
+                this.staticRoutes = previousStaticRoutes;
+                throw error;
+            }
+            finally {
+                installActive = false;
+            }
+        }
         this.plugins.push(plugin);
         this.logger.log("plugin", `Registered plugin: ${plugin.name}@${plugin.version || "unknown"}`, {
             name: plugin.name,
@@ -146,52 +349,79 @@ export class CallableMockInstance {
             hasProcess: typeof plugin.process === "function",
             hasOnError: typeof plugin.onError === "function",
         });
-        if (plugin.install && this.callableRef) {
-            plugin.install(this.callableRef);
-        }
         return this;
     }
+    uninstallPlugins(plugins) {
+        for (let index = plugins.length - 1; index >= 0; index -= 1) {
+            const plugin = plugins[index];
+            if (!plugin.uninstall || !this.callableRef)
+                continue;
+            try {
+                const uninstallResult = plugin.uninstall(this.callableRef);
+                if (isThenable(uninstallResult)) {
+                    void Promise.resolve(uninstallResult).catch((error) => {
+                        this.logger.log("plugin", `Async uninstall for ${plugin.name} failed: ${errorMessage(error)}`);
+                    });
+                    this.logger.log("plugin", `Plugin ${plugin.name} returned an unsupported Promise from uninstall()`);
+                }
+            }
+            catch (error) {
+                this.logger.log("plugin", `Plugin ${plugin.name} uninstall failed: ${errorMessage(error)}`);
+            }
+        }
+    }
     // ===== Request Spy / History API =====
+    cloneRecord(r) {
+        return {
+            method: r.method,
+            path: r.path,
+            params: { ...r.params },
+            query: { ...r.query },
+            headers: { ...r.headers },
+            body: snapshotHistoryValue(r.body),
+            timestamp: r.timestamp,
+            response: {
+                status: r.response.status,
+                body: snapshotHistoryValue(r.response.body),
+            },
+        };
+    }
     /**
-     * FIX 2.3: Deep-clone a request record so callers cannot corrupt internal
-     * history by mutating nested body/response objects.
-     * Falls back to a shallow spread for bodies that are not structuredClone-able
-     * (e.g. Buffers, streams — rare in practice but defensively handled).
+     * History stores the canonical request path — percent-encoded and
+     * trailing-slash-normalized exactly as `handle()` produced it — so a spy
+     * filter must be put into the same form before it is compared, or the very
+     * string the caller passed to `handle()` would not match its own record.
+     * `canonicalizePath` is idempotent, so an already-encoded filter keeps
+     * matching and both spellings work.
      */
-    cloneRecord(r) {
-        try {
-            return structuredClone(r);
-        }
-        catch {
-            return {
-                ...r,
-                response: { ...r.response },
-            };
-        }
+    #historyMatcher(method, path) {
+        const wanted = path === undefined ? undefined : normalizePath(canonicalizePath(path));
+        return (r) => (!method || r.method === method) && (!wanted || r.path === wanted);
     }
     history(method, path) {
         if (method || path) {
             return this.requestHistory
-                .filter((r) => (!method || r.method === method) && (!path || r.path === path))
+                .filter(this.#historyMatcher(method, path))
                 .map((r) => this.cloneRecord(r));
         }
         return this.requestHistory.map((r) => this.cloneRecord(r));
     }
     called(method, path) {
         if (method || path) {
-            return this.requestHistory.some((r) => (!method || r.method === method) && (!path || r.path === path));
+            return this.requestHistory.some(this.#historyMatcher(method, path));
         }
         return this.requestHistory.length > 0;
     }
     callCount(method, path) {
         if (method || path) {
-            return this.requestHistory.filter((r) => (!method || r.method === method) && (!path || r.path === path)).length;
+            return this.requestHistory.filter(this.#historyMatcher(method, path))
+                .length;
         }
         return this.requestHistory.length;
     }
     lastRequest(method, path) {
         if (method || path) {
-            const filtered = this.requestHistory.filter((r) => (!method || r.method === method) && (!path || r.path === path));
+            const filtered = this.requestHistory.filter(this.#historyMatcher(method, path));
             const last = filtered[filtered.length - 1];
             // FIX 2.3: return a deep clone so callers cannot corrupt internal history
             return last ? this.cloneRecord(last) : undefined;
@@ -227,202 +457,429 @@ export class CallableMockInstance {
     }
     emit(event, data) {
         const set = this.listeners.get(event);
-        if (set) {
-            for (const listener of set) {
-                listener(data);
+        if (!set)
+            return;
+        const snapshot = { ...data };
+        if ("headers" in data) {
+            snapshot.headers = Object.freeze({ ...data.headers });
+        }
+        if ("params" in data) {
+            snapshot.params = Object.freeze({ ...data.params });
+        }
+        const eventData = Object.freeze(snapshot);
+        for (const listener of [...set]) {
+            try {
+                const listenerResult = listener(eventData);
+                if (isThenable(listenerResult)) {
+                    void Promise.resolve(listenerResult).catch((error) => {
+                        this.logger.log("event", `${event} listener rejected: ${errorMessage(error)}`);
+                    });
+                }
+            }
+            catch (error) {
+                this.logger.log("event", `${event} listener failed: ${errorMessage(error)}`);
             }
         }
     }
     // ===== Reset / Lifecycle =====
     reset() {
-        this.interceptHandle?.restore();
-        this.interceptHandle = null;
+        const retiredGeneration = this.requestGeneration;
+        this.requestGeneration = { activeAdmissions: 0 };
+        this.historyGeneration = Symbol("schmock.history.generation");
         this.close();
+        const installedPlugins = this.plugins;
+        this.plugins = [];
+        this.#retireRequestGeneration(retiredGeneration, installedPlugins);
         this.routes = [];
         this.staticRoutes.clear();
-        this.plugins = [];
         this.requestHistory = [];
         this.listeners.clear();
-        // FIX 3.3: assign a fresh object instead of deleting keys off the caller's
-        // reference — this avoids mutating the external state object passed by the user
-        if (this.globalConfig.state) {
-            this.globalConfig.state = {};
-        }
+        this.globalConfig.state = {};
         this.logger.log("lifecycle", "Mock fully reset");
     }
     resetHistory() {
+        this.historyGeneration = Symbol("schmock.history.generation");
         this.requestHistory = [];
         this.logger.log("lifecycle", "Request history cleared");
     }
     resetState() {
-        // FIX 3.3: assign a fresh object instead of deleting keys off the caller's
-        // reference — this avoids mutating the external state object passed by the user
-        if (this.globalConfig.state) {
-            this.globalConfig.state = {};
-        }
+        this.globalConfig.state = {};
         this.logger.log("lifecycle", "State cleared");
     }
+    #captureRequestAdmission() {
+        const requestGeneration = this.requestGeneration;
+        requestGeneration.activeAdmissions += 1;
+        return {
+            requestGeneration,
+            historyGeneration: this.historyGeneration,
+            plugins: this.plugins.slice(),
+            routes: this.routes.slice(),
+            staticRoutes: new Map(this.staticRoutes),
+            state: this.globalConfig.state,
+            namespace: this.globalConfig.namespace,
+            globalDelay: this.globalConfig.delay,
+            maxHistorySize: this.globalConfig.maxHistorySize,
+            released: false,
+        };
+    }
+    #releaseRequestAdmission(admission) {
+        if (admission.released)
+            return;
+        admission.released = true;
+        const generation = admission.requestGeneration;
+        generation.activeAdmissions -= 1;
+        if (generation.activeAdmissions === 0 &&
+            generation.retiredPlugins !== undefined) {
+            const plugins = generation.retiredPlugins;
+            generation.retiredPlugins = undefined;
+            this.uninstallPlugins(plugins);
+        }
+    }
+    #retireRequestGeneration(generation, plugins) {
+        generation.retiredPlugins = plugins;
+        if (generation.activeAdmissions === 0) {
+            generation.retiredPlugins = undefined;
+            this.uninstallPlugins(plugins);
+        }
+    }
+    createRequestAdmission() {
+        const admission = this.#captureRequestAdmission();
+        return {
+            handle: (method, path, options) => this.handle(method, path, options, admission),
+            release: () => this.#releaseRequestAdmission(admission),
+        };
+    }
     // ===== Standalone Server =====
     listen(port = 0, hostname = "127.0.0.1") {
-        if (this.server) {
+        if (this.server || this.pendingServerStart) {
             throw new SchmockError("Server is already running", "SERVER_ALREADY_RUNNING");
         }
-        // Lazy-load node:http so browser bundles never pull it in. See issue #395.
-        return import("node:http").then(({ createServer }) => this.#startHttpServer(createServer, port, hostname));
+        let resolveStart = (_info) => { };
+        let rejectStart = (_error) => { };
+        const startPromise = new Promise((resolve, reject) => {
+            resolveStart = resolve;
+            rejectStart = reject;
+        });
+        const operation = {
+            token: Symbol("schmock.server.start"),
+            port,
+            hostname,
+            resolve: resolveStart,
+            reject: rejectStart,
+            settled: false,
+        };
+        this.pendingServerStart = operation;
+        const closeBarrier = this.serverCloseBarrier ?? Promise.resolve();
+        void closeBarrier
+            // Lazy-load node:http so browser bundles never pull it in. See issue #395.
+            .then(() => import("node:http"))
+            .then(({ createServer }) => {
+            if (!this.#ownsServerStart(operation))
+                return;
+            this.#startHttpServer(operation, createServer);
+        })
+            .catch((error) => {
+            this.#rejectServerStart(operation, error);
+        });
+        return startPromise;
+    }
+    #ownsServerStart(operation) {
+        return this.pendingServerStart === operation && !operation.settled;
     }
-    #startHttpServer(createServer, port, hostname) {
+    #startHttpServer(operation, createServer) {
         const httpServer = createServer((req, res) => {
+            const admittedRequest = this.createRequestAdmission();
+            const abortController = new AbortController();
+            const abortRequest = () => abortController.abort();
+            req.once("aborted", abortRequest);
+            res.once("close", abortRequest);
+            let requestMethod = req.method?.toUpperCase() === "HEAD" ? "HEAD" : "GET";
             const handleRequest = async () => {
-                const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
-                const method = toHttpMethod(req.method ?? "GET");
-                const path = url.pathname;
-                const headers = parseNodeHeaders(req);
-                const query = parseNodeQuery(url);
-                const body = await collectBody(req, headers);
-                const schmockResponse = await this.handle(method, path, {
-                    headers,
-                    body,
-                    query,
-                });
-                writeSchmockResponse(res, schmockResponse);
+                try {
+                    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+                    const method = toHttpMethod(req.method ?? "GET");
+                    requestMethod = method;
+                    const path = url.pathname;
+                    const headers = parseNodeHeaders(req);
+                    const query = parseNodeQuery(url);
+                    const body = await collectBody(req, headers);
+                    const schmockResponse = await admittedRequest.handle(method, path, {
+                        headers,
+                        body,
+                        query,
+                        signal: abortController.signal,
+                    });
+                    writeSchmockResponse(res, schmockResponse);
+                }
+                finally {
+                    req.off("aborted", abortRequest);
+                    res.off("close", abortRequest);
+                    admittedRequest.release();
+                }
             };
             handleRequest().catch((error) => {
-                if (!res.headersSent) {
-                    res.writeHead(500, { "content-type": "application/json" });
+                // A failing error-response write must never escape this handler as an
+                // unhandled rejection: destroy the socket so the client is not left
+                // hanging on a response that will never arrive.
+                try {
+                    const ingressError = error instanceof HttpIngressError ? error : undefined;
+                    const status = ingressError?.status ?? 500;
+                    const code = ingressError?.code ?? "SERVER_ERROR";
+                    if (!res.headersSent && !res.writableEnded) {
+                        if (ingressError)
+                            res.shouldKeepAlive = false;
+                        // `shouldKeepAlive = false` alone emits no Connection header when
+                        // writeHead is given a header object, so the announcement has to be
+                        // explicit. It travels on the transport's own header channel rather
+                        // than on the response: normalizeResponse strips hop-by-hop headers
+                        // from everything a route produces.
+                        const transportHeaders = ingressError
+                            ? { connection: "close" }
+                            : undefined;
+                        const response = normalizeResponse({
+                            status,
+                            body: {
+                                error: error instanceof Error
+                                    ? error.message
+                                    : "Internal Server Error",
+                                code,
+                            },
+                            headers: { "content-type": "application/json" },
+                        }, requestMethod);
+                        if (ingressError?.status === 413) {
+                            writeRejectedSchmockResponse(req, res, response, transportHeaders);
+                        }
+                        else {
+                            writeSchmockResponse(res, response, transportHeaders);
+                        }
+                    }
+                    else if (!res.writableEnded) {
+                        res.end();
+                    }
+                }
+                catch {
+                    res.destroy();
                 }
-                res.end(JSON.stringify({
-                    error: error instanceof Error ? error.message : "Internal Server Error",
-                    code: "SERVER_ERROR",
-                }));
             });
         });
-        this.server = httpServer;
-        return new Promise((resolve, reject) => {
-            httpServer.on("error", reject);
-            httpServer.listen(port, hostname, () => {
+        operation.server = httpServer;
+        const handleStartupError = (error) => {
+            this.#rejectServerStart(operation, error);
+        };
+        httpServer.once("error", handleStartupError);
+        try {
+            httpServer.listen(operation.port, operation.hostname, () => {
+                httpServer.off("error", handleStartupError);
+                if (!this.#ownsServerStart(operation)) {
+                    this.#beginServerClose(httpServer);
+                    return;
+                }
                 const addr = httpServer.address();
-                const actualPort = addr !== null && typeof addr === "object" ? addr.port : port;
-                this.serverInfo = { port: actualPort, hostname };
-                this.logger.log("server", `Listening on ${hostname}:${actualPort}`);
-                resolve(this.serverInfo);
+                const actualPort = addr !== null && typeof addr === "object"
+                    ? addr.port
+                    : operation.port;
+                const info = { port: actualPort, hostname: operation.hostname };
+                operation.settled = true;
+                this.pendingServerStart = undefined;
+                this.server = httpServer;
+                this.logger.log("server", `Listening on ${operation.hostname}:${actualPort}`);
+                operation.resolve(info);
             });
+        }
+        catch (error) {
+            httpServer.off("error", handleStartupError);
+            this.#rejectServerStart(operation, error);
+        }
+    }
+    #rejectServerStart(operation, error) {
+        if (operation.settled)
+            return;
+        operation.settled = true;
+        if (this.pendingServerStart === operation) {
+            this.pendingServerStart = undefined;
+        }
+        if (operation.server) {
+            this.#beginServerClose(operation.server);
+        }
+        operation.reject(error);
+    }
+    #cancelServerStart() {
+        const operation = this.pendingServerStart;
+        if (!operation)
+            return;
+        this.#rejectServerStart(operation, new SchmockError("Server start was cancelled", "SERVER_START_CANCELLED"));
+    }
+    #beginServerClose(server) {
+        const closePromise = new Promise((resolve) => {
+            try {
+                server.close(() => resolve());
+            }
+            catch {
+                resolve();
+            }
+        });
+        try {
+            server.closeAllConnections();
+        }
+        catch {
+            // A not-yet-listening server has no connections to close.
+        }
+        const previousBarrier = this.serverCloseBarrier ?? Promise.resolve();
+        const combinedBarrier = Promise.all([previousBarrier, closePromise]).then(() => undefined);
+        this.serverCloseBarrier = combinedBarrier;
+        void combinedBarrier.finally(() => {
+            if (this.serverCloseBarrier === combinedBarrier) {
+                this.serverCloseBarrier = undefined;
+            }
         });
     }
     close() {
-        if (!this.server) {
+        this.#cancelServerStart();
+        const server = this.server;
+        if (!server)
             return;
-        }
-        this.server.closeAllConnections();
-        this.server.close();
         this.server = undefined;
-        this.serverInfo = undefined;
+        this.#beginServerClose(server);
         this.logger.log("server", "Server stopped");
     }
     // ===== Fetch Interceptor =====
     intercept(options) {
-        if (this.interceptHandle?.active) {
-            throw new SchmockError("Already intercepting. Call restore() first.", "ALREADY_INTERCEPTING");
+        // Ownership is a lease, not a lock: nested providers, separate roots, and
+        // a manual intercept() alongside an adapter each get their own registry
+        // slot with their own options, released independently. The owner symbol
+        // keeps them one mock for dispatch, so a single request reaches handle()
+        // once no matter how many leases this instance holds.
+        const lease = createFetchInterceptor((method, path, opts) => this.handle(method, path, opts), options, () => this.createRequestAdmission(), this.interceptOwner);
+        const handle = {
+            restore: () => {
+                lease.restore();
+                if (this.interceptHandles.delete(handle)) {
+                    this.logger.log("lifecycle", `Interception lease released (${this.interceptHandles.size} still held)`);
+                }
+            },
+            update: (nextOptions) => {
+                lease.update(nextOptions);
+            },
+            get active() {
+                return lease.active;
+            },
+        };
+        this.interceptHandles.add(handle);
+        this.logger.log("lifecycle", `Interception lease acquired (${this.interceptHandles.size} held)`);
+        return handle;
+    }
+    async handle(method, path, options, admission) {
+        const requestAdmission = admission ?? this.#captureRequestAdmission();
+        try {
+            return await this.#handleAdmittedRequest(method, path, options, requestAdmission);
+        }
+        finally {
+            this.#releaseRequestAdmission(requestAdmission);
         }
-        this.interceptHandle = createFetchInterceptor((method, path, opts) => this.handle(method, path, opts), options);
-        return this.interceptHandle;
     }
-    async handle(method, path, options) {
+    async #handleAdmittedRequest(method, requestedPath, options, admission) {
+        // Canonicalize before anything observes the path: a transport hands over an
+        // already-encoded `url.pathname` while a direct handle() caller may type
+        // literal unicode, and every lifecycle event, log line and 404 message must
+        // report the same spelling.
+        const path = canonicalizePath(requestedPath);
+        const requestGeneration = admission.requestGeneration;
+        const historyGeneration = admission.historyGeneration;
+        const requestPlugins = admission.plugins;
+        const requestRoutes = admission.routes;
+        const requestStaticRoutes = admission.staticRoutes;
+        const requestState = admission.state;
+        const namespace = admission.namespace;
+        const globalDelay = admission.globalDelay;
+        const maxHistorySize = admission.maxHistorySize;
+        const signal = options?.signal;
+        throwIfAborted(signal);
         const handleStart = performance.now();
         const requestId = this.globalConfig.debug ? crypto.randomUUID() : "";
-        const reqQuery = options?.query || {};
-        const reqHeaders = options?.headers || {};
+        const reqQuery = { ...(options?.query ?? {}) };
+        const reqHeaders = { ...(options?.headers ?? {}) };
+        const requestBody = options?.body;
         this.logger.log("request", `[${requestId}] ${method} ${path}`, {
-            headers: reqHeaders,
+            headers: redactSensitiveHeaders(reqHeaders),
             query: reqQuery,
-            bodyType: options?.body ? typeof options.body : "none",
+            // Presence, not truthiness: "", 0 and false are bodies too.
+            bodyType: options !== undefined && "body" in options && options.body !== undefined
+                ? typeof options.body
+                : "none",
         });
         this.logger.time(`request-${requestId}`);
-        this.emit("request:start", {
-            method,
-            path,
-            headers: reqHeaders,
-        });
+        if (this.requestGeneration === requestGeneration) {
+            this.emit("request:start", {
+                method,
+                path,
+                headers: reqHeaders,
+            });
+        }
+        // Hoisted so the catch block can finalize a matched request the same way
+        // the success path does — same delay override, same history record.
+        let requestPath = path;
+        let matchedRoute;
+        let params = {};
         try {
             // Apply namespace if configured
-            let requestPath = path;
-            if (this.globalConfig.namespace && this.globalConfig.namespace !== "/") {
-                const namespace = this.globalConfig.namespace.startsWith("/")
-                    ? this.globalConfig.namespace
-                    : `/${this.globalConfig.namespace}`;
+            if (namespace && namespace !== "/") {
+                const normalizedNamespace = canonicalizePath(namespace.startsWith("/") ? namespace : `/${namespace}`);
                 const pathToCheck = path.startsWith("/") ? path : `/${path}`;
                 // Check if path starts with namespace
                 // handle both "/api/users" (starts with /api) and "/api" (exact match)
                 // but NOT "/apiv2" (prefix match but wrong segment)
-                const isMatch = pathToCheck === namespace ||
-                    pathToCheck.startsWith(namespace.endsWith("/") ? namespace : `${namespace}/`);
+                const isMatch = pathToCheck === normalizedNamespace ||
+                    pathToCheck.startsWith(normalizedNamespace.endsWith("/")
+                        ? normalizedNamespace
+                        : `${normalizedNamespace}/`);
                 if (!isMatch) {
-                    this.logger.log("route", `[${requestId}] Path doesn't match namespace ${namespace}`);
-                    const error = new RouteNotFoundError(method, path);
-                    const response = {
-                        status: 404,
-                        body: { error: error.message, code: error.code },
-                        headers: {},
-                    };
-                    this.emit("request:end", {
+                    this.logger.log("route", `[${requestId}] Path doesn't match namespace ${normalizedNamespace}`);
+                    // A request outside the namespace is a route miss like any other, so
+                    // it reports one instead of silently ending.
+                    return this.#finalizeMiss({
                         method,
                         path,
-                        status: 404,
-                        duration: performance.now() - handleStart,
+                        requestId,
+                        handleStart,
+                        requestGeneration,
                     });
-                    this.logger.timeEnd(`request-${requestId}`);
-                    return response;
                 }
                 // Remove namespace prefix, ensuring we always start with /
-                const stripped = pathToCheck.slice(namespace.length);
+                const stripped = pathToCheck.slice(normalizedNamespace.length);
                 requestPath = stripped.startsWith("/") ? stripped : `/${stripped}`;
             }
+            // One trailing-slash normalization for the whole request: route lookup
+            // and parameter extraction must see the identical string, or a request
+            // could match a route and then capture no parameters.
+            requestPath = normalizePath(requestPath);
             // Find matching route
-            const matchedRoute = findRoute(method, requestPath, this.staticRoutes, this.routes);
+            matchedRoute = findRoute(method, requestPath, requestStaticRoutes, requestRoutes);
             if (!matchedRoute) {
                 this.logger.log("route", `[${requestId}] No route found for ${method} ${requestPath}`);
-                this.emit("request:notfound", { method, path: requestPath });
-                const error = new RouteNotFoundError(method, path);
-                const response = {
-                    status: 404,
-                    body: { error: error.message, code: error.code },
-                    headers: {},
-                };
-                this.emit("request:end", {
+                return this.#finalizeMiss({
                     method,
-                    path: requestPath,
-                    status: 404,
-                    duration: performance.now() - handleStart,
+                    path,
+                    requestId,
+                    handleStart,
+                    requestGeneration,
                 });
-                this.logger.timeEnd(`request-${requestId}`);
-                return response;
             }
             this.logger.log("route", `[${requestId}] Matched route: ${method} ${matchedRoute.path}`);
             // Extract parameters from the matched route
-            const params = extractParams(matchedRoute, requestPath);
-            this.emit("request:match", {
-                method,
-                path: requestPath,
-                routePath: matchedRoute.path,
-                params,
-            });
-            // Generate initial response from route handler
-            const context = {
-                method,
-                path: requestPath,
-                params,
-                query: reqQuery,
-                headers: reqHeaders,
-                body: options?.body,
-                state: this.globalConfig.state || {},
-            };
-            let result;
-            if (isGeneratorFunction(matchedRoute.generator)) {
-                result = await matchedRoute.generator(context);
-            }
-            else {
-                result = matchedRoute.generator;
+            params = extractParams(matchedRoute, requestPath);
+            if (this.requestGeneration === requestGeneration) {
+                this.emit("request:match", {
+                    method,
+                    // Every lifecycle event carries the ORIGINAL request path; the
+                    // namespace-stripped route form is exposed as routePath.
+                    path,
+                    routePath: matchedRoute.path,
+                    params,
+                });
             }
-            // Build plugin context
+            throwIfAborted(signal);
+            // Build plugin context before route code so request guards can reject
+            // invalid or unauthorized requests without triggering side effects.
             let pluginContext = {
                 path: requestPath,
                 route: matchedRoute.config,
@@ -430,94 +887,238 @@ export class CallableMockInstance {
                 params,
                 query: reqQuery,
                 headers: reqHeaders,
-                body: options?.body,
+                body: requestBody,
                 state: new Map(),
-                routeState: this.globalConfig.state || {},
+                routeState: requestState,
+                signal,
             };
+            const preflightResult = await runPluginBeforeRequest(requestPlugins, pluginContext, this.logger, signal);
+            throwIfAborted(signal);
+            pluginContext = preflightResult.context;
+            if (preflightResult.requestShortCircuited === true) {
+                pluginContext = { ...pluginContext, requestShortCircuited: true };
+            }
+            let result = preflightResult.response;
+            let skipPostProcessing = preflightResult.recoveredFromError === true;
+            if (result === undefined) {
+                const context = {
+                    method: pluginContext.method,
+                    path: pluginContext.path,
+                    params: pluginContext.params,
+                    query: pluginContext.query,
+                    headers: pluginContext.headers,
+                    body: pluginContext.body,
+                    state: pluginContext.routeState ?? requestState,
+                    pluginState: pluginContext.state,
+                    signal,
+                };
+                try {
+                    if (isGeneratorFunction(matchedRoute.generator)) {
+                        result = await awaitWithAbort(matchedRoute.generator(context), signal);
+                    }
+                    else {
+                        result = matchedRoute.generator;
+                    }
+                    throwIfAborted(signal);
+                }
+                catch (error) {
+                    throwIfAborted(signal);
+                    const recovery = await recoverGeneratorError(requestPlugins, pluginContext, error, this.logger, signal);
+                    throwIfAborted(signal);
+                    pluginContext = recovery.context;
+                    result = recovery.response;
+                    skipPostProcessing = recovery.recoveredFromError === true;
+                }
+            }
             // Run plugin pipeline to transform the response
             try {
-                const pipelineResult = await runPluginPipeline(this.plugins, pluginContext, result, this.logger);
-                pluginContext = pipelineResult.context;
-                result = pipelineResult.response;
+                if (skipPostProcessing) {
+                    this.logger.log("pipeline", "Skipping response processors after error recovery");
+                }
+                else {
+                    const pipelineResult = await runPluginPipeline(requestPlugins, pluginContext, result, this.logger, signal);
+                    throwIfAborted(signal);
+                    pluginContext = pipelineResult.context;
+                    result = pipelineResult.response;
+                }
             }
             catch (error) {
                 this.logger.log("error", `[${requestId}] Plugin pipeline error: ${errorMessage(error)}`);
                 throw error;
             }
             // Parse and prepare response
-            const response = parseResponse(result, matchedRoute.config);
-            // Apply delay (route-level overrides global)
-            await this.applyDelay(matchedRoute.config.delay);
-            // Record request in history (FIFO-bounded when maxHistorySize is set)
-            this.requestHistory.push({
+            const response = normalizeResponse(parseResponse(result, matchedRoute.config), method);
+            await this.#finalizeMatchedRequest({
                 method,
-                path: requestPath,
+                path,
+                requestPath,
                 params,
-                query: reqQuery,
-                headers: reqHeaders,
-                body: options?.body,
-                timestamp: Date.now(),
-                response: { status: response.status, body: response.body },
-            });
-            const maxHistorySize = this.globalConfig.maxHistorySize;
-            if (typeof maxHistorySize === "number" &&
-                maxHistorySize >= 0 &&
-                this.requestHistory.length > maxHistorySize) {
-                this.requestHistory.splice(0, this.requestHistory.length - maxHistorySize);
-            }
-            this.emit("request:end", {
-                method,
-                path: requestPath,
-                status: response.status,
-                duration: performance.now() - handleStart,
+                reqQuery,
+                reqHeaders,
+                requestBody,
+                response,
+                routeDelay: matchedRoute.config.delay,
+                globalDelay,
+                record: true,
+                signal,
+                requestGeneration,
+                historyGeneration,
+                maxHistorySize,
+                requestId,
+                handleStart,
             });
-            // Log successful response
-            this.logger.log("response", `[${requestId}] Sending response ${response.status}`, {
-                status: response.status,
-                headers: response.headers,
-                bodyType: typeof response.body,
-            });
-            this.logger.timeEnd(`request-${requestId}`);
             return response;
         }
         catch (error) {
+            throwIfAborted(signal);
             this.logger.log("error", `[${requestId}] Error processing request: ${errorMessage(error)}`, error);
             // Return error response
-            const errorResponse = {
+            const responseError = error instanceof Error ? error : new Error(errorMessage(error));
+            const errorResponse = markResponseException(normalizeResponse({
                 status: 500,
                 body: {
-                    error: errorMessage(error),
+                    error: responseError.message,
                     code: error instanceof SchmockError ? error.code : "INTERNAL_ERROR",
                 },
-                headers: {},
-            };
-            // Apply delay even for error responses
-            await this.applyDelay();
-            this.emit("request:end", {
+                headers: { "content-type": "application/json" },
+            }, method), responseError);
+            // A request that matched a route did happen: it is finalized exactly like
+            // a successful one — its own delay override, and a history record.
+            await this.#finalizeMatchedRequest({
                 method,
                 path,
-                status: 500,
-                duration: performance.now() - handleStart,
+                requestPath,
+                params,
+                reqQuery,
+                reqHeaders,
+                requestBody,
+                response: errorResponse,
+                routeDelay: matchedRoute?.config.delay,
+                globalDelay,
+                record: matchedRoute !== undefined,
+                signal,
+                requestGeneration,
+                historyGeneration,
+                maxHistorySize,
+                requestId,
+                handleStart,
             });
-            this.logger.log("error", `[${requestId}] Returning error response 500`);
-            this.logger.timeEnd(`request-${requestId}`);
             return errorResponse;
         }
     }
+    /**
+     * Finish a request that matched a route.
+     *
+     * Order matters: delay first (an abort during it must escape before anything
+     * is committed), then the history record, then `request:end`, then the logs.
+     */
+    async #finalizeMatchedRequest(input) {
+        const { response, maxHistorySize } = input;
+        // Apply delay (route-level overrides global)
+        await this.applyDelay(input.routeDelay, input.globalDelay, input.signal);
+        throwIfAborted(input.signal);
+        // Record request in history (FIFO-bounded when maxHistorySize is set)
+        if (input.record &&
+            this.requestGeneration === input.requestGeneration &&
+            this.historyGeneration === input.historyGeneration &&
+            maxHistorySize !== 0) {
+            this.requestHistory.push({
+                method: input.method,
+                path: input.requestPath,
+                params: { ...input.params },
+                query: { ...input.reqQuery },
+                headers: { ...input.reqHeaders },
+                body: snapshotHistoryValue(input.requestBody),
+                timestamp: Date.now(),
+                response: {
+                    status: response.status,
+                    body: snapshotHistoryValue(response.body),
+                },
+            });
+            // The constructor already rejected a limit that is not a non-negative
+            // integer, so a plain comparison is enough here.
+            if (maxHistorySize !== undefined &&
+                this.requestHistory.length > maxHistorySize) {
+                this.requestHistory.splice(0, this.requestHistory.length - maxHistorySize);
+            }
+        }
+        if (this.requestGeneration === input.requestGeneration) {
+            this.emit("request:end", {
+                method: input.method,
+                path: input.path,
+                status: response.status,
+                duration: performance.now() - input.handleStart,
+            });
+        }
+        this.logger.log("response", `[${input.requestId}] Sending response ${response.status}`, {
+            status: response.status,
+            headers: redactSensitiveHeaders(response.headers),
+            bodyType: typeof response.body,
+        });
+        this.logger.timeEnd(`request-${input.requestId}`);
+    }
+    /**
+     * Finish a request that matched no route — an unknown path or one outside the
+     * configured namespace. Misses stay delay-free and out of history: nothing
+     * ran, so there is nothing to record.
+     */
+    #finalizeMiss(input) {
+        if (this.requestGeneration === input.requestGeneration) {
+            this.emit("request:notfound", {
+                method: input.method,
+                path: input.path,
+            });
+        }
+        const error = new RouteNotFoundError(input.method, input.path);
+        const response = markRouteNotFound(normalizeResponse({
+            status: 404,
+            body: { error: error.message, code: error.code },
+            headers: { "content-type": "application/json" },
+        }, input.method));
+        if (this.requestGeneration === input.requestGeneration) {
+            this.emit("request:end", {
+                method: input.method,
+                path: input.path,
+                status: 404,
+                duration: performance.now() - input.handleStart,
+            });
+        }
+        this.logger.timeEnd(`request-${input.requestId}`);
+        return response;
+    }
     /**
      * Apply configured response delay
      * Supports both fixed delays and random delays within a range
      * @private
      */
-    async applyDelay(routeDelay) {
-        const effectiveDelay = routeDelay ?? this.globalConfig.delay;
+    async applyDelay(routeDelay, globalDelay, signal) {
+        const effectiveDelay = routeDelay ?? globalDelay;
         if (!effectiveDelay) {
+            throwIfAborted(signal);
             return;
         }
-        const ms = Array.isArray(effectiveDelay)
+        const configuredMs = Array.isArray(effectiveDelay)
             ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
                 effectiveDelay[0]
             : effectiveDelay;
-        await new Promise((resolve) => setTimeout(resolve, ms));
+        const ms = Math.max(0, configuredMs);
+        throwIfAborted(signal);
+        await new Promise((resolve, reject) => {
+            const finish = () => {
+                signal?.removeEventListener("abort", abort);
+                resolve();
+            };
+            const abort = () => {
+                clearTimeout(timer);
+                try {
+                    throwIfAborted(signal);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            const timer = setTimeout(finish, ms);
+            signal?.addEventListener("abort", abort, { once: true });
+        });
     }
 }