fulmine.js 5.12.3 → 5.13.1

package/README.md

@@ -21,6 +21,8 @@ There is a command that does that replacing for you, across a whole project, and
 npx fulmine.js verify              # can this machine and this image even run it
 npx fulmine.js migrate --dry-run   # say what it would change, change nothing
 npx fulmine.js migrate             # do it
+npx fulmine.js override            # when a framework requires express in its own code, not in yours
+npx fulmine.js angular             # angular.json's server build, which esbuild would otherwise inline
 npx fulmine.js differences         # just the list of what to check by hand
 npx fulmine.js profile             # what listen() decided about each route
 npx fulmine.js explain /api/items  # what happens when a request for that route arrives
@@ -64,6 +66,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
     - [Response](#response)
     - [Router](#router)
 - [Tested middlewares](#tested-middlewares)
+- [Tested frameworks](#tested-frameworks)
 - [Tested view engines](#tested-view-engines)
 - [Examples](./examples/README.md)
 - [Working on Fulmine](./CONTRIBUTING.md)
@@ -78,9 +81,9 @@ Compatibility here is not a claim, it is a test suite. Every test runs against r
 
 Fulmine is faster than Express where the framework itself is doing the work, and the same speed where it is not. Both halves of that sentence matter, so here is the honest version.
 
-**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. Plain routing lands between 1.9x and 4.3x: hello-world 1.9x to 2.2x, an API endpoint with params and a query 3.2x to 4.3x, five route shapes served by one process 2.5x to 3.3x, nested routers 2.1x to 3.1x, a urlencoded body 3.4x to 4.1x, a thousand concurrent connections 2.7x to 3.2x. Route tables are where the native router shows: a thousand routes 9.7x to 12.9x, with a parameter in every one of them 10.4x to 14x, a parameterised route in a mounted router 7.1x to 8.3x. Those routes go to µWS's own router instead of being scanned, so the gap grows with the table instead of shrinking. Even the chain of 100 middlewares, for a long time the one routing row that stayed even because its cost is calling application code a hundred times, sits at 1.5x to 1.7x after the per-request work of August 2026.
+**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. The spreads below are the last nine CI runs, which landed on three different runner shapes, all on Node 26. Plain routing lands between 1.8x and 4.9x: hello-world 1.8x to 2.9x, an API endpoint with params and a query 3.1x to 4.9x, five route shapes served by one process 2.4x to 4.0x, nested routers 2.0x to 3.4x, a urlencoded body 3.3x to 4.6x, a thousand concurrent connections 2.6x to 3.7x. Route tables are where the native router shows: a thousand routes 9.7x to 17.4x, with a parameter in every one of them 10x to 21.2x, a parameterised route in a mounted router 6.8x to 8.8x. Those routes go to µWS's own router instead of being scanned, so the gap grows with the table instead of shrinking. Even the chain of 100 middlewares, for a long time the one routing row that stayed even because its cost is calling application code a hundred times, sits at 1.7x to 2.1x after the per-request work of August 2026.
 
-**Where it is a wash.** Any request whose cost is dominated by work both servers hand to the same library. A 512 KiB JSON body is `JSON.parse`, a gzipped response is zlib, a hashed upload is OpenSSL, a 5 MiB stream is memory bandwidth. On those the ratio is capped by arithmetic somewhere around 1.0x to 1.2x, and no amount of work on either server moves it. The benchmark labels those rows rather than quietly publishing them as if the two were equivalent.
+**Where it is a wash.** Any request whose cost is dominated by work both servers hand to the same library. A 512 KiB JSON body is `JSON.parse`, a gzipped response is zlib, a hashed upload is OpenSSL, a 5 MiB stream is memory bandwidth. On those the ratio is capped by arithmetic somewhere between 1.0x and 1.5x, depending on how much of the request is the shared work, and no amount of effort on either server moves it. The benchmark labels those rows rather than quietly publishing them as if the two were equivalent.
 
 Two things worth knowing before comparing numbers with anyone:
 
@@ -155,8 +158,16 @@ The `server.ts` that `ng add @angular/ssr` generates is an ordinary Express appl
 one-line change applies, and `@angular/ssr`'s own `AngularNodeAppEngine` and
 `writeResponseToNodeResponse` work against Fulmine's request and response unchanged. One extra step
 is needed, and it is Angular's build rather than this library: the server bundle is built with
-esbuild, which tries to inline every dependency and cannot load µWS's native binary. Declare the two
-as external in `angular.json`:
+esbuild, which tries to inline every dependency and cannot load µWS's native binary. The two names
+have to be declared external in `angular.json`, which is what this writes:
+
+```sh
+npx fulmine.js angular             # every server build in angular.json
+npx fulmine.js angular --dry-run   # say what it would write, write nothing
+```
+
+It adds this to each build target that produces a server bundle, and leaves the browser-only ones
+alone:
 
 ```json
 "architect": { "build": { "options": {
@@ -179,40 +190,51 @@ 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:
+application keeps working. The adapter is in the package, so there is nothing to write:
 
 ```ts
 import { NestFactory } from "@nestjs/core";
-import { ExpressAdapter } from "@nestjs/platform-express";
-import fulmine from "fulmine.js";
+import { FulmineExpressAdapter } from "fulmine.js/nest";
 
-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()));
+const app = await NestFactory.create(AppModule, new FulmineExpressAdapter());
 await app.listen(3000);
 ```
 
+Pass your own application where it needs options, TLS being the usual reason:
+`new FulmineExpressAdapter(fulmine({ uwsOptions }))`. `@nestjs/platform-express` is an optional peer
+dependency, so nothing is installed for anyone who never imports this.
+
+What it changes is one line and two edges. The line: Nest's own 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 is the server rather than being put inside one. The edges: `forceCloseConnections`
+has nothing to destroy, since the sockets belong to µWS and nothing emits `connection`, so it now
+says so instead of quietly doing nothing; and Nest decides whether it has already added its body
+parsers by scanning `app.router.stack`, which is not there, so the adapter remembers instead of
+letting a second call add a second pair. `httpsOptions` is refused rather than silently starting a
+plaintext server: TLS is configured on the app, through `uwsOptions`.
+
 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.
+A Nest application answering the same bytes on both is [a case in the integration
+suite](./integrations/cases/nest.js), so this is tested rather than claimed.
 
 ### 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,
 so there is nothing for `migrate` to rewrite. Every package manager can answer `express` with this
-package instead, for your project and everything under it:
+package instead, for your project and everything under it, and this writes the block for whichever
+one your project uses:
+
+```sh
+npx fulmine.js override             # read the lockfile, write the block, say what to run next
+npx fulmine.js override --dry-run   # say what it would write, write nothing
+```
+
+It refuses rather than overwrites where a substitution is already there and is not this package. By
+hand it is one of these:
 
 ```jsonc
 // npm and its lockfile, in package.json
@@ -393,10 +415,17 @@ routes get:
 
 Optimized routes can be up to 10 times faster than normal routes, as they're using native uWS router and have pre-calculated path.
 
-On top of that, a handler simple enough to be read at registration time is compiled into a uWS declarative response and answered natively, without entering JavaScript at all. That needs the route to have nothing in front of it, not a middleware and not a `Router` it was mounted under, and a single handler that only calls `res.status`, `res.set`, `res.type`, `res.append`, `res.send`, `res.json`, `res.sendStatus` or `res.end` with literal arguments, plus `req.params` and `req.query`. `res.set` takes a pair or a whole object of them, and `res.type` takes what it takes anywhere, since a media type is a lookup on a literal. Anything else, a variable, a call, an `if`, falls back to ordinary routing. `return res.send(...)` compiles, `res.send(...)` does too, and so does an object or an array of literals however deeply nested. Mounting a `Router` costs only this: the routes inside one are still registered on the native uWS router with their full path, and are as fast as any other optimized route. Three things follow from the response being static:
+On top of that, a handler simple enough to be read at registration time is compiled into a uWS declarative response and answered natively, without entering JavaScript at all. That needs the route to have nothing in front of it, not a middleware and not a `Router` it was mounted under, and a single handler that only calls `res.status`, `res.set`, `res.type`, `res.append`, `res.send`, `res.json`, `res.sendStatus` or `res.end` with literal arguments, plus `req.query`. `res.set` takes a pair or a whole object of them, and `res.type` takes what it takes anywhere, since a media type is a lookup on a literal. Anything else, a variable, a call, an `if`, falls back to ordinary routing. `return res.send(...)` compiles, `res.send(...)` does too, and so does an object or an array of literals however deeply nested. Mounting a `Router` costs only this: the routes inside one are still registered on the native uWS router with their full path, and are as fast as any other optimized route.
 
-- it cannot answer `304 Not Modified`. The ETag is still sent, so caches keep working, but a conditional request gets the whole body back rather than an empty 304. Express replies 304 there.
-- it carries a `Content-Length` while its body is literal all the way through. A body with a piece taken from the request, `res.send(req.params.id)`, has no length until the request arrives, so that one is framed as `Transfer-Encoding: chunked`. uWS writes the framing either way, which is why neither header can be set by hand.
+Three things are refused whatever the handler does, and all three are the same fact: a response written at startup cannot read the request.
+
+- one that would carry an `ETag` or a `Last-Modified`, since it could never answer with the `304 Not Modified` that the validator invites. `etag` is on by default, so `app.set("etag", false)` is what puts an ordinary route on this path.
+- one whose route captures, `/users/:id`, since a value that cannot be decoded is a `400` in Express and nothing runs here to raise it.
+- a `204`, `205` or `304`, since the body would go out with the status and a client frames those as bodiless whatever it reads.
+
+Two things then follow from the response being static:
+
+- it carries a `Content-Length` while its body is literal all the way through. A body with a piece taken from the request, `res.send(req.query.q)`, has no length until the request arrives, so that one is framed as `Transfer-Encoding: chunked`. uWS writes the framing either way, which is why neither header can be set by hand.
 - it answers `Connection: keep-alive` even to a request that asked for `Connection: close`. The connection is still closed, since uWS decides that itself, and a client that asked to close is closing anyway.
 
 `app.set("declarative responses", false)` turns the whole thing off if you would rather have Express's exact framing than the speed.
@@ -483,7 +512,7 @@ Runnable: [`examples/compression.js`](./examples/compression.js).
 
 6. Do not set `body methods` to read body of requests with GET method or other methods that don't need a body. Reading body makes endpoint about 15% slower.
 
-7. `app.set("etag", false)` is worth about 8% on small responses, measured on both Fulmine and Express, which pay it almost identically. It is the single biggest thing an ordinary route does: in a CPU profile of one, hashing the body and building the tag are about 21% of the time that is not spent waiting, more than writing the headers and more than building the request and the response together. Know what you are trading: without an ETag a client cannot make a conditional request, so there are no `304 Not Modified` replies and every response is downloaded in full. On anything cacheable the bandwidth a 304 saves is usually worth far more than the 8%. It is left on by default for that reason. Turn it off for an API whose responses are never revalidated.
+7. `app.set("etag", false)` is worth about 8% on small responses, measured on both Fulmine and Express, which pay it almost identically. It is the single biggest thing an ordinary route does: in a CPU profile of one, hashing the body and building the tag are about 21% of the time that is not spent waiting, more than writing the headers and more than building the request and the response together. Know what you are trading: without an ETag a client cannot make a conditional request, so there are no `304 Not Modified` replies and every response is downloaded in full. On anything cacheable the bandwidth a 304 saves is usually worth far more than the 8%. It is left on by default for that reason. Turn it off for an API whose responses are never revalidated, and note that it is the same setting that decides whether a simple route is compiled into a native response, above.
 
 8. By default, Fulmine creates 1 (or 0 if your CPU has only 1 core) child thread to improve performance of reading files. You can change this number by setting `threads` to a different number in `express()`, or set to 0 to disable thread pool (`express({ threads: 0 })`). Threads are shared between all express() instances, with largest `threads` number being used. Using more threads will not necessarily improve performance. Sometimes not using threads at all is faster, so measure both.
 
@@ -530,7 +559,7 @@ app.ws("/room/:id", {
 - **The behavior object is µWS's**, settings included: `maxPayloadLength`, `idleTimeout`, `compression`, `maxBackpressure`, `sendPingsAutomatically` and the rest are passed through untouched, as are the `open`, `message`, `drain`, `close`, `ping`, `pong`, `dropped` and `subscription` handlers. The socket is µWS's too, so `send`, `subscribe`, `publish`, `cork` and `getBufferedAmount` behave exactly as its documentation describes.
 - **`upgrade(req, res)` is this project's addition.** It runs before the handshake with the same `Request` and `Response` your routes get, so a session, a token or a header decides whether the socket opens. Answering the response, with `res.sendStatus(401)` or any other write, declines the upgrade. Returning a promise holds the handshake until it settles, which is what an authentication lookup needs.
 - **`ws.req` is that request**, and it outlives the response: the client's address, headers, query and params are readable from any handler for as long as the socket is open. Hanging your own values on it in `upgrade` is how per-connection state gets to `message`.
-- **Routers work.** `router.ws("/lobby", …)` mounted with `app.use("/chat", router)` serves `/chat/lobby`.
+- **Routers work.** `router.ws("/lobby", ...)` mounted with `app.use("/chat", router)` serves `/chat/lobby`.
 - **Paths are the ones µWS matches**: literal, or with parameters that are a whole segment such as `/room/:id`. Anything else throws where it is written rather than failing to match later.
 - **Broadcasting from outside a socket**: `app.publish(topic, message)` and `app.numSubscribers(topic)`.
 
@@ -706,8 +735,10 @@ 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 six of its own:
+Fulmine adds eight of its own:
 
+- `body methods`, unset by default. The body is read for POST, PUT, PATCH and QUERY, and this names the methods to read one for as well: `app.set("body methods", ["DELETE"])`. Reading a body no handler asks for costs about 15%, which is why the built-in list is short rather than every method.
+- `native routes`, on by default. Off, every request walks the ordinary chain instead of letting µWS match what it can, which is slower and answers the same. It is a diagnostic rather than a tuning knob: it exists so one application can be served both ways and the two sets of answers compared, which is how the optimizer is tested. A compiled response needs a native registration to hang on, so turning this off turns `declarative responses` off with it.
 - `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.
@@ -848,6 +879,29 @@ Almost all middlewares that are compatible with Express are compatible with Fulm
 `express` itself, so testing it here needs a dependency override rather than the one-line swap
 everything else takes.
 
+## Tested frameworks
+
+The list above is middlewares. A framework built on Express is a much larger user of the Express
+surface than any application is, so those have a suite of their own, in
+[`integrations/`](./integrations): the same application served twice, once on Express and once here,
+with the two outputs compared byte for byte. The four that render pages are built first, by that
+suite, so what is compared is what their own build produces.
+
+- ✅ [NestJS](https://nestjs.com) through [`fulmine.js/nest`](#nestjs)
+- ✅ [Next.js](https://nextjs.org) as a custom server, `next().getRequestHandler()`
+- ✅ [Astro](https://astro.build) through `@astrojs/node` in middleware mode
+- ✅ [SvelteKit](https://svelte.dev/docs/kit) through `@sveltejs/adapter-node`
+- ✅ [React Router v7](https://reactrouter.com) through `@react-router/express`
+- ✅ [Apollo Server](https://www.apollographql.com/docs/apollo-server) through
+  [`@as-integrations/express5`](https://www.npmjs.com/package/@as-integrations/express5)
+- ✅ [tRPC](https://trpc.io) through `@trpc/server/adapters/express`
+- ✅ [Angular SSR](#angular-ssr), which is an ordinary Express `server.ts` plus one line of build
+  configuration
+
+Each of these mounts on an ordinary Express application, so there is nothing to install and nothing
+to configure beyond what that framework already asks for. Nest is the exception, and only because
+its adapter decides what to listen on: that one is [`fulmine.js/nest`](#nestjs).
+
 ## Tested view engines
 
 Any Express view engine should work. Here's list of engines we include in our test suite:

package/package.json

@@ -1,8 +1,20 @@
 {
     "name": "fulmine.js",
-    "version": "5.12.3",
+    "version": "5.13.1",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
+    "exports": {
+        ".": {
+            "types": "./src/types.d.ts",
+            "default": "./src/index.js"
+        },
+        "./nest": {
+            "types": "./src/nest.d.ts",
+            "default": "./src/nest.js"
+        },
+        "./package.json": "./package.json",
+        "./*": "./*"
+    },
     "bin": {
         "fulmine": "src/cli.js"
     },
@@ -29,6 +41,8 @@
         "cover:full": "nyc --silent npm run test && nyc --silent --no-clean npm run test:unit && nyc --silent --no-clean npm run test:express && nyc report",
         "cover:check": "nyc check-coverage --statements 94.5 --branches 90 --functions 94 --lines 94.5",
         "examples:install": "npm --prefix examples install",
+        "test:integrations": "npm --prefix integrations test",
+        "integrations:install": "npm --prefix integrations install",
         "fuzz:wire": "node tools/wire-fuzz.js",
         "fuzz:headers": "node tools/header-fuzz.js",
         "fuzz:session": "node tools/session-fuzz.js"
@@ -93,10 +107,21 @@
         "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.69.0",
         "vary": "^1.1.2"
     },
+    "peerDependencies": {
+        "@nestjs/platform-express": ">=10"
+    },
+    "peerDependenciesMeta": {
+        "@nestjs/platform-express": {
+            "optional": true
+        }
+    },
     "devDependencies": {
         "@commitlint/cli": "^21.2.1",
         "@commitlint/config-conventional": "^21.2.0",
         "@eslint/js": "^10.0.1",
+        "@nestjs/common": "^11.2.1",
+        "@nestjs/core": "^11.2.1",
+        "@nestjs/platform-express": "^11.2.1",
         "@release-it/conventional-changelog": "^12.0.0",
         "@types/accepts": "^1.3.7",
         "@types/bytes": "^3.1.5",
@@ -160,8 +185,10 @@
         "pkg-pr-new": "^0.0.87",
         "prettier": "^3.9.6",
         "pug": "^3.0.4",
+        "reflect-metadata": "^0.2.2",
         "release-it": "^21.0.1",
         "response-time": "^2.3.4",
+        "rxjs": "^7.8.2",
         "serve-favicon": "^2.5.1",
         "serve-index": "^1.9.2",
         "serve-static": "^2.2.1",

package/src/adopt.js

@@ -0,0 +1,324 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// The two commands that edit a config file rather than source: `npx fulmine.js override` and
+// `npx fulmine.js angular`.
+//
+// `migrate` rewrites `require("express")` in your own files, which is all an application needs. The
+// two cases it cannot reach are both a line in a JSON file that nobody remembers the shape of:
+//
+//   override   A framework built on Express does not require it in your code, it requires it in its
+//              own, so there is no specifier to rewrite. Every package manager can answer `express`
+//              with this package instead, for the whole tree, and each one spells it differently.
+//   angular    An Angular server bundle is built with esbuild, which inlines every dependency and
+//              cannot load µWS's native binary. Two names in `externalDependencies` fix it, and
+//              nothing in the error message it fails with says so.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const SELF = "fulmine.js";
+const REPLACES = "express";
+
+/** The major this package tracks, which is the range an override should ask for. */
+const MAJOR = require("../package.json").version.split(".")[0];
+
+/** Where each manager keeps its substitutions, and what to call it when telling someone. */
+const MANAGERS = {
+    npm: { keys: ["overrides"], reinstall: "npm install" },
+    pnpm: { keys: ["pnpm", "overrides"], reinstall: "pnpm install" },
+    yarn: { keys: ["resolutions"], reinstall: "yarn install" }
+};
+
+/** A lockfile, and the manager that wrote it. bun is here to be refused, see detectManager. */
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["package-lock.json", "npm"],
+    ["npm-shrinkwrap.json", "npm"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"]
+];
+
+/**
+ * The indentation a file already uses, so rewriting it does not reformat every line.
+ *
+ * @param {string} source
+ * @returns {string|number} what JSON.stringify takes as its third argument
+ */
+function indentOf(source) {
+    const first = source.match(/\n([ \t]+)"/);
+    if (!first) {
+        return 4;
+    }
+    return first[1].startsWith("\t") ? "\t" : first[1].length;
+}
+
+/**
+ * Reads a JSON file, or explains why it could not be read rather than throwing a parser error.
+ *
+ * The read is attempted rather than guarded by an existence check. Both commands go on to write the
+ * file they read, and a check on a path followed by a write to the same path is the shape of a race
+ * whatever the odds of losing it. `code` is what a caller names the missing file by.
+ *
+ * @param {string} file
+ * @returns {{data: any, source: string}|{error: string, code: string|undefined}}
+ */
+function readJson(file) {
+    let source;
+    try {
+        source = fs.readFileSync(file, "utf8");
+    } catch (e) {
+        const err = /** @type {NodeJS.ErrnoException} */ (e);
+        return { error: `${file} could not be read: ${err.message}`, code: err.code };
+    }
+    try {
+        return { data: JSON.parse(source), source };
+    } catch (e) {
+        const err = /** @type {Error} */ (e);
+        return { error: `${file} is not valid JSON and was left alone: ${err.message}`, code: undefined };
+    }
+}
+
+/**
+ * Which package manager this project uses.
+ *
+ * The `packageManager` field is asked first: a project that declares one is using it whatever
+ * lockfiles are lying around. A project with neither gets npm, since that is what `npx` came with.
+ *
+ * @param {string} dir
+ * @param {any} pkg the parsed package.json
+ * @returns {{manager: string, why: string}}
+ */
+function detectManager(dir, pkg) {
+    const declared = typeof pkg.packageManager === "string" ? pkg.packageManager.split("@")[0] : undefined;
+    if (declared && (MANAGERS[declared] || declared === "bun")) {
+        return { manager: declared, why: `the packageManager field says ${declared}` };
+    }
+    for (const [file, manager] of LOCKFILES) {
+        if (fs.existsSync(path.join(dir, file))) {
+            return { manager, why: `${file} is here` };
+        }
+    }
+    return { manager: "npm", why: "no lockfile and no packageManager field, so npm" };
+}
+
+/**
+ * Reads a nested key, and answers undefined rather than throwing on a missing level.
+ *
+ * @param {any} object
+ * @param {string[]} keys
+ * @returns {any}
+ */
+function readPath(object, keys) {
+    let at = object;
+    for (const key of keys) {
+        if (at === null || typeof at !== "object") return undefined;
+        at = at[key];
+    }
+    return at;
+}
+
+/**
+ * Writes a nested key, making the levels above it as it goes.
+ *
+ * @param {any} object
+ * @param {string[]} keys
+ * @param {any} value
+ * @returns {void}
+ */
+function writePath(object, keys, value) {
+    let at = object;
+    for (const key of keys.slice(0, -1)) {
+        if (at[key] === null || typeof at[key] !== "object") at[key] = {};
+        at = at[key];
+    }
+    at[keys[keys.length - 1]] = value;
+}
+
+/**
+ * npx fulmine.js override [dir] [--dry-run]
+ *
+ * Puts the substitution in package.json where this project's package manager reads it, and says
+ * what to run next. It deliberately does not run the install: the reinstall throws away
+ * node_modules, and that is not something a command should do to somebody's working tree without
+ * being watched.
+ *
+ * @param {string[]} argv everything after the command name
+ * @returns {number} exit code
+ */
+function override(argv) {
+    const dryRun = argv.includes("--dry-run");
+    const dir = path.resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
+    const file = path.join(dir, "package.json");
+
+    const read = readJson(file);
+    if ("error" in read) {
+        console.error(read.code === "ENOENT" ? `no package.json in ${dir}` : read.error);
+        return 1;
+    }
+    const { data: pkg, source } = read;
+
+    const { manager, why } = detectManager(dir, pkg);
+    if (manager === "bun") {
+        console.error(
+            `this project uses bun (${why}), and bun cannot run this package at all: µWebSockets.js\n` +
+                "is a native node addon and bun does not load it. Nothing was changed."
+        );
+        return 1;
+    }
+
+    const { keys, reinstall } = MANAGERS[manager];
+    const where = keys.join(".");
+    const wanted = `npm:${SELF}@^${MAJOR}`;
+
+    const existing = readPath(pkg, [...keys, REPLACES]);
+    if (existing === wanted) {
+        console.log(`${where}.${REPLACES} already says ${wanted}, so there is nothing to change.`);
+        console.log(`Check it took: ${manager === "npm" ? "npm ls express" : `${manager} why express`}`);
+        return 0;
+    }
+    if (existing !== undefined) {
+        console.error(
+            `${where}.${REPLACES} already says ${JSON.stringify(existing)}, which is not this package.\n` +
+                "Nothing was changed: overwriting somebody else's substitution is not this command's call."
+        );
+        return 1;
+    }
+
+    writePath(pkg, [...keys, REPLACES], wanted);
+    const rewritten = JSON.stringify(pkg, null, indentOf(source)) + "\n";
+
+    // the block on its own, so what was added can be read without diffing a whole package.json
+    const shown = {};
+    writePath(shown, keys, { [REPLACES]: wanted });
+    console.log(`${manager}, because ${why}`);
+    console.log(`${dryRun ? "would add" : "added"} to package.json:\n`);
+    console.log(
+        JSON.stringify(shown, null, 2)
+            .split("\n")
+            .map((line) => `  ${line}`)
+            .join("\n") + "\n"
+    );
+    if (!dryRun) {
+        fs.writeFileSync(file, rewritten);
+    }
+
+    console.log("Then reinstall, so the lockfile is written again:\n");
+    console.log(`  rm -rf node_modules && ${reinstall}\n`);
+    const check = manager === "npm" ? "npm ls express" : `${manager} why express`;
+    console.log(`It took when \`${check}\` names ${SELF}.\n`);
+    console.log("Two things to know before you trust it:\n");
+    console.log(`  The substitution reaches every dependency that asks for ${REPLACES}, including ones you have`);
+    console.log("  never looked at. Run your own tests afterwards, and read `npx fulmine.js differences`:");
+    console.log("  what a framework does with Express is usually more than what an application does.\n");
+    console.log(`  A package that reaches into ${REPLACES}/lib/... rather than its public surface will not find`);
+    console.log("  what it expects, since the files there are ours.\n");
+    return 0;
+}
+
+/**
+ * Every build target in an angular.json that produces a server bundle.
+ *
+ * A browser-only build has nothing to declare external: the bundle it makes never loads µWS. What
+ * marks a server build is `ssr`, `server` or `outputMode` in its options, which is what `ng add
+ * @angular/ssr` writes.
+ *
+ * @param {any} config the parsed angular.json
+ * @returns {{name: string, options: any}[]}
+ */
+function serverBuilds(config) {
+    const found = [];
+    for (const [name, project] of Object.entries(config.projects ?? {})) {
+        const targets = readPath(project, ["architect"]) ?? readPath(project, ["targets"]);
+        const options = readPath(targets, ["build", "options"]);
+        if (!options || typeof options !== "object") continue;
+        if (options.ssr === undefined && options.server === undefined && options.outputMode === undefined) continue;
+        found.push({ name, options });
+    }
+    return found;
+}
+
+/**
+ * npx fulmine.js angular [dir] [--dry-run]
+ *
+ * Declares this package and µWebSockets.js external in every server build, which is what stops
+ * esbuild trying to inline a native binary it cannot read.
+ *
+ * @param {string[]} argv everything after the command name
+ * @returns {number} exit code
+ */
+function angular(argv) {
+    const dryRun = argv.includes("--dry-run");
+    const given = path.resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
+
+    // The argument is either the file or the directory holding it, and which one comes out of
+    // reading it rather than out of a stat: a directory reads as EISDIR and a missing path as
+    // ENOENT, and in both cases the file to look for is angular.json inside it. Asked this way
+    // round because this function goes on to write the file it read, and a check on a path followed
+    // by a write to the same path is the shape of a race whatever the odds of losing it.
+    let file = given;
+    let read = readJson(file);
+    if ("error" in read && (read.code === "EISDIR" || read.code === "ENOENT")) {
+        file = path.join(given, "angular.json");
+        read = readJson(file);
+    }
+    if ("error" in read) {
+        console.error(read.code === "ENOENT" ? `no angular.json at ${file}` : read.error);
+        return 1;
+    }
+    const { data: config, source } = read;
+
+    const builds = serverBuilds(config);
+    if (!builds.length) {
+        console.error(
+            "no server build in angular.json: every build target here produces a browser bundle, and a\n" +
+                "browser bundle never loads µWebSockets.js. Nothing to declare external, and nothing changed.\n" +
+                "Run `ng add @angular/ssr` first if this application is meant to render on the server."
+        );
+        return 1;
+    }
+
+    let changed = 0;
+    for (const { name, options } of builds) {
+        const external = Array.isArray(options.externalDependencies) ? options.externalDependencies : [];
+        const missing = [SELF, "uWebSockets.js"].filter((one) => !external.includes(one));
+        if (!missing.length) {
+            console.log(`${name}: already external, nothing to change`);
+            continue;
+        }
+        options.externalDependencies = [...external, ...missing];
+        changed++;
+        console.log(`${name}: ${dryRun ? "would declare" : "declared"} ${missing.join(" and ")} external`);
+    }
+
+    if (!changed) {
+        return 0;
+    }
+    if (!dryRun) {
+        fs.writeFileSync(file, JSON.stringify(config, null, indentOf(source)) + "\n");
+    }
+
+    console.log(`\n${dryRun ? "would rewrite" : "rewrote"} ${path.relative(process.cwd(), file) || file}\n`);
+    console.log("The server.ts that `ng add @angular/ssr` generates is an ordinary Express application, so");
+    console.log("`npx fulmine.js migrate` is what changes the import in it. @angular/ssr's own");
+    console.log("AngularNodeAppEngine and writeResponseToNodeResponse work against this unchanged.\n");
+    return 0;
+}
+
+module.exports = { override, angular, detectManager, serverBuilds, indentOf };

package/src/cli.js

@@ -31,6 +31,13 @@ limitations under the License.
 //
 // Whether this machine and this project can run it at all: the node version, the C library, the
 // µWebSockets.js binary, the base image a Dockerfile names. See src/verify.js.
+//
+// npx fulmine override [dir]
+// npx fulmine angular [dir]
+//
+// The two things a project needs that are a line in a JSON file rather than a specifier in a source
+// file: the package manager substitution, for a framework that requires express in its own code,
+// and angular.json's externalDependencies. See src/adopt.js.
 
 const fs = require("fs");
 const path = require("path");
@@ -38,6 +45,7 @@ const acorn = require("acorn");
 // the same walk express.testing asserts on, so the command and the assertions cannot drift
 const { collectRoutes } = require("./testing.js");
 const { verify } = require("./verify.js");
+const { override, angular } = require("./adopt.js");
 
 const FROM = "express";
 const TO = "fulmine.js";
@@ -85,11 +93,12 @@ 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 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.'
+        "a compiled route keeps its connection header",
+        "A handler simple enough to be read at registration time is answered natively, and a client\n" +
+            "that sent Connection: close is still told keep-alive, though the socket does close. A body\n" +
+            "with a piece of the query in it is framed chunked, since its length is not known until the\n" +
+            "request arrives. A response that would carry a validator is never compiled, so conditional\n" +
+            'requests behave as on Express. app.set("declarative responses", false) turns it off.'
     ],
     [
         "headers are capped at 4096 bytes by default",
@@ -822,9 +831,19 @@ function main(argv) {
     if (command === "explain") {
         return explain(argv.slice(1));
     }
+    if (command === "override") {
+        return override(argv.slice(1));
+    }
+    if (command === "angular") {
+        return angular(argv.slice(1));
+    }
     if (command !== "migrate") {
         console.log(`Usage:
   npx ${TO} migrate [dir]      rewrite require("${FROM}") and import from "${FROM}" to "${TO}"
+  npx ${TO} override [dir]     answer ${FROM} with this package for the whole dependency tree, for
+                               when a framework requires ${FROM} in its own code and not in yours
+  npx ${TO} angular [dir]      declare this package external in angular.json's server build, which
+                               esbuild otherwise tries to inline a native binary into
   npx ${TO} profile [entry]    load an application without listening and print what compiling
                                its routes decided, route by route
   npx ${TO} explain <route>    what happens when a request for that route arrives
@@ -832,7 +851,7 @@ function main(argv) {
   npx ${TO} differences        print what behaves differently, without changing anything
 
 Options:
-  --dry-run                    migrate: say what would change and change nothing`);
+  --dry-run                    migrate, override, angular: say what would change and change nothing`);
         return command ? 1 : 0;
     }
 

package/src/declarative.js

@@ -715,13 +715,10 @@ module.exports = function compileDeclarative(cb, app) {
             return false;
         }
 
-        // A status that carries no content, which is a rule about the message and not about the
-        // application: express drops the body and the framing headers for 204 and 304, and node
-        // writes a lone Content-Length: 0 for 205. Compiled, the body went out anyway, so
-        // res.sendStatus(204) answered "No Content" with a Content-Length of ten. A client frames
-        // a 204 as bodiless whatever the headers say, so those ten bytes were read as the start of
-        // the next answer on the connection, which is a desync on any keep-alive client. The
-        // ordinary path already writes all three the way express does: this hands them back to it.
+        // A status that carries no content. Compiled, the body went out with it, and a client
+        // frames these as bodiless whatever the headers say, so those bytes were read as the start
+        // of the next answer on the connection. The ordinary path already writes all three the way
+        // express does.
         if (BODILESS_STATUSES.has(statusCode) || statusCode < 200) {
             return false;
         }
@@ -771,15 +768,10 @@ module.exports = function compileDeclarative(cb, app) {
             body.push({ type: "text", value: statuses.message[statusCode] || String(statusCode) });
         }
 
-        // 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.
+        // A response that would carry a validator is not compiled at all: µWS answers it without
+        // reading the request, so it could never turn a conditional GET into the 304 the validator
+        // invites. Dropping the ETag instead would leave the simplest routes of an application
+        // without one, so `etag` false is how a route stays compiled.
         if (headers.some((header) => VALIDATOR_HEADERS.has(header[0].toLowerCase()))) {
             return false;
         }

package/src/middlewares.js

@@ -810,13 +810,20 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 return next();
             }
 
+            // The property goes on the request before anything is decided, and its value stays
+            // undefined: body-parser's read() does exactly this, and the two halves both matter.
+            // Undefined, so a handler can still tell "nothing parsed this" from "the body was
+            // empty", which seeding an empty object would lose. Present, because `"body" in req`
+            // is how a library asks whether a parser has run at all: Apollo's express middleware
+            // refuses the request with a 500 when the property is missing, and tRPC's adapter
+            // reads the body itself when it is, so getting either half wrong breaks one of them.
+            if (!("body" in req)) {
+                req.body = undefined;
+            }
+
             // 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",
-            // so it must not be seeded with an empty object first.
-
             // skip reading body for no content type
             // a function decides for itself, and body-parser lets it see a request that carries no
             // content-type at all. Only the string and array forms need one to match against

package/src/nest.d.ts

@@ -0,0 +1,39 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { ExpressAdapter } from "@nestjs/platform-express";
+
+/**
+ * Nest's Express adapter, listening on uWebSockets.js instead of on node.
+ *
+ * ```ts
+ * import { NestFactory } from "@nestjs/core";
+ * import { FulmineExpressAdapter } from "fulmine.js/nest";
+ *
+ * const app = await NestFactory.create(AppModule, new FulmineExpressAdapter());
+ * await app.listen(3000);
+ * ```
+ *
+ * `@nestjs/platform-express` is an optional peer dependency: this entry point is the only thing
+ * that needs it, and nothing loads it unless you import this.
+ */
+export declare class FulmineExpressAdapter extends ExpressAdapter {
+    /**
+     * @param instance an application from `fulmine()`; one is created when omitted. Pass your own
+     * when it needs options, TLS being the usual reason: `fulmine({ uwsOptions })`.
+     */
+    constructor(instance?: any);
+}

package/src/nest.js

@@ -0,0 +1,119 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// require("fulmine.js/nest"): the Nest HTTP adapter, so a Nest application runs on µWS without
+// anyone having to write this file themselves.
+//
+//     import { NestFactory } from "@nestjs/core";
+//     import { FulmineExpressAdapter } from "fulmine.js/nest";
+//
+//     const app = await NestFactory.create(AppModule, new FulmineExpressAdapter());
+//     await app.listen(3000);
+//
+// @nestjs/platform-express takes any Express instance, and this is one, so everything above the
+// adapter - controllers, pipes, guards, interceptors - is untouched. Three things below it are not,
+// and they are the whole reason this file exists:
+//
+//   - initHttpServer wraps the instance in http.createServer() and listens on that. Every request
+//     would then arrive through node's parser and be replayed into µWS's shapes by node-shim.js,
+//     which is the slow path that exists for supertest. The app already answers as an http.Server,
+//     so it is the server instead of being put inside one.
+//   - registerParserMiddleware decides whether Nest's body parsers are already in the chain by
+//     scanning app.router.stack for them. There is no layer array here to scan, routes are compiled
+//     rather than kept as layers, so the answer was always "no" and a second call added a second
+//     pair. It is remembered here instead, which is the same answer by a different route.
+//   - httpsOptions asks node to make a TLS server out of the instance. TLS here belongs to µWS and
+//     is configured when the app is built, so that combination is refused with the line to write
+//     rather than silently starting a plaintext server.
+//
+// @nestjs/platform-express is an optional peer dependency: this file is the only one that requires
+// it, and nothing loads this file unless you ask for it by name.
+
+"use strict";
+
+const { ExpressAdapter } = require("@nestjs/platform-express");
+const fulmine = require("./index.js");
+
+/**
+ * Nest's Express adapter, listening on µWebSockets.js instead of on node.
+ *
+ * Pass a configured app when you need one, `new FulmineExpressAdapter(fulmine({ uwsOptions }))`;
+ * with no argument it builds a default one, the same as `new ExpressAdapter()` does.
+ */
+class FulmineExpressAdapter extends ExpressAdapter {
+    /**
+     * @param {any} [instance] an application from `fulmine()`; one is created when omitted
+     */
+    constructor(instance) {
+        super(instance || fulmine());
+        /**
+         * Whether Nest's body parsers are in the chain, standing in for the layer array Express
+         * has and this does not. See registerParserMiddleware below.
+         * @type {boolean}
+         */
+        this._parsersRegistered = false;
+    }
+
+    /**
+     * The app is the server. Nest calls this once, from NestApplication's constructor.
+     *
+     * @param {any} [options] the options NestFactory.create was given
+     * @returns {void}
+     */
+    initHttpServer(options) {
+        if (options?.httpsOptions) {
+            throw new Error(
+                "fulmine.js: httpsOptions cannot be used here, since there is no node server to give " +
+                    "them to. TLS belongs to µWS and is configured when the app is built:\n" +
+                    '  new FulmineExpressAdapter(fulmine({ uwsOptions: { key_file_name: "key.pem", cert_file_name: "cert.pem" } }))'
+            );
+        }
+        this.httpServer = this.getInstance();
+        if (options?.forceCloseConnections) {
+            // trackOpenConnections() listens for 'connection', which nothing emits: the sockets
+            // belong to µWS and never become node ones. Said out loud, because a shutdown that
+            // quietly waits forever for what it thinks it can destroy is worse than one that does
+            // not offer to. Through Nest's own logger, so the line arrives where every other line
+            // from the framework does; it is private in the typings and inherited all the same
+            /** @type {any} */ (this).logger.warn(
+                "forceCloseConnections has no effect on fulmine.js: the sockets belong to µWS. " +
+                    "app.close() stops accepting and waits for the requests in flight; an idle keep-alive " +
+                    "connection is closed by µWS through uwsOptions.idleTimeout, not by node."
+            );
+        }
+    }
+
+    /**
+     * Nest's json and urlencoded parsers, added once however often this is called.
+     *
+     * Express answers "are they there already" by scanning `app.router.stack` for a layer whose
+     * handler is named `jsonParser` or `urlencodedParser`. There is no such array here, so the scan
+     * answered no every time and a second call put a second pair in front of every request.
+     *
+     * @param {string} [prefix]
+     * @param {boolean} [rawBody]
+     * @returns {void}
+     */
+    registerParserMiddleware(prefix, rawBody) {
+        if (this._parsersRegistered) return;
+        this._parsersRegistered = true;
+        super.registerParserMiddleware(prefix, rawBody);
+    }
+}
+
+// a named export and nothing else: `import { FulmineExpressAdapter } from "fulmine.js/nest"`, which
+// is how @nestjs/platform-express exports ExpressAdapter too
+module.exports = { FulmineExpressAdapter };

package/src/request.js

@@ -181,10 +181,9 @@ function endsWithChunked(value) {
  * The path of the url a request carries right now, without the query.
  *
  * Express reads it off req.url on every access, so a middleware that assigns req.url is seen by
- * whatever runs next, the callback after it in the same route included: the router takes a rewrite
- * over at its next hop, and until then the field is a hop behind. `req.url = req.url.replace(/^\/+/,
- * "/")` reported "//" for the rest of its own route where express reports "/". The field answers
- * while the two agree, which is every read of a request nobody rewrote.
+ * whatever runs next, the callback after it in the same route included: the router only takes a
+ * rewrite over at its next hop. The cached field answers while the two agree, which is every read
+ * of a request nobody rewrote.
  *
  * @param {any} req
  * @returns {string}
@@ -369,11 +368,12 @@ module.exports = class Request extends LazyReadable {
     /** A bodyless request whose empty end has not been delivered yet, see the constructor. */
     #emptyBody = false;
 
-    /**
-     * What a body parser left behind, and undefined until one claims the request.
-     * @type {any}
-     */
-    body;
+    // `body` is deliberately not declared here. A class field would put the property on every
+    // request, and on Express there is none until a body parser assigns one. `"body" in req` is how
+    // a library asks whether the body has already been read, and tRPC's express adapter asks
+    // exactly that: answering yes on a request nobody had parsed handed it an undefined body and
+    // turned every mutation into "Unexpected end of JSON input". Its type lives in types.d.ts,
+    // where the rest of the public request surface is described.
 
     /**
      * The response this request arrived with, linked so either reaches the other.

package/src/response.js

@@ -589,9 +589,16 @@ module.exports = class Response extends LazyWritable {
      *
      * Nothing is written here despite the name: the headers go out when the body does.
      *
+     * Every header goes through setHeader and not through set. This is node's method, not
+     * Express's: Express does not override it, so a content-type given here keeps the value it was
+     * given, where `res.set("content-type", "text/html")` would have a charset appended to it. A
+     * handler that builds its own response and writes it with writeHead is how every meta-framework
+     * on top of Express answers, @astrojs/node and @sveltejs/adapter-node included, so the charset
+     * was being added to pages nobody asked it for.
+     *
      * @param {number} statusCode
-     * @param {string|Record<string, any>} [statusMessage] the reason phrase, or the headers
-     * @param {Record<string, any>} [headers]
+     * @param {string|Record<string, any>|any[]} [statusMessage] the reason phrase, or the headers
+     * @param {Record<string, any>|any[]} [headers]
      * @returns {this}
      */
     writeHead(statusCode, statusMessage, headers) {
@@ -605,8 +612,22 @@ module.exports = class Response extends LazyWritable {
             // string reaching here was already taken as the phrase above and simply has no keys.
             headers = /** @type {Record<string, any>} */ (statusMessage);
         }
+        if (Array.isArray(headers)) {
+            // node takes a flat list here, name then value, and not a list of pairs. An odd length
+            // is the caller's mistake and node names the argument in what it throws
+            if (headers.length % 2 !== 0) {
+                /** @type {NodeJS.ErrnoException} */
+                const err = new TypeError(`The argument 'headers' is invalid. Received ${JSON.stringify(headers)}`);
+                err.code = "ERR_INVALID_ARG_VALUE";
+                throw err;
+            }
+            for (let i = 0; i < headers.length; i += 2) {
+                this.setHeader(headers[i], headers[i + 1]);
+            }
+            return this;
+        }
         for (const header in headers) {
-            this.set(header, headers[header]);
+            this.setHeader(header, headers[header]);
         }
         return this;
     }

package/src/router.js

@@ -893,6 +893,16 @@ function onNativeAborted() {
     // error goes only to whoever listens for it, since a destroy(err) with no listener
     // would take down the process
     request.emit("aborted");
+    // and the response dies between the two, which is where node puts it. Destroyed rather than
+    // told to emit 'close', because being destroyed is the state express is in here and everything
+    // after it follows from that state rather than having to be reproduced: 'close' goes out once,
+    // a later res.write returns false and calls its callback with ERR_STREAM_DESTROYED, and no
+    // 'error' is emitted, which a destroy(err) here would.
+    //
+    // Without this a handler learnt about the abort only from a write failing, so one that had sent
+    // its head and gone quiet never learnt at all. `res.on("close")` is where cancellation hangs in
+    // every proxy and every streaming endpoint, so it never ran for exactly the shape that needs it.
+    response.destroy();
     request.destroy(request.listenerCount("error") > 0 ? err : undefined);
     response.socket?.emit("error", err);
 }
@@ -1079,7 +1089,17 @@ function stepsOver(route, req) {
     if (route.bodyMethods === undefined) {
         route.bodyMethods = req.app.get("body methods") ?? null;
     }
-    return route.bodyMethods === null || !route.bodyMethods.includes(req.method);
+    if (route.bodyMethods !== null && route.bodyMethods.includes(req.method)) {
+        return false;
+    }
+    // The layer is not entered, so it leaves the one mark it would have left: the parser puts
+    // `body` on the request before it works out that there is nothing to read. A library asks
+    // `"body" in req` to tell "a parser has run" from "none has", and a skip that did not leave
+    // it would answer a GET differently from express. See the same seeding in middlewares.js
+    if (!("body" in req)) {
+        req.body = undefined;
+    }
+    return true;
 }
 
 /**

package/src/testing.js

@@ -171,6 +171,32 @@ function expectNative(app, patterns) {
     );
 }
 
+/**
+ * Why a route µWS already matches is still not compiled into a response.
+ *
+ * The handler is the last answer, not the first: three refusals come before it, and blaming the
+ * handler for one of those sends the reader to rewrite something that was already simple enough.
+ *
+ * @param {any} app
+ * @param {{path: string}} entry
+ * @returns {string}
+ */
+function whyNotCompiled(app, entry) {
+    if (!app.get("declarative responses")) {
+        return "answered by µWS, but declarative responses are turned off";
+    }
+    if (entry.path.includes(":")) {
+        return "answered by µWS, but the route captures, and nothing runs to decode the value";
+    }
+    if (app.get("etag")) {
+        return (
+            "answered by µWS, but a response carrying an ETag could never answer the conditional " +
+            'request it invites: app.set("etag", false) is what puts a route here'
+        );
+    }
+    return "answered by µWS, but the handler is not simple enough to compile";
+}
+
 /**
  * Throws unless every route named is answered from a response written at startup, which is the
  * step past native: µWS answers it without entering javascript at all.
@@ -189,9 +215,7 @@ function expectDeclarative(app, patterns) {
                 .map(
                     (entry) =>
                         `  ${entry.method} ${entry.path}\n    ` +
-                        (entry.native
-                            ? "answered by µWS, but the handler is no longer simple enough to compile"
-                            : entry.reason)
+                        (entry.native ? whyNotCompiled(app, entry) : entry.reason)
                 )
                 .join("\n") +
             `\n\nRun \`npx fulmine profile\` to see the whole picture.`