fulmine.js 5.12.2 → 5.13.0

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
@@ -285,7 +307,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 request whose `Content-Length` cannot be trusted is refused by hanging up, with no answer at all.** Node's parser refuses two of these with a `400` and Fulmine refuses the same two: a repeated `Content-Length`, whatever the values say, and one that is not a plain count of bytes, an empty value included. µWS accepts both and frames the request on the first value, or on no body at all, so what the client sent as a body is read as the next request on the connection: that is request smuggling, and a proxy in front reading the other value is all it takes. The answer differs from Express because it cannot be helped. µWS only skips the request it has already queued when the response is closed rather than completed, and writing the `400` completes it, so the choice is between telling the client and stopping the smuggled request. Nothing well behaved sends two content-lengths.
+- **A request whose framing cannot be trusted is refused by hanging up, with no answer at all.** Node's parser refuses each of these with a `400` and Fulmine refuses the same ones: a repeated `Content-Length`; one that is not a plain count of bytes, an empty value or a count past `Number.MAX_SAFE_INTEGER` included; a `Transfer-Encoding` whose last coding is not `chunked`; and a method nobody defines, which includes a lowercase one, since methods are case sensitive. µWS accepts all of them. It frames the request on the first length, or on no body at all, and it takes any token as a method, so `{"a":1}GET /path HTTP/1.1` is a request line to it. What the client sent as a body is then read as the next request on the connection: that is request smuggling, and a proxy in front disagreeing about the framing is all it takes. The answer differs from Express because it cannot be helped. µWS only skips the request it has already queued when the response is closed rather than completed, and writing the `400` completes it, so the choice is between telling the client and stopping the smuggled request. Nothing well behaved sends any of these.
 - **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:
@@ -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.2",
+    "version": "5.13.0",
     "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"
     },
@@ -28,7 +40,12 @@
         "release:local": "node tools/release-local.js",
         "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"
+        "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"
     },
     "engines": {
         "node": ">=22"
@@ -72,7 +89,7 @@
         "bytes": "^3.1.2",
         "compressible": "^2.0.18",
         "content-disposition": "^1.1.0",
-        "cookie": "^1.1.1",
+        "cookie": "^0.7.2",
         "cookie-signature": "^1.2.2",
         "encodeurl": "^2.0.0",
         "fast-decode-uri-component": "^1.0.1",
@@ -90,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",
@@ -157,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/application.js

@@ -529,8 +529,8 @@ class Application extends Router {
     _serveGeneric(res, req) {
         const request = this.handleRequest(res, req);
         const response = request.res;
-        if (request._badFraming === true) {
-            return this._refuseFraming(response);
+        if (request._mustRefuse === true) {
+            return this._refuseRequest(response);
         }
         try {
             this._routeRequestDirect(request, response);