expediate 1.0.5 → 1.0.6

package/dist/router.js

@@ -19,14 +19,10 @@
  * DEALINGS IN THE SOFTWARE.
  */
 'use strict';
-import * as crypto from 'crypto';
-import * as fs from 'fs';
 import * as http from 'http';
 import * as https from 'https';
 import * as http2 from 'http2';
-import * as path from 'path';
-import { parseMultipartBody, extractCharset, readReqBody } from './misc.js';
-import { serveFile } from './static.js';
+import { updateHttpObjects } from './http-objects.js';
 // ---------------------------------------------------------------------------
 // Pattern compilation
 // ---------------------------------------------------------------------------
@@ -100,7 +96,7 @@ function isGlobPattern(pattern) {
  * compileGlob('/api/*')    .test('/api/users/123');   // false
  * ```
  */
-function compileGlob(glob) {
+function compileGlob(glob, exact = false) {
     // Escape all regex special characters, leaving our wildcard characters intact.
     let src = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
     // Replace in order: `**` must be handled before `*`.
@@ -109,7 +105,7 @@ function compileGlob(glob) {
         .replace(/\*/g, '[^/]*') // single-segment wildcard
         .replace(/\?/g, '[^/]') // single-character wildcard
         .replace(/\x00GLOBSTAR\x00/g, '.*'); // cross-segment wildcard
-    return new RegExp('^' + src);
+    return new RegExp('^' + src + (exact ? '$' : ''));
 }
 /**
 /**
@@ -184,7 +180,7 @@ function extractInlinePattern(str, openIdx) {
  * re.exec('/users/7')?.groups; // { id: '7' }
  * ```
  */
-function compilePlainPath(path) {
+function compilePlainPath(path, exact = false) {
     const segments = path.split('/').filter((s) => s.length > 0);
     const src = segments
         .map((seg) => {
@@ -214,10 +210,12 @@ function compilePlainPath(path) {
         .join('/');
     // Validate and return — surface any regex syntax errors as SyntaxError.
     try {
-        return new RegExp('^/?' + src + '(?=/|$)');
+        return new RegExp(exact
+            ? '^/?' + src + (src ? '/?' : '') + '$'
+            : '^/?' + src + '(?=/|$)');
     }
     catch (e) {
-        throw new SyntaxError(`Invalid inline regex constraint in path '${path}': ${e.message}`);
+        throw new SyntaxError(`Invalid inline regex constraint in path '${path}': ${e.message}`, { cause: e });
     }
 }
 /**
@@ -233,12 +231,12 @@ function compilePlainPath(path) {
  * @param path - The raw path pattern supplied by the caller.
  * @returns A `RegExp` suitable for use in `matchRouteLayer`.
  */
-function compilePattern(path) {
+function compilePattern(path, exact = false) {
     if (path instanceof RegExp)
         return path;
     if (isGlobPattern(path))
-        return compileGlob(path);
-    return compilePlainPath(path);
+        return compileGlob(path, exact);
+    return compilePlainPath(path, exact);
 }
 // ---------------------------------------------------------------------------
 // Layer construction
@@ -265,7 +263,15 @@ function compilePattern(path) {
 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 };
+    // Reject RegExp patterns with the global (g) or sticky (y) flag.
+    // Both flags make RegExp.exec()/test() stateful: lastIndex advances after
+    // each match, so the same regex object alternates match/no-match across
+    // requests, causing intermittent 404s that are nearly impossible to debug.
+    // Express 4 silently allowed this (a known footgun); we reject it early.
+    if (path instanceof RegExp && (path.global || path.sticky))
+        throw new TypeError(`Route RegExp /${path.source}/${path.flags} must not use the g (global) or y (sticky) flag — ` +
+            'these flags make exec() stateful and cause intermittent routing failures.');
+    return { method, path, regex: compilePattern(path, !stripPath), stripPath, middleware };
 }
 // ---------------------------------------------------------------------------
 // Layer matching
@@ -291,12 +297,17 @@ function buildRouteLayer(method, path, middleware, stripPath) {
  *          `false` otherwise.
  */
 function matchRouteLayer(layer, req, path) {
-    if (layer.method && layer.method !== req.method)
+    // A HEAD request is served by a matching GET layer (RFC 7231 §4.3.2); Node
+    // suppresses the response body for HEAD automatically, so the GET handler can
+    // run unchanged.
+    if (layer.method &&
+        layer.method !== req.method &&
+        !(req.method === 'HEAD' && layer.method === 'GET'))
         return false;
     const m = layer.regex.exec(path);
     if (m === null)
         return false;
-    const captured = m.groups ?? {};
+    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.
@@ -307,328 +318,6 @@ function matchRouteLayer(layer, req, path) {
     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) => {
-        // If a body-parsing middleware already consumed the stream, return the cached value.
-        if ('body' in rReq)
-            return Promise.resolve(rReq.body ?? null);
-        return readReqBody(rReq, resolvedReqOpts(opts), 'application/json')
-            .then(ret => {
-            if (ret == null)
-                return null;
-            const charset = 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) => {
-        // If a body-parsing middleware already consumed the stream, return the cached string.
-        const cached = rReq.body;
-        if (typeof cached === 'string')
-            return Promise.resolve(cached);
-        return readReqBody(rReq, resolvedReqOpts(opts), null)
-            .then(ret => {
-            if (ret == null)
-                return null;
-            const charset = extractCharset(ret.mimetype);
-            return ret.content.toString(charset);
-        });
-    };
-    rReq.formData = (opts) => {
-        // If a body-parsing middleware already consumed the stream, return the cached parts.
-        const cached = rReq.body;
-        if (Array.isArray(cached))
-            return Promise.resolve(cached);
-        return readReqBody(rReq, resolvedReqOpts(opts), 'multipart/form-data')
-            .then(ret => {
-            if (ret == null)
-                return null;
-            try {
-                const parts = parseMultipartBody(ret.mimetype, ret.content);
-                rReq.body = parts;
-                return parts;
-            }
-            catch (ex) {
-                // console.error('Body Err', 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;
-            }
-            serveFile(filepath)(rReq, rRes, () => { });
-        });
-    };
-    rRes.type = (mime) => {
-        res.setHeader('Content-Type', mime);
-        return rRes;
-    };
-    rRes.etag = (value, strong = false) => {
-        res.setHeader('ETag', strong ? `"${value}"` : `W/"${value}"`);
-        return rRes;
-    };
-}
 /**
  * Test whether a layer's path pattern matches the given path string,
  * **ignoring the HTTP method**.  Does NOT mutate `req`.
@@ -674,9 +363,9 @@ function registerRoute(routes, method, path, arg, stripPath) {
     else if (typeof arg === 'function') {
         routes.push(buildRouteLayer(method, path, arg, stripPath));
     }
-    else if (arg && typeof arg.listener === 'function') {
+    else if (arg && typeof (arg).listener === 'function') {
         // Router instance — unwrap its listener.
-        routes.push(buildRouteLayer(method, path, arg.listener, stripPath));
+        routes.push(buildRouteLayer(method, path, (arg).listener, stripPath));
     }
     else {
         throw new TypeError('Unexpected value registered as middleware: expected a Middleware ' +
@@ -700,7 +389,7 @@ function registerRoute(routes, method, path, arg, stripPath) {
 function extractRouterPrefix(arg) {
     if (Array.isArray(arg) || typeof arg === 'function')
         return undefined;
-    return arg.prefix;
+    return (arg).prefix;
 }
 // ---------------------------------------------------------------------------
 // Router factory
@@ -753,7 +442,11 @@ function extractRouterPrefix(arg) {
  *
  * 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' }));
+ *
+ * // Custom 404: register a catch-all as the LAST layer. Because layers match
+ * // in registration order, it only runs when nothing earlier claimed the
+ * // request. Use `all('/**', …)` (glob) to match any method and path.
+ * app.all('/**', (_req, res) => res.status(404).json({ error: 'Not Found' }));
  *
  * app.listen(3000, () => console.log('Listening'));
  * process.on('SIGTERM', () => app.shutdown(10_000));
@@ -767,10 +460,10 @@ function createRouter(prefixOrOpts, opts) {
     const timeoutMs = options.timeout;
     const trustProxy = options.trustProxy ?? false;
     const routes = [];
-    /** Currently registered error handler, or `undefined` for the default 500. */
+    /** Ordered error-handling middlewares registered via `router.error()`. */
+    const errorHandlers = [];
+    /** Terminal fallback registered via `router.onError()`, or `undefined`. */
     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. */
@@ -782,7 +475,7 @@ function createRouter(prefixOrOpts, opts) {
      * 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.
+     * - **404** — no layer's path matched (register a catch-all last to customise).
      * - **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,
@@ -814,23 +507,51 @@ function createRouter(prefixOrOpts, opts) {
         }
         // ── Centralised error dispatch ─────────────────────────────────────────
         // Invoked for sync throws, async rejections, and next(err) calls.
+        //
+        // Resolution order:
+        //   1. Each error() middleware in turn (it may end the response or forward).
+        //   2. The onError() terminal fallback, if registered.
+        //   3. Bubble to the parent router's error channel via done(err).
+        //   4. Top-level router with no handler → default 500.
         const invokeErrorHandler = (e) => {
             if (res.writableEnded)
                 return;
-            if (errorHandler) {
-                try {
-                    errorHandler(e, req, res);
+            let i = 0;
+            const runNext = (err) => {
+                if (res.writableEnded)
+                    return;
+                // 1. Ordered error() middleware chain.
+                if (i < errorHandlers.length) {
+                    const handler = errorHandlers[i++];
+                    try {
+                        // `next()` forwards the same error; `next(newErr)` replaces it.
+                        handler(err, req, res, (nextErr) => runNext(nextErr ?? err));
+                    }
+                    catch (e2) {
+                        runNext(e2);
+                    }
+                    return;
                 }
-                catch (e2) {
-                    // console.error('Root Err', e2)
-                    if (!res.writableEnded)
-                        res.status(500).end(`Error ${method} ${url}`);
+                // 2. onError() terminal fallback for this router.
+                if (errorHandler) {
+                    try {
+                        errorHandler(err, req, res);
+                    }
+                    catch {
+                        if (!res.writableEnded)
+                            res.status(500).end(`Error ${method} ${url}`);
+                    }
+                    return;
                 }
-            }
-            else {
-                console.warn(e);
+                // 3. Bubble to the parent router's error channel (when mounted via use()).
+                if (done) {
+                    done(err);
+                    return;
+                }
+                // 4. Top-level router with no handler: default 500.
                 res.status(500).end(`Error ${method} ${url}`);
-            }
+            };
+            runNext(e);
         };
         // ── Safe middleware invocation ─────────────────────────────────────────
         // Catches sync throws AND async rejections, routing both to invokeErrorHandler.
@@ -859,11 +580,20 @@ function createRouter(prefixOrOpts, opts) {
                 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, () => {
+                        // For prefix layers (use), restore req.path and req.baseUrl after
+                        // the sub-router calls done() so subsequent sibling layers see the
+                        // original values.
+                        const baseUrlBefore = req.baseUrl;
+                        const strippedPrefix = pathBefore.slice(0, pathBefore.length - req.path.length);
+                        req.baseUrl = baseUrlBefore + strippedPrefix;
+                        // The continuation doubles as the sub-router's `done`: it runs both
+                        // when the sub-router falls through (no error) and when it bubbles an
+                        // error up. Forward `err` so a bubbled error reaches this router's
+                        // error channel instead of being silently dropped.
+                        invoke(layer.middleware, (err) => {
                             req.path = pathBefore;
-                            next();
+                            req.baseUrl = baseUrlBefore;
+                            next(err);
                         });
                         return;
                     }
@@ -877,23 +607,28 @@ function createRouter(prefixOrOpts, opts) {
             }
             // All layers exhausted without a full match.
             if (allowedMethods.size > 0) {
-                // Path is registered, but not for this method.
+                // The path is registered, just not for this method.  Build the Allow
+                // header, advertising HEAD (served by GET) and OPTIONS (handled here)
+                // alongside the explicitly registered methods.
+                if (allowedMethods.has('GET'))
+                    allowedMethods.add('HEAD');
+                allowedMethods.add('OPTIONS');
                 const allow = [...allowedMethods].sort().join(', ');
+                // Automatic OPTIONS: when nothing claimed the request (no explicit
+                // OPTIONS route, no cors() middleware), reply 204 with the Allow header.
+                if (method === 'OPTIONS') {
+                    res.status(204, { Allow: allow }).end();
+                    return;
+                }
+                // Otherwise the method is genuinely not allowed for this path.
                 res.status(405, { Allow: allow }).end(`Cannot ${method} ${url}`);
                 return;
             }
-            // Genuine 404 — delegate to parent router, not-found handler, or default.
+            // Genuine 404 — delegate to the parent router, or send the default 404.
+            // To customise, register a catch-all layer last (e.g. `app.all('/**', …)`);
+            // it matches in registration order after every real route.
             if (done)
                 return done();
-            if (notFoundHandler) {
-                try {
-                    notFoundHandler(req, res, () => { });
-                }
-                catch (e) {
-                    invokeErrorHandler(e);
-                }
-                return;
-            }
             res.status(404).end(`Cannot ${method} ${url}`);
         };
         try {
@@ -954,13 +689,31 @@ function createRouter(prefixOrOpts, opts) {
         post: makeRegister('POST', false),
         delete: makeRegister('DELETE', false),
         patch: makeRegister('PATCH', false),
+        head: makeRegister('HEAD', false),
+        options: makeRegister('OPTIONS', false),
+        // ── route ────────────────────────────────────────────────────────────────
+        route(path) {
+            // Each method forwards to the router's own registration helper with the
+            // cached path and returns the builder so calls can be chained.
+            const builder = {
+                all(...args) { router.all(path, ...args); return builder; },
+                get(...args) { router.get(path, ...args); return builder; },
+                put(...args) { router.put(path, ...args); return builder; },
+                post(...args) { router.post(path, ...args); return builder; },
+                delete(...args) { router.delete(path, ...args); return builder; },
+                patch(...args) { router.patch(path, ...args); return builder; },
+                head(...args) { router.head(path, ...args); return builder; },
+                options(...args) { router.options(path, ...args); return builder; },
+            };
+            return builder;
+        },
         // ── onError ─────────────────────────────────────────────────────────────
         onError(handler) {
             errorHandler = handler;
         },
-        // ── setNotFound ──────────────────────────────────────────────────────────
-        setNotFound(handler) {
-            notFoundHandler = handler;
+        // ── error ────────────────────────────────────────────────────────────────
+        error(handler) {
+            errorHandlers.push(handler);
         },
         // ── routes ───────────────────────────────────────────────────────────────
         routes() {