fulmine.js 5.1.4 → 5.1.7

package/NOTICE

@@ -12,6 +12,10 @@ itself and can be inspected with `git log` and `git shortlog -sn`.
 Fulmine is not affiliated with, endorsed by, or maintained by the authors of
 Ultimate Express.
 
+This product includes code derived from fast-querystring
+(https://github.com/anonrig/fast-querystring), Copyright (c) Yagiz Nizipli,
+licensed under the MIT License, vendored in src/parse-query.js.
+
 As required by section 4(b) of the Apache License, the following are the
 significant changes made to the original work:
 
@@ -19,10 +23,27 @@ significant changes made to the original work:
   - Public API documented, and type checked from those annotations.
   - Router dispatch reworked so a chain of N middlewares allocates one promise
     instead of N, and the mount stack is no longer walked on every hop.
-  - Request bodies are collected into a single buffer instead of being copied
-    once per chunk and again on concatenation.
+  - Request bodies are collected in native code by uWebSockets.js when the
+    length is known, with the size limit enforced before any byte reaches
+    JavaScript, instead of being copied once per chunk and again on
+    concatenation; the body parsers read the few headers they need from the
+    raw header entries and bind the caller's async context only when a read
+    actually goes asynchronous.
   - Empty request bodies now produce the same value each Express body parser
     produces, rather than being skipped.
+  - Routes whose path is a literal are registered as native uWebSockets.js
+    routes, with their path and method handed to the request as
+    registration-time constants.
+  - sendFile answers small unchanged files from a stat-validated cache, and
+    concurrent reads of the same file are coalesced.
+  - The query string parser is vendored from fast-querystring and answers on a
+    bare null prototype, matching how Express displays parsed queries.
+  - Express 5's own test suite runs against Fulmine as a CI gate, from a
+    pinned checkout of Express.
+  - The app is callable as a request listener, so http.createServer(app),
+    supertest and anything else that invokes an app directly keeps working
+    through a node:http shim.
+  - Releases are built and published to npm from CI.
   - Benchmark harness reworked: wrk replaced by autocannon so the suite runs
     anywhere Node does, NODE_ENV is set, load errors and response validation are
     no longer discarded, rows bounded by shared work are labelled, and scenarios

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.
@@ -90,6 +90,31 @@ npx fulmine differences         # print the list below and change nothing
 The command is installed under both `fulmine` and `fulmine.js`. Use `fulmine`: `npx` cannot run a
 command whose name ends in `.js` on Windows, where it exits without a word.
 
+## Docker
+
+Two things about µWebSockets.js make a Dockerfile that works for Express fail here, and both have easy answers:
+
+- **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-trixie AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+FROM node:22-trixie-slim
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+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
 
 - `app.listen()` returns the app, not an `http.Server`. There is no node server underneath, so `server.close()`, `server.address()` and anything that attaches itself to a real `http.Server` need a look. `app.close()`, `app.address()` and `app.listening` are there and do what you would expect.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.1.4",
+    "version": "5.1.7",
     "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,14 @@ 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;
+                }
+                this._skipPresets.clear();
+            }
             if (typeof value === "function") {
                 this.settings["etag fn"] = value;
             } else {
@@ -431,10 +440,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");
 
@@ -289,7 +290,10 @@ function serveStatic(root, options) {
     options._ownEtag = true;
 
     return (req, res, next) => {
-        next = AsyncResource.bind(next);
+        // Not bound here: every path down to sendFile is synchronous, statSync included, so the
+        // caller's async context is intact at each of these next() calls. Only sendFile's
+        // completion can arrive on a uWS callback that carries no context, and that one
+        // continuation is bound where it is handed over.
 
         // a file is read, not written: anything but GET and HEAD belongs to whoever comes next, or
         // is refused outright when this middleware is the last word
@@ -410,11 +414,15 @@ function serveStatic(root, options) {
 
         options._stat = stat;
 
-        return res.sendFile(_path, options, (e) => {
-            if (e) {
-                next(options.fallthrough && FALLTHROUGH_STATUSES.has(e.status) ? undefined : e);
-            }
-        });
+        return res.sendFile(
+            _path,
+            options,
+            AsyncResource.bind((e) => {
+                if (e) {
+                    next(options.fallthrough && FALLTHROUGH_STATUSES.has(e.status) ? undefined : e);
+                }
+            })
+        );
     };
 }
 
@@ -462,9 +470,11 @@ function createInflate(contentEncoding) {
  * @param {string} [charsetPolicy] which charsets this parser accepts, as body-parser draws the
  *   lines: "utf" (json, utf-* only), "urlencoded" (utf-8 and iso-8859-1), "any" (anything iconv
  *   knows), or undefined for a parser that never decodes (raw)
+ * @param {boolean} [keepsBuffer] whether the collected buffer itself escapes to the application,
+ *   which rules out handing it a view over uWS memory
  * @returns {(options?: object) => Function} the middleware factory
  */
-function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy) {
+function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy, keepsBuffer) {
     return function (options) {
         // a copy, because everything below writes the parsed values back: with the caller's own
         // object, altering it after the parser was built would alter the parser
@@ -500,6 +510,10 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
         }
         if (typeof options.defaultCharset === "undefined") options.defaultCharset = "utf-8";
 
+        // whether the collected bytes escape the collection callback: the raw parser hands the
+        // buffer itself to the application, and a verify hook may keep what it is shown
+        const copyBody = keepsBuffer || typeof options.verify === "function";
+
         // Whether a content-type is one this parser claims, remembered per parser.
         //
         // Only reached when the caller asked for a wildcard or a list, since a plain type takes the
@@ -513,15 +527,18 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
 
         let additionalMethods;
 
-        return (req, res, next) => {
-            next = AsyncResource.bind(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.
 
             // skip reading body twice
             if (req.bodyRead) {
                 return next();
             }
 
-            const type = req.headers["content-type"];
+            // straight from the raw entries: three headers do not justify building the object
+            const type = req._rawHeader("content-type");
 
             // req.body is deliberately left undefined until a parser claims the request. That is
             // what lets a handler tell "nothing parsed this" apart from "the body was empty",
@@ -534,13 +551,13 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 return next();
             }
 
-            const length = req.headers["content-length"];
+            const length = req._rawHeader("content-length");
 
             // No content-length and no transfer-encoding means the request carries no body at all,
             // and a body parser must leave it alone rather than parse nothing into an empty value.
             // type-is applies this before matching the type, but the simpleType shortcut below
             // compares strings directly and would otherwise skip the check.
-            if (req.headers["transfer-encoding"] === undefined && isNaN(length)) {
+            if (req._rawHeader("transfer-encoding") === undefined && isNaN(length)) {
                 return next();
             }
 
@@ -620,7 +637,8 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             const abs = [];
             let inflate;
             let totalSize = 0;
-            const contentEncoding = (req.headers["content-encoding"] || "identity").toLowerCase();
+            const rawContentEncoding = req._rawHeader("content-encoding");
+            const contentEncoding = (rawContentEncoding || "identity").toLowerCase();
             if (!options.inflate && contentEncoding !== "identity") {
                 return next(
                     bodyError("content encoding unsupported", 415, "encoding.unsupported", {
@@ -629,19 +647,64 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 );
             }
             if (options.inflate) {
-                inflate = createInflate(req.headers["content-encoding"]);
+                inflate = createInflate(rawContentEncoding);
                 if (inflate === false) {
                     return next(
                         bodyError(
-                            'unsupported content encoding "' + req.headers["content-encoding"] + '"',
+                            'unsupported content encoding "' + rawContentEncoding + '"',
                             415,
                             "encoding.unsupported",
-                            { encoding: req.headers["content-encoding"] }
+                            {
+                                encoding: rawContentEncoding
+                            }
                         )
                     );
                 }
             }
 
+            // From here the body really gets read, and uWS delivers it on native callbacks that
+            // carry no async context, so this is the one continuation that has to be bound: an
+            // upstream middleware's AsyncLocalStorage must still be there when next runs
+            next = AsyncResource.bind(next);
+
+            // with a known content-length and nothing to decompress, uWS can collect the whole
+            // body in native code: one callback instead of one per chunk, the limit enforced
+            // before any byte reaches JS, and no copy at all - the parsers turn the bytes into
+            // req.body before the callback returns, so a view over uWS's own memory is enough
+            if (!req.receivedData && !inflate && !isNaN(length) && Number(length) > 0 && req._res.collectBody) {
+                req.bodyRead = true;
+                const declared = Number(length);
+                req._res.collectBody(options.limit, (body) => {
+                    if (body === null) {
+                        // over maxSize: uWS refused it natively
+                        return next(
+                            bodyError("request entity too large", 413, "entity.too.large", {
+                                limit: options.limit,
+                                received: options.limit
+                            })
+                        );
+                    }
+                    if (body.byteLength !== declared) {
+                        return next(
+                            bodyError("request size did not match content length", 400, "request.size.invalid", {
+                                expected: declared,
+                                length: declared,
+                                received: body.byteLength
+                            })
+                        );
+                    }
+                    let buf = Buffer.from(body);
+                    if (copyBody) {
+                        buf = Buffer.from(buf);
+                    }
+                    if (!runVerify(req, res, next, options, buf)) {
+                        return;
+                    }
+                    beforeReturn(req, res, next, options, buf, encoding);
+                });
+                return;
+            }
+
             // uWS neuters its ArrayBuffer after the callback, so every chunk has to be copied out of
             // it - and then Buffer.concat copied the whole body a second time. when content-length is
             // known and we aren't inflating, the final size is known up front, so chunks can go
@@ -813,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;
     };
 }
 
@@ -860,10 +931,17 @@ const json = createBodyParser(
     "utf"
 );
 
-const raw = createBodyParser("application/octet-stream", function (req, res, next, options, buf) {
-    req.body = buf;
-    next();
-});
+const raw = createBodyParser(
+    "application/octet-stream",
+    function (req, res, next, options, buf) {
+        req.body = buf;
+        next();
+    },
+    undefined,
+    undefined,
+    // req.body is the collected buffer itself, so it must not be a view over uWS memory
+    true
+);
 
 const text = createBodyParser(
     "text/plain",

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) {
@@ -324,6 +369,28 @@ module.exports = class Request extends Readable {
         });
     }
 
+    /**
+     * One header by its lowercase wire name, straight from the raw entries. The body parsers ask
+     * for three of these per request, and materializing the whole headers object for that costs
+     * more than all three scans together. Reads the built object instead when it already exists,
+     * so joined duplicates come out the same either way.
+     *
+     * @param {string} name lowercase
+     * @returns {string|undefined}
+     */
+    _rawHeader(name) {
+        if (this.#cachedHeaders !== null) {
+            return this.#cachedHeaders[name];
+        }
+        const entries = this.#rawHeadersEntries;
+        for (let i = 0, len = entries.length; i < len; i += 2) {
+            if (entries[i] === name) {
+                return entries[i + 1];
+            }
+        }
+        return undefined;
+    }
+
     /**
      * Whether there is any point still reading the body: once the response is finished or the
      * connection is gone, uWS has nothing left to hand over.

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 { chainSkipsHeaders } = 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,38 @@ 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; mutable,
+        // because a middleware added after listen has to be able to take it back
+        skipHeaders: 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 +851,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 +1142,16 @@ 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;
+            }
+            this._skipPresets.clear();
+        }
+
         return parent;
     }
 
@@ -1338,10 +1383,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 +1464,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) {
+                skipHolder = { skipHeaders: true };
+                (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 +1485,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 +1516,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 +1527,45 @@ 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.
+        let getSkips = false;
+        let headSkips = false;
+        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 = chainSkipsHeaders(getChain, noLaterMatch);
+                headSkips = headChain === getChain ? getSkips : chainSkipsHeaders(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) {
+                preset.skipHeaders = true;
+                (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 +1595,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 +1613,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,247 @@
+"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"]);
+
+// 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
+const NO = 0; // could read headers, or could not be read at all
+const SAFE = 1; // never reads a header, never touches next
+const SAFE_NEXT = 2; // never reads a header, calls next: fine mid-chain, and at the end of
+// the chain only when no later route could catch the fall-through
+
+const verdicts = new WeakMap();
+
+/**
+ * What one callback provably does. The default is NO: any shape this walk does not understand
+ * and any alias of req, res or next keeps the header copy. That inversion is what makes
+ * source analysis sound to act on.
+ *
+ * @param {Function} fn
+ * @returns {number} NO, SAFE or SAFE_NEXT
+ */
+function callbackSkipsHeaders(fn) {
+    if (fn[kGetSafe]) {
+        return SAFE_NEXT;
+    }
+    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 NO;
+    }
+    let root = /** @type {any} */ (tree.body[0]);
+    if (!root) {
+        return NO;
+    }
+    if (root.type === "ExpressionStatement") {
+        root = root.expression;
+    }
+    if (
+        root.type !== "FunctionDeclaration" &&
+        root.type !== "ArrowFunctionExpression" &&
+        root.type !== "FunctionExpression"
+    ) {
+        return NO;
+    }
+
+    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 NO;
+        }
+    }
+    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 ok = true;
+    let usesNext = false;
+    walk(root.body, null, (node, parent) => {
+        if (!ok || node.type !== "Identifier") {
+            return;
+        }
+        const name = node.name;
+        if (name === "eval" || name === "arguments") {
+            ok = false;
+            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 handler, 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) {
+                ok = false;
+                return;
+            }
+            usesNext = true;
+            const args = parent.arguments;
+            if (args.length === 0) {
+                return;
+            }
+            const arg = args[0];
+            if (
+                args.length > 1 ||
+                (arg.type !== "NewExpression" &&
+                    arg.type !== "ObjectExpression" &&
+                    !(arg.type === "Literal" && typeof arg.value !== "string"))
+            ) {
+                ok = false;
+            }
+            return;
+        }
+        if (!parent || parent.type !== "MemberExpression" || parent.object !== node || parent.computed) {
+            ok = false;
+            return;
+        }
+        const member = parent.property.name;
+        if (name === reqName ? !REQ_OK.has(member) : !RES_OK.has(member)) {
+            ok = false;
+        }
+    });
+    return ok ? (usesNext ? SAFE_NEXT : SAFE) : NO;
+}
+
+/**
+ * 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);
+        }
+    }
+}
+
+/**
+ * Whether a native literal route's whole chain provably never reads a request header, so the
+ * request constructor may skip copying them and read the few framing headers directly.
+ *
+ * A callback that calls next passes anywhere but in the terminal route, where next would fall
+ * out of the chain: there it only passes when the caller established that no later route
+ * could catch the fall-through.
+ *
+ * @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 handler
+ * @returns {boolean}
+ */
+function chainSkipsHeaders(chain, allowTerminalNext) {
+    for (let i = 0; i < chain.length; i++) {
+        const entry = chain[i];
+        const callbacks = entry.callbacks;
+        if (!Array.isArray(callbacks)) {
+            return false;
+        }
+        const terminal = i === chain.length - 1;
+        for (const cb of callbacks) {
+            if (typeof cb !== "function") {
+                return false;
+            }
+            const verdict = callbackSkipsHeaders(cb);
+            if (verdict === NO || (verdict === SAFE_NEXT && terminal && !allowTerminalNext)) {
+                return false;
+            }
+        }
+        // a param callback runs code this walk never saw
+        if (entry.paramCallbacks && entry.paramCallbacks.size > 0) {
+            return false;
+        }
+    }
+    return true;
+}
+
+module.exports = { chainSkipsHeaders, callbackSkipsHeaders, kGetSafe };