@schmock/core 2.4.1 → 2.6.0

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 {};

package/dist/node-server.js

@@ -0,0 +1,166 @@
+import { errorMessage, SchmockError } from "./errors.js";
+import { DEFAULT_MAX_BODY_SIZE, serveNodeRequest } from "./http-helpers.js";
+/**
+ * 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 class NodeServerController {
+    #server;
+    #pendingStart;
+    #closeBarrier;
+    #admitRequest;
+    #logger;
+    constructor(options) {
+        this.#admitRequest = options.admitRequest;
+        this.#logger = options.logger;
+    }
+    listen(port, hostname) {
+        if (this.#server || this.#pendingStart) {
+            throw new SchmockError("Server is already running", "SERVER_ALREADY_RUNNING");
+        }
+        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.#pendingStart = operation;
+        const closeBarrier = this.#closeBarrier ?? Promise.resolve();
+        void closeBarrier
+            // Lazy-load node:http so browser bundles never pull it in (issue #395).
+            // The rejection handler must sit on the import() expression itself:
+            // esbuild (and so the Angular application builder) leaves a dynamic
+            // import unresolved only when that expression handles its own failure,
+            // and the outer .catch() below does not count. Without it a
+            // `platform: "browser"` build fails with `Could not resolve "node:http"`.
+            .then(() => import("node:http").catch((error) => {
+            throw error;
+        }))
+            .then(({ createServer }) => {
+            if (!this.#ownsServerStart(operation))
+                return;
+            this.#startHttpServer(operation, createServer);
+        })
+            .catch((error) => {
+            this.#rejectServerStart(operation, error);
+        });
+        return startPromise;
+    }
+    close() {
+        this.#cancelServerStart();
+        const server = this.#server;
+        if (!server)
+            return;
+        this.#server = undefined;
+        this.#beginServerClose(server);
+        this.#logger.log("server", "Server stopped");
+    }
+    #ownsServerStart(operation) {
+        return this.#pendingStart === operation && !operation.settled;
+    }
+    #startHttpServer(operation, createServer) {
+        const httpServer = createServer((req, res) => {
+            // Admitted on arrival, before the request is parsed, so a reset() while
+            // its body uploads neither changes its routes nor uninstalls its plugins.
+            const admittedRequest = this.#admitRequest();
+            void serveNodeRequest(req, res, {
+                handle: admittedRequest.handle,
+                maxBodySize: DEFAULT_MAX_BODY_SIZE,
+            }).finally(() => admittedRequest.release());
+        });
+        operation.server = httpServer;
+        const handleStartupError = (error) => {
+            this.#rejectServerStart(operation, error);
+        };
+        httpServer.once("error", handleStartupError);
+        // Once listening, a server-level 'error' (an accept failure such as
+        // EMFILE) must still have a listener: with none, Node rethrows it as an
+        // uncaught exception and takes the whole test runner down.
+        const reportServerError = (error) => {
+            this.#logger.log("server", `Server error: ${errorMessage(error)}`);
+        };
+        try {
+            httpServer.listen(operation.port, operation.hostname, () => {
+                // Attach the permanent reporter BEFORE dropping the startup handler:
+                // the other order leaves a window with no 'error' listener at all.
+                httpServer.on("error", reportServerError);
+                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
+                    : operation.port;
+                const info = { port: actualPort, hostname: operation.hostname };
+                operation.settled = true;
+                this.#pendingStart = 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.#pendingStart === operation) {
+            this.#pendingStart = undefined;
+        }
+        if (operation.server) {
+            this.#beginServerClose(operation.server);
+        }
+        operation.reject(error);
+    }
+    #cancelServerStart() {
+        const operation = this.#pendingStart;
+        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.#closeBarrier ?? Promise.resolve();
+        const combinedBarrier = Promise.all([previousBarrier, closePromise]).then(() => undefined);
+        this.#closeBarrier = combinedBarrier;
+        void combinedBarrier.finally(() => {
+            if (this.#closeBarrier === combinedBarrier) {
+                this.#closeBarrier = undefined;
+            }
+        });
+    }
+}

package/dist/parser.d.ts

@@ -17,4 +17,3 @@ export interface ParsedRoute {
  * // => { method: 'GET', path: '/users/:id', pattern: /^\/users\/([^/]+)$/, params: ['id'] }
  */
 export declare function parseRouteKey(routeKey: string): ParsedRoute;
-//# sourceMappingURL=parser.d.ts.map

package/dist/parser.js

@@ -22,32 +22,155 @@ export function parseRouteKey(routeKey) {
         throw new RouteParseError(routeKey, 'Expected format: "METHOD /path" (e.g., "GET /users")');
     }
     const [, method, rawPath] = match;
