fulmine.js 5.1.6 → 5.1.8

package/README.md

@@ -55,7 +55,7 @@ to run it yourself.
 
 Numbers produced by a project about itself deserve suspicion, so Fulmine also stands in public arenas, run by their own rigs under their own rules:
 
-- **[HttpArena](https://www.http-arena.com/#sort=rps:-1&q=Js)** (the link lands filtered on the JavaScript entries): the saved run measures 5.89 million pipelined requests per second, 1.12 million on baseline and 1.04 million on the json profile, ahead of every JavaScript entry on the board.
+- **[HttpArena](https://www.http-arena.com/#sort=rps:-1&q=Js)** (the link lands filtered on the JavaScript entries): first among the JavaScript entries and second overall across every language on the board. The saved run measures 7.64 million pipelined requests per second, 1.12 million on the json profile, 457 thousand on compressed json and 222 thousand on the Postgres profile.
 - **[web-frameworks](https://github.com/the-benchmarker/web-frameworks)**: entry merged, numbers arrive with their next published round.
 
 More to come as their maintainers take the entries in.
@@ -94,18 +94,18 @@ command whose name ends in `.js` on Windows, where it exits without a word.
 
 Two things about µWebSockets.js make a Dockerfile that works for Express fail here, and both have easy answers:
 
-- **No Alpine.** µWebSockets.js ships prebuilt binaries linked against glibc. Alpine images use musl, so the binary does not load. Use a Debian-based image such as `node:22-slim` instead of `node:22-alpine`.
-- **`git` must be there when `npm install` runs.** µWebSockets.js is not on npm; it is installed straight from GitHub (`github:uNetworking/uWebSockets.js`), and npm uses git to fetch it. Full images like `node:22` have git; `-slim` ones do not.
+- **No Alpine, and no Debian bookworm either.** µWebSockets.js ships prebuilt binaries linked against glibc 2.38 or newer. Alpine images use musl, so the binary does not load at all; `node:22` and `node:22-slim` are Debian bookworm, whose glibc 2.36 fails at startup with `GLIBC_2.38' not found`. Use the trixie variants: `node:22-trixie-slim` and up.
+- **`git` must be there when `npm install` runs.** µWebSockets.js is not on npm; it is installed straight from GitHub (`github:uNetworking/uWebSockets.js`), and npm uses git to fetch it. Full images like `node:22-trixie` have git; `-slim` ones do not.
 
 The clean way to satisfy both is a multi-stage build: install with the full image, run with the slim one.
 
 ```dockerfile
-FROM node:22 AS build
+FROM node:22-trixie AS build
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --omit=dev
 
-FROM node:22-slim
+FROM node:22-trixie-slim
 WORKDIR /app
 COPY --from=build /app/node_modules ./node_modules
 COPY . .
@@ -113,7 +113,7 @@ EXPOSE 3000
 CMD ["node", "server.js"]
 ```
 
-A single-stage `node:22-slim` image works too if you `apt-get install -y git` before `npm ci`. Prebuilt binaries exist for x64 and arm64 on Linux, macOS and Windows, so nothing is compiled at install time either way.
+A single-stage `node:22-trixie-slim` image works too if you `apt-get install -y git ca-certificates` before `npm ci`. Prebuilt binaries exist for x64 and arm64 on Linux, macOS and Windows, so nothing is compiled at install time either way.
 
 ## Differences from Express
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.1.6",
+    "version": "5.1.8",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {

package/src/application.js

@@ -128,9 +128,10 @@ class Application extends Router {
              * @param {any} res
              * @param {any} app
              * @param {any} [preset]
+             * @param {any} [skipHolder]
              */
-            constructor(req, res, app, preset) {
-                super(req, res, app, preset);
+            constructor(req, res, app, preset, skipHolder) {
+                super(req, res, app, preset, skipHolder);
             }
         };
         this._response = class extends Response {
@@ -359,6 +360,15 @@ class Application extends Router {
             this.settings[key] = Array.isArray(value) ? value.map((dir) => path.resolve(dir)) : path.resolve(value);
             return this;
         } else if (key === "etag") {
+            // an etag arriving after listen would make send consult freshness headers the
+            // header-skip routes never copied, so those skips are taken back
+            if (value !== false && this._skipPresets?.size) {
+                for (const preset of this._skipPresets) {
+                    preset.skipHeaders = false;
+                    preset.skipQuery = false;
+                }
+                this._skipPresets.clear();
+            }
             if (typeof value === "function") {
                 this.settings["etag fn"] = value;
             } else {
@@ -431,10 +441,12 @@ class Application extends Router {
      * @param {any} res uWS response
      * @param {any} req uWS request, readable only during this call
      * @param {any} [preset] a literal registration's constants, see nativePreset in the router
+     * @param {any} [skipHolder] where a granted header skip lives, forwarded whole: dropping
+     *   it here silently turned every skip off, since the native closures call this override
      * @returns {any} the request, with the response reachable as request.res
      */
-    handleRequest(res, req, preset) {
-        const request = super.handleRequest(res, req, preset);
+    handleRequest(res, req, preset, skipHolder) {
+        const request = super.handleRequest(res, req, preset, skipHolder);
         // removal rides the close listener the Response constructor already has, since a second
         // once() per request measured a tenth of a microsecond on the hot path.
         // An aborted response only flips its flags without emitting 'close', which is why

package/src/middlewares.js

@@ -22,6 +22,7 @@ const zlib = require("fast-zlib");
 const typeis = require("type-is");
 const qs = require("qs");
 const parseQuery = require("./parse-query.js");
+const { kGetSafe } = require("./usage.js");
 const { AsyncResource } = require("async_hooks");
 const { fastQueryParse, NullObject, asStatError, httpError, memoizeByString } = require("./utils.js");
 
@@ -526,7 +527,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
 
         let additionalMethods;
 
-        return (req, res, next) => {
+        const parserMiddleware = (req, res, next) => {
             // Not bound yet: every return in this prologue is synchronous, so the caller's async
             // context is still intact and an AsyncResource here would be 1.4 microseconds of
             // nothing. The bind happens below, only once a real read is about to go async.
@@ -875,6 +876,14 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 req.on("end", onEnd);
             }
         };
+        // A GET without a declared body leaves this middleware through the synchronous
+        // no-body exit before anything type- or charset-shaped is read, and a GET that does
+        // declare one takes the full header copy in the constructor, so the header-skip
+        // analysis may trust it. A type function sees the request itself, so it may not.
+        if (typeof options.type !== "function") {
+            parserMiddleware[kGetSafe] = true;
+        }
+        return parserMiddleware;
     };
 }
 

package/src/request.js

@@ -200,16 +200,61 @@ module.exports = class Request extends Readable {
      * @param {any} [preset] a literal native registration's constants: µWS matched the URL byte
      *   for byte against that exact pattern and dispatched by method, so path, method and what
      *   derives from them are known without asking
+     * @param {any} [skipHolder] where a granted header skip lives: the preset itself for a
+     *   literal registration, a holder of its own for a parameterised one
      */
-    constructor(req, res, app, preset) {
+    constructor(req, res, app, preset, skipHolder) {
         // the same object every time: Readable reads these options and never writes to them
         super(READABLE_OPTIONS);
         this._res = res;
         this._req = req;
         this.readable = true;
-        currentRequest = this;
-        this._req.forEach(Request.#collectHeader);
-        currentRequest = null;
+        if (skipHolder !== undefined && skipHolder.skipHeaders) {
+            // The chain behind this registration provably never reads a header, so instead of
+            // copying them all out of uWS the constructor asks for the four that steer the
+            // framework itself: body framing, keep-alive, and accept for the error page a
+            // throw could still need. A GET that does declare a body is the rare case, and
+            // the parsers and the stream want the whole picture, so it takes the full copy.
+            const length = req.getHeader("content-length");
+            const transferEncoding = req.getHeader("transfer-encoding");
+            if ((length !== "" && length !== "0") || transferEncoding !== "") {
+                currentRequest = this;
+                this._req.forEach(Request.#collectHeader);
+                currentRequest = null;
+            } else {
+                const entries = this.#rawHeadersEntries;
+                const connection = req.getHeader("connection");
+                if (connection !== "") {
+                    entries.push("connection", connection);
+                    if (connection.length === 5 && connection.toLowerCase() === "close") {
+                        this._connectionClose = true;
+                    }
+                }
+                const accept = req.getHeader("accept");
+                if (accept !== "") {
+                    entries.push("accept", accept);
+                }
+                // send consults freshness whatever the etag setting: if-none-match can be "*"
+                // and a handler may set a validator by hand, so the conditional trio has to be
+                // really absent rather than merely uncopied
+                const ifNoneMatch = req.getHeader("if-none-match");
+                if (ifNoneMatch !== "") {
+                    entries.push("if-none-match", ifNoneMatch);
+                }
+                const ifModifiedSince = req.getHeader("if-modified-since");
+                if (ifModifiedSince !== "") {
+                    entries.push("if-modified-since", ifModifiedSince);
+                }
+                const cacheControl = req.getHeader("cache-control");
+                if (cacheControl !== "") {
+                    entries.push("cache-control", cacheControl);
+                }
+            }
+        } else {
+            currentRequest = this;
+            this._req.forEach(Request.#collectHeader);
+            currentRequest = null;
+        }
         this.routeCount = 1;
         this.key = key++;
         if (key > 100000) {
@@ -218,9 +263,16 @@ module.exports = class Request extends Readable {
         this.app = app;
         // both forms are kept, because both are asked for: the query with its "?" goes into
         // req.url, and req.query parses the raw one. Keeping only the first meant slicing the "?"
-        // back off for every request that reads req.query.
-        this._rawQuery = req.getQuery() ?? "";
-        this.urlQuery = this._rawQuery === "" ? "" : "?" + this._rawQuery;
+        // back off for every request that reads req.query. When the chain provably reads
+        // neither, the native call is not made at all: the framework's own answers, the 404
+        // included, are written from the path alone
+        if (skipHolder !== undefined && skipHolder.skipQuery) {
+            this._rawQuery = "";
+            this.urlQuery = "";
+        } else {
+            this._rawQuery = req.getQuery() ?? "";
+            this.urlQuery = this._rawQuery === "" ? "" : "?" + this._rawQuery;
+        }
         if (preset) {
             // the registration's constants: two native crossings and their strings not asked for
             this.path = preset.path;

package/src/router.js

@@ -36,6 +36,7 @@ const compileDeclarative = require("./declarative.js");
 const statuses = require("statuses");
 const { METHODS } = require("http");
 const { isNodeRequest, serveNodeRequest } = require("./node-shim.js");
+const { chainUsage } = require("./usage.js");
 
 // every method the declarative compiler can emit: a patched one must disable compilation, or the
 // patch would be honoured everywhere but on compiled routes
@@ -691,10 +692,39 @@ function nativePreset(path, method, strict) {
         endsWithSlash,
         opPath: endsWithSlash && path !== "/" && !strict ? path.slice(0, -1) : path,
         isOptions: method === "OPTIONS",
-        isHead: method === "HEAD"
+        isHead: method === "HEAD",
+        // set at registration when the whole chain provably never reads a header, or never
+        // reads the query; mutable, because a middleware added after listen takes them back
+        skipHeaders: false,
+        skipQuery: false
     };
 }
 
+/**
+ * Whether any error middleware exists anywhere under this router, mounted routers and sub-apps
+ * included. The header-skip analysis needs the answer to be no: a throw inside an analyzed
+ * handler would hand the request to code nobody analyzed.
+ *
+ * @param {any} router
+ * @returns {boolean}
+ */
+function hasErrorMiddleware(router) {
+    for (const route of router._routes) {
+        for (const callback of route.callbacks) {
+            // a mounted router or a callable sub-app carries routes of its own; the callable
+            // app is also a function, so the routes are looked for first
+            if (callback && callback._routes) {
+                if (hasErrorMiddleware(callback)) {
+                    return true;
+                }
+            } else if (typeof callback === "function" && callback.length >= 4) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
 /**
  *
  */
@@ -822,6 +852,12 @@ module.exports = class Router extends EventEmitter {
         this._paramCallbacks = new Map();
         this._mountpathCache = new Map();
         this._routes = [];
+        // the native presets allowed to skip the header copy, so a late middleware or an etag
+        // arriving after listen can take the permission back; null until one is granted
+        /** @type {Set<any>|null} */
+        this._skipPresets = null;
+        /** @type {boolean|undefined} */
+        this._hasErrMwCache = undefined;
         // an array when mounted on several paths at once, as Express allows
         /** @type {string|string[]} */
         this.mountpath = "/";
@@ -1107,6 +1143,17 @@ module.exports = class Router extends EventEmitter {
         }
         this._routes.push(...routes);
 
+        // 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
+        this._hasErrMwCache = undefined;
+        if (this._skipPresets?.size) {
+            for (const preset of this._skipPresets) {
+                preset.skipHeaders = false;
+                preset.skipQuery = false;
+            }
+            this._skipPresets.clear();
+        }
+
         return parent;
     }
 
@@ -1338,10 +1385,12 @@ module.exports = class Router extends EventEmitter {
      * @param {any} res uWS response
      * @param {any} req uWS request, readable only during this call
      * @param {any} [preset] a literal registration's constants, see nativePreset
+     * @param {any} [skipHolder] the object a granted header skip lives on: the preset itself
+     *   for a literal registration, a holder of its own for a parameterised one
      * @returns {any} the request, with the response reachable as request.res
      */
-    handleRequest(res, req, preset) {
-        const request = new this._request(req, res, this, preset);
+    handleRequest(res, req, preset, skipHolder) {
+        const request = new this._request(req, res, this, preset, skipHolder);
         const response = new this._response(res, request, this);
         request.res = response;
         response.req = request;
@@ -1417,7 +1466,15 @@ module.exports = class Router extends EventEmitter {
         if (route.path.includes(":")) {
             route.optimizedParams = route.path.match(regExParam).map((p) => p.slice(1));
         }
-        const makeHandler = (chain, preset) => {
+        const makeHandler = (chain, preset, skips) => {
+            // 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
+            let skipHolder = preset;
+            if (skipHolder === undefined && (skips.skipHeaders || skips.skipQuery)) {
+                skipHolder = { skipHeaders: skips.skipHeaders, skipQuery: 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.
             // Falling back resumes after the mount, not after the router's leaf: the leaf can have
@@ -1430,7 +1487,7 @@ module.exports = class Router extends EventEmitter {
             // and this one never did. nativeDone and nativeFail defer their epilogues to a
             // microtask, which is where the await used to resume, so the visible order holds
             return (res, req) => {
-                const request = this.handleRequest(res, req, preset);
+                const request = this.handleRequest(res, req, preset, skipHolder);
                 const response = request.res;
                 if (optimizedParams) {
                     request.optimizedParams = new NullObject();
@@ -1461,6 +1518,7 @@ module.exports = class Router extends EventEmitter {
         const getChain =
             route.method === "GET" ? optimizedPath.filter((r) => r.all || r.method !== "HEAD") : optimizedPath;
         route.optimizedPath = optimizedPath;
+        const headChain = getChain.length === optimizedPath.length ? getChain : optimizedPath;
 
         // A fully literal registration knows path and method here, so each registration site
         // hands the request constructor its own constants. An "any" registration serves every
@@ -1471,11 +1529,47 @@ module.exports = class Router extends EventEmitter {
         // registering that path here is the only way it could
         const strictHere = Boolean((route.owner ?? this).get("strict routing"));
 
-        let fn = makeHandler(getChain, canPreset ? nativePreset(route.path, route.method, strictHere) : undefined);
+        // Whether requests served by this registration may skip the header copy: GET and its
+        // HEAD twins only, the app must not compute etags (send would consult freshness
+        // headers), no error middleware may exist anywhere (a throw hands the request to code
+        // the analysis never saw), and every callback in the chain has to pass the source
+        // analysis in usage.js, whose default answer is no.
+        const NO_SKIPS = { skipHeaders: false, skipQuery: false };
+        let getSkips = NO_SKIPS;
+        let headSkips = NO_SKIPS;
+        if (route.method === "GET" && this.get("etag") === false) {
+            let hasErr = this._hasErrMwCache;
+            if (hasErr === undefined) {
+                hasErr = this._hasErrMwCache = hasErrorMiddleware(this);
+            }
+            if (!hasErr) {
+                // a terminal next() may only fall into the framework's own 404, so no later
+                // route may be able to catch the same path
+                const owner = route.owner ?? this;
+                const noLaterMatch = !owner._isFollowedByAnOverlap.call(owner, route, owner._routes);
+                getSkips = chainUsage(getChain, noLaterMatch);
+                headSkips = headChain === getChain ? getSkips : chainUsage(headChain, noLaterMatch);
+            }
+        }
+        // remembered so a middleware or setting arriving after listen can take the skips back
+        const makePreset = (path, method, skips) => {
+            const preset = nativePreset(path, method, strictHere);
+            if (skips.skipHeaders || skips.skipQuery) {
+                preset.skipHeaders = skips.skipHeaders;
+                preset.skipQuery = skips.skipQuery;
+                (this._skipPresets ??= new Set()).add(preset);
+            }
+            return preset;
+        };
+
+        let fn = makeHandler(
+            getChain,
+            canPreset ? makePreset(route.path, route.method, getSkips) : undefined,
+            getSkips
+        );
         const jsFn = fn;
 
         let replacedPath = route.path;
-        const headChain = getChain.length === optimizedPath.length ? getChain : optimizedPath;
 
         // the response prototype the route will really run under: its own app's, which sees a
         // method patched there or inherited from a parent app, falling back to the registering app
@@ -1505,13 +1599,17 @@ module.exports = class Router extends EventEmitter {
                 fn !== jsFn
                     ? fn
                     : canPreset
-                      ? makeHandler(getChain, nativePreset(route.path + "/", route.method, strictHere))
+                      ? makeHandler(getChain, makePreset(route.path + "/", route.method, getSkips), getSkips)
                       : fn;
             this.uwsApp[method](replacedPath + "/", slashFn);
             if (method === "get") {
                 this.uwsApp.head(
                     replacedPath + "/",
-                    makeHandler(headChain, canPreset ? nativePreset(route.path + "/", "HEAD", strictHere) : undefined)
+                    makeHandler(
+                        headChain,
+                        canPreset ? makePreset(route.path + "/", "HEAD", headSkips) : undefined,
+                        headSkips
+                    )
                 );
             }
         }
@@ -1519,7 +1617,7 @@ 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 ? nativePreset(route.path, "HEAD", strictHere) : undefined)
+                makeHandler(headChain, canPreset ? makePreset(route.path, "HEAD", headSkips) : undefined, headSkips)
             );
         }
     }

package/src/usage.js

@@ -0,0 +1,286 @@
+"use strict";
+
+const acorn = require("acorn");
+
+// Marks a middleware the analysis may trust on a GET request without reading its source: the
+// body parsers set it, whose prologue only reads body-framing headers and leaves a bodyless
+// GET alone (and a GET that declares a body falls back to the full header copy).
+const kGetSafe = Symbol("fulmine.getSafe");
+
+// What a handler may do with `req` and still let the header copy be skipped: members whose
+// reads never reach a header. Anything else, computed access included, keeps the copy.
+// req.res and req.app are deliberately absent: the walk judges only the member directly on
+// the parameter, so anything that can reach another object could reach headers through it.
+const REQ_OK = new Set(["query", "params", "body", "method", "path", "url", "baseUrl", "originalUrl", "route"]);
+
+// Reading any of these needs the query string fetched: req.url and req.originalUrl carry it
+const REQ_QUERY = new Set(["query", "url", "originalUrl"]);
+
+// Writing any of these re-enters routing: dispatch treats a changed req.url as a rewrite and
+// walks routes nobody analyzed, so an assignment is as disqualifying as an unknown call
+const REQ_NO_WRITE = new Set(["url", "originalUrl", "path", "baseUrl", "method"]);
+
+// What a handler may do with `res`: writing the response. Anything that negotiates against
+// request headers (format, redirect, sendFile, jsonp) is deliberately absent.
+const RES_OK = new Set([
+    "json",
+    "send",
+    "end",
+    "status",
+    "sendStatus",
+    "set",
+    "setHeader",
+    "header",
+    "get",
+    "type",
+    "contentType",
+    "append",
+    "vary",
+    "links",
+    "locals",
+    "statusCode",
+    "writeHead",
+    "headersSent",
+    "finished",
+    "cork"
+]);
+
+// what the analysis can say about one callback, as independent facts
+const UNKNOWN = 1; // a shape the walk cannot vouch for: could do anything
+const NEXT_PLAIN = 2; // calls next() bare: advances the chain, may fall off its end
+const NEXT_ERROR = 4; // calls next(err): lands in the framework's own error answer
+const QUERY = 8; // reads req.query, req.url or req.originalUrl
+
+const verdicts = new WeakMap();
+
+/**
+ * What one callback provably does, as a mask of the facts above. The default is UNKNOWN: any
+ * shape this walk does not understand and any alias of req, res or next could do anything.
+ * That inversion is what makes source analysis sound to act on.
+ *
+ * @param {Function} fn
+ * @returns {number}
+ */
+function callbackUsage(fn) {
+    if (fn[kGetSafe]) {
+        // the body parsers: they advance the chain and read nothing a skip would miss
+        return NEXT_PLAIN;
+    }
+    let verdict = verdicts.get(fn);
+    if (verdict === undefined) {
+        verdict = analyze(fn);
+        verdicts.set(fn, verdict);
+    }
+    return verdict;
+}
+
+/** @param {Function} fn @returns {number} */
+function analyze(fn) {
+    let code = fn.toString();
+    if (code.startsWith("function") || code.startsWith("async function")) {
+        code = code.replace(/function *\(/, "function __cb(");
+    }
+    let tree;
+    try {
+        tree = acorn.parse(code, { ecmaVersion: "latest" });
+    } catch {
+        // class methods and native functions do not parse alone, and unread code is unknown code
+        return UNKNOWN;
+    }
+    let root = /** @type {any} */ (tree.body[0]);
+    if (!root) {
+        return UNKNOWN;
+    }
+    if (root.type === "ExpressionStatement") {
+        root = root.expression;
+    }
+    if (
+        root.type !== "FunctionDeclaration" &&
+        root.type !== "ArrowFunctionExpression" &&
+        root.type !== "FunctionExpression"
+    ) {
+        return UNKNOWN;
+    }
+
+    const params = /** @type {any[]} */ (root.params);
+    // rest or destructured parameters alias the objects somewhere the walk cannot follow
+    for (const p of params) {
+        if (p.type !== "Identifier") {
+            return UNKNOWN;
+        }
+    }
+    const reqName = params[0] ? params[0].name : null;
+    const resName = params[1] ? params[1].name : null;
+    const nextName = params[2] ? params[2].name : null;
+
+    // Every appearance of the three names in the whole body is judged, nested functions
+    // included: an inner binding that shadows one of them only makes this stricter, never
+    // looser, so scope tracking is not needed for soundness.
+    let mask = 0;
+    walk(root.body, null, (node, parent) => {
+        if (mask & UNKNOWN) {
+            return;
+        }
+        if (node.type === "MemberExpression" && !node.computed && node.object.type === "Identifier") {
+            const owner = node.object.name;
+            if (owner !== reqName) {
+                return;
+            }
+            const member = node.property.name;
+            if (REQ_QUERY.has(member)) {
+                mask |= QUERY;
+            }
+            // an assignment, an update or a delete on the routing members re-enters dispatch
+            if (
+                REQ_NO_WRITE.has(member) &&
+                parent &&
+                ((parent.type === "AssignmentExpression" && parent.left === node) ||
+                    (parent.type === "UpdateExpression" && parent.argument === node) ||
+                    (parent.type === "UnaryExpression" && parent.operator === "delete" && parent.argument === node))
+            ) {
+                mask |= UNKNOWN;
+            }
+            return;
+        }
+        if (node.type !== "Identifier") {
+            return;
+        }
+        const name = node.name;
+        if (name === "eval" || name === "arguments") {
+            mask |= UNKNOWN;
+            return;
+        }
+        if (name !== reqName && name !== resName && name !== nextName) {
+            return;
+        }
+        // being renamed inside a member expression (req.query's `query`) is not a use
+        if (parent && parent.type === "MemberExpression" && parent.property === node && !parent.computed) {
+            return;
+        }
+        // a redeclaration as an inner parameter or variable name is not a use either
+        if (
+            parent &&
+            (((parent.type === "FunctionDeclaration" ||
+                parent.type === "FunctionExpression" ||
+                parent.type === "ArrowFunctionExpression") &&
+                parent.params.includes(node)) ||
+                (parent.type === "VariableDeclarator" && parent.id === node) ||
+                (parent.type === "Property" && parent.key === node && !parent.computed))
+        ) {
+            return;
+        }
+        if (name === nextName) {
+            // calling next is how a chain advances, and past its end or with an error the
+            // request lands in the framework's own final answer, which the constructor's
+            // accept pre-read covers. Anything but a direct call aliases the continuation,
+            // and an argument that could be the string "route" would leave the chain for
+            // routes nobody analyzed, so only shapes that cannot be a string pass.
+            if (!parent || parent.type !== "CallExpression" || parent.callee !== node) {
+                mask |= UNKNOWN;
+                return;
+            }
+            const args = parent.arguments;
+            if (args.length === 0) {
+                mask |= NEXT_PLAIN;
+                return;
+            }
+            const arg = args[0];
+            if (
+                args.length > 1 ||
+                (arg.type !== "NewExpression" &&
+                    arg.type !== "ObjectExpression" &&
+                    !(arg.type === "Literal" && typeof arg.value !== "string"))
+            ) {
+                mask |= UNKNOWN;
+                return;
+            }
+            mask |= NEXT_ERROR;
+            return;
+        }
+        if (!parent || parent.type !== "MemberExpression" || parent.object !== node || parent.computed) {
+            mask |= UNKNOWN;
+            return;
+        }
+        const member = parent.property.name;
+        if (name === reqName ? !REQ_OK.has(member) : !RES_OK.has(member)) {
+            mask |= UNKNOWN;
+        }
+    });
+    return mask;
+}
+
+/**
+ * Walks every node, handing each its parent. Arrays and nested objects are entered, nothing
+ * is interpreted: the judging happens in the visitor.
+ *
+ * @param {any} node
+ * @param {any} parent
+ * @param {(node: any, parent: any) => void} visit
+ */
+function walk(node, parent, visit) {
+    if (!node || typeof node.type !== "string") {
+        return;
+    }
+    visit(node, parent);
+    for (const key in node) {
+        if (key === "type" || key === "start" || key === "end") {
+            continue;
+        }
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item && typeof item.type === "string") {
+                    walk(item, node, visit);
+                }
+            }
+        } else if (value && typeof value.type === "string") {
+            walk(value, node, visit);
+        }
+    }
+}
+
+/**
+ * What a native route's whole chain provably never does, so the request constructor may leave
+ * that work undone: skipHeaders spares the header copy, skipQuery the query fetch.
+ *
+ * A callback that calls next() bare passes anywhere but in the terminal route, where it would
+ * fall out of the chain: there it only passes when the caller established that no later route
+ * could catch the fall-through. The framework's own 404 answers with the path alone, so the
+ * fall-through itself needs neither headers nor query.
+ *
+ * @param {any[]} chain the routes the native handler runs, in order, this route last
+ * @param {boolean} allowTerminalNext whether a fall-through past the chain lands only in the
+ *   framework's own final answer
+ * @returns {{skipHeaders: boolean, skipQuery: boolean}}
+ */
+function chainUsage(chain, allowTerminalNext) {
+    const none = { skipHeaders: false, skipQuery: false };
+    let query = false;
+    for (let i = 0; i < chain.length; i++) {
+        const entry = chain[i];
+        const callbacks = entry.callbacks;
+        if (!Array.isArray(callbacks)) {
+            return none;
+        }
+        const terminal = i === chain.length - 1;
+        for (const cb of callbacks) {
+            if (typeof cb !== "function") {
+                return none;
+            }
+            const mask = callbackUsage(cb);
+            if (mask & UNKNOWN || (mask & NEXT_PLAIN && terminal && !allowTerminalNext)) {
+                return none;
+            }
+            if (mask & QUERY) {
+                query = true;
+            }
+        }
+        // a param callback runs code this walk never saw
+        if (entry.paramCallbacks && entry.paramCallbacks.size > 0) {
+            return none;
+        }
+    }
+    return { skipHeaders: true, skipQuery: !query };
+}
+
+module.exports = { chainUsage, callbackUsage, kGetSafe, UNKNOWN, NEXT_PLAIN, NEXT_ERROR, QUERY };