fulmine.js 5.11.0 → 5.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 # Fulmine.js
 
-A drop-in replacement for Express 5, running on [µWebSockets.js](https://github.com/uNetworking/uWebSockets.js) instead of `node:http`. Your existing middleware keeps working.
+Fulmine - means lightning ⚡ in Italian - is a drop-in replacement for Express 5, running on [µWebSockets.js](https://github.com/uNetworking/uWebSockets.js) instead of `node:http`. Your existing middleware keeps working.
 
 ```js
 const express = require("fulmine.js"); // instead of require("express")
@@ -29,9 +29,12 @@ npx fulmine.js explain /api/items  # what happens when a request for that route
 See [Migrating](#migrating) for what it handles and what it deliberately does not.
 
 [![npm version](https://img.shields.io/npm/v/fulmine.js)](https://www.npmjs.com/package/fulmine.js)
-[![Node.js >= 22.0.0](https://img.shields.io/badge/Node.js-%3E=22.0.0-green)](https://nodejs.org)
+[![Node.js 22 | 24 | 26](https://img.shields.io/badge/Node.js-22%20%7C%2024%20%7C%2026-green)](https://nodejs.org)
+[![HTTP Arena](https://img.shields.io/endpoint?url=https://www.http-arena.com/badge/fulmine/h1.json)](https://www.http-arena.com/#tuned=0)
 [![Coverage Status](https://coveralls.io/repos/github/nigrosimone/fulmine.js/badge.svg?branch=main)](https://coveralls.io/github/nigrosimone/fulmine.js?branch=main)
 [![CodeQL](https://github.com/nigrosimone/fulmine.js/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/nigrosimone/fulmine.js/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/nigrosimone/fulmine.js/badge)](https://scorecard.dev/viewer/?uri=github.com/nigrosimone/fulmine.js)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14089/badge)](https://www.bestpractices.dev/projects/14089)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
 ## Table of contents
@@ -43,6 +46,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
 - [Difference from similar projects](#difference-from-similar-projects)
 - [Migrating](#migrating)
     - [Angular SSR](#angular-ssr)
+    - [NestJS](#nestjs)
     - [When Express is somebody else's dependency](#when-express-is-somebody-elses-dependency)
 - [Docker](#docker)
 - [Differences from Express](#differences-from-express)
@@ -172,6 +176,38 @@ that runs on Express and here alike, and the same measurement says a page costs
 stores only the body makes the server hash the whole document again on every hit, and measures level
 with no cache at all on the serving side.
 
+### NestJS
+
+`@nestjs/platform-express` takes an Express instance, so it takes this one, and everything in a Nest
+application keeps working. One line stands between that and the speed: the adapter wraps whatever
+instance it is given in `http.createServer()` and listens on that, which is the shim, so every
+request goes through `node:http` and the application runs at Express's pace. The app here already
+answers as an `http.Server`, so it can be the server rather than being wrapped in one:
+
+```ts
+import { NestFactory } from "@nestjs/core";
+import { ExpressAdapter } from "@nestjs/platform-express";
+import fulmine from "fulmine.js";
+
+class FulmineAdapter extends ExpressAdapter {
+    initHttpServer() {
+        // instead of http.createServer(instance): listen() and close() are then µWS's
+        (this as any).httpServer = this.getInstance();
+    }
+}
+
+const app = await NestFactory.create(AppModule, new FulmineAdapter(fulmine()));
+await app.listen(3000);
+```
+
+Measured on the same Nest application, controllers, pipes and body parsing unchanged: **1.2x on a
+route answering text and 1.9x on one answering JSON with a route parameter**. `app.close()` closes
+the port, as it does on the shim.
+
+Two things to know. `forceCloseConnections` has nothing to destroy, since the sockets belong to µWS
+and nothing emits `connection`, and Nest looks at `app.router.stack` to decide whether it has
+already added its body parsers, which is not there, so it adds them once more than it would.
+
 ### When Express is somebody else's dependency
 
 A framework built on Express does not `require("express")` in your code, it requires it in its own,
@@ -249,6 +285,7 @@ A single-stage `node:26-trixie-slim` image works too if you `apt-get install -y
 - `app.listen()` returns the app rather than a separate server object, and the app answers as an `http.Server`: `app instanceof http.Server` is true, which is what the graceful shutdown wrappers and the connection trackers look for. There is still no node server underneath, the socket belongs to µWS, so what is answered is the surface and not the plumbing. There: `close()`, `address()`, `listening`, `getConnections()`, `ref()`, `unref()`, `setTimeout()` and the `keepAliveTimeout` family. Not there: nothing emits `connection`, `request` or `upgrade`, `getConnections()` counts the requests in flight rather than sockets, and the timeouts belong to µWS and are set through `uwsOptions.idleTimeout`. Anything that wants to serve its own protocol on the socket, socket.io being the usual case, still wants `app.uwsApp`. Runnable: [`examples/graceful-shutdown.js`](./examples/graceful-shutdown.js).
 - `x-powered-by` is disabled by default. Express sends `X-Powered-By: Express` unless you turn it off; Fulmine does not send it unless you turn it on with `app.set("x-powered-by", true)`. The header only tells anyone asking which framework is running.
 - request body is only read for POST, PUT, PATCH and QUERY requests by default. You can add additional methods by setting `body methods` to array with uppercased methods.
+- **A compiled route answers `connection: keep-alive` to a client that sent `Connection: close`.** A handler simple enough to be read at registration time is answered by µWS from a response written once at `listen()`, and that response cannot read the request. The socket still closes, so what is wrong is the header and not the transport. A response that would carry a validator is never compiled, so conditional requests behave as on Express; `app.set("declarative responses", false)` turns compiling off.
 - **Informational responses go nowhere.** `res.writeEarlyHints()`, `res.writeContinue()` and `res.writeProcessing()` are all there, take what node's take and throw what node's throw once the head has gone out, but nothing reaches the wire: µWebSockets.js has no API for a `1xx`. They exist so that code written for Express keeps running rather than dying on "is not a function", which is the only thing a drop-in can honestly promise here. `res.addTrailers()` is the same story, and `res.setTimeout()` and `req.setTimeout()` register the listener without changing anything, since µWS runs its own idle timeout through `uwsOptions.idleTimeout`.
 - For HTTPS, instead of doing this:
 
@@ -292,6 +329,7 @@ app.listen(3000, () => {
 Runnable: [`examples/https.js`](./examples/https.js).
 
 - This also applies to non-SSL HTTP too. Use `app.listen()` rather than creating a server by hand. `http.createServer(app)` does work, because the app is a request listener like Express's and answers node's requests through a shim, which is what lets `supertest`, `vhost` and anything else that calls an app keep working. But it serves those requests through `node:http` rather than through µWS, so the speed is Express's. It is there for compatibility, not for production.
+- **Node 22, 24 and 26, not every version above 22.** µWebSockets.js ships one prebuilt binary per Node ABI and skips the odd lines, so Node 23 and 25 have no binary to load and fail at `require`. `npx fulmine.js verify` says which binary this machine wants and whether it is there. The odd/even model ends with Node 26, so the gap closes on its own.
 - Node.JS max header size is 16384 bytes, while uWebSockets by default is 4096 bytes, so if you need longer headers set the env variable `UWS_HTTP_MAX_HEADERS_SIZE` to max byte count you need.
 - uWebSockets drops a request whose body arrives slower than 16KB/s, and the timeout is not reachable from JavaScript, while Node.JS waits as long as the client needs. Uploads over very slow connections can therefore fail here and succeed on Express. A body stalled for 5 seconds still completes; one stalled for 12 seconds gets its socket reset at around 11.8 seconds.
 
@@ -667,8 +705,9 @@ Two of these keep a compiled form alongside the value, which you can also set di
 - `etag fn`, the function that produces an ETag. Setting `etag` compiles one; setting this replaces it.
 - `query parser fn`, likewise for `query parser`.
 
-Fulmine adds five of its own:
+Fulmine adds six of its own:
 
+- `etag methods`, unset by default. Express computes the generated ETag for every method, and so does this until told otherwise. `app.set("etag methods", ["GET", "HEAD"])` skips the digest on every other method, where freshness is not defined and the validator can never match: worth 21% here on a 4KB POST answer. An ETag set by hand still goes out whatever the method.
 - `declarative responses`, on by default. Lets a simple enough handler be compiled into a native uWS response, described under [Performance tips](#performance-tips).
 - `connection headers`, on by default. Express sends `Connection: keep-alive` and `Keep-Alive` on every response, and so does this. Turn it off and neither goes out, while a connection the client asked to close still answers `Connection: close`: it is the advertisement that goes, not the truth. Worth 2% to 3.5% here on a route that is not compiled, plus the bytes.
 - `file cache`, on by default. Small files served by `res.sendFile` come from a bounded in-process cache, checked against the file's `stat` on every request, so an edited file is never served stale. Turn it off where every request has to reach the disk, which is what a public benchmark asks of a standard entry: it was worth about 4% on a 4KB file here, so the cost of turning it off is small.

package/package.json

@@ -1,15 +1,14 @@
 {
     "name": "fulmine.js",
-    "version": "5.11.0",
+    "version": "5.12.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
-        "fulmine": "src/cli.js",
-        "fulmine.js": "src/cli.js"
+        "fulmine": "src/cli.js"
     },
     "scripts": {
         "test": "node tests/index.js",
-        "test:unit": "node --test \"tests/unit/*.test.js\"",
+        "test:unit": "node --test --test-timeout=120000 \"tests/unit/*.test.js\"",
         "test:types": "tsd --files tests/types/*.test-d.ts",
         "test:express": "node tools/express-suite.js",
         "fuzz": "node tools/fuzz.js",
@@ -69,7 +68,7 @@
     "dependencies": {
         "@types/express": "^5.0.6",
         "accepts": "^2.0.0",
-        "acorn": "^8.16.0",
+        "acorn": "^8.18.0",
         "bytes": "^3.1.2",
         "compressible": "^2.0.18",
         "content-disposition": "^1.1.0",
@@ -83,8 +82,8 @@
         "mime-types": "^3.0.2",
         "ms": "^2.1.3",
         "proxy-addr": "^2.0.7",
-        "qs": "^6.15.2",
-        "range-parser": "^1.2.1",
+        "qs": "^6.15.3",
+        "range-parser": "^1.3.0",
         "statuses": "^2.0.2",
         "tseep": "^1.3.1",
         "type-is": "^2.1.0",
@@ -92,7 +91,6 @@
         "vary": "^1.1.2"
     },
     "devDependencies": {
-        "@codechecks/client": "^0.1.12",
         "@commitlint/cli": "^21.2.1",
         "@commitlint/config-conventional": "^21.2.0",
         "@eslint/js": "^10.0.1",
@@ -106,7 +104,7 @@
         "@types/fresh": "^0.5.3",
         "@types/mime-types": "^3.0.1",
         "@types/ms": "^2.1.0",
-        "@types/node": "^25.9.1",
+        "@types/node": "^26.2.0",
         "@types/proxy-addr": "^2.0.3",
         "@types/statuses": "^2.0.6",
         "@types/type-is": "^1.6.7",
@@ -118,21 +116,21 @@
         "cookie-parser": "^1.4.7",
         "cookie-session": "^2.1.1",
         "cors": "^2.8.6",
-        "ejs": "^3.1.10",
+        "ejs": "^6.0.1",
         "errorhandler": "^1.5.2",
         "eslint": "^10.8.0",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-jsdoc": "^63.3.2",
+        "eslint-plugin-jsdoc": "^64.1.0",
         "etag": "^1.8.1",
-        "eventsource": "^4.1.0",
-        "exit-hook": "^2.2.1",
+        "eventsource": "^5.0.0",
+        "exit-hook": "^5.1.0",
         "express": "^5",
         "express-art-template": "^1.0.1",
         "express-basic-auth": "^1.2.1",
         "express-dot-engine": "^1.0.8",
         "express-fast-json-stringify": "^1.3.0",
         "express-fileupload": "^1.5.2",
-        "express-handlebars": "^8.0.7",
+        "express-handlebars": "^9.0.1",
         "express-http-proxy": "^2.1.2",
         "express-mongo-sanitize": "^2.2.0",
         "express-rate-limit": "^8.5.2",
@@ -143,20 +141,20 @@
         "globals": "^17.8.0",
         "graphql-http": "^1.22.4",
         "helmet": "^8.2.0",
-        "http-proxy-middleware": "^3.0.5",
+        "http-proxy-middleware": "^4.2.0",
         "husky": "^9.1.7",
         "lint-staged": "^17.3.0",
         "method-override": "^3.0.0",
         "morgan": "^1.11.0",
         "multer": "^2.1.1",
         "mustache-express": "^1.3.2",
-        "nyc": "^17.1.0",
+        "nyc": "^18.0.0",
         "on-finished": "^2.4.1",
         "on-headers": "^1.1.0",
-        "pako": "^2.1.0",
+        "pako": "^3.0.1",
         "passport": "^0.7.0",
         "passport-local": "^1.0.0",
-        "pkg-pr-new": "^0.0.75",
+        "pkg-pr-new": "^0.0.87",
         "prettier": "^3.9.6",
         "pug": "^3.0.4",
         "release-it": "^21.0.1",

package/src/application.js

@@ -26,7 +26,8 @@ const {
     createETagGenerator,
     fastQueryParse,
     durationSetting,
-    NullObject
+    NullObject,
+    settingsEpoch
 } = require("./utils.js");
 const parseQuery = require("./parse-query.js");
 const Request = require("./request.js");
@@ -396,16 +397,22 @@ class Application extends Router {
                 // express's wording, which applications match on
                 throw new TypeError("unknown value for query parser function: " + value);
             }
-        } 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();
+        } else if (key === "etag methods") {
+            // fulmine's own: the methods whose send() computes a generated ETag. Unset means all
+            // of them, which is express's behaviour and what its suite asserts per method; naming
+            // ["GET", "HEAD"] skips the digest everywhere a validator can never match, which
+            // measured +21% on a 4KB POST answer. See issue #10.
+            if (value != null && (!Array.isArray(value) || value.some((m) => typeof m !== "string"))) {
+                throw new TypeError('"etag methods" wants an array of method names, or null for all of them');
             }
+            value = value == null ? undefined : value.map((m) => m.toUpperCase());
+        } else if (key === "etag") {
+            // The skips are not taken back here. They used to be, because send consults freshness
+            // and the skip branch looked like it had not copied the headers for it, but that
+            // branch reads if-none-match, if-modified-since and cache-control by name whatever
+            // this setting says, see request.js:527, and req.fresh reads nothing else off the
+            // request. Registering a route or a middleware after listen still takes them back,
+            // see router.js:1615: that is a different question, about code the analysis never saw.
             if (typeof value === "function") {
                 this.settings["etag fn"] = value;
             } else {
@@ -428,6 +435,8 @@ class Application extends Router {
         }
 
         this.settings[key] = value;
+        // any app's hot-settings copy may resolve through this one, see Router#_hot
+        settingsEpoch.n++;
         return this;
     }
 
@@ -520,13 +529,18 @@ class Application extends Router {
     _serveGeneric(res, req) {
         const request = this.handleRequest(res, req);
         const response = request.res;
-        // armed up front here: this handler can outlive the callback on every path through it
-        this._armAbort(res, response);
-
-        this._routeRequestDirect(request, response);
-        // the synchronous stretch has run under the cork uWS holds for this callback, and
-        // whatever comes after it is outside
-        response._corkNeeded = true;
+        try {
+            this._routeRequestDirect(request, response);
+        } finally {
+            // the synchronous stretch has run under the cork uWS holds for this callback, and
+            // whatever comes after it is outside
+            response._corkNeeded = true;
+            // an abort can only arrive after this callback returns, as the native handler's
+            // finally says: a response that finished inside it never needs uWS told at all
+            if (!response.finished) {
+                this._armAbort(res, response);
+            }
+        }
     }
 
     /**

package/src/cli.js

@@ -85,10 +85,11 @@ const DIFFERENCES = [
         'Express sends X-Powered-By: Express unless told not to. Set app.set("x-powered-by", true) to send it.'
     ],
     [
-        "a compiled route is framed differently and never answers 304",
-        "A handler simple enough to be read at registration time is answered natively, which means chunked\n" +
-            "framing with no Content-Length, and a conditional request gets the whole body rather than a 304.\n" +
-            'app.set("declarative responses", false) turns that off.'
+        "a compiled route is framed differently and keeps its connection header",
+        "A handler simple enough to be read at registration time is answered natively: chunked framing\n" +
+            "with no Content-Length, and a client that sent Connection: close is still told keep-alive,\n" +
+            "though the socket does close. A response that would carry a validator is never compiled, so\n" +
+            'conditional requests behave as on Express. app.set("declarative responses", false) turns it off.'
     ],
     [
         "headers are capped at 4096 bytes by default",
@@ -493,9 +494,43 @@ ${error.stack ?? error}`);
         );
         return null;
     }
+    stopFileWorkers(apps);
     return { apps, entry };
 }
 
+/**
+ * Ends the file-reading threads that building an application started.
+ *
+ * An Application starts one per `threads` in its constructor, and these commands only ever read
+ * what compiling the routes decided: nothing here serves a file, so nothing here needs a thread.
+ * They are unref'd, so leaving them would not hang the process, but they are threads holding the
+ * library the application loaded, and this command is often not the whole process. It also stops
+ * them outliving the directory they were loaded from, which is how a test that profiles a copy and
+ * then removes it saw "Cannot find module .../src/worker.js" arrive after it had finished.
+ *
+ * Best effort throughout: a build with no workers, or a worker already gone, is not an error here.
+ *
+ * @param {any[]} apps
+ * @returns {void}
+ */
+function stopFileWorkers(apps) {
+    const seen = new Set();
+    for (const app of apps) {
+        for (const holder of app?.workers ?? []) {
+            const worker = holder?.worker;
+            if (!worker || seen.has(worker)) {
+                continue;
+            }
+            seen.add(worker);
+            try {
+                worker.terminate();
+            } catch {
+                // a thread that never started, or already ended, needs nothing
+            }
+        }
+    }
+}
+
 /**
  * Loads an application without letting it listen, and prints what compiling its routes decided.
  *

package/src/declarative.js

@@ -50,6 +50,10 @@ const typeValueOf = (type) => (type.indexOf("/") === -1 ? contentTypeFor(type) :
 const MAX_INSTRUCTION_LENGTH = 65535;
 
 // the three that write a body, of which only one may appear
+// The headers a conditional request is answered from. A compiled response cannot read the request,
+// so it cannot honour one, and a handler that sets one has to stay on the ordinary path.
+const VALIDATOR_HEADERS = new Set(["etag", "last-modified"]);
+
 const bodyMethods = new Set(["send", "json", "end"]);
 // and the four that finish the response, after which nothing a handler does is observable
 const terminalMethods = new Set(["send", "json", "end", "sendStatus"]);
@@ -734,10 +738,13 @@ module.exports = function compileDeclarative(cb, app) {
         }
 
         for (const header of headers) {
-            if (header[0].toLowerCase() === "content-length") {
+            const name = header[0].toLowerCase();
+            if (name === "content-length") {
                 return false;
             }
-            decRes = decRes.writeHeader(header[0], header[1]);
+            // lowercased as the ordinary path stores every name, so the two paths answer the
+            // same bytes whatever casing the handler wrote, see issue #7
+            decRes = decRes.writeHeader(name, header[1]);
         }
 
         // sendStatus sends the status message as its body. It has to join `body` here, before the
@@ -748,24 +755,22 @@ module.exports = function compileDeclarative(cb, app) {
             body.push({ type: "text", value: statuses.message[statusCode] || String(statusCode) });
         }
 
-        // an empty body gets no ETag, which is what Express does and what the ordinary path here
-        // already did
-        if (
-            body.length &&
-            (bodyFromSend || sendStatusUsed) &&
-            app.get("etag") &&
-            !headers.some((header) => header[0].toLowerCase() === "etag")
-        ) {
-            if (body.some((part) => part.type !== "text")) {
-                return false;
-            } else {
-                const etag = app.get("etag fn")(body.map((part) => part.value.toString()).join(""));
-                // an application's own etag function is allowed to decline, and a declarative
-                // response cannot answer with a header whose value is nothing
-                if (etag) {
-                    decRes = decRes.writeHeader("ETag", etag);
-                }
-            }
+        // A response that would carry a validator is not compiled at all.
+        //
+        // µWS answers a declarative response without reading the request, so it cannot answer a
+        // conditional GET: it used to write an ETag computed over the compiled body at listen and
+        // then ignore it, so every revalidation got 200 and the whole body where Express answers
+        // 304 with none. Dropping the ETag instead would have kept the route compiled, at the
+        // price of no validator at all on the simplest routes of every application. Refusing
+        // keeps Express's answer, and `etag` false is how a route that does not need one stays
+        // compiled, which is what both benchmarks here already set.
+        if (headers.some((header) => VALIDATOR_HEADERS.has(header[0].toLowerCase()))) {
+            return false;
+        }
+        // an empty body gets no ETag, in Express and on the ordinary path here, so it has nothing
+        // to lose by being compiled
+        if (body.length && (bodyFromSend || sendStatusUsed) && app.get("etag")) {
+            return false;
         }
 
         // No Content-Length header here: uWS writes the framing itself, and a response carrying

package/src/index.js

@@ -35,6 +35,15 @@ try {
     // older uWS builds do not expose _cfg; there is nothing to fall back to
 }
 
+try {
+    // the compile cache, in node since 22.8: the next boot of the same code skips compiling it.
+    // Asked for here because in practice the framework is the entry point of the application
+    // using it. Respects NODE_DISABLE_COMPILE_CACHE, and booting without a cache is not an error
+    require("node:module").enableCompileCache?.();
+} catch (error) {
+    // node below 22.8, or a disk the cache cannot be written to
+}
+
 // The factory doubles as a namespace, as in Express: Router, static and the body parsers hang off
 // the function that creates an app.
 //

package/src/middlewares.js

@@ -935,13 +935,16 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // 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) {
+            // with 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. A declared length was the
+            // original case; a chunked body accumulates in the same native vector and only loses
+            // the length check, since there is no declaration to hold it to
+            const declared = Number(length);
+            const declaresLength = !isNaN(declared) && declared > 0;
+            if (!req.receivedData && !inflate && req._res.collectBody && (declaresLength || isNaN(declared))) {
                 req.bodyRead = true;
-                const declared = Number(length);
                 req._res.collectBody(limit, (body) => {
                     if (body === null) {
                         // over maxSize: uWS refused it natively
@@ -952,7 +955,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                             })
                         );
                     }
-                    if (body.byteLength !== declared) {
+                    if (declaresLength && body.byteLength !== declared) {
                         return next(
                             bodyError("request size did not match content length", 400, "request.size.invalid", {
                                 expected: declared,

package/src/request.js

@@ -592,6 +592,10 @@ module.exports = class Request extends LazyReadable {
             this._isOptions = this.method === "OPTIONS";
             this._isHead = this.method === "HEAD";
         }
+        // the folded _opPath and the percent scan of _originalPath, built on the hop that first
+        // wants them and dropped by every rewrite, see _pathMatches and Walk#dispatch
+        this._opPathLower = null;
+        this._mayFailDecode = null;
         this.params = {};
 
         // Two Sets per request, for two things almost no request needs.
@@ -812,7 +816,7 @@ module.exports = class Request extends LazyReadable {
      * meant to carry one value, but nothing stops a proxy from appending.
      */
     get #authority() {
-        const trust = this.app.get("trust proxy fn");
+        const trust = this.app._hot().trustProxyFn;
         // parsedIp is what connection.remoteAddress carries, without building the socket stand-in
         const isTrusted = !!(trust && trust(this.parsedIp, 0));
         const rawHeader = (isTrusted && this.headers["x-forwarded-host"]) || this.headers["host"];
@@ -886,7 +890,7 @@ module.exports = class Request extends LazyReadable {
      * @returns {string|undefined} undefined on a unix socket, which has no address
      */
     get ip() {
-        const trust = this.app.get("trust proxy fn");
+        const trust = this.app._hot().trustProxyFn;
         if (!trust) {
             return this.parsedIp;
         }
@@ -899,7 +903,7 @@ module.exports = class Request extends LazyReadable {
      * @returns {string[]}
      */
     get ips() {
-        const trust = this.app.get("trust proxy fn");
+        const trust = this.app._hot().trustProxyFn;
         if (!trust) {
             return [];
         }
@@ -918,7 +922,7 @@ module.exports = class Request extends LazyReadable {
         // own ssl flag answers when nothing has built the stand-in yet
         const conn = this.#cachedConnection;
         const proto = (conn ? conn.encrypted : this.app.ssl) ? "https" : "http";
-        const trust = this.app.get("trust proxy fn");
+        const trust = this.app._hot().trustProxyFn;
         if (!trust) {
             return proto;
         }
@@ -956,6 +960,8 @@ module.exports = class Request extends LazyReadable {
         this.path = newPath;
         this.endsWithSlash = newPath.charCodeAt(newPath.length - 1) === 0x2f;
         this._opPath = newPath;
+        this._opPathLower = null;
+        this._mayFailDecode = null;
         this._lastUrl = newUrl;
     }
 
@@ -985,7 +991,7 @@ module.exports = class Request extends LazyReadable {
      * @returns {Record<string, any>}
      */
     get query() {
-        const qp = this.app.get("query parser fn");
+        const qp = this.app._hot().queryParserFn;
         // the vendored default already answers on a bare null prototype, so it goes out as is;
         // any other parser is copied onto one, which is what kept fast-querystring's result from
         // inspecting as "Empty <[Object: null prototype] {}>" where Express shows the bare form
@@ -1053,7 +1059,7 @@ module.exports = class Request extends LazyReadable {
      */
     _readRawIp() {
         const uwsRes = this._res;
-        if (this.app.get("trust proxy protocol")) {
+        if (this.app._hot().trustProxyProtocol) {
             const proxied = uwsRes.getProxiedRemoteAddress();
             // empty unless a preamble arrived, which is the only thing that tells the two apart
             if (proxied.byteLength !== 0) {

package/src/response.js

@@ -31,6 +31,9 @@ const {
     isPreconditionFailure,
     isRangeFresh,
     escapeHtml,
+    validateHeaderName,
+    validateHeaderValue,
+    headerIsWritable,
     withDefaultCharset,
     withUtf8Charset,
     asStatError,
@@ -305,7 +308,7 @@ module.exports = class Response extends LazyWritable {
         if (req._connectionClose) {
             this.headers.connection = "close";
         }
-        if (this.app.get("x-powered-by")) {
+        if (app._hot().xPoweredBy) {
             this.headers["x-powered-by"] = "Fulmine";
         }
 
@@ -613,6 +616,10 @@ module.exports = class Response extends LazyWritable {
      * not one of them: uWS wants the length through tryEnd or endWithoutBody, so it is taken out
      * here and kept on totalSize, where it also turns chunked framing off.
      *
+     * One writeHeader per header on purpose. Packing the whole head into a single writeStatus
+     * works on the wire, and was measured slower: constant header strings cross the boundary
+     * already flat, while the packed head is concatenated fresh per response, see issue #11.
+     *
      * @param {boolean} utf8 unused, kept because node's equivalent takes it and the two callers
      *   differ on what they know about the body
      */
@@ -881,8 +888,18 @@ module.exports = class Response extends LazyWritable {
         // req.fresh, which compares If-None-Match against it.
         // body is defined by the time it gets here, so an empty one still earns an ETag. Testing
         // its truthiness instead meant send("") and send(null) came back without one.
-        const etagFn = this.app.get("etag fn");
-        if (etagFn && !this.headers["etag"] && !this.req.noEtag) {
+        // Every method by default, not only GET and HEAD: gating it looked safe, freshness being
+        // defined over those two alone, and express's own suite failed on it, "should send ETag
+        // in response to <METHOD> request" exists per method. The "etag methods" setting is that
+        // gate as an opt-in, see issue #10.
+        const hot = this.app._hot();
+        const etagFn = hot.etagFn;
+        if (
+            etagFn &&
+            !this.headers["etag"] &&
+            !this.req.noEtag &&
+            (hot.etagMethods === null || hot.etagMethods.has(this.req.method))
+        ) {
             const etag = etagFn(body);
             // an application's own etag function is allowed to decline: returning nothing means no
             // header, rather than a header saying "undefined"
@@ -1318,27 +1335,51 @@ module.exports = class Response extends LazyWritable {
      * @param {any} value an array sends the header once per entry
      * @returns {this}
      * @throws {Error} once the headers have gone out
-     * @throws {TypeError} if the name is not a string
+     * @throws {TypeError} if the name is not a token, the value is undefined, or the value holds a
+     *   character that cannot go on the wire
      */
     setHeader(field, value) {
         if (this.headersSent) {
             throw new Error("Cannot set headers after they are sent to the client");
         }
-        if (typeof field !== "string") {
-            throw new TypeError("Header name must be a valid HTTP token");
-        } else {
-            field = field.toLowerCase();
-            if (Array.isArray(value)) {
-                // each entry as text, as node serialises them: a raw number reaching uWS's
-                // writeHeader would throw mid-response
-                this.headers[field] = value.map(String);
-                return this;
-            }
-            this.headers[field] = String(value);
+        validateHeaderName(field);
+        if (value === undefined) {
+            /** @type {NodeJS.ErrnoException} */
+            const err = new TypeError(`Invalid value "undefined" for header "${field}"`);
+            err.code = "ERR_HTTP_INVALID_HEADER_VALUE";
+            throw err;
         }
+        // each entry as text, as node serialises them: a raw number reaching uWS's writeHeader
+        // would throw mid-response. Coerced before it is checked, since that is the string the
+        // wire gets, and checked before it is stored: a value that got in here would be written by
+        // whatever flushes next, and on the error path that is a second throw with nobody left to
+        // catch it
+        const out = Array.isArray(value) ? value.map(String) : String(value);
+        validateHeaderValue(field, out);
+        this.headers[field.toLowerCase()] = out;
         return this;
     }
 
+    /**
+     * Throws away any header that could not be written, so that flushing this response cannot fail
+     * on one. setHeader refuses these on the way in, but `res.headers` is the live object, so an
+     * assignment into that still gets a value in here.
+     *
+     * Only the error page calls it. A throw out of the flush there is not recoverable: the error
+     * page is what runs after a throw, so it would be the second one, with nobody left to catch
+     * it, and on the node shim that is the process. Everything writable is left alone, since a
+     * middleware's own headers belong on the error response too.
+     *
+     * @returns {void}
+     */
+    _dropUnwritableHeaders() {
+        for (const header in this.headers) {
+            if (!headerIsWritable(header, this.headers[header])) {
+                delete this.headers[header];
+            }
+        }
+    }
+
     /**
      * Hands the status line and the headers over now, without waiting for a body, which is node's
      * flushHeaders(). Callers use it to let the client start on the head while the body is still
@@ -1387,10 +1428,6 @@ module.exports = class Response extends LazyWritable {
      * @param {() => void} [callback]
      * @returns {void}
      */
-
-    /**
-     *
-     */
     writeEarlyHints(hints, callback) {
         this.#refuseInformationAfterHead();
         // node writes the hints first and calls back after, so a caller that sequences work on it
@@ -1460,7 +1497,7 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * node's `assignSocket` and `detachSocket`, which the http server uses when a response is
+     * node's `assignSocket`, which the http server uses when a response is
      * handed a raw socket. There is no such socket here.
      *
      * @param {any} [socket]
@@ -1469,6 +1506,8 @@ module.exports = class Response extends LazyWritable {
     assignSocket(socket) {}
 
     /**
+     * node's `detachSocket`, which the http server uses when a response is
+     * handed a raw socket. There is no such socket here.
      * @param {any} [socket]
      * @returns {void}
      */
@@ -1595,11 +1634,11 @@ module.exports = class Response extends LazyWritable {
                 this.set(header, field[header]);
             }
         } else {
-            field = field.toLowerCase();
+            const name = field.toLowerCase();
             // a header is text on the wire whatever it was here, and Express coerces at this point,
             // so res.get answers what was sent rather than the number or object it was given
             let out = Array.isArray(value) ? value.map(String) : String(value);
-            if (field === "content-type") {
+            if (name === "content-type") {
                 if (Array.isArray(out)) {
                     throw new TypeError("Content-Type cannot be set to an Array");
                 }
@@ -1607,6 +1646,9 @@ module.exports = class Response extends LazyWritable {
                 // missing application/manifest+json among others, which Express does charset.
                 out = withDefaultCharset(out);
             }
+            // the name as it was written, not the lowercased one: setHeader lowercases it itself,
+            // and it is the name that a refused header is reported by, which Express takes from
+            // what the caller passed
             this.setHeader(field, out);
         }
         return this;
@@ -1643,12 +1685,15 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * Every header set so far, as the object they are kept in rather than a copy, so writing to
-     * it writes to the response.
+     * Every header set so far, as a shallow copy on a null prototype, which is what node's
+     * OutgoingMessage answers. It used to hand out the live object, and a write into that
+     * reached the wire without setHeader's validation, see issue #6; nothing in here or in the
+     * middleware that was checked relies on the live one, so the copy costs an allocation on a
+     * method the framework itself never calls.
      * @returns {Record<string, any>}
      */
     getHeaders() {
-        return this.headers;
+        return Object.assign({ __proto__: null }, this.headers);
     }
 
     /**
@@ -1837,10 +1882,8 @@ module.exports = class Response extends LazyWritable {
         if (!this.headers["content-type"]) {
             this.headers["content-type"] = "application/json; charset=utf-8";
         }
-        const escape = this.app.get("json escape");
-        const replacer = this.app.get("json replacer");
-        const spaces = this.app.get("json spaces");
-        return this.send(stringify(body, replacer, spaces, escape));
+        const hot = this.app._hot();
+        return this.send(stringify(body, hot.jsonReplacer, hot.jsonSpaces, hot.jsonEscape));
     }
 
     /**
@@ -2002,7 +2045,8 @@ module.exports = class Response extends LazyWritable {
     type(type) {
         const ct = type.indexOf("/") === -1 ? contentTypeFor(type) : type;
 
-        return this.set("content-type", ct);
+        // the name Express passes, since a refused value is reported by the name it was set under
+        return this.set("Content-Type", ct);
     }
 
     /**

package/src/router.js

@@ -28,7 +28,8 @@ const {
     uwsPrefersEarlier,
     regexpGroupKeys,
     NullObject,
-    EMPTY_REGEX
+    EMPTY_REGEX,
+    settingsEpoch
 } = require("./utils.js");
 const Response = require("./response.js");
 const Request = require("./request.js");
@@ -47,6 +48,26 @@ const HAS_LETTER = /[a-zA-Z]/;
 // hands out one number per app.route(), so the routes it creates know they belong together
 let routeGroups = 0;
 
+// The settings the request and response hot paths read, resolved to plain fields: each read was a
+// variadic get() whose rest array escapes into createRoute, plus a dictionary miss per mount level
+// for the json keys, which have no default. One shape for every router, stale when the epoch moves.
+class HotSettings {
+    /** Every field declared up front, one hidden class for every router's copy. */
+    constructor() {
+        this.epoch = 0;
+        this.xPoweredBy = false;
+        this.etagFn = undefined;
+        // null means every method, which is express's behaviour and the default
+        this.etagMethods = null;
+        this.queryParserFn = undefined;
+        this.trustProxyFn = undefined;
+        this.trustProxyProtocol = false;
+        this.jsonEscape = undefined;
+        this.jsonReplacer = undefined;
+        this.jsonSpaces = undefined;
+    }
+}
+
 /**
  * Whether an earlier route would have answered this path had case not mattered. A guard is a
  * folded string when the earlier path is a literal, and an insensitive pattern when it has
@@ -207,8 +228,12 @@ class Walk {
             // express matches a layer's path before it looks at the method, and decodes the
             // parameters there, so a malformed escape answers 400 even when no route of this
             // method exists. Only a path carrying a percent can produce one, and that check keeps
-            // every other request from matching routes it could never run
-            const mayFailDecode = req._originalPath.indexOf("%") !== -1;
+            // every other request from matching routes it could never run. Scanned once per
+            // rewrite and kept on the request: a middleware-heavy chain scanned it per hop
+            const mayFailDecode = (req._mayFailDecode ??= req._originalPath.indexOf("%") !== -1);
+            // 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++) {
@@ -637,20 +662,12 @@ function mountPrefixLength(route, req) {
  */
 function setMountedPath(req) {
     req._opPath = req._consumed === 0 ? req._originalPath : req._originalPath.slice(req._consumed);
+    req._opPathLower = null;
     req.url = req._opPath === "" ? "/" + req.urlQuery : req._opPath + req.urlQuery;
     req.path = req._opPath === "" ? "/" : req._opPath;
     req._lastUrl = req.url;
 }
 
-/**
- * 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
- * shift, so a RegExp mount capturing one group leaves the route's own group numbered from one.
- *
- * @param {Record<string, any>} own what this route's own pattern captured
- * @param {Record<string, any>[]} stack the mounts, outermost first
- * @returns {Record<string, any>}
- */
 /**
  * Whether this route reads the parameters of the mounts above it, which is its own router asking
  * for them. The stack holds what a mergeParams router captured on the way in, and a plain router
@@ -763,6 +780,8 @@ function adoptPlainRequest(req, router) {
     req._originalPath = path;
     req.endsWithSlash = path.charCodeAt(path.length - 1) === 0x2f;
     req._opPath = path;
+    req._opPathLower = null;
+    req._mayFailDecode = null;
     req._lastUrl = req.url;
     req._isOptions = req.method === "OPTIONS";
     req._isHead = req.method === "HEAD";
@@ -778,13 +797,6 @@ function adoptPlainRequest(req, router) {
     req.app = req.app ?? router;
 }
 
-/**
- * Refuses a handler that could never be called, where it was written rather than on the first
- * request that reaches it. Express words both of these and applications match on the text.
- *
- * @param {any[]} handlers
- * @param {string} [emptyMessage] app.use() says it its own way
- */
 /**
  * The uWS onAborted handler, bound to the response: a closure here captured two locals and cost
  * a context plus a function per request, for a path that only ever runs on a client abort.
@@ -875,13 +887,6 @@ const CALLBACK_PLAIN = 0;
 const CALLBACK_ERROR = 1;
 const CALLBACK_ROUTER = 2;
 
-/**
- * Hands the request and the response to the app about to handle them, so that a mounted sub-app's
- * settings decide what its responses do. Express re-parents both objects for the same reason.
- *
- * @param {any} req
- * @param {any} app
- */
 /**
  * Reports a parameter that will not decode, unless something is already being reported.
  *
@@ -1083,6 +1088,7 @@ function restoreApp(route, req) {
 }
 
 /**
+ * useApp
  * @param {any} req
  * @param {any} app
  */
@@ -1259,6 +1265,12 @@ module.exports = class Router extends EventEmitter {
     /** @type {boolean|undefined} */
     _caseFlag;
 
+    /**
+     * The hot-path settings resolved to fields, good while the epoch stands, see _hot().
+     * @type {HotSettings}
+     */
+    _hotSettings = new HotSettings();
+
     /**
      * @param {object} [settings] router options. caseSensitive and strict are accepted under the
      *   names Express's Router takes, and stored under the setting names the rest of the code reads
@@ -1391,6 +1403,33 @@ module.exports = class Router extends EventEmitter {
         return this.createRoute("GET", path, this, ...callbacks);
     }
 
+    /**
+     * The settings the hot path reads, as fields on one object rather than a get() per read.
+     * Refreshed through get(), parent fallback and all, when the epoch says a set() or a mount
+     * happened anywhere since they were resolved; until then a read is a monomorphic field load.
+     *
+     * @returns {HotSettings}
+     */
+    _hot() {
+        const hot = this._hotSettings;
+        if (hot.epoch === settingsEpoch.n) {
+            return hot;
+        }
+        hot.xPoweredBy = !!this.get("x-powered-by");
+        hot.etagFn = this.get("etag fn");
+        // a Set here, an array in the settings: send() asks per response, set() runs once
+        const etagMethods = this.get("etag methods");
+        hot.etagMethods = etagMethods == null ? null : new Set(etagMethods);
+        hot.queryParserFn = this.get("query parser fn");
+        hot.trustProxyFn = this.get("trust proxy fn");
+        hot.trustProxyProtocol = !!this.get("trust proxy protocol");
+        hot.jsonEscape = this.get("json escape");
+        hot.jsonReplacer = this.get("json replacer");
+        hot.jsonSpaces = this.get("json spaces");
+        hot.epoch = settingsEpoch.n;
+        return hot;
+    }
+
     /**
      * A routing flag, read once and kept. Express builds a router's matcher the first time the
      * router is needed and hands it caseSensitive and strict there, so a mount that happens after
@@ -1504,9 +1543,13 @@ module.exports = class Router extends EventEmitter {
             if (pattern === "/*") {
                 return true;
             }
-            if (!this._caseSensitive()) {
-                path = path.toLowerCase();
-                pattern = pattern.toLowerCase();
+            // bare fields, frozen by dispatch once per scan: even the freeze's own undefined
+            // check measured 0.45us per request on a scan of four hundred routes
+            if (!this._caseFlag) {
+                // the pattern was folded at registration. The path is folded once per rewrite and
+                // kept on the request, not folded again per route: every _opPath write drops it
+                pattern = /** @type {string} */ (route.patternLower);
+                path = req._opPathLower ??= path.toLowerCase();
             }
             if (pattern === path) {
                 return true;
@@ -1515,7 +1558,7 @@ module.exports = class Router extends EventEmitter {
             // pattern would have carried as "/?" is allowed here instead. The registered path has
             // had its own taken off already, unless it is the root
             return (
-                !this._strictRouting() &&
+                !this._strictFlag &&
                 path.length === pattern.length + 1 &&
                 path.charCodeAt(path.length - 1) === 0x2f &&
                 path.startsWith(pattern)
@@ -1572,13 +1615,17 @@ module.exports = class Router extends EventEmitter {
             if (path === "*") {
                 path = "/{*splat}";
             }
+            const pattern =
+                method === "USE" || needsConversionToRegex(path)
+                    ? patternToRegex(path, method === "USE", this._caseSensitive(), this._strictRouting())
+                    : path;
             const route = {
                 method: method === "USE" ? "ALL" : method,
                 path,
-                pattern:
-                    method === "USE" || needsConversionToRegex(path)
-                        ? patternToRegex(path, method === "USE", this._caseSensitive(), this._strictRouting())
-                        : path,
+                pattern,
+                // folded here once: _pathMatches compares insensitively per route per hop, and
+                // the registered text never changes. null for a compiled pattern
+                patternLower: typeof pattern === "string" ? pattern.toLowerCase() : null,
                 callbacks,
                 // instanceof walks a prototype chain and length is a property load, and both used
                 // to run for every callback of every hop
@@ -1862,11 +1909,17 @@ module.exports = class Router extends EventEmitter {
                     // computed for whichever route µWS lands on runs everything that could have
                     // matched before it
                 } else if (
-                    (canBeOptimized(route.path) ||
-                        // parameters that are whole segments are matched by µWS the same way
-                        (canBeOptimizedWithParams(route.path) &&
-                            // inside a mounted router, only when nothing after it could match
-                            (!pathPrefix || !router._isFollowedByAnOverlap(route, router._routes)))) &&
+                    // parameters that are whole segments are matched by µWS the same way
+                    (canBeOptimized(route.path) || canBeOptimizedWithParams(route.path)) &&
+                    // Inside a mounted router, only when nothing after it could answer the same
+                    // path. This used to be asked of parameter routes alone, and a literal one
+                    // needs it just as much: µWS picks by specificity where Express picks by
+                    // registration order, and a chain carries only what runs in front of its
+                    // route, so `router.get("/a", (req, res, next) => next())` followed by
+                    // `router.get("/:x", ...)` left the mount instead of reaching the second
+                    // route, and answered 404 where Express answers it. Found by the fuzzer,
+                    // replay with --seed 221940161 --rounds 1.
+                    (!pathPrefix || !router._isFollowedByAnOverlap(route, router._routes)) &&
                     supportedUwsMethods.has(route.method)
                 ) {
                     // something outside this router, written before the mount it is in, that could
@@ -1929,7 +1982,7 @@ module.exports = class Router extends EventEmitter {
                     }
                 } else if (!supportedUwsMethods.has(route.method)) {
                     route._whyGeneric = `µWS does not serve ${route.method}`;
-                } else if (canBeOptimizedWithParams(route.path)) {
+                } else if (canBeOptimized(route.path) || canBeOptimizedWithParams(route.path)) {
                     // eligible but for the overlap test, which only applies inside a mount
                     route._whyGeneric = "a route after it in the same mounted router could answer the same paths";
                 } else {
@@ -2108,14 +2161,20 @@ module.exports = class Router extends EventEmitter {
         const strictHere = (route.owner ?? this)._strictRouting();
 
         // 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
+        // HEAD twins only, 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.
+        //
+        // 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
+        // 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.
         const NO_SKIPS = { skipHeaders: false, skipQuery: false };
         let getSkips = NO_SKIPS;
         let headSkips = NO_SKIPS;
-        if (route.method === "GET" && this.get("etag") === false) {
+        if (route.method === "GET") {
             let hasErr = this._hasErrMwCache;
             if (hasErr === undefined) {
                 hasErr = this._hasErrMwCache = hasErrorMiddleware(this);
@@ -2594,6 +2653,9 @@ module.exports = class Router extends EventEmitter {
                 callback.mountpath = /** @type {string|string[]} */ (path === "" ? "/" : path);
                 callback.parent = this;
                 callback.emit("mount", this);
+                // what the child resolves through its parent just changed, so every kept
+                // resolution is stale
+                settingsEpoch.n++;
             }
         }
         this.createRoute("USE", path, this, ...callbacks);
@@ -2673,6 +2735,9 @@ module.exports = class Router extends EventEmitter {
     _sendErrorPage(request, response, err, checkEnv = false) {
         err = this._generateErrorPage(err, response.statusCode, checkEnv);
         request.noEtag = true;
+        // a header that cannot be written is what brought the request here in the first place when
+        // the throw came out of the flush, and writing it again would throw with nobody left
+        response._dropUnwritableHeaders();
         response.setHeader("Content-Type", "text/html; charset=utf-8");
         response.setHeader("X-Content-Type-Options", "nosniff");
         response.setHeader("Content-Security-Policy", "default-src 'none'");

package/src/utils.js

@@ -961,6 +961,11 @@ const defaultSettings = {
     "connection headers": true
 };
 
+// Moved by Application#set and by a mount, whichever app they happen on: a router cannot know
+// which mounted children resolve a setting through it, so instead of walking them the resolved
+// copies everywhere go stale at once and are re-read on their next use, see Router#_hot
+const settingsEpoch = { n: 1 };
+
 // What a file's stat was, for as long as "stat cache" says it stays good. Size and mtime only,
 // never a body, and only when a window was asked for: nginx's open_file_cache makes the same
 // trade, and the worst a stale entry does is answer with the file as it was a moment ago.
@@ -1424,6 +1429,70 @@ function withUtf8Charset(value) {
     return CHARSET_PARAM.test(value) ? value.replace(CHARSET_PARAM, UTF8_CHARSET) : `${value}${UTF8_CHARSET}`;
 }
 
+// What node lets a header name and a header value hold. Express gets these checks from node's own
+// setHeader, and uWS makes them load bearing rather than cosmetic: it writes `key: value\r\n` with
+// no validation of its own, so a CR or an LF that reaches it ends the header early and everything
+// after it is read by the client as a header of its own, or as a whole second response.
+const HEADER_TOKEN = /^[\^_`a-zA-Z\-0-9!#$%&'*+.|~]+$/;
+const HEADER_VALUE = /[^\t\x20-\x7e\x80-\xff]/;
+
+/**
+ * Refuses a header name that is not an HTTP token, the way node's setHeader does and with its
+ * error, so an application catching ERR_INVALID_HTTP_TOKEN behind Express catches it here.
+ *
+ * @param {any} name
+ * @returns {void}
+ * @throws {TypeError} if the name is not a token, which includes not being a string
+ */
+function validateHeaderName(name) {
+    if (typeof name !== "string" || !HEADER_TOKEN.test(name)) {
+        /** @type {NodeJS.ErrnoException} */
+        const err = new TypeError(`Header name must be a valid HTTP token ["${name}"]`);
+        err.code = "ERR_INVALID_HTTP_TOKEN";
+        throw err;
+    }
+}
+
+/**
+ * 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
+ * comma joined string node happens to test.
+ *
+ * @param {string} name the header being set, which is what node names in the message
+ * @param {string|string[]} value already coerced to text
+ * @returns {void}
+ * @throws {TypeError} if a character is not allowed in a header value
+ */
+function validateHeaderValue(name, value) {
+    if (Array.isArray(value)) {
+        for (const one of value) {
+            validateHeaderValue(name, one);
+        }
+        return;
+    }
+    if (HEADER_VALUE.test(value)) {
+        /** @type {NodeJS.ErrnoException} */
+        const err = new TypeError(`Invalid character in header content ["${name}"]`);
+        err.code = "ERR_INVALID_CHAR";
+        throw err;
+    }
+}
+
+/**
+ * Whether this pair could be written to the wire at all. Used on the error path, where throwing
+ * again is what turns one bad header into a dead process.
+ *
+ * @param {string} name
+ * @param {any} value
+ * @returns {boolean}
+ */
+function headerIsWritable(name, value) {
+    if (!HEADER_TOKEN.test(name)) {
+        return false;
+    }
+    return Array.isArray(value) ? value.every((one) => !HEADER_VALUE.test(one)) : !HEADER_VALUE.test(value);
+}
+
 // The status send picks for a failed stat. Anything else is the file being there but unreadable,
 // which is the server's problem and not the request's.
 const STAT_ERROR_STATUS = { ENAMETOOLONG: 404, ENOTDIR: 404, ENOENT: 404 };
@@ -1517,9 +1586,13 @@ module.exports = {
     uwsPrefersEarlier,
     regexpGroupKeys,
     escapeHtml,
+    validateHeaderName,
+    validateHeaderValue,
+    headerIsWritable,
     withDefaultCharset,
     withUtf8Charset,
     asStatError,
     httpError,
-    EMPTY_REGEX
+    EMPTY_REGEX,
+    settingsEpoch
 };