-    // Canonicalize once, here, so `path`, `pattern`, the duplicate check, the
+    // Tokenize once, then derive `path`, `pattern` and `params` from the same
+    // tokens. `path` is canonicalized here so the duplicate check, the
     // static-route Map key and getRoutes() all agree on one spelling: the
     // percent-encoded transport form with a single trailing slash stripped.
-    const path = normalizePath(canonicalizePath(rawPath));
-    // Parameter names are restricted to [A-Za-z0-9_-] so that surrounding
-    // literals (".json", brackets, parens, etc.) terminate the name and can
-    // be escaped without bleeding into the parameter regex. Build the
-    // pattern by splitting the path on the param marker, escaping each
-    // literal segment, then substituting the capture group for each :name.
-    const params = [];
-    const regexPath = path
-        .split(/(:[a-zA-Z0-9_-]+)/g)
-        .map((segment) => {
-        const paramMatch = segment.match(/^:([a-zA-Z0-9_-]+)$/);
-        if (paramMatch) {
-            params.push(paramMatch[1]);
-            return "([^/]+)";
-        }
-        return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    })
-        .join("");
-    const pattern = new RegExp(`^${regexPath}$`);
+    const tokens = tokenizeRoutePath(routeKey, normalizePath(rawPath));
+    const params = tokens.flatMap((token) => token.kind === "param" ? [token.name] : []);
     return {
         method: toHttpMethod(method),
-        path,
-        pattern,
+        path: serializeRoutePath(tokens, params.length > 0),
+        pattern: new RegExp(`^${compileRoutePattern(tokens)}$`),
         params,
     };
 }
+const PLAIN_NAME_CHAR = /^[A-Za-z0-9_-]$/;
+const TRAILING_HYPHENS = /-+$/;
+/** A bare colon that a later parse would read as the start of a parameter. */
+const COLON_BEFORE_NAME = /:(?=[A-Za-z0-9_-])/g;
+/**
+ * Read the parameter whose ':' sits at `index`, or undefined when that colon
+ * is a literal: nothing name-like follows it, or the quote is unclosed or
+ * empty (both of which were literal text before quoted names existed).
+ */
+function readParam(path, index) {
+    if (path[index] !== ":")
+        return undefined;
+    if (path[index + 1] === '"') {
+        const close = path.indexOf('"', index + 2);
+        if (close <= index + 2)
+            return undefined;
+        return { name: path.slice(index + 2, close), quoted: true, end: close + 1 };
+    }
+    let end = index + 1;
+    while (end < path.length && PLAIN_NAME_CHAR.test(path[end]))
+        end += 1;
+    if (end === index + 1)
+        return undefined;
+    return { name: path.slice(index + 1, end), quoted: false, end };
+}
+function tokenizeRoutePath(routeKey, path) {
+    const tokens = [];
+    let literal = "";
+    const pushParam = (name, quoted) => {
+        if (literal) {
+            tokens.push({ kind: "literal", text: literal });
+            literal = "";
+        }
+        const previous = tokens[tokens.length - 1];
+        if (previous?.kind === "param") {
+            throw new RouteParseError(routeKey, `Parameters ":${previous.name}" and ":${name}" are adjacent, so nothing decides where one ends. Put a literal between them (e.g. ":${previous.name}-:${name}"), or write a literal colon as "\\:".`);
+        }
+        tokens.push({ kind: "param", name, quoted });
+    };
+    let index = 0;
+    while (index < path.length) {
+        if (path[index] === "\\" && path[index + 1] === ":") {
+            literal += ":";
+            index += 2;
+            continue;
+        }
+        const param = readParam(path, index);
+        if (!param) {
+            literal += path[index];
+            index += 1;
+            continue;
+        }
+        if (!param.quoted && readParam(path, param.end)) {
+            const name = param.name.replace(TRAILING_HYPHENS, "");
+            if (name) {
+                pushParam(name, false);
+            }
+            else {
+                // A name made only of hyphens leaves nothing to name: the colon is
+                // literal text, as it would be without the parameter that follows.
+                literal += ":";
+            }
+            literal += param.name.slice(name.length);
+        }
+        else {
+            pushParam(param.name, param.quoted);
+        }
+        index = param.end;
+    }
+    if (literal)
+        tokens.push({ kind: "literal", text: literal });
+    return tokens;
+}
+/**
+ * The route's canonical spelling: literals in the percent-encoded transport
+ * form (see canonicalizePath) and parameters as written. A route with
+ * parameters keeps a `\:` escape wherever a bare colon would start a
+ * parameter. A route without parameters is spelled as its literal path,
+ * because that string is also the static-route key a request is looked up by.
+ */
+function serializeRoutePath(tokens, hasParams) {
+    return tokens
+        .map((token) => {
+        if (token.kind === "param") {
+            return token.quoted ? `:"${token.name}"` : `:${token.name}`;
+        }
+        const canonical = canonicalizePath(token.text);
+        return hasParams
+            ? canonical.replace(COLON_BEFORE_NAME, "\\:")
+            : canonical;
+    })
+        .join("");
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function escapeCharClass(char) {
+    return char.replace(/[\\\]^-]/g, "\\$&");
+}
+/**
+ * Compile tokens to a regex source.
+ *
+ * A parameter that is the only one in its path segment, or the last one,
+ * captures `[^/]+` exactly as it always has — so `:name.json` still matches
+ * "report.v2.json" greedily. A parameter followed in the same segment by a
+ * literal and then another parameter also excludes that literal's first
+ * character, so it can only end at the separator:
+ * `:year-:month-:day` → `([^/-]+)-([^/-]+)-([^/]+)`. A percent-encoded
+ * literal is excluded whole rather than by its "%": `:first :last` →
+ * `((?:(?!%20)[^/])+)%20([^/]+)`. Without the exclusion
+ * every capture could end anywhere, and a long non-matching segment
+ * backtracked quadratically (two parameters) or cubically (three).
+ */
+function compileRoutePattern(tokens) {
+    return tokens
+        .map((token, index) => {
+        if (token.kind === "literal") {
+            return escapeRegExp(canonicalizePath(token.text));
+        }
+        const next = tokens[index + 1];
+        if (next?.kind === "literal" &&
+            !next.text.includes("/") &&
+            tokens[index + 2]?.kind === "param") {
+            const separator = canonicalizePath(next.text);
+            // A separator that canonicalizes to a percent triplet (a space, a
+            // brace, any non-ASCII character) starts with "%", and excluding "%"
+            // itself would forbid every encoded character in the capture ("José"
+            // is "Jos%C3%A9"). Exclude the whole encoded literal instead: the
+            // capture still cannot contain the separator, so it can only end at
+            // its first occurrence and the match stays linear.
+            if (separator.startsWith("%")) {
+                return `((?:(?!${escapeRegExp(separator)})[^/])+)`;
+            }
+            return `([^/${escapeCharClass(separator[0])}]+)`;
+        }
+        return "([^/]+)";
+    })
+        .join("");
+}

