expediate 1.0.4 → 1.0.5

package/dist/cjs/router.js

@@ -0,0 +1,898 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto = require("crypto");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const http2 = require("http2");
+const path = require("path");
+const misc_js_1 = require("./misc.js");
+const static_js_1 = require("./static.js");
+// ---------------------------------------------------------------------------
+// Pattern compilation
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a path string contains glob characters (`*` or `?`).
+ *
+ * A pattern is considered a glob when it contains at least one unescaped
+ * `*` or `?` character, following the same convention as `.gitignore`.
+ *
+ * @param pattern - The path string to inspect.
+ * @returns `true` if the pattern should be treated as a glob.
+ */
+function isGlobPattern(pattern) {
+    return /(?<!\\)[*?]/.test(pattern);
+}
+/**
+ * Compile a `.gitignore`-style glob string into a prefix-anchored `RegExp`.
+ *
+ * Supported wildcard syntax:
+ * - `?`  — matches exactly one character that is not `/`.
+ * - `*`  — matches zero or more characters that are not `/`.
+ * - `**` — matches zero or more path segments (any characters including `/`).
+ *
+ * The returned expression is anchored at the start (`^`) so it always matches
+ * a prefix of the current path; the matched portion is stripped by
+ * `matchRouteLayer` when `layer.stripPath` is `true`.
+ *
+ * @param glob - The glob pattern to compile.
+ * @returns A prefix-anchored `RegExp`.
+ *
+ * @example
+ * ```ts
+ * compileGlob('/**\/*.php').test('/admin/index.php'); // true
+ * compileGlob('/api/*')    .test('/api/users');       // true
+ * compileGlob('/api/*')    .test('/api/users/123');   // false
+ * ```
+ */
+function compileGlob(glob) {
+    // Escape all regex special characters, leaving our wildcard characters intact.
+    let src = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    // Replace in order: `**` must be handled before `*`.
+    src = src
+        .replace(/\*\*/g, '\x00GLOBSTAR\x00') // temporary placeholder
+        .replace(/\*/g, '[^/]*') // single-segment wildcard
+        .replace(/\?/g, '[^/]') // single-character wildcard
+        .replace(/\x00GLOBSTAR\x00/g, '.*'); // cross-segment wildcard
+    return new RegExp('^' + src);
+}
+/**
+ * Compile a plain path string with optional `:name` parameter segments into a
+ * prefix-anchored `RegExp` that uses named capture groups.
+ *
+ * Each `:name` segment is converted to `(?<name>[^/]+)`, making named
+ * captures available directly on the `RegExp` match result.
+ * Literal segments are escaped and matched exactly.
+ *
+ * The expression matches up to a segment boundary (`/` or end-of-string) so
+ * that `/users` never inadvertently matches `/users-admin`.
+ *
+ * @param path - A plain path string such as `'/users/:id/posts'`.
+ * @returns A prefix-anchored `RegExp` with named groups for each parameter.
+ *
+ * @example
+ * ```ts
+ * const re = compilePlainPath('/users/:id');
+ * re.exec('/users/42/comments')?.groups; // { id: '42' }
+ * ```
+ */
+function compilePlainPath(path) {
+    const segments = path.split('/').filter((s) => s.length > 0);
+    const src = segments
+        .map((seg) => seg.startsWith(':')
+        ? `(?<${seg.slice(1)}>[^/]+)` // named parameter segment
+        : seg.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .join('/');
+    // Allow a trailing slash or an additional path segment after the prefix.
+    return new RegExp('^/?' + src + '(?=/|$)');
+}
+/**
+ * Convert any supported path pattern into the single canonical `RegExp`
+ * used by `matchRouteLayer`.
+ *
+ * | Input type   | Strategy                                              |
+ * |--------------|-------------------------------------------------------|
+ * | Glob string  | {@link compileGlob} — `.gitignore`-style wildcards    |
+ * | Plain string | {@link compilePlainPath} — `:name` → named groups     |
+ * | `RegExp`     | Used as-is; named groups are surfaced as params       |
+ *
+ * @param path - The raw path pattern supplied by the caller.
+ * @returns A `RegExp` suitable for use in `matchRouteLayer`.
+ */
+function compilePattern(path) {
+    if (path instanceof RegExp)
+        return path;
+    if (isGlobPattern(path))
+        return compileGlob(path);
+    return compilePlainPath(path);
+}
+// ---------------------------------------------------------------------------
+// Layer construction
+// ---------------------------------------------------------------------------
+/**
+ * Build a `Layer` that represents a single registered route entry.
+ *
+ * The `path` argument may be a plain string with `:name` parameters, a glob
+ * string, or a `RegExp`. In all three cases the pattern is pre-compiled into
+ * a single `RegExp` stored as `layer.regex`.
+ *
+ * @param method     - HTTP method to restrict this layer to (uppercased), or
+ *                     `null` to match any method.
+ * @param path       - URL path pattern (plain string, glob, or `RegExp`).
+ * @param middleware - The middleware function to invoke on a match.
+ * @param stripPath  - When `true`, the matched prefix is stripped from
+ *                     `req.path` before the middleware runs. Pass `true` for
+ *                     prefix/`use` registrations and `false` for exact-method
+ *                     routes so that chained middlewares sharing the same path
+ *                     can each match in turn.
+ * @returns A fully initialised `Layer` ready to be pushed into the route table.
+ * @throws {TypeError} When `middleware` is not a callable function.
+ */
+function buildRouteLayer(method, path, middleware, stripPath) {
+    if (typeof middleware !== 'function')
+        throw new TypeError('Incorrect middleware type: expected a function');
+    return { method, path, regex: compilePattern(path), stripPath, middleware };
+}
+// ---------------------------------------------------------------------------
+// Layer matching
+// ---------------------------------------------------------------------------
+/**
+ * Test whether an incoming request matches the given layer and, on success,
+ * mutate `req` to reflect the match.
+ *
+ * All pattern types (plain string, glob, `RegExp`) are handled identically
+ * through `layer.regex`. Named capture groups in the match result are merged
+ * into `req.params` and `req.queries.route`.
+ *
+ * Path stripping is conditional on `layer.stripPath`:
+ * - `true`  (prefix routes) — the matched prefix is removed from `req.path`
+ *   so nested routers only see the remaining suffix.
+ * - `false` (exact-method routes) — `req.path` is left unchanged so that
+ *   subsequent chained middlewares sharing the same pattern can still match.
+ *
+ * @param layer - The layer to test.
+ * @param req   - The incoming request (mutated in-place on a successful match).
+ * @param path  - The current value of `req.path` to test against.
+ * @returns `true` if the layer matches and `req` has been updated;
+ *          `false` otherwise.
+ */
+function matchRouteLayer(layer, req, path) {
+    if (layer.method && layer.method !== req.method)
+        return false;
+    const m = layer.regex.exec(path);
+    if (m === null)
+        return false;
+    const captured = m.groups ?? {};
+    // Only rewrite req.path for prefix-style (use) registrations.
+    // Exact-method routes leave req.path intact so chained middlewares
+    // sharing the same path each see the full, unmodified path.
+    if (layer.stripPath) {
+        req.path = path.slice(m[0].length) || '/';
+    }
+    req.queries.route = captured;
+    Object.assign(req.params, captured);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Cookie helpers
+// ---------------------------------------------------------------------------
+/**
+ * Decode a raw cookie value, stripping the `j:` prefix and JSON-parsing the
+ * payload when present.  Plain string values are returned unchanged.
+ *
+ * @param raw - The raw cookie value as it appears after the `=` in the header.
+ * @returns The decoded value: a JS value for `j:` cookies, or the raw string.
+ */
+function decodeJsonCookie(raw) {
+    if (!raw.startsWith('j:'))
+        return raw;
+    try {
+        return JSON.parse(raw.slice(2));
+    }
+    catch {
+        return raw; // malformed JSON — fall back to raw string
+    }
+}
+/**
+ * Sign a cookie value with HMAC-SHA256.
+ *
+ * The produced string follows the `cookie-signature` wire format:
+ * `s:<value>.<base64url-HMAC>`, where `<value>` is the raw (possibly
+ * `j:`-prefixed) string and the HMAC is computed over that raw string.
+ *
+ * @param value  - The raw cookie value to sign (may include a `j:` prefix).
+ * @param secret - The HMAC secret.
+ * @returns The signed cookie string with the `s:` prefix.
+ */
+function signCookieValue(value, secret) {
+    const sig = crypto
+        .createHmac('sha256', secret)
+        .update(value)
+        .digest('base64url');
+    return `s:${value}.${sig}`;
+}
+/**
+ * Verify and decode a signed cookie value.
+ *
+ * The input must start with `s:` and follow the format produced by
+ * {@link signCookieValue}: `s:<value>.<base64url-HMAC>`.
+ *
+ * Uses `crypto.timingSafeEqual` to prevent timing-based signature attacks.
+ *
+ * @param signed - The raw `Set-Cookie` value including the `s:` prefix.
+ * @param secret - The HMAC secret to verify against.
+ * @returns The inner value string on success, or `false` when the signature
+ *          is absent or does not match (indicating a tampered cookie).
+ */
+function verifyCookieValue(signed, secret) {
+    if (!signed.startsWith('s:'))
+        return false;
+    const withoutPrefix = signed.slice(2);
+    const lastDot = withoutPrefix.lastIndexOf('.');
+    if (lastDot === -1)
+        return false;
+    const value = withoutPrefix.slice(0, lastDot);
+    const received = withoutPrefix.slice(lastDot + 1);
+    const expected = crypto
+        .createHmac('sha256', secret)
+        .update(value)
+        .digest('base64url');
+    const receivedBuf = Buffer.from(received, 'base64url');
+    const expectedBuf = Buffer.from(expected, 'base64url');
+    if (receivedBuf.length !== expectedBuf.length)
+        return false;
+    if (!crypto.timingSafeEqual(receivedBuf, expectedBuf))
+        return false;
+    return value;
+}
+// ---------------------------------------------------------------------------
+// HTTP object augmentation
+// ---------------------------------------------------------------------------
+/**
+ * Augment a raw `http.IncomingMessage` / `http.ServerResponse` pair with the
+ * additional fields and helpers expected by router middleware.
+ *
+ * This function is idempotent — it exits immediately when `req.queries` is
+ * already defined, so it is safe to call multiple times on the same pair.
+ *
+ * **Fields added to `req`:**
+ * - `originalUrl` — the unmodified URL string.
+ * - `path`        — the pathname portion of the URL.
+ * - `params`      — merged map initialised from URL query parameters.
+ * - `queries`     — structured query buckets (`url`, `route`).
+ * - `cookies`     — parsed `Cookie` header values.
+ *
+ * **Helpers added to `res`:**
+ * - `send(data?)`             — write `data` and end the response.
+ * - `json(data)`              — serialise to JSON and end.
+ * - `status(code, headers?)`  — set the status code and optional headers.
+ * - `redirect(url)`           — issue a 302 redirect.
+ * - `cookie(name, val, opts)` — append a `Set-Cookie` header.
+ *
+ * @param req         - The raw incoming message to augment.
+ * @param res         - The raw server response to augment.
+ * @param secret      - Optional cookie-signing secret.
+ * @param trustProxy  - When `true`, resolve `req.ip` from `X-Forwarded-For`.
+ */
+function updateHttpObjects(req, res, secret, trustProxy) {
+    const rReq = req;
+    const rRes = res;
+    if (rReq.queries)
+        return; // Already augmented.
+    rReq.queries = {};
+    // Resolve the client IP address.
+    // When trustProxy is true the leftmost value in X-Forwarded-For is used
+    // (the originating client behind the proxy chain).  Otherwise we read the
+    // raw TCP remote address directly from the socket, which cannot be spoofed.
+    if (trustProxy) {
+        const xff = req.headers['x-forwarded-for'];
+        const first = Array.isArray(xff) ? xff[0] : xff;
+        rReq.ip = (first ? first.split(',')[0].trim() : req.socket?.remoteAddress) ?? '';
+    }
+    else {
+        rReq.ip = req.socket?.remoteAddress ?? '';
+    }
+    const qry = new URL(`http://${req.headers.host}${req.url}`);
+    rReq.originalUrl = req.url;
+    rReq.path = qry.pathname;
+    // Parse URL query parameters.
+    // FEAT-03: repeated keys (e.g. ?tag=a&tag=b) accumulate into arrays.
+    const urlParams = {};
+    for (const [key, value] of qry.searchParams.entries()) {
+        const existing = urlParams[key];
+        if (existing === undefined) {
+            urlParams[key] = value;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            urlParams[key] = [existing, value];
+        }
+    }
+    rReq.queries.url = urlParams;
+    // params stays StringMap — use first value for repeated keys.
+    const flatParams = {};
+    for (const [key, value] of Object.entries(urlParams)) {
+        flatParams[key] = Array.isArray(value) ? value[0] : value;
+    }
+    rReq.params = flatParams;
+    // Parse cookies.
+    if (rReq.cookies == null) {
+        rReq.cookies = {};
+        if (req.headers.cookie) {
+            for (const part of req.headers.cookie.split(';')) {
+                const eqIdx = part.indexOf('=');
+                if (eqIdx === -1)
+                    continue;
+                const name = part.slice(0, eqIdx).trim();
+                const rawVal = part.slice(eqIdx + 1).trim();
+                if (rawVal.startsWith('s:')) {
+                    // Signed cookie — verify the HMAC signature.
+                    if (secret) {
+                        const inner = verifyCookieValue(rawVal, secret);
+                        if (inner === false)
+                            continue; // tampered — silently omit
+                        rReq.cookies[name] = decodeJsonCookie(inner);
+                    }
+                    else {
+                        // No secret configured — include the raw value so the application
+                        // can at least inspect that a signed cookie was sent.
+                        rReq.cookies[name] = rawVal;
+                    }
+                }
+                else {
+                    // Plain or JSON-encoded cookie.
+                    rReq.cookies[name] = decodeJsonCookie(rawVal);
+                }
+            }
+        }
+    }
+    const resolvedReqOpts = (opts) => ({
+        limit: opts?.limit ?? '100kb',
+        inflate: opts?.inflate ?? true,
+        reviver: null,
+        strict: opts?.strict ?? false,
+    });
+    rReq.json = (opts) => {
+        return (0, misc_js_1.readReqBody)(rReq, resolvedReqOpts(opts), 'application/json')
+            .then(ret => {
+            if (ret == null)
+                return null;
+            const charset = (0, misc_js_1.extractCharset)(ret.mimetype);
+            try {
+                const parsed = JSON.parse(ret.content.toString(charset), opts?.reviver ?? undefined);
+                rReq.body = parsed;
+                return parsed;
+            }
+            catch (ex) {
+                return Promise.reject({ status: 400, message: 'Bad Request: ' + ex.message });
+            }
+        });
+    };
+    rReq.text = (opts) => {
+        return (0, misc_js_1.readReqBody)(rReq, resolvedReqOpts(opts), null)
+            .then(ret => {
+            if (ret == null)
+                return null;
+            const charset = (0, misc_js_1.extractCharset)(ret.mimetype);
+            return ret.content.toString(charset);
+        });
+    };
+    rReq.formData = (opts) => {
+        return (0, misc_js_1.readReqBody)(rReq, resolvedReqOpts(opts), 'multipart/form-data')
+            .then(ret => {
+            if (ret == null)
+                return null;
+            try {
+                const parts = (0, misc_js_1.parseMultipartBody)(ret.mimetype, ret.content);
+                rReq.body = parts;
+                return parts;
+            }
+            catch (ex) {
+                return Promise.reject({ status: ex.status ?? 500, message: ex.message ?? String(ex) });
+            }
+        });
+    };
+    rRes.setHeader('X-Powered-By', 'Expediate');
+    rRes.send = (data) => {
+        if (data)
+            res.write(data);
+        res.end();
+    };
+    rRes.json = (data) => {
+        res.setHeader('Content-Type', 'application/json');
+        res.write(JSON.stringify(data));
+        res.end();
+    };
+    rRes.status = (code, headers) => {
+        res.statusCode = code;
+        if (headers)
+            for (const [k, v] of Object.entries(headers))
+                res.setHeader(k, v);
+        return rRes;
+    };
+    rRes.redirect = (url) => {
+        res.setHeader('location', url);
+        res.writeHead(302);
+        res.write(`Found. Redirecting to ${url}`);
+        res.end();
+    };
+    rRes.cookie = (name, value, options) => {
+        const opts = options ?? {};
+        // Serialise: objects get the j: prefix so the reader can JSON-decode them.
+        let val = typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value);
+        if (opts.signed) {
+            if (!secret)
+                throw new Error('Signed cookies require a secret — pass { secret } to createRouter()');
+            val = signCookieValue(val, secret);
+        }
+        let txt = `${name}=${val}`;
+        if (opts.maxAge != null) {
+            const maxAgeMs = opts.maxAge;
+            const maxAgeSec = Math.floor(maxAgeMs / 1000);
+            opts.expires = new Date(Date.now() + maxAgeMs);
+            txt += `; Max-Age=${maxAgeSec}`;
+        }
+        if (opts.expires)
+            txt += `; Expires=${opts.expires.toUTCString()}`;
+        txt += `; Path=${opts.path ?? '/'}`;
+        if (opts.httpOnly)
+            txt += '; HttpOnly';
+        if (opts.secure)
+            txt += '; Secure';
+        if (opts.sameSite)
+            txt += `; SameSite=${opts.sameSite}`;
+        // Append rather than overwrite so multiple cookies can be set on the same
+        // response.  res.setHeader() would replace any previously set Set-Cookie
+        // header; instead, accumulate into an array.
+        const existing = res.getHeader('Set-Cookie');
+        if (existing == null) {
+            res.setHeader('Set-Cookie', txt);
+        }
+        else if (Array.isArray(existing)) {
+            res.setHeader('Set-Cookie', [...existing, txt]);
+        }
+        else {
+            res.setHeader('Set-Cookie', [existing, txt]);
+        }
+        return rRes;
+    };
+    rRes.download = (filepath, filename) => {
+        const name = filename ?? path.basename(filepath);
+        // Use double-quotes and escape any double-quote in the filename per RFC 6266.
+        const safeName = name.replace(/"/g, '\\"');
+        res.setHeader('Content-Disposition', `attachment; filename="${safeName}"`);
+        // Guard: return 404 when the file does not exist (serveFile would send 500
+        // for any stat error; we want the conventional 404 for downloads).
+        fs.access(filepath, fs.constants.F_OK, (err) => {
+            if (err) {
+                if (!rRes.writableEnded)
+                    rRes.status(404).end('Not Found');
+                return;
+            }
+            (0, static_js_1.serveFile)(filepath)(rReq, rRes, () => { });
+        });
+    };
+    rRes.type = (mime) => {
+        res.setHeader('Content-Type', mime);
+        return rRes;
+    };
+}
+/**
+ * Test whether a layer's path pattern matches the given path string,
+ * **ignoring the HTTP method**.  Does NOT mutate `req`.
+ *
+ * Used exclusively for **405 Method Not Allowed** detection: when
+ * `matchRouteLayer` returns `false` due to a method mismatch, calling this
+ * function lets the dispatcher confirm that the path itself is registered
+ * (just under a different method) so it can respond with 405 and an
+ * `Allow` header instead of the generic 404.
+ *
+ * @param layer - The layer whose path pattern to test.
+ * @param path  - The current value of `req.path`.
+ * @returns `true` when the path pattern matches, regardless of method.
+ */
+function pathMatchesLayer(layer, path) {
+    return layer.regex.test(path);
+}
+// ---------------------------------------------------------------------------
+// Route registration helpers
+// ---------------------------------------------------------------------------
+/**
+ * Recursively resolve a `MiddlewareArg` value down to individual `Middleware`
+ * functions and push one `Layer` per function into the route table.
+ *
+ * Accepted input shapes (processed recursively):
+ * - A `Middleware` function → pushed directly as a layer.
+ * - A `Router` instance    → its `listener` is unwrapped and pushed.
+ * - An array of either     → each element is processed recursively.
+ *
+ * @param routes    - The mutable route table to push into.
+ * @param method    - HTTP method string or `null` for method-agnostic layers.
+ * @param path      - URL pattern (plain string, glob, or `RegExp`).
+ * @param arg       - The middleware value(s) to register.
+ * @param stripPath - Forwarded to `buildRouteLayer`.
+ * @throws {TypeError} When `arg` contains a value that cannot be resolved to
+ *                     a `Middleware` function.
+ */
+function registerRoute(routes, method, path, arg, stripPath) {
+    if (Array.isArray(arg)) {
+        for (const item of arg)
+            registerRoute(routes, method, path, item, stripPath);
+    }
+    else if (typeof arg === 'function') {
+        routes.push(buildRouteLayer(method, path, arg, stripPath));
+    }
+    else if (arg && typeof arg.listener === 'function') {
+        // Router instance — unwrap its listener.
+        routes.push(buildRouteLayer(method, path, arg.listener, stripPath));
+    }
+    else {
+        throw new TypeError('Unexpected value registered as middleware: expected a Middleware ' +
+            'function, a Router instance, or an array of either');
+    }
+}
+/**
+ * If `arg` is a `Router` instance, return its configured {@link Router.prefix};
+ * otherwise return `undefined`.
+ *
+ * Used by `router.use()` to infer the mount path when no explicit path is
+ * provided:
+ * ```ts
+ * const v1 = createRouter('/api/v1');
+ * app.use(v1); // prefix '/api/v1' is inferred automatically
+ * ```
+ *
+ * @param arg - The first argument passed to `router.use()`.
+ * @returns The router's prefix string, or `undefined`.
+ */
+function extractRouterPrefix(arg) {
+    if (Array.isArray(arg) || typeof arg === 'function')
+        return undefined;
+    return arg.prefix;
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create and return a new `Router` instance.
+ *
+ * The returned object exposes an Express-compatible routing API and doubles
+ * as a middleware function itself (via `router.listener`), so it can be
+ * mounted inside another router:
+ * ```ts
+ * parent.use('/api', child);
+ * // or, if child has a prefix:
+ * parent.use(child);
+ * ```
+ *
+ * **Prefix shorthand:**
+ * Pass a path string as the first argument to associate a prefix with this
+ * router.  The prefix is used automatically when the router is mounted via
+ * `parent.use(child)`:
+ * ```ts
+ * const v1 = createRouter('/api/v1');
+ * v1.get('/users', handler);   // handler is reached at /api/v1/users
+ * app.use(v1);                  // same as app.use('/api/v1', v1)
+ * ```
+ *
+ * **Path patterns** accepted by all route-registration methods:
+ * - Plain strings with optional `:name` segments — e.g. `'/users/:id'`.
+ * - Glob strings following `.gitignore` rules — e.g. `'/**\/*.php'`.
+ * - `RegExp` objects — used directly; named groups become route parameters.
+ *
+ * **Error handling:**
+ * Register a global error handler with `router.onError()`.  It is called
+ * when any middleware throws, rejects, or calls `next(err)`.
+ *
+ * **Graceful shutdown:**
+ * Call `router.shutdown()` to stop the server created by `router.listen()`.
+ *
+ * @param prefixOrOpts - Optional path prefix string (e.g. `'/api/v1'`) **or**
+ *                       an {@link RouterOptions} object.
+ * @param opts         - Options when `prefixOrOpts` is a string.
+ * @returns A fully initialised `Router`.
+ *
+ * @example
+ * ```ts
+ * const app = createRouter({ secret: process.env.COOKIE_SECRET, timeout: 30_000 });
+ *
+ * const v1 = createRouter('/api/v1');
+ * v1.get('/users', handler);
+ *
+ * app.use(v1);
+ * app.onError((err, _req, res) => res.status(500).json({ error: String(err) }));
+ * app.setNotFound((_req, res) => res.status(404).json({ error: 'Not Found' }));
+ *
+ * app.listen(3000, () => console.log('Listening'));
+ * process.on('SIGTERM', () => app.shutdown(10_000));
+ * ```
+ */
+function createRouter(prefixOrOpts, opts) {
+    // Resolve overloaded first argument.
+    const routerPrefix = typeof prefixOrOpts === 'string' ? prefixOrOpts : undefined;
+    const options = typeof prefixOrOpts === 'object' ? prefixOrOpts : (opts ?? {});
+    const secret = options.secret;
+    const timeoutMs = options.timeout;
+    const trustProxy = options.trustProxy ?? false;
+    const routes = [];
+    /** Currently registered error handler, or `undefined` for the default 500. */
+    let errorHandler;
+    /** Currently registered not-found handler, or `undefined` for the default 404. */
+    let notFoundHandler;
+    /** Server created by `router.listen()`, used by `router.shutdown()`. */
+    let activeServer = null;
+    /** All open sockets tracked for forced teardown on shutdown. */
+    const activeSockets = new Set();
+    // ──────────────────────────────────────────────────────────────────────────
+    // Core dispatch listener
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Core dispatch function. Walks the route table in registration order and
+     * invokes the first layer that matches the current request.
+     *
+     * - **404** (or custom `setNotFound` handler) — no layer's path matched.
+     * - **405 Method Not Allowed** — a layer's path matched but no layer
+     *   accepted the HTTP method.  The `Allow` header lists all registered methods.
+     * - **500** (or custom `onError` handler) — a middleware threw or rejected,
+     *   or `next(err)` was called with a non-null error.
+     */
+    const listener = (req, res, done) => {
+        const method = req.method;
+        const url = req.url;
+        let idx = 0;
+        updateHttpObjects(req, res, secret, trustProxy);
+        // ── Optional per-request timeout ──────────────────────────────────────
+        // Uses both a socket-level idle timeout (as the transport boundary) and a
+        // wall-clock setTimeout guard.  The wall-clock timer is the primary
+        // mechanism because it is unaffected by the OS socket buffer state;
+        // socket.setTimeout is set in addition so the idle signal propagates down
+        // to keep-alive connections that would otherwise hold the socket open.
+        if (timeoutMs) {
+            if (req.socket)
+                req.socket.setTimeout(timeoutMs);
+            const timer = setTimeout(() => {
+                if (!res.writableEnded)
+                    res.status(408).end('Request Timeout');
+            }, timeoutMs);
+            res.once('finish', () => {
+                clearTimeout(timer);
+                if (req.socket)
+                    req.socket.setTimeout(0);
+            });
+        }
+        // ── Centralised error dispatch ─────────────────────────────────────────
+        // Invoked for sync throws, async rejections, and next(err) calls.
+        const invokeErrorHandler = (e) => {
+            if (res.writableEnded)
+                return;
+            if (errorHandler) {
+                try {
+                    errorHandler(e, req, res);
+                }
+                catch (e2) {
+                    if (!res.writableEnded)
+                        res.status(500).end(`Error ${method} ${url}`);
+                }
+            }
+            else {
+                console.warn(e);
+                res.status(500).end(`Error ${method} ${url}`);
+            }
+        };
+        // ── Safe middleware invocation ─────────────────────────────────────────
+        // Catches sync throws AND async rejections, routing both to invokeErrorHandler.
+        const invoke = (mw, nextFn) => {
+            try {
+                const ret = mw(req, res, nextFn);
+                if (ret instanceof Promise)
+                    ret.catch(invokeErrorHandler);
+            }
+            catch (e) {
+                invokeErrorHandler(e);
+            }
+        };
+        // Accumulate methods from layers whose path matched but whose method
+        // did not, for a 405 response with an accurate Allow header.
+        const allowedMethods = new Set();
+        // ── Main dispatch loop ─────────────────────────────────────────────────
+        const next = (err) => {
+            // If an error is passed, skip remaining routes and call error handler.
+            if (err != null) {
+                invokeErrorHandler(err);
+                return;
+            }
+            while (idx < routes.length) {
+                const layer = routes[idx++];
+                const pathBefore = req.path;
+                if (matchRouteLayer(layer, req, req.path)) {
+                    if (layer.stripPath) {
+                        // For prefix layers (use), restore req.path after the sub-router
+                        // calls done() so that subsequent sibling layers see the original path.
+                        invoke(layer.middleware, () => {
+                            req.path = pathBefore;
+                            next();
+                        });
+                        return;
+                    }
+                    invoke(layer.middleware, next);
+                    return;
+                }
+                // Path matched but method did not → remember for 405 detection.
+                if (layer.method !== null && pathMatchesLayer(layer, pathBefore)) {
+                    allowedMethods.add(layer.method);
+                }
+            }
+            // All layers exhausted without a full match.
+            if (allowedMethods.size > 0) {
+                // Path is registered, but not for this method.
+                const allow = [...allowedMethods].sort().join(', ');
+                res.status(405, { Allow: allow }).end(`Cannot ${method} ${url}`);
+                return;
+            }
+            // Genuine 404 — delegate to parent router, not-found handler, or default.
+            if (done)
+                return done();
+            if (notFoundHandler) {
+                try {
+                    notFoundHandler(req, res, () => { });
+                }
+                catch (e) {
+                    invokeErrorHandler(e);
+                }
+                return;
+            }
+            res.status(404).end(`Cannot ${method} ${url}`);
+        };
+        try {
+            next();
+        }
+        catch (e) {
+            invokeErrorHandler(e);
+        }
+    };
+    // ──────────────────────────────────────────────────────────────────────────
+    // Registration helper for method-specific routes
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Return the route-registration function used by all HTTP-method helpers.
+     *
+     * @param method    - HTTP method to restrict layers to, or `null` for any.
+     * @param stripPath - Whether the matched path prefix should be stripped.
+     */
+    function makeRegister(method, stripPath) {
+        return (path, ...args) => {
+            for (const arg of args)
+                registerRoute(routes, method, path, arg, stripPath);
+        };
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // `use()` — supports both path-first and no-path (Router-first) forms
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Register prefix-style middleware.  Accepts:
+     * 1. `use(path, ...middlewares)` — explicit path.
+     * 2. `use(routerOrMiddleware, ...more)` — infers path from Router.prefix or '/'.
+     */
+    const use = (pathOrFirst, ...args) => {
+        if (typeof pathOrFirst === 'string' || pathOrFirst instanceof RegExp) {
+            // Normal form: explicit path string or RegExp.
+            for (const arg of args)
+                registerRoute(routes, null, pathOrFirst, arg, true);
+        }
+        else {
+            // No explicit path: the first argument is itself a middleware / Router.
+            // Infer mount path from the Router's prefix, or default to '/'.
+            const inferredPath = extractRouterPrefix(pathOrFirst) ?? '/';
+            registerRoute(routes, null, inferredPath, pathOrFirst, true);
+            for (const arg of args)
+                registerRoute(routes, null, '/', arg, true);
+        }
+    };
+    // ──────────────────────────────────────────────────────────────────────────
+    // Public router object
+    // ──────────────────────────────────────────────────────────────────────────
+    const router = {
+        prefix: routerPrefix,
+        listener,
+        use,
+        all: makeRegister(null, false),
+        get: makeRegister('GET', false),
+        put: makeRegister('PUT', false),
+        post: makeRegister('POST', false),
+        delete: makeRegister('DELETE', false),
+        patch: makeRegister('PATCH', false),
+        // ── onError ─────────────────────────────────────────────────────────────
+        onError(handler) {
+            errorHandler = handler;
+        },
+        // ── setNotFound ──────────────────────────────────────────────────────────
+        setNotFound(handler) {
+            notFoundHandler = handler;
+        },
+        // ── routes ───────────────────────────────────────────────────────────────
+        routes() {
+            return routes.map((l) => ({
+                method: l.method,
+                path: l.path,
+                stripPath: l.stripPath,
+            }));
+        },
+        // ── shutdown ─────────────────────────────────────────────────────────────
+        shutdown(timeout = 5000) {
+            if (!activeServer)
+                return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                // Stop accepting new connections.  Resolves when all existing
+                // connections have been closed (or when forcibly destroyed below).
+                activeServer.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+                // Forcibly destroy any remaining idle sockets after the grace period.
+                if (timeout > 0) {
+                    setTimeout(() => {
+                        for (const socket of activeSockets)
+                            socket.destroy();
+                        activeSockets.clear();
+                    }, timeout);
+                }
+            });
+        },
+        // ── listen ───────────────────────────────────────────────────────────────
+        listen(port, opts, cb) {
+            if (typeof opts === 'function') {
+                cb = opts;
+                opts = undefined;
+            }
+            const rawListener = listener;
+            let server;
+            const tlsOpts = opts;
+            if (tlsOpts?.key && tlsOpts?.cert) {
+                if (tlsOpts.http2) {
+                    // HTTP/2 secure server — same TLS options, different factory.
+                    server = http2.createSecureServer(tlsOpts, rawListener);
+                }
+                else {
+                    server = https.createServer(tlsOpts, rawListener);
+                }
+            }
+            else {
+                server = http.createServer(rawListener);
+            }
+            // Track open sockets so shutdown() can forcibly destroy them.
+            server.on('connection', (socket) => {
+                activeSockets.add(socket);
+                socket.once('close', () => activeSockets.delete(socket));
+            });
+            activeServer = server;
+            server.listen(port, cb);
+            return server;
+        },
+    };
+    return router;
+}
+exports.default = createRouter;