@schmock/core 2.4.0 → 2.5.0

package/dist/interceptor.js

@@ -1,14 +1,29 @@
 /// <reference path="../schmock.d.ts" />
 import { awaitWithAbort, throwIfAborted } from "./abort.js";
-import { isBinaryBody } from "./binary.js";
-import { canonicalizePath, getResponseException, isRouteNotFound, toHttpMethod, } from "./constants.js";
-import { normalizeResponse, serializeResponseBody, } from "./response-normalizer.js";
+import { canonicalizePath, getResponseException, isHttpMethod, isRouteNotFound, matchPathPrefix, parsePathPrefix, } from "./constants.js";
+import { buildFormattedErrorResponse, buildJsonErrorResponse, normalizeResponse, serializeResponseBody, withDefaultContentType, } from "./response-normalizer.js";
 const PASSTHROUGH = Symbol("schmock.fetch.passthrough");
-// A lease whose baseUrl filter rejected the request never reached its handler.
-// It is distinct from PASSTHROUGH so the dispatch loop can tell "this owner
-// already ran" from "this lease was not interested in the request at all".
+// A lease whose baseUrl filter rejected the request never reached its handler:
+// it was not interested in the request at all, and claimed nothing.
 const FILTERED = Symbol("schmock.fetch.filtered");
+// A newer lease of the same mock already asked it this exact request, so
+// asking again would only repeat the answer and its lifecycle events.
+const ALREADY_CONSULTED = Symbol("schmock.fetch.already-consulted");
 const RELATIVE_REQUEST_BASE = "http://schmock.invalid/";
+/**
+ * Marks an admission whose `handle()` already returns responses normalized
+ * for the request method (hop-by-hop headers dropped, a HEAD body stripped):
+ * only the admissions a `schmock()` instance of this copy creates. The
+ * interceptor re-normalizes the responses of any other admission, such as a
+ * hand-written one passed to `createFetchInterceptor`. Deliberately
+ * unregistered: an admission from a second copy of `@schmock/core` is simply
+ * normalized again.
+ */
+export const NORMALIZED_ADMISSION_KEY = Symbol("schmock.normalized-admission");
+function isNormalizedAdmission(admission) {
+    return (admission !== undefined &&
+        Reflect.get(admission, NORMALIZED_ADMISSION_KEY) === true);
+}
 let activeSession;
 function getRelativeRequestBase() {
     const candidates = [
@@ -106,29 +121,42 @@ function createInterceptorSession() {
         }
         const normalizedRequest = normalizeFetchRequest(input, init);
         throwIfAborted(normalizedRequest.request.signal);
-        // A mock is consulted at most once per request, however many leases it
-        // holds: without this, nested providers on one mock would run handle()
-        // — and emit request:start/notfound/end — once per lease.
-        const consultedOwners = new Set();
+        // A mock is asked each distinct effective request at most once, however
+        // many leases it holds: without this, nested providers on one mock would
+        // run handle() — and emit request:start/notfound/end — once per lease.
+        // The key is the request each lease would issue after its own baseUrl
+        // filter and beforeRequest, so an older lease whose hook rewrites the
+        // request (an outer provider stripping "/api") still gets its turn.
+        const consultedRequests = new Map();
+        const claimFor = (owner) => (requestKey) => {
+            if (owner === undefined)
+                return true;
+            let keys = consultedRequests.get(owner);
+            if (keys === undefined) {
+                keys = new Set();
+                consultedRequests.set(owner, keys);
+            }
+            if (keys.has(requestKey))
+                return false;
+            keys.add(requestKey);
+            return true;
+        };
         for (let index = snapshot.length - 1; index >= 0; index -= 1) {
             const registered = snapshot[index];
-            const { owner } = registered;
-            if (owner !== undefined && consultedOwners.has(owner)) {
-                continue;
-            }
-            const result = await awaitWithAbort(registered.intercept(normalizedRequest), normalizedRequest.request.signal);
+            const result = await awaitWithAbort(registered.intercept({
+                request: normalizedRequest,
+                claim: claimFor(registered.owner),
+            }), normalizedRequest.request.signal);
             throwIfAborted(normalizedRequest.request.signal);
-            // The lease filtered the request out before admission, so its owner
-            // keeps its turn — a sibling lease may carry a matching baseUrl.
-            if (result === FILTERED) {
+            // FILTERED: this lease was not interested, so a sibling lease may be.
+            // ALREADY_CONSULTED: the mock already answered this exact request.
+            // PASSTHROUGH: the mock has no route for it. All three move on.
+            if (result === FILTERED ||
+                result === ALREADY_CONSULTED ||
+                result === PASSTHROUGH) {
                 continue;
             }
-            if (result !== PASSTHROUGH) {
-                return result;
-            }
-            if (owner !== undefined) {
-                consultedOwners.add(owner);
-            }
+            return result;
         }
         return awaitWithAbort(baselineFetch(normalizedRequest.request), normalizedRequest.request.signal);
     };
@@ -176,31 +204,6 @@ function registerInterceptor(intercept, applyOptions, owner) {
         },
     };
 }