package/dist/plugin-hooks.d.ts

@@ -0,0 +1,57 @@
+import type { DebugLogger } from "./debug-logger.js";
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Reject, when it is piped, a plugin that could never work: one without a
+ * `process` function (it answered every matched request with a 500), or one
+ * whose `install`, `beforeRequest` or `onExchange` is a truthy non-function.
+ * The `install` and `beforeRequest` shapes already failed before this check;
+ * `onExchange` is new, so no working setup breaks.
+ */
+export declare function assertValidPlugin(plugin: unknown): asserts plugin is Schmock.Plugin;
+/** Whether any plugin observes exchanges (a function `onExchange`). */
+export declare function hasExchangeObserver(plugins: readonly Schmock.Plugin[]): boolean;
+/**
+ * Report one settled exchange to each plugin's `onExchange`, in pipe order.
+ * Every observer gets its own frozen snapshot, built right before its call, so
+ * none sees or alters another's copy. A throwing or rejecting observer is
+ * logged and never stops the others. Reporting stops as soon as `isLive`
+ * returns false.
+ */
+export declare function runExchangeHooks(input: {
+    plugins: readonly Schmock.Plugin[];
+    exchange: Schmock.Exchange;
+    logger: Pick<DebugLogger, "log">;
+    isLive?: () => boolean;
+}): void;
+/** The live reads a hook's instance forwards to the mock. */
+export interface HookReadAccess {
+    history(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord[];
+    called(method?: Schmock.HttpMethod, path?: string): boolean;
+    callCount(method?: Schmock.HttpMethod, path?: string): number;
+    lastRequest(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord | undefined;
+    getRoutes(): Schmock.RouteInfo[];
+    getState(): Record<string, unknown>;
+}
+type RouteRegistrar = (route: Schmock.RouteKey, generator: Schmock.Generator, config: Schmock.RouteConfig) => void;
+/**
+ * Run a plugin's `install()` against an expiring facade that may register
+ * routes. A Promise returned from `install()` is rejected: the routes it would
+ * register later could not be rolled back. The caller owns the rollback of
+ * whatever the hook registered before it threw.
+ */
+export declare function runInstallHook(input: {
+    plugin: Schmock.Plugin;
+    reads: HookReadAccess;
+    registerRoute: RouteRegistrar;
+    logger: DebugLogger;
+}): void;
+/**
+ * Run `uninstall()` for each plugin, last piped first. A failing hook is
+ * logged and never stops the others.
+ */
+export declare function runUninstallHooks(input: {
+    plugins: readonly Schmock.Plugin[];
+    reads: HookReadAccess;
+    logger: DebugLogger;
+}): void;
+export {};