fulmine.js 5.15.0 → 5.16.0

package/src/router.js

@@ -242,36 +242,45 @@ class Walk {
             // frozen here, once per scan: _pathMatches reads the two flags as bare fields, and
             // calling this per route measured 0.45us of a scan of four hundred
             router._freezeRoutingFlags();
-            // written out rather than through a predicate handed to findIndexStartingFrom, which
-            // was one closure per hop of every request not on a compiled chain
-            for (; routeIndex < routes.length; routeIndex++) {
-                const r = routes[routeIndex];
-                // A HEAD request enters a route whose path matched even when its verb cannot serve
-                // one: express exempts HEAD from the method check ("if (!hasMethod && method !==
-                // 'HEAD')" in router/index.js), so the layer's parameters are captured and its
-                // param() callbacks run before the route is dropped. Only asked when the router has
-                // callbacks to run, since entering a route to step straight back out of it is
-                // otherwise pure cost with nothing to show for it. runRoute steps over it.
-                if (!(
-                    r.all ||
-                    r.method === req.method ||
-                    req._isOptions ||
-                    (req._isHead && (r.gettable || r.paramCallbacks.size > 0))
-                )) {
-                    // taken only to fail: _preprocessRequest decodes again and turns it into the
-                    // error, so the handlers of a route this request cannot run never see it
-                    if (mayFailDecode && router._pathMatches(r, req) && router._paramsFailToDecode(r, req)) {
-                        break;
-                    }
-                    continue;
-                }
-                if (router._pathMatches(r, req)) {
-                    // matched, and then stepped over: a body parser this request gets nothing out
-                    // of costs a hop and answers with next() at the end of it
-                    if (r.bodyParserOnly === true && stepsOver(r, req)) {
+            if (routes === router._routes) {
+                // the router's own table has an index over its literal routes, so the scan visits
+                // the handful that could match instead of every one, see _scanFrom
+                routeIndex = router._scanFrom(req, routeIndex, mayFailDecode);
+            } else {
+                // a compiled chain's own array, always short: the linear scan stays.
+                // Written out rather than through a predicate handed to findIndexStartingFrom,
+                // which was one closure per hop of every request not on a compiled chain
+                const method = req.method;
+                const length = routes.length;
+                for (; routeIndex < length; routeIndex++) {
+                    const r = routes[routeIndex];
+                    // A HEAD request enters a route whose path matched even when its verb cannot
+                    // serve one: express exempts HEAD from the method check ("if (!hasMethod &&
+                    // method !== 'HEAD')" in router/index.js), so the layer's parameters are
+                    // captured and its param() callbacks run before the route is dropped. Only
+                    // asked when the router has callbacks to run, since entering a route to step
+                    // straight back out of it is otherwise pure cost. runRoute steps over it.
+                    if (!(
+                        r.all ||
+                        r.method === method ||
+                        req._isOptions ||
+                        (req._isHead && (r.gettable || r.paramCallbacks.size > 0))
+                    )) {
+                        // taken only to fail: _preprocessRequest decodes again and turns it into
+                        // the error, so the handlers of a route this request cannot run never see it
+                        if (mayFailDecode && router._pathMatches(r, req) && router._paramsFailToDecode(r, req)) {
+                            break;
+                        }
                         continue;
                     }
-                    break;
+                    if (router._pathMatches(r, req)) {
+                        // matched, and then stepped over: a body parser this request gets nothing
+                        // out of costs a hop and answers with next() at the end of it
+                        if (r.bodyParserOnly === true && stepsOver(r, req)) {
+                            continue;
+                        }
+                        break;
+                    }
                 }
             }
         }
@@ -402,7 +411,11 @@ class Walk {
                 useApp(req, route.mountApp);
             }
             const taken = mountPrefixLength(route, req);
-            (req._stack ??= []).push(taken);
+            // pushed negative when this mount consumes the whole remaining path: express invents
+            // the "/" the routes below see, and the pop has to know, see leaveHop and issue #17
+            (req._stack ??= []).push(
+                taken !== 0 && req._consumed + taken === req._originalPath.length ? -taken : taken
+            );
             // a use with no path consumes nothing, so everything below would work out the values
             // that are already there. Only skipped without a trailing slash, where the rules about
             // one cannot bite. An application is mostly pathless middleware, and this is per hop
@@ -466,6 +479,68 @@ class Walk {
         return this.step(undefined);
     }
 
+    /**
+     * Leaves the route the walk is on: the mount pop, the router hand-back, and the hop to the
+     * route after. Out of step so the commonest hop, callbacks exhausted by a plain next(), goes
+     * here without re-running step's prologue and compares.
+     *
+     * @param {boolean} isRouter next("router") rather than next("route")
+     */
+    leaveHop(isRouter) {
+        const req = this.req;
+        const route = this.route;
+        if (route.use && !route.keepMount) {
+            const pushed = req._stack.pop();
+            const taken = pushed < 0 ? -pushed : pushed;
+            // a rewrite done inside this middleware is taken now: the pop below recomputes
+            // req.url from the original path and would silently revert it. The slashAdded
+            // mangle belongs to the mount that consumed a prefix, not to a pathless use
+            if (req.url !== req._lastUrl) {
+                req._absorbUrlRewrite(taken !== 0);
+                req._consumed -= taken;
+                setMountedPath(req);
+            } else {
+                if (pushed < 0 && req._originalPath.length > req._consumed) {
+                    // a rewrite below this mount left a remainder where entry had none: express
+                    // strips the first character of it when it rejoins, see issue #17
+                    req._originalPath =
+                        req._originalPath.slice(0, req._consumed) + req._originalPath.slice(req._consumed + 1);
+                    req._mayFailDecode = null;
+                }
+                if (taken !== 0) {
+                    // a pathless use consumed nothing and rewrote nothing, so the recompute would
+                    // write back the very values it reads
+                    req._consumed -= taken;
+                    setMountedPath(req);
+                }
+            }
+            restoreApp(route, req);
+        }
+        if (isRouter) {
+            if (this.skipCheck) {
+                // on a compiled chain, leaving the router is what running out of chain
+                // already means: ordinary routing takes over after the mount. With no
+                // mount in the chain the router being left is the app's own, and nothing
+                // of it may run afterwards, not even a middleware registered later
+                if (this.skipUntil?.keepMount) {
+                    return this.dispatch(this.routes.length);
+                }
+                return this.resolve(false);
+            }
+            // out of this router entirely, so whoever mounted it carries on after the
+            // mount. The app's own walk has nobody after it, and answers 404
+            return this.resolve(false);
+        }
+        req.routeCount++;
+        // dispatch is a plain call, so a synchronous throw would escape here instead of
+        // rejecting, as it used to when this recursed through the async _routeRequest
+        try {
+            return this.dispatch(this.routeIndex + 1);
+        } catch (err) {
+            return this.reject(err);
+        }
+    }
+
     /**
      * One hop, which is what next() does: with nothing, run the route's next callback; with "route",
      * leave the route; with anything else, remember it as the error and carry on.
@@ -479,39 +554,7 @@ class Walk {
         const router = this.router;
         if (thingamabob) {
             if (thingamabob === "route" || thingamabob === "router") {
-                if (route.use && !route.keepMount) {
-                    // a rewrite done inside this middleware is taken now: the pop below recomputes
-                    // req.url from the original path and would silently revert it
-                    if (req.url !== req._lastUrl) {
-                        req._absorbUrlRewrite();
-                    }
-                    req._consumed -= req._stack.pop();
-                    setMountedPath(req);
-                    restoreApp(route, req);
-                }
-                if (thingamabob === "router") {
-                    if (this.skipCheck) {
-                        // on a compiled chain, leaving the router is what running out of chain
-                        // already means: ordinary routing takes over after the mount. With no
-                        // mount in the chain the router being left is the app's own, and nothing
-                        // of it may run afterwards, not even a middleware registered later
-                        if (this.skipUntil?.keepMount) {
-                            return this.dispatch(this.routes.length);
-                        }
-                        return this.resolve(false);
-                    }
-                    // out of this router entirely, so whoever mounted it carries on after the
-                    // mount. The app's own walk has nobody after it, and answers 404
-                    return this.resolve(false);
-                }
-                req.routeCount++;
-                // dispatch is a plain call, so a synchronous throw would escape here instead of
-                // rejecting, as it used to when this recursed through the async _routeRequest
-                try {
-                    return this.dispatch(this.routeIndex + 1);
-                } catch (err) {
-                    return this.reject(err);
-                }
+                return this.leaveHop(thingamabob === "router");
             } else {
                 req._error = thingamabob;
                 req._errorKey = route.routeKey;
@@ -521,7 +564,7 @@ class Walk {
         const kind = route.callbackKinds[this.callbackIndex];
         const callback = route.callbacks[this.callbackIndex++];
         if (!callback) {
-            return this.step("route");
+            return this.leaveHop(false);
         }
         // skipping routes we already went through via optimized path. Before the Router branch
         // below and not after it: a mount whose chain was compiled has already run, and running it
@@ -715,6 +758,10 @@ function mountPrefixLength(route, req) {
     if (route.pattern === EMPTY_REGEX) {
         return 0;
     }
+    // the registration-time constant of a literal mount, exec-free. See createRoute
+    if (route.mountLen !== undefined) {
+        return route.mountLen;
+    }
     if (typeof route.pattern === "string") {
         return route.pattern.length;
     }
@@ -801,6 +848,61 @@ function mergesParams(route, fallback) {
     return Boolean(owner?._settings?.mergeParams);
 }
 
+// shared empty candidate list, so _scanFrom never tests for a missing map entry twice
+const EMPTY_INDICES = /** @type {number[]} */ ([]);
+
+/**
+ * The generic scan's index over a router's literal routes: route positions by folded pattern, so
+ * a scan visits the routes registered for this exact path instead of comparing every one. String
+ * patterns are pure literals, everything else, "/*" included, stays in alwaysVisit and is still
+ * matched per request by _pathMatches.
+ *
+ * @param {any[]} routes the router's own table
+ * @param {boolean} caseFlag the frozen case-sensitivity flag
+ * @returns {{map: Map<string, number[]>, alwaysVisit: number[]}}
+ */
+function buildLiteralIndex(routes, caseFlag) {
+    const map = new Map();
+    const alwaysVisit = [];
+    for (let i = 0; i < routes.length; i++) {
+        const pattern = routes[i].pattern;
+        if (typeof pattern === "string" && pattern !== "/*") {
+            const key = caseFlag ? pattern : routes[i].patternLower;
+            const list = map.get(key);
+            if (list === undefined) {
+                map.set(key, [i]);
+            } else {
+                list.push(i);
+            }
+        } else {
+            alwaysVisit.push(i);
+        }
+    }
+    return { map, alwaysVisit };
+}
+
+/**
+ * The position of the first value >= from in an ascending list, which is list.length when there
+ * is none: where a scan resuming at `from` enters a candidate list.
+ *
+ * @param {number[]} list
+ * @param {number} from
+ * @returns {number}
+ */
+function firstAtLeast(list, from) {
+    let low = 0;
+    let high = list.length;
+    while (low < high) {
+        const mid = (low + high) >> 1;
+        if (list[mid] < from) {
+            low = mid + 1;
+        } else {
+            high = mid;
+        }
+    }
+    return low;
+}
+
 /**
  * The route's own params merged with those of the mounts it sits under, in express's order: an
  * outer mount first, the route's own last. Numbered captures do not overwrite each other, they
@@ -1712,6 +1814,90 @@ module.exports = class Router extends EventEmitter {
         return fullMountpath;
     }
 
+    /**
+     * The generic scan over this router's own table, driven by the literal index: only the routes
+     * registered for this exact path, plus every non-literal route, are visited, in registration
+     * order, and each visited one still answers through the same method gate and _pathMatches the
+     * plain loop used. The routes skipped are exactly the literals whose string compare provably
+     * fails, so the first index this answers is the one the plain loop found.
+     *
+     * Runs after _freezeRoutingFlags, which is what makes _caseFlag and _strictFlag readable here
+     * and the lazily built index stable.
+     *
+     * @param {any} req
+     * @param {number} startIndex where to resume the scan
+     * @param {boolean} mayFailDecode whether the path carries a percent escape
+     * @returns {number} the index of the route to enter, or the table length for none
+     */
+    _scanFrom(req, startIndex, mayFailDecode) {
+        const routes = this._routes;
+        const index = (this._literalIndex ??= buildLiteralIndex(routes, /** @type {boolean} */ (this._caseFlag)));
+        let path = req._opPath;
+        if (path === "") {
+            path = "/";
+        }
+        if (!this._caseFlag) {
+            path = req._opPathLower ??= path.toLowerCase();
+        }
+        const exact = index.map.get(path) ?? EMPTY_INDICES;
+        // the trailing-slash twin _pathMatches allows outside strict routing, as a key: a path
+        // "/a/" can only text-match a literal "/a", so that list joins the candidates
+        const slashed =
+            !this._strictFlag && path.charCodeAt(path.length - 1) === 0x2f
+                ? (index.map.get(path.slice(0, -1)) ?? EMPTY_INDICES)
+                : EMPTY_INDICES;
+        const always = index.alwaysVisit;
+        let exactAt = firstAtLeast(exact, startIndex);
+        let slashedAt = firstAtLeast(slashed, startIndex);
+        let alwaysAt = firstAtLeast(always, startIndex);
+        const method = req.method;
+        const none = routes.length;
+        for (;;) {
+            // the next candidate in registration order, from whichever list holds it
+            let routeIndex = none;
+            if (exactAt < exact.length && exact[exactAt] < routeIndex) {
+                routeIndex = exact[exactAt];
+            }
+            if (slashedAt < slashed.length && slashed[slashedAt] < routeIndex) {
+                routeIndex = slashed[slashedAt];
+            }
+            if (alwaysAt < always.length && always[alwaysAt] < routeIndex) {
+                routeIndex = always[alwaysAt];
+            }
+            if (routeIndex === none) {
+                return none;
+            }
+            if (exactAt < exact.length && exact[exactAt] === routeIndex) {
+                exactAt++;
+            }
+            if (slashedAt < slashed.length && slashed[slashedAt] === routeIndex) {
+                slashedAt++;
+            }
+            if (alwaysAt < always.length && always[alwaysAt] === routeIndex) {
+                alwaysAt++;
+            }
+            const r = routes[routeIndex];
+            // the same gates as the plain loop, comments and all: see dispatch
+            if (!(
+                r.all ||
+                r.method === method ||
+                req._isOptions ||
+                (req._isHead && (r.gettable || r.paramCallbacks.size > 0))
+            )) {
+                if (mayFailDecode && this._pathMatches(r, req) && this._paramsFailToDecode(r, req)) {
+                    return routeIndex;
+                }
+                continue;
+            }
+            if (this._pathMatches(r, req)) {
+                if (r.bodyParserOnly === true && stepsOver(r, req)) {
+                    continue;
+                }
+                return routeIndex;
+            }
+        }
+    }
+
     /**
      * Whether a route's path matches this request. A plain string compares directly, which is what
      * makes a route eligible for the native router; anything carrying a parameter or a wildcard was
@@ -1887,6 +2073,13 @@ module.exports = class Router extends EventEmitter {
                 // the "body methods" setting as it stood the first time this layer was reached,
                 // kept the way the parser behind it keeps it. undefined until then
                 bodyMethods: undefined,
+                // a literal mount consumes exactly its registered text, so what the per-hop exec
+                // in mountPrefixLength answers is a constant. "/" stays with the exec: its clamp
+                // against a parent that consumed everything is not a constant
+                mountLen:
+                    method === "USE" && typeof path === "string" && path.length > 1 && !/[:*{\\]/.test(path)
+                        ? path.length
+                        : undefined,
                 // a mount written as a RegExp matches a piece of path that is not known until a
                 // request comes in, so its stack entry cannot be the path itself
                 regexMount: method === "USE" && path instanceof RegExp,
@@ -1937,6 +2130,8 @@ module.exports = class Router extends EventEmitter {
             routes.push(route);
         }
         this._routes.push(...routes);
+        // the literal index positions are stale the moment the table grows
+        this._literalIndex = undefined;
 
         // anything registered after listen invalidates what the header-skip analysis proved:
         // it could catch a throw or read what a chain never did, so every skip is taken back
@@ -2396,14 +2591,23 @@ module.exports = class Router extends EventEmitter {
                   needsConversionToRegex(p) ? patternToRegex(p, false, false) : p.toLowerCase()
               )
             : null;
-        const makeHandler = (chain, preset, skips) => {
+        const makeHandler = (chain, preset, skips, wireMethod) => {
             // the mutable object a granted skip lives on, so a middleware arriving after
             // listen can take it back: a literal registration's preset doubles as it, and a
-            // parameterised one, which has no preset, gets a holder of its own
+            // parameterised one, which has no preset, gets a holder of its own. It also carries
+            // the registration's method, so the constructor settles it with one compare
             let skipHolder = preset;
-            if (skipHolder === undefined && (skips.skipHeaders || skips.skipQuery)) {
-                skipHolder = { skipHeaders: skips.skipHeaders, skipQuery: skips.skipQuery };
-                (this._skipPresets ??= new Set()).add(skipHolder);
+            if (skipHolder === undefined && (skips.skipHeaders || skips.skipQuery || wireMethod !== null)) {
+                skipHolder = {
+                    skipHeaders: skips.skipHeaders,
+                    skipQuery: skips.skipQuery,
+                    method: wireMethod,
+                    isOptions: wireMethod === "OPTIONS",
+                    isHead: wireMethod === "HEAD"
+                };
+                if (skips.skipHeaders || skips.skipQuery) {
+                    (this._skipPresets ??= new Set()).add(skipHolder);
+                }
             }
             // all three are registration-time constants: computing them in the handler was a
             // closure and a scan of the chain on every native request.
@@ -2430,6 +2634,8 @@ module.exports = class Router extends EventEmitter {
                     return this._refuseRequest(response);
                 }
                 if (optimizedParams) {
+                    // slicing these out of the already-fetched path instead measured a wash:
+                    // the segment scan costs what the crossing costs
                     request.optimizedParams = new NullObject();
                     for (let i = 0; i < optimizedParams.length; i++) {
                         request.optimizedParams[optimizedParams[i]] = req.getParameter(i);
@@ -2475,8 +2681,8 @@ module.exports = class Router extends EventEmitter {
         // analysis in usage.js, whose default answer is no.
         //
         // The etag setting is not one of the conditions. It used to be, on the grounds that send
-        // consults freshness, but the skip branch reads if-none-match, if-modified-since and
-        // cache-control by name whatever the setting, see the comment at request.js:527, and
+        // consults freshness, but the skip branch reads if-none-match and if-modified-since by
+        // name whatever the setting, see the comment at request.js:527, and
         // req.fresh reads nothing else off the request. Requiring etag off as well cost the copy
         // to every application that left it on, which is every application that did not go
         // looking for the setting.
@@ -2508,10 +2714,13 @@ module.exports = class Router extends EventEmitter {
             return preset;
         };
 
+        // the wire token this registration answers; "any" serves every verb and stays dynamic
+        const wireMethod = method === "any" ? null : route.method;
         let fn = makeHandler(
             getChain,
             canPreset ? makePreset(route.path, route.method, getSkips) : undefined,
-            getSkips
+            getSkips,
+            wireMethod
         );
         const jsFn = fn;
 
@@ -2564,7 +2773,12 @@ module.exports = class Router extends EventEmitter {
                 fn !== jsFn
                     ? fn
                     : canPreset
-                      ? makeHandler(getChain, makePreset(route.path + "/", route.method, getSkips), getSkips)
+                      ? makeHandler(
+                            getChain,
+                            makePreset(route.path + "/", route.method, getSkips),
+                            getSkips,
+                            wireMethod
+                        )
                       : fn;
             this.uwsApp[method](replacedPath + "/", slashFn);
             if (method === "get") {
@@ -2573,7 +2787,8 @@ module.exports = class Router extends EventEmitter {
                     makeHandler(
                         headChain,
                         canPreset ? makePreset(route.path + "/", "HEAD", headSkips) : undefined,
-                        headSkips
+                        headSkips,
+                        "HEAD"
                     )
                 );
             }
@@ -2582,7 +2797,12 @@ module.exports = class Router extends EventEmitter {
             // its own handler always: the shared one would carry the GET registration's method
             this.uwsApp.head(
                 replacedPath,
-                makeHandler(headChain, canPreset ? makePreset(route.path, "HEAD", headSkips) : undefined, headSkips)
+                makeHandler(
+                    headChain,
+                    canPreset ? makePreset(route.path, "HEAD", headSkips) : undefined,
+                    headSkips,
+                    "HEAD"
+                )
             );
         }
     }
@@ -2741,14 +2961,16 @@ module.exports = class Router extends EventEmitter {
                 raiseDecodeFailure(req, route, err);
                 return "route";
             }
-            if (mergesParams(route, this) && req._paramStack !== null && req._paramStack.length > 0) {
+            // the stack check first: it is two field loads, mergesParams is a call, and almost
+            // no request carries a param stack at all
+            if (req._paramStack !== null && req._paramStack.length > 0 && mergesParams(route, this)) {
                 req.params = mergeParams(req.params, req._paramStack);
             }
         } else {
             // express 5 gives every matched route null-prototype params; only a pathless
             // middleware layer keeps the plain object, as its router hands one to fast_slash
             req.params = route.use && route.path === "" ? {} : Object.create(null);
-            if (mergesParams(route, this) && req._paramStack !== null && req._paramStack.length > 0) {
+            if (req._paramStack !== null && req._paramStack.length > 0 && mergesParams(route, this)) {
                 req.params = mergeParams(req.params, req._paramStack);
             }
         }
@@ -3132,8 +3354,12 @@ module.exports = class Router extends EventEmitter {
             return;
         }
         response.status(404);
-        // the whole path, not what a mount left behind in req.path
-        this._sendErrorPage(request, response, `Cannot ${request.method} ${request._originalPath}`, false);
+        // the pathname of originalUrl, as express's finalhandler prints it: _originalPath absorbs
+        // a req.url rewrite, originalUrl never changes
+        const originalUrl = String(request.originalUrl);
+        const queryIndex = originalUrl.indexOf("?");
+        const pathname = queryIndex === -1 ? originalUrl : originalUrl.slice(0, queryIndex);
+        this._sendErrorPage(request, response, `Cannot ${request.method} ${pathname}`, false);
     }
 };
 

package/src/types.d.ts

@@ -50,6 +50,12 @@ declare module "fulmine.js" {
             enforceEncoding?: string;
             /** Brotli options. The default quality is 4. */
             brotli?: BrotliOptions;
+            /**
+             * The encodings this middleware may answer with; what is not named is never used,
+             * however the client ranks it. Fulmine's own option, the compression module has no
+             * equivalent. An uncompressed answer is always on offer.
+             */
+            encodings?: ("br" | "gzip" | "deflate" | "identity")[];
         }
         // what listen() decided about each route, for a test to hold on to
         interface RouteVerdict {

package/src/utils.js

@@ -1510,6 +1510,11 @@ function validateHeaderName(name) {
     }
 }
 
+// values already accepted, so the constant strings middleware writes per request, helmet's CSP
+// among them, skip the scan. Insert-only after the regex accepts, so a hit cannot change a
+// verdict; bounded, and set-cookie values are per-user so they stay out
+const KNOWN_HEADER_VALUES = new Set();
+
 /**
  * Refuses a header value holding a character that cannot go on the wire, with node's error. An
  * array is sent as one header per entry, so each entry is checked on its own rather than as the
@@ -1527,9 +1532,19 @@ function validateHeaderValue(name, value) {
         }
         return;
     }
+    if (KNOWN_HEADER_VALUES.has(value)) {
+        return;
+    }
     if (HEADER_VALUE.test(value)) {
         throw headerError(`Invalid character in header content ["${name}"]`, "ERR_INVALID_CHAR");
     }
+    if (
+        KNOWN_HEADER_VALUES.size < 512 &&
+        value.length <= 1024 &&
+        !(name.length === 10 && name.toLowerCase() === "set-cookie")
+    ) {
+        KNOWN_HEADER_VALUES.add(value);
+    }
 }
 
 /**
@@ -1629,6 +1644,7 @@ module.exports = {
     negotiateEncoding,
     ENCODING_BR,
     ENCODING_GZIP,
+    ENCODING_DEFLATE,
     ENCODING_ANY,
     memoizeByString,
     isRangeFresh,