-/**
- * Parse the user-supplied baseUrl option into its origin and path parts.
- * - "/api"                  → { origin: null, path: "/api" }
- * - "https://x.com/api/v1"  → { origin: "https://x.com", path: "/api/v1" }
- * - "https://x.com"         → { origin: "https://x.com", path: "" }
- *
- * Trailing slash is stripped from the path so the segment-boundary check
- * works the same way for "/api" and "/api/".
- */
-function parseBaseUrl(baseUrl) {
-    if (baseUrl.includes("://")) {
-        try {
-            const parsed = new URL(baseUrl);
-            const canonicalPath = canonicalizePath(parsed.pathname);
-            const path = canonicalPath === "/" ? "" : canonicalPath.replace(/\/$/, "");
-            return { origin: parsed.origin, path };
-        }
-        catch {
-            // Fall through to path-only handling
-        }
-    }
-    const canonicalPath = canonicalizePath(baseUrl);
-    const path = canonicalPath === "/" ? "" : canonicalPath.replace(/\/$/, "");
-    return { origin: null, path };
-}
 function extractQuery(url) {
     return Object.fromEntries(url.searchParams);
 }
@@ -216,18 +219,25 @@ function normalizeMediaType(contentType) {
 }
 async function extractBody(request) {
     if (request.body === null)
-        return undefined;
-    const body = request.clone();
+        return { value: undefined, malformedJson: false };
     const mediaType = normalizeMediaType(request.headers.get("content-type"));
-    if (mediaType === "application/json" || mediaType.endsWith("+json")) {
-        const text = await body.text();
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            return text;
-        }
+    if (mediaType !== "application/json" && !mediaType.endsWith("+json")) {
+        return { value: await extractNonJsonBody(request), malformedJson: false };
+    }
+    const text = await request.clone().text();
+    // An empty JSON body is no body at all, as the Node ingress reads it.
+    if (text === "")
+        return { value: undefined, malformedJson: false };
+    try {
+        return { value: JSON.parse(text), malformedJson: false };
+    }
+    catch {
+        return { value: text, malformedJson: true };
     }
+}
+async function extractNonJsonBody(request) {
+    const body = request.clone();
+    const mediaType = normalizeMediaType(request.headers.get("content-type"));
     if (mediaType === "application/x-www-form-urlencoded") {
         return Object.fromEntries(new URLSearchParams(await body.text()));
     }
@@ -239,98 +249,99 @@ async function extractBody(request) {
     }
     return body.arrayBuffer();
 }
+/** An admission's route probe (`hasRoute`), when it carries one. */
+function routeProbeOf(admission) {
+    if (admission === undefined)
+        return undefined;
+    const probe = Reflect.get(admission, "hasRoute");
+    if (typeof probe !== "function")
+        return undefined;
+    // Anything but a definite `false` counts as a route, so an unexpected
+    // answer, or a throw, only costs the body read the probe would have saved.
+    return (method, path) => {
+        try {
+            return Reflect.apply(probe, admission, [method, path]) !== false;
+        }
+        catch {
+            return true;
+        }
+    };
+}
 function isAbortError(error) {
     return (typeof error === "object" &&
         error !== null &&
         "name" in error &&
         error.name === "AbortError");
 }
-function toFetchResponse(response, method) {
-    const headers = { ...response.headers };
-    const hasContentType = Object.keys(headers).some((name) => name.toLowerCase() === "content-type");
-    if (!hasContentType &&
-        response.body !== null &&
-        response.body !== undefined) {
-        if (isBinaryBody(response.body)) {
-            headers["content-type"] = "application/octet-stream";
-        }
-        else if (typeof response.body !== "string") {
-            headers["content-type"] = "application/json";
-        }
-    }
-    const normalized = normalizeResponse({ ...response, headers }, method);
-    return new Response(serializeResponseBody(normalized) ?? null, {
+/**
+ * Build the fetch Response from an already-normalized Schmock response.
+ */
+function createFetchResponse(normalized, context) {
+    const response = new Response(serializeResponseBody(normalized) ?? null, {
         status: normalized.status,
         headers: normalized.headers,
     });
+    // A constructed Response has an empty url. Real fetch reports the request
+    // URL, and code resolving links with `new URL(next, res.url)` needs it.
+    Object.defineProperty(response, "url", { value: context.url });
+    return response;
+}
+function toFetchResponse(response, context) {
+    return createFetchResponse(normalizeResponse(withDefaultContentType(response), context.method), context);
+}
+function jsonErrorResponse(input) {
+    return createFetchResponse(buildJsonErrorResponse({
+        status: input.status,
+        error: input.error,
+        code: input.code,
+        method: input.context.method,
+    }), input.context);
 }
 /**
- * Formatted error bodies are always JSON, so the replaced response's own
- * content type must be dropped rather than inherited. Every case variant goes
- * first: leaving a `Content-Type` beside the forced lowercase key makes the
- * pair transport-invalid and the normalizer rejects it.
+ * A request this lease owns but cannot route: pass it on, or answer the same
+ * 404 a route miss gets when passthrough is off.
  */
-function withJsonContentType(headers) {
-    const result = {};
-    for (const [name, value] of Object.entries(headers ?? {})) {
-        if (name.toLowerCase() === "content-type")
-            continue;
-        result[name] = value;
-    }
-    result["content-type"] = "application/json";
-    return result;
+function unroutedResult(passthrough, context) {
+    if (passthrough)
+        return PASSTHROUGH;
+    return jsonErrorResponse({
+        status: 404,
+        error: "No matching mock route found",
+        code: "ROUTE_NOT_FOUND",
+        context,
+    });
 }
 /**
- * Invoke the errorFormatter for a core-marked exception and build its
- * response, falling back to a minimal safe body when the formatter throws or
- * its result is not serializable.
- *
- * This helper is TOTAL — it never throws. It runs inside the interceptor's
- * `try`, so an escaping error would land in the catch below and invoke the
- * formatter a second time; the re-entrancy is exactly the defect the Express
- * adapter's `sendFormattedError` was shaped to avoid.
- *
- * `responseHeaders` carries the (post-hook) headers of the response being
- * replaced so metadata such as `retry-after` survives. There are two distinct
- * fallbacks. When the inherited headers are untransportable, the send is
- * retried once with the fixed JSON header set and the SAME formatted body —
- * nothing is on the wire yet, and losing the body would silently change the
- * user's error contract. Only a failure of the formatter itself, or of its
- * body, reaches the minimal fallback, which deliberately inherits nothing.
+ * The fetch Response for an errorFormatter result, built by the shared
+ * {@link buildFormattedErrorResponse}. TOTAL: it never throws, and the
+ * formatter runs exactly once. It runs inside the interceptor's `try`, so an
+ * escaping error would land in the catch below and invoke the formatter a
+ * second time.
  */
-function formatInterceptedError(errorFormatter, error, responseHeaders, method) {
-    try {
-        const formatted = errorFormatter(error);
-        try {
-            return toFetchResponse({
-                status: 500,
-                body: formatted,
-                headers: withJsonContentType(responseHeaders),
-            }, method);
-        }
-        catch {
-            // `formatted` is reused, so the formatter still fires exactly once.
-            return toFetchResponse({
-                status: 500,
-                body: formatted,
-                headers: { "content-type": "application/json" },
-            }, method);
-        }
-    }
-    catch {
-        return toFetchResponse({
-            status: 500,
-            body: { error: "Internal Server Error", code: "INTERNAL_ERROR" },
-            headers: { "content-type": "application/json" },
-        }, method);
-    }
+function formattedErrorResponse(input) {
+    return createFetchResponse(buildFormattedErrorResponse({
+        formatter: input.formatter,
+        error: input.error,
+        inheritedHeaders: input.responseHeaders,
+        method: input.context.method,
+    }), input.context);
+}
+/** Fetch reports the request URL without its fragment. */
+function responseUrlOf(url) {
+    const responseUrl = new URL(url.href);
+    responseUrl.hash = "";
+    return responseUrl.href;
+}
+function effectiveRequestKey(method, path) {
+    return `${method} ${canonicalizePath(path)}`;
 }
 /**
  * Create a fetch interceptor that routes requests through mock.handle().
  *
- * `owner` identifies the mock behind the lease. Leases sharing an owner are
- * consulted at most once per request, so a mock held by several leases runs
- * its handler — and emits its lifecycle events — once per network request.
+ * `owner` identifies the mock behind the lease. Leases sharing an owner ask it
+ * each distinct effective request (method and path after the lease's own
+ * beforeRequest) at most once, so a mock held by several leases runs its
+ * handler — and emits its lifecycle events — once per request it is asked.
  */
 export function createFetchInterceptor(handle, options = {}, admitRequest, owner) {
     // The options live in a mutable cell that each request reads once at its
@@ -338,7 +349,7 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
     // hooks without re-registering — re-registration would move the lease to the
     // front of the dispatch order and steal precedence from other mocks.
     let currentOptions = options;
-    return registerInterceptor(async ({ request, url, origin }) => {
+    return registerInterceptor(async ({ request: { request, url, origin }, claim, }) => {
         const { baseUrl, passthrough = true, beforeRequest, beforeResponse, errorFormatter, } = currentOptions;
         const path = canonicalizePath(url.pathname);
         // BaseUrl filter — non-matching requests go straight to real fetch.
@@ -348,32 +359,74 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
         //   - path form ("/api"): match pathname prefix only.
         // Both enforce a segment boundary so "/api" doesn't match "/apiv2".
         if (baseUrl) {
-            const { origin: baseOrigin, path: basePath } = parseBaseUrl(baseUrl);
-            if (baseOrigin && origin !== baseOrigin) {
+            const base = parsePathPrefix(baseUrl);
+            if (base.origin && origin !== base.origin) {
                 return FILTERED;
             }
-            if (basePath) {
-                const isMatch = path === basePath || path.startsWith(`${basePath}/`);
-                if (!isMatch) {
-                    return FILTERED;
-                }
+            if (!matchPathPrefix(base, path)) {
+                return FILTERED;
             }
         }
         throwIfAborted(request.signal);
-        const initialMethod = toHttpMethod(request.method);
+        const context = {
+            method: request.method,
+            url: responseUrlOf(url),
+        };
+        const initialMethod = request.method.toUpperCase();
+        // Without a beforeRequest hook (which may change the method or path)
+        // the effective request is already known, so it is claimed before this
+        // lease can answer anything: once a newer lease of the same mock has
+        // passed it through, an older passthrough:false lease must not answer
+        // it with a 404 or a malformed-JSON 400. A lease with a hook claims only
+        // after the hook, so its own 400 for a malformed JSON body (which comes
+        // before the hook) still answers.
+        if (beforeRequest === undefined &&
+            !claim(effectiveRequestKey(initialMethod, path))) {
+            return ALREADY_CONSULTED;
+        }
+        // No route can ever match a method outside the supported set (WebDAV's
+        // PROPFIND, a CDN PURGE), so it is a miss like any other rather than a
+        // rejected fetch. Checked before admission, which it never needs.
+        if (!isHttpMethod(initialMethod)) {
+            return unroutedResult(passthrough, context);
+        }
+        context.method = initialMethod;
         const admission = admitRequest?.();
         const admittedHandle = admission?.handle ?? handle;
-        let effectiveMethod = initialMethod;
+        // Without a beforeRequest hook (which receives the body and may change
+        // the method or path), the request handle() will see is already known,
+        // so a passthrough lease asks the admission whether any route answers
+        // it. On a definite miss the body is never read: the request reaches
+        // the network untouched, and handle() still runs, without a body, so
+        // request:start/notfound/end are emitted exactly as before.
+        const routeProbe = passthrough && !beforeRequest ? routeProbeOf(admission) : undefined;
+        // The request handed to errorFormatter: the latest one this lease built,
+        // so it reflects beforeRequest once that hook has returned.
+        let formatterRequest;
         try {
-            const body = await awaitWithAbort(extractBody(request), request.signal);
+            const body = routeProbe !== undefined && !routeProbe(initialMethod, path)
+                ? { value: undefined, malformedJson: false }
+                : await awaitWithAbort(extractBody(request), request.signal);
             throwIfAborted(request.signal);
+            // With passthrough off the lease owns every request that reaches it,
+            // as the Node server does, so a JSON body that does not parse gets
+            // the server's 400 before any route runs or history records it.
+            if (body.malformedJson && !passthrough) {
+                return jsonErrorResponse({
+                    status: 400,
+                    error: "Malformed JSON request body",
+                    code: "MALFORMED_JSON",
+                    context,
+                });
+            }
             let adapterRequest = {
                 method: request.method,
                 path,
                 headers: extractHeaders(request),
-                body,
+                body: body.value,
                 query: extractQuery(url),
             };
+            formatterRequest = adapterRequest;
             // Apply beforeRequest hook
             if (beforeRequest) {
                 throwIfAborted(request.signal);
@@ -381,16 +434,27 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
                 throwIfAborted(request.signal);
                 if (modified) {
                     adapterRequest = modified;
+                    formatterRequest = modified;
                 }
             }
             throwIfAborted(request.signal);
+            // A hook may produce a method no route can match; that is a miss
+            // too, as the Angular adapter treats it.
+            const effectiveMethod = adapterRequest.method.toUpperCase();
+            if (!isHttpMethod(effectiveMethod)) {
+                return unroutedResult(passthrough, context);
+            }
+            context.method = effectiveMethod;
+            if (beforeRequest !== undefined &&
+                !claim(effectiveRequestKey(effectiveMethod, adapterRequest.path))) {
+                return ALREADY_CONSULTED;
+            }
             const requestOptions = {
                 headers: adapterRequest.headers,
                 body: adapterRequest.body,
                 query: adapterRequest.query,
                 signal: request.signal,
             };
-            effectiveMethod = toHttpMethod(adapterRequest.method);
             const schmockResponse = await awaitWithAbort(admittedHandle(effectiveMethod, adapterRequest.path, requestOptions), request.signal);
             throwIfAborted(request.signal);
             // Exception provenance is carried on the response as a non-enumerable
@@ -401,17 +465,7 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
             const internalError = getResponseException(schmockResponse);
             // Route not found — passthrough or 404
             if (isRouteNotFound(schmockResponse)) {
-                if (passthrough) {
-                    return PASSTHROUGH;
-                }
-                return toFetchResponse({
-                    status: 404,
-                    body: {
-                        error: "No matching mock route found",
-                        code: "ROUTE_NOT_FOUND",
-                    },
-                    headers: { "content-type": "application/json" },
-                }, effectiveMethod);
+                return unroutedResult(passthrough, context);
             }
             // Apply beforeResponse hook
             let response = schmockResponse;
@@ -429,9 +483,22 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
             // Angular): a beforeResponse that rewrites an exception into a 503 or
             // a 200 is honoured instead of being forced back to a formatted 500.
             if (errorFormatter && internalError && response.status === 500) {
-                return formatInterceptedError(errorFormatter, internalError, response.headers, effectiveMethod);
+                const seenRequest = adapterRequest;
+                return formattedErrorResponse({
+                    formatter: (error) => errorFormatter(error, seenRequest),
+                    error: internalError,
+                    responseHeaders: response.headers,
+                    context,
+                });
+            }
+            // A schmock() admission's handle() already normalized its own output
+            // for this method; with no hook to replace or mutate it, a second
+            // pass would only re-validate the same tree. Anything else, including
+            // a hand-written admission's response, is re-normalized.
+            if (isNormalizedAdmission(admission) && beforeResponse === undefined) {
+                return createFetchResponse(withDefaultContentType(schmockResponse), context);
             }
-            return toFetchResponse(response, effectiveMethod);
+            return toFetchResponse(response, context);
         }
         catch (error) {
             throwIfAborted(request.signal);
@@ -439,13 +506,23 @@ export function createFetchInterceptor(handle, options = {}, admitRequest, owner
                 throw error;
             }
             if (errorFormatter) {
-                const formatted = errorFormatter(error instanceof Error ? error : new Error(String(error)));
+                // A formatter that throws here propagates and rejects the fetch; a
+                // body it returns that cannot be serialized falls back to the same
+                // INTERNAL_ERROR body the core-marked path uses.
+                const failure = error instanceof Error ? error : new Error(String(error));
+                // No request was built when the body itself could not be read.
+                const formatted = errorFormatter(failure, formatterRequest ?? {
+                    method: request.method,
+                    path,
+                    headers: extractHeaders(request),
+                    query: extractQuery(url),
+                });
                 throwIfAborted(request.signal);
-                return toFetchResponse({
-                    status: 500,
-                    body: formatted,
-                    headers: { "content-type": "application/json" },
-                }, effectiveMethod);
+                return formattedErrorResponse({
+                    formatter: () => formatted,
+                    error: failure,
+                    context,
+                });
             }
             throw error;
         }

package/dist/node-server.d.ts

@@ -0,0 +1,27 @@
+import type { DebugLogger } from "./debug-logger.js";
+interface NodeServerControllerOptions {
+    /**
+     * Admit one request against the mock. Called on arrival, before the request
+     * is parsed, and released once it is answered.
+     */
+    readonly admitRequest: () => Schmock.RequestAdmission;
+    readonly logger: DebugLogger;
+}
+/**
+ * The standalone HTTP server behind `mock.listen()` / `mock.close()`.
+ *
+ * Owns the start and close state machines: at most one server is running or
+ * starting, a `close()` during start-up cancels the start, and a new start
+ * waits for every earlier server to finish closing (the close barrier) so a
+ * restart on the same port never races the old socket.
+ *
+ * `node:http` is imported lazily, on the first `listen()`, so a browser bundle
+ * that never listens never pulls it in (issue #395).
+ */
+export declare class NodeServerController {
+    #private;
+    constructor(options: NodeServerControllerOptions);
+    listen(port: number, hostname: string): Promise<Schmock.ServerInfo>;
+    close(): void;
+}
+export {};