fulmine.js 5.9.0 → 5.11.0

package/README.md

@@ -18,12 +18,12 @@ import type { Request, Response } from "fulmine.js";
 There is a command that does that replacing for you, across a whole project, and then tells you the handful of things that behave differently:
 
 ```sh
-npx fulmine verify              # can this machine and this image even run it
-npx fulmine migrate --dry-run   # say what it would change, change nothing
-npx fulmine migrate             # do it
-npx fulmine differences         # just the list of what to check by hand
-npx fulmine profile             # what listen() decided about each route
-npx fulmine explain /api/items  # what happens when a request for that route arrives
+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 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
 ```
 
 See [Migrating](#migrating) for what it handles and what it deliberately does not.
@@ -61,6 +61,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
     - [Router](#router)
 - [Tested middlewares](#tested-middlewares)
 - [Tested view engines](#tested-view-engines)
+- [Examples](./examples/README.md)
 - [Working on Fulmine](./CONTRIBUTING.md)
 
 ## Why this exists
@@ -115,22 +116,19 @@ It is likewise not affiliated with the OpenJS Foundation or the Express.js proje
 
 ## Migrating
 
-In a lot of cases, replacing `require("express")` with `require("fulmine.js")` is the whole migration. `npx fulmine migrate` does that across a project:
+In a lot of cases, replacing `require("express")` with `require("fulmine.js")` is the whole migration. `npx fulmine.js migrate` does that across a project:
 
 ```sh
-npx fulmine migrate [dir]       # defaults to the current directory
-npx fulmine migrate --dry-run   # say what it would rewrite and rewrite nothing
-npx fulmine differences         # print the list below and change nothing
+npx fulmine.js migrate [dir]       # defaults to the current directory
+npx fulmine.js migrate --dry-run   # say what it would rewrite and rewrite nothing
+npx fulmine.js differences         # print the list below and change nothing
 ```
 
-The command is installed under both `fulmine` and `fulmine.js`. Use `fulmine`: `npx` cannot run a
-command whose name ends in `.js` on Windows, where it exits without a word.
-
 It also names the middlewares it found that have a faster one built in here, `compression`,
 `body-parser` and `serve-static`, and leaves them to you: the replacement is reached through the
 `express` import, and no rewrite can know that it is in scope where they are required.
 
-`npx fulmine verify` is the question that comes before all of that: whether this machine, and the
+`npx fulmine.js verify` is the question that comes before all of that: whether this machine, and the
 image this will be deployed in, can run it at all. There is a µWebSockets.js binary underneath, and
 a binary is built per platform, per architecture and per node ABI, and linked against glibc. An
 Alpine base, a node version the pinned build has no binary for, a `FROM node:20-alpine` written
@@ -248,7 +246,7 @@ A single-stage `node:26-trixie-slim` image works too if you `apt-get install -y
 
 ## Differences from Express
 
-- `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`.
+- `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.
 - **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`.
@@ -291,6 +289,8 @@ app.listen(3000, () => {
 });
 ```
 
+Runnable: [`examples/https.js`](./examples/https.js).
+
 - This also applies to non-SSL HTTP too. Use `app.listen()` rather than creating a server by hand. `http.createServer(app)` does work, because the app is a request listener like Express's and answers node's requests through a shim, which is what lets `supertest`, `vhost` and anything else that calls an app keep working. But it serves those requests through `node:http` rather than through µWS, so the speed is Express's. It is there for compatibility, not for production.
 - Node.JS max header size is 16384 bytes, while uWebSockets by default is 4096 bytes, so if you need longer headers set the env variable `UWS_HTTP_MAX_HEADERS_SIZE` to max byte count you need.
 - uWebSockets drops a request whose body arrives slower than 16KB/s, and the timeout is not reachable from JavaScript, while Node.JS waits as long as the client needs. Uploads over very slow connections can therefore fail here and succeed on Express. A body stalled for 5 seconds still completes; one stalled for 12 seconds gets its socket reset at around 11.8 seconds.
@@ -325,7 +325,7 @@ arriving at a handler costs no matching at all:
 That is the whole difference on a large route table: the scan grows with the table and the match
 does not, which is why a thousand routes measure 10x and a handful measure 3x.
 
-Two more things happen on the way in, and `npx fulmine profile` will tell you which of them your
+Two more things happen on the way in, and `npx fulmine.js profile` will tell you which of them your
 routes get:
 
 ```text
@@ -349,24 +349,24 @@ routes get:
 
 1. Fulmine tries to optimize routing as much as possible, but it's only possible if:
 
-- the path is a plain string, or its parameters are whole segments: `/users/:id` and `/a/:b/c/:d` qualify, `/flights/:from-:to` does not, and neither does a `*splat` or a `{}` group. Routing is case-insensitive by default, as in Express; a request in the registered case is still served natively, any other case takes the ordinary path, and a route whose overlap with an earlier one leans on a cased literal goes the ordinary way for every request.
+- the path is a plain string, or its parameters are whole segments: `/users/:id` and `/a/:b/c/:d` qualify, `/flights/:from-:to` does not, and neither does a `*splat` or a `{}` group. Routing is case-insensitive by default, as in Express; a request in the registered case is still served natively, any other case takes the ordinary path, and a route whose overlap with an earlier one leans on a cased literal goes the ordinary way for every request. That last one is worth knowing about: `app.set("case sensitive routing", true)` is Express's own setting, and with it `/Users/list` no longer overlaps `/users/:id`, so both are matched by µWS instead of one of them falling back.
 - inside a mounted router, nothing registered after the route in that router could match the same path. `/orders/:id`, `/orders/:id/items` and `/invoices/:id` are all optimized together, since no request reaches two of them. `/users/:id` followed by `/users/me` is not: Express answers `/users/me` with the first of the two and the native router would answer it with the second, so both go the ordinary way.
 
 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.append`, `res.send`, `res.json`, `res.sendStatus` or `res.end` with literal arguments, plus `req.params` and `req.query`. 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.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:
 
 - 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 is framed as `Transfer-Encoding: chunked` and carries no `Content-Length`, because uWS writes that framing itself.
+- 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.
 - 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.
 
-None of that is guesswork you have to do from the outside. `listen()` decides it all, and `npx fulmine profile` prints what it decided:
+None of that is guesswork you have to do from the outside. `listen()` decides it all, and `npx fulmine.js profile` prints what it decided:
 
 ```sh
-npx fulmine profile              # the file package.json's "main" points at
-npx fulmine profile server.js    # or name it
+npx fulmine.js profile              # the file "main" or the start script points at
+npx fulmine.js profile server.js    # or name it
 ```
 
 ```text
@@ -403,9 +403,9 @@ expectDeclarative(app, "/health"); // the step past native: no javascript at all
 routeReport(app); // the whole list, to assert on however you like
 ```
 
-A path is written as it was registered, `"/users/:id"` and not `"/users/7"`, and a trailing `*` names everything under a prefix. A pattern that matches no route throws too, so a misspelled path fails instead of passing quietly. The application does not need to be listening.
+A path is written as it was registered, `"/users/:id"` and not `"/users/7"`, and a trailing `*` names everything under a prefix. A pattern that matches no route throws too, so a misspelled path fails instead of passing quietly. The application does not need to be listening. Runnable: [`examples/fast-routes.js`](./examples/fast-routes.js).
 
-`npx fulmine explain /api/items/:id` answers the other question, the one about a single endpoint rather than about the table: how it is matched, what is copied out of the request, what runs and what each layer costs the route.
+`npx fulmine.js explain /api/items/:id` answers the other question, the one about a single endpoint rather than about the table: how it is matched, what is copied out of the request, what runs and what each layer costs the route.
 
 ```text
 GET /api/items/:id
@@ -425,9 +425,9 @@ The same verdict reaches the browser, per request, with `express.serverTiming()`
 Server-Timing: route;desc="native", hdr;desc="not copied", db;dur=3.62, total;dur=4.66
 ```
 
-`route;desc="native"` means µWS matched the path in C++ and the chain was worked out at startup; `route;desc="router"` means this one was matched here, layer by layer. `res.timing(name, ms, desc)` and `res.time(name, fn)` add marks of your own, and `fn` may return a promise. The duration ends where the header does, since Server-Timing goes out with the head. A route compiled into a response never enters JavaScript, so nothing times it: `npx fulmine profile` is where those are counted.
+`route;desc="native"` means µWS matched the path in C++ and the chain was worked out at startup; `route;desc="router"` means this one was matched here, layer by layer. `res.timing(name, ms, desc)` and `res.time(name, fn)` add marks of your own, and `fn` may return a promise. The duration ends where the header does, since Server-Timing goes out with the head. A route compiled into a response never enters JavaScript, so nothing times it: `npx fulmine.js profile` is where those are counted. Runnable: [`examples/server-timing.js`](./examples/server-timing.js).
 
-2. Do not use external `serve-static` module. Instead use built-in `express.static()` middleware, which is optimized for Fulmine. If your build already writes `.br` and `.gz` files next to the originals, `express.static(dir, { preCompressed: true })` serves those to the clients that accept them, so nothing is compressed at request time and a fraction of the bytes goes out: on a 4KB script with a brotli twin, 12 times fewer. It costs no more than serving the file itself, one `stat` per request, because the twin is looked for before the file and its own `stat` is the only one the request needs. A type that is already compressed, a woff2 or a webp, is not looked up at all, and which twins a path has is remembered for a second: `{ cache: false }` asks the disk every time, `{ cache: "5s" }` sets the window. Only their presence is remembered, never their size or mtime, so nothing is ever described by a stale number. `Vary: Accept-Encoding` is sent whether or not a twin is found, the content type stays the one the requested name implies, and each variant carries its own ETag.
+2. Do not use external `serve-static` module. Instead use built-in `express.static()` middleware, which is optimized for Fulmine. If your build already writes `.br` and `.gz` files next to the originals, `express.static(dir, { preCompressed: true })` serves those to the clients that accept them, so nothing is compressed at request time and a fraction of the bytes goes out: on a 4KB script with a brotli twin, 12 times fewer. It costs no more than serving the file itself, one `stat` per request, because the twin is looked for before the file and its own `stat` is the only one the request needs. A type that is already compressed, a woff2 or a webp, is not looked up at all, and which twins a path has is remembered for a second: `{ cache: false }` asks the disk every time, `{ cache: "5s" }` sets the window. Only their presence is remembered, never their size or mtime, so nothing is ever described by a stale number. `Vary: Accept-Encoding` is sent whether or not a twin is found, the content type stays the one the requested name implies, and each variant carries its own ETag. Runnable: [`examples/static-precompressed.js`](./examples/static-precompressed.js).
 
 3. Do not use `body-parser` module. Instead use built-in `express.text()`, `express.json()` etc.
 
@@ -438,11 +438,13 @@ Server-Timing: route;desc="native", hdr;desc="not copied", db;dur=3.62, total;du
 app.use(express.compression({ threshold: 1024 }));
 ```
 
-5. If a route answers with a JSON shape you know in advance, [express-fast-json-stringify](https://www.npmjs.com/package/express-fast-json-stringify) compiles that shape into a serializer and `res.fastJson()` replaces `res.json()`. `JSON.stringify()` has to walk an object it knows nothing about; a compiled serializer does not.
+Runnable: [`examples/compression.js`](./examples/compression.js).
+
+5. If a route answers with a JSON shape you know in advance, [express-fast-json-stringify](https://www.npmjs.com/package/express-fast-json-stringify) compiles that shape into a serializer and `res.fastJson()` replaces `res.json()`. `JSON.stringify()` has to walk an object it knows nothing about; a compiled serializer does not. It is worth reaching for, and a CPU profile says why: on a route answering 3.6KB of JSON, serialising it is about 25% of the time that is not spent waiting, ahead of the ETag at 19% and of everything the framework does to route the request and build its request and response objects.
 
 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. 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.
 
 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.
 
@@ -461,7 +463,7 @@ app.get("/", (req, res) => res.send("hello"));
 app.listen(3000, () => console.log(`worker ${process.pid} listening`));
 ```
 
-Anything held per process is now held per worker: an in-memory cache, a rate-limit counter, a session store or a `Map` of connected sockets is not shared, and needs Redis or something like it to be. `app.close()` in the primary stops the workers, and a `SIGTERM` or `SIGINT` that reaches only the primary, which is what a container sends, is passed on to them.
+Anything held per process is now held per worker: an in-memory cache, a rate-limit counter, a session store or a `Map` of connected sockets is not shared, and needs Redis or something like it to be. `app.close()` in the primary stops the workers, and a `SIGTERM` or `SIGINT` that reaches only the primary, which is what a container sends, is passed on to them. Runnable: [`examples/cluster.js`](./examples/cluster.js).
 
 ## WebSockets
 
@@ -493,7 +495,7 @@ app.ws("/room/:id", {
 - **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)`.
 
-A WebSocket route and an ordinary route can share a path: the upgrade goes to the WebSocket route, a plain GET goes through normal routing.
+A WebSocket route and an ordinary route can share a path: the upgrade goes to the WebSocket route, a plain GET goes through normal routing. Runnable, with a page that opens the socket: [`examples/websocket.js`](./examples/websocket.js).
 
 If you would rather use the `ws` module's API, [Ultimate WS](https://github.com/dimdenGD/ultimate-ws) is a drop-in replacement for it written against Ultimate Express, and Fulmine still exposes the mechanism it hooks into, but that combination is not covered by this project's tests. `app.uwsApp` also remains available for anything µWS offers that this does not.
 
@@ -524,7 +526,7 @@ function before it checks for a server, and an app here is callable. That refusa
 answer. Even if it accepted the object, there is no node socket behind it to take an upgrade over,
 so it would have failed later and more quietly. Plain HTTP keeps serving either way. This is covered
 by `tests/tests/middlewares/socket-io.js`, which runs the same file against Express and against
-Fulmine and compares the output.
+Fulmine and compares the output. Runnable: [`examples/socket-io.js`](./examples/socket-io.js).
 
 ## HTTP/3
 
@@ -565,7 +567,9 @@ app.set("trust proxy protocol", true);
 
 `trust proxy` and this can both be on. The preamble decides what the connection's address is, and
 `trust proxy` then peels `X-Forwarded-For` off that, so a proxy that sends both is read the way it
-meant.
+meant. It is the binary v2 preamble that µWS reads, not the v1 text line, so a connection starting
+with `PROXY TCP4 ...` is answered as a malformed request. Runnable, with a client that writes one:
+[`examples/proxy-protocol.js`](./examples/proxy-protocol.js).
 
 ## Versioning
 
@@ -663,10 +667,12 @@ 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 three of its own:
+Fulmine adds five of its own:
 
 - `declarative responses`, on by default. Lets a simple enough handler be compiled into a native uWS response, described under [Performance tips](#performance-tips).
+- `connection headers`, on by default. Express sends `Connection: keep-alive` and `Keep-Alive` on every response, and so does this. Turn it off and neither goes out, while a connection the client asked to close still answers `Connection: close`: it is the advertisement that goes, not the truth. Worth 2% to 3.5% here on a route that is not compiled, plus the bytes.
 - `file cache`, on by default. Small files served by `res.sendFile` come from a bounded in-process cache, checked against the file's `stat` on every request, so an edited file is never served stale. Turn it off where every request has to reach the disk, which is what a public benchmark asks of a standard entry: it was worth about 4% on a 4KB file here, so the cost of turning it off is small.
+- `stat cache`, off by default. Takes a duration, `app.set("stat cache", "1s")`. The size and mtime of a file served by `res.sendFile` or `express.static` are remembered for that long, so a file that is asked for again inside the window costs no syscall at all. It was worth 15% on a 3KB file and 3% on a 200KB one, where the bytes are the work. What it costs is the one promise the `file cache` keeps: inside the window an edited file is served as it was, so keep the window shorter than you would notice.
 - `trust proxy protocol`, off by default. Takes `req.ip` from a PROXY protocol preamble, described under [Behind a proxy](#behind-a-proxy). Read the warning there before turning it on.
 
 ### Request
@@ -813,6 +819,20 @@ Any Express view engine should work. Here's list of engines we include in our te
 - ✅ [express-handlebars](https://npmjs.com/package/express-handlebars)
 - ✅ [swig](https://npmjs.com/package/swig)
 
+## Examples
+
+[`examples/`](./examples/README.md) has one runnable file per thing this does that Express does not:
+the cluster option, `app.ws()`, socket.io through `attachApp`, the pre-compressed twins,
+`express.compression()`, `express.serverTiming()`, TLS through `uwsOptions`, the PROXY protocol,
+what `listen()` decided about each route, and the app answering as an `http.Server`. What an
+Express application already does is documented by Express and is not repeated there.
+
+```sh
+cd examples
+npm install
+node websocket.js
+```
+
 ## Working on Fulmine
 
 How to run the suites, what each of them is for, and how to write a comparison test:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.9.0",
+    "version": "5.11.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -29,9 +29,7 @@
         "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",
-        "demo:start": "npm --prefix demo install && npm --prefix demo start",
-        "demo:deploy": "cd demo && fly deploy",
-        "demo:logs": "fly logs --app fulmine-demo"
+        "examples:install": "npm --prefix examples install"
     },
     "engines": {
         "node": ">=22"

package/src/application.js

@@ -25,6 +25,7 @@ const {
     compileTrust,
     createETagGenerator,
     fastQueryParse,
+    durationSetting,
     NullObject
 } = require("./utils.js");
 const parseQuery = require("./parse-query.js");
@@ -379,6 +380,9 @@ class Application extends Router {
                 configurable: true,
                 value: false
             });
+        } else if (key === "stat cache") {
+            // compiled here so the read path is a number and not a duration to parse per request
+            this.settings["stat cache ms"] = durationSetting(value, "stat cache");
         } else if (key === "query parser") {
             if (value === "extended") {
                 this.settings["query parser fn"] = fastQueryParse;

package/src/cli.js

@@ -304,7 +304,40 @@ function walk(node, visit) {
 const DEFAULT_ENTRIES = ["server.js", "app.js", "index.js", "src/server.js", "src/app.js", "src/index.js"];
 
 /**
- * The file to load, from the argument, or from package.json's main, or from the usual names.
+ * The file a start script runs, when it runs node on one.
+ *
+ * "main" is about what a package exports, and a service usually exports nothing: the entry of a
+ * deployed application is far more often the one written here, which is also the only place that
+ * knows about a src/ or a bin/ the usual names do not cover.
+ *
+ * @param {unknown} script the "start" script, as package.json wrote it
+ * @returns {string|null}
+ */
+function entryFromScript(script) {
+    if (typeof script !== "string") {
+        return null;
+    }
+    const words = script.split(/\s+/).filter(Boolean);
+    if (!/^(node|nodejs)$/.test(path.basename(words[0] ?? "", ".exe"))) {
+        // ts-node, nodemon, a shell pipeline: what that runs is not a file this can load
+        return null;
+    }
+    for (const word of words.slice(1)) {
+        if (word.startsWith("-")) {
+            continue; // --env-file=.env, --watch, and the rest of node's own flags
+        }
+        const candidate = path.resolve(word);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+        break; // the first thing that is not a flag is the file, and it is not there
+    }
+    return null;
+}
+
+/**
+ * The file to load, from the argument, from package.json's main or start script, or from the
+ * usual names.
  *
  * @param {string|undefined} given
  * @returns {string|null}
@@ -319,6 +352,12 @@ function findEntry(given) {
         if (pkg.main && fs.existsSync(path.resolve(pkg.main))) {
             return path.resolve(pkg.main);
         }
+        // a main that names a file nobody built, dist/server.js in a TypeScript project, is worth
+        // no more than no main at all
+        const started = entryFromScript(pkg.scripts?.start);
+        if (started) {
+            return started;
+        }
     } catch {
         // no package.json, or one that will not parse: the usual names are still worth trying
     }
@@ -331,6 +370,57 @@ function findEntry(given) {
     return null;
 }
 
+/**
+ * Every build of this library the application could load, as the prototype that owns listen().
+ *
+ * The command runs from its own copy, and the application loads whichever one resolves from its
+ * own directory. That is usually the same file and sometimes is not: a global install, an
+ * `npx fulmine.js@version`, a workspace that hoisted a second copy, or the `express` name pointing
+ * here through an override. Patching only this command's copy leaves the application's own listen()
+ * to bind the port, and the command then reports that the file built nothing.
+ *
+ * An app is a callable, so its own prototype is not the one that carries the methods: walk up to
+ * whichever link owns listen.
+ *
+ * @param {string} entry
+ * @returns {any[]} the prototypes to stub, this command's copy first
+ */
+function listenOwners(entry) {
+    const builds = new Set([require("./index.js")]);
+    for (const specifier of [TO, FROM]) {
+        try {
+            builds.add(require(require.resolve(specifier, { paths: [path.dirname(entry), process.cwd()] })));
+        } catch {
+            // not installed next to the application, or not resolvable from there
+        }
+    }
+
+    const owners = [];
+    for (const build of builds) {
+        if (typeof build !== "function") {
+            continue;
+        }
+        let app;
+        try {
+            app = build();
+        } catch {
+            continue; // not an application factory, or one that will not build without arguments
+        }
+        // real express resolves under the same two names, and has none of this to stub
+        if (typeof app._compileOptimizedRoutes !== "function") {
+            continue;
+        }
+        let proto = Object.getPrototypeOf(app);
+        while (proto && !Object.prototype.hasOwnProperty.call(proto, "listen")) {
+            proto = Object.getPrototypeOf(proto);
+        }
+        if (proto && !owners.includes(proto)) {
+            owners.push(proto);
+        }
+    }
+    return owners;
+}
+
 /**
  * The applications a file builds, compiled but not listening.
  *
@@ -348,42 +438,38 @@ function loadApps(argv, command) {
     if (!entry) {
         console.error(
             `Nothing to ${command}: name the file that builds the application, or run this from a
-` + "directory whose package.json main points at it."
+` + "directory whose package.json main or start script points at it."
         );
         return null;
     }
 
-    // the same module instance the application will load, so patching this prototype patches the
-    // application it builds. An app is a callable, so its own prototype is not the one that carries
-    // the methods: walk up to whichever link owns listen
-    const express = require("./index.js");
-    let proto = Object.getPrototypeOf(express());
-    while (proto && !Object.prototype.hasOwnProperty.call(proto, "listen")) {
-        proto = Object.getPrototypeOf(proto);
-    }
-    if (!proto) {
+    const owners = listenOwners(entry);
+    if (owners.length === 0) {
         console.error("This build of fulmine has no listen() to stand in for, which should not happen.");
         return null;
     }
 
     const listened = [];
-    const realListen = proto.listen;
-    proto.listen = function stubbedListen() {
-        this._compileOptimizedRoutes();
-        listened.push(this);
-        return this;
-    };
+    const real = owners.map((proto) => proto.listen);
+    for (const proto of owners) {
+        proto.listen = function stubbedListen() {
+            this._compileOptimizedRoutes();
+            listened.push(this);
+            return this;
+        };
+    }
+    const restore = () => owners.forEach((proto, i) => (proto.listen = real[i]));
 
     try {
         require(entry);
     } catch (e) {
         const error = /** @type {any} */ (e);
-        proto.listen = realListen;
+        restore();
         console.error(`${path.relative(process.cwd(), entry)} could not be loaded:
 ${error.stack ?? error}`);
         return null;
     }
-    proto.listen = realListen;
+    restore();
 
     let apps = listened;
     if (apps.length === 0) {
@@ -400,7 +486,10 @@ ${error.stack ?? error}`);
     if (apps.length === 0) {
         console.error(
             `${path.relative(process.cwd(), entry)} built no application: it neither called listen() nor
-` + "exported one. Point this at the file that does."
+` +
+                `exported one. Point this at the file that does. A listen() that runs after an await is
+` +
+                "not seen either, since this loads the file rather than waiting on what it started."
         );
         return null;
     }

package/src/declarative.js

@@ -18,7 +18,7 @@ limitations under the License.
 */
 
 const acorn = require("acorn");
-const { stringify, withDefaultCharset, withUtf8Charset } = require("./utils.js");
+const { stringify, withDefaultCharset, withUtf8Charset, contentTypeFor } = require("./utils.js");
 // H3App, DeclarativeResponse and _cfg all exist at runtime but are missing from the
 // declaration file the package ships, so the module is read through a loose alias
 const uWS = require("uWebSockets.js");
@@ -27,8 +27,28 @@ const statuses = require("statuses");
 
 const parser = acorn.Parser;
 
-const allowedResMethods = ["set", "header", "setHeader", "sendStatus", "status", "send", "json", "end", "append"];
+const allowedResMethods = [
+    "set",
+    "header",
+    "setHeader",
+    "type",
+    "contentType",
+    "sendStatus",
+    "status",
+    "send",
+    "json",
+    "end",
+    "append"
+];
+
 const allowedIdentifiers = ["query", "params", ...allowedResMethods];
+
+/** What res.type(x) sets the content type to, which is a lookup on a literal. */
+const typeValueOf = (type) => (type.indexOf("/") === -1 ? contentTypeFor(type) : type);
+
+// what one instruction of a declarative response can carry, since uWS writes its length as a u16
+const MAX_INSTRUCTION_LENGTH = 65535;
+
 // the three that write a body, of which only one may appear
 const bodyMethods = new Set(["send", "json", "end"]);
 // and the four that finish the response, after which nothing a handler does is observable
@@ -84,6 +104,23 @@ function collectNodeTypes(node, types) {
     }
 }
 
+/**
+ * The key a property writes, when it is one this can read: a plain name or a literal, never
+ * computed and never a getter or a spread.
+ *
+ * @param {any} property
+ * @returns {string|null} null when the shape is not one of those
+ */
+function literalKeyOf(property) {
+    if (property.type !== "Property" || property.computed || property.kind !== "init") {
+        return null;
+    }
+    if (property.key.type === "Identifier") {
+        return property.key.name;
+    }
+    return property.key.type === "Literal" ? String(property.key.value) : null;
+}
+
 /**
  * The value a literal expression denotes, for the shapes whose value is known at registration
  * time. Anything else throws, which the catch around the whole compiler turns into ordinary
@@ -403,34 +440,62 @@ module.exports = function compileDeclarative(cb, app) {
 
         // get headers
         for (const call of callExprs) {
+            const isType = call.obj.propertyName === "type" || call.obj.propertyName === "contentType";
             if (
                 call.obj.propertyName === "header" ||
                 call.obj.propertyName === "setHeader" ||
-                call.obj.propertyName === "set"
+                call.obj.propertyName === "set" ||
+                isType
             ) {
-                if (call.arguments[0].type !== "Literal" || call.arguments[1].type !== "Literal") {
-                    return false;
-                }
-                // String() at capture: a numeric literal would reach uWS's writeHeader as itself,
-                // and uWS refuses anything that is not a string
-                let [header, value] = [call.arguments[0].value, String(call.arguments[1].value)];
-                const name = String(header).toLowerCase();
-                // res.set charsets a content-type and res.setHeader does not, since the second is
-                // node's and node does not know what a media type is
-                if (call.obj.propertyName !== "setHeader" && name === "content-type") {
-                    value = withDefaultCharset(value);
-                }
-                const index = headers.findIndex((entry) => String(entry[0]).toLowerCase() === name);
-                if (index === -1) {
-                    headers.push([header, value]);
+                // type() is set("content-type", ...) with the media type looked up first, and
+                // set() takes a whole object as well, which is one set() per pair. setHeader is
+                // node's and throws on anything but a string, so it is not offered the object.
+                let pairs;
+                if (isType) {
+                    if (call.arguments[0].type !== "Literal") {
+                        return false;
+                    }
+                    pairs = [["content-type", typeValueOf(String(call.arguments[0].value))]];
+                } else if (call.arguments.length === 1 && call.obj.propertyName !== "setHeader") {
+                    if (call.arguments[0].type !== "ObjectExpression") {
+                        return false;
+                    }
+                    pairs = [];
+                    for (const property of call.arguments[0].properties) {
+                        const key = literalKeyOf(property);
+                        if (key === null || property.value.type !== "Literal") {
+                            return false;
+                        }
+                        pairs.push([key, String(property.value.value)]);
+                    }
                 } else {
-                    // in place, so the header keeps the position it was first given
-                    headers[index][1] = value;
-                    // set replaces the header outright, so any further value append left there
-                    // goes with it. Replacing only the first left the response carrying both.
-                    for (let i = headers.length - 1; i > index; i--) {
-                        if (String(headers[i][0]).toLowerCase() === name) {
-                            headers.splice(i, 1);
+                    if (call.arguments[0].type !== "Literal" || call.arguments[1]?.type !== "Literal") {
+                        return false;
+                    }
+                    // String() at capture: a numeric literal would reach uWS's writeHeader as
+                    // itself, and uWS refuses anything that is not a string
+                    pairs = [[call.arguments[0].value, String(call.arguments[1].value)]];
+                }
+
+                for (let [header, value] of pairs) {
+                    const name = String(header).toLowerCase();
+                    // res.set charsets a content-type and res.setHeader does not, since the second
+                    // is node's and node does not know what a media type is
+                    if (call.obj.propertyName !== "setHeader" && name === "content-type") {
+                        value = withDefaultCharset(value);
+                    }
+                    const index = headers.findIndex((entry) => String(entry[0]).toLowerCase() === name);
+                    if (index === -1) {
+                        headers.push([header, value]);
+                    } else {
+                        // in place, so the header keeps the position it was first given
+                        headers[index][1] = value;
+                        // set replaces the header outright, so any further value append left there
+                        // goes with it. Replacing only the first left the response carrying both.
+                        for (let i = headers.length - 1; i > index; i--) {
+                            if (String(headers[i][0]).toLowerCase() === name) {
+                                headers.splice(i, 1);
+                            }
                         }
                     }
                 }
@@ -656,14 +721,15 @@ module.exports = function compileDeclarative(cb, app) {
         // the same two the ordinary path seeds every response with. Without them a route answered
         // different headers depending only on whether it happened to be compilable, which is worse
         // than either choice on its own, and a client had no idle timeout to go on.
+        const advertise = app.get("connection headers") !== false;
         const connection = headers.find((header) => header[0].toLowerCase() === "connection");
-        if (!connection) {
+        if (!connection && advertise) {
             decRes = decRes.writeHeader("connection", "keep-alive");
         }
         // not on a connection the handler is closing: Keep-Alive describes one that is staying
         // open, and the ordinary path leaves it out for the same reason
         const closing = typeof connection?.[1] === "string" && connection[1].toLowerCase() === "close";
-        if (!closing && !headers.some((header) => header[0].toLowerCase() === "keep-alive")) {
+        if (advertise && !closing && !headers.some((header) => header[0].toLowerCase() === "keep-alive")) {
             decRes = decRes.writeHeader("keep-alive", "timeout=10");
         }
 
@@ -702,15 +768,23 @@ module.exports = function compileDeclarative(cb, app) {
             }
         }
 
-        // No Content-Length here, and it is not an oversight. uWS writes a DeclarativeResponse
-        // with Transfer-Encoding: chunked and adds that header itself, so setting Content-Length
-        // as well produces a response carrying both, which is invalid and which clients reject
-        // outright. Every declarative response is therefore chunked, where Express always sends
-        // a length. Changing it means changing uWS.
+        // No Content-Length header here: uWS writes the framing itself, and a response carrying
+        // both is invalid. Which framing it writes is decided at the end of this function.
         if (app.get("x-powered-by")) {
             decRes = decRes.writeHeader("x-powered-by", "Fulmine");
         }
 
+        // A body that is literal all the way through goes out as one end(), which is what makes
+        // uWS frame it with a Content-Length, as Express does. A part interpolated from the
+        // request has no length until the request arrives, so those stay a write each and uWS
+        // chunks them.
+        const literal = body.every((part) => part.type === "text")
+            ? body.map((part) => String(part.value)).join("")
+            : null;
+        if (literal && literal.length <= MAX_INSTRUCTION_LENGTH) {
+            return decRes.end(literal);
+        }
+
         for (const bodyPart of body) {
             if (bodyPart.type === "text" && String(bodyPart.value).length) {
                 decRes = decRes.write(String(bodyPart.value));

package/src/middlewares.js

@@ -37,6 +37,7 @@ const {
     memoizeByString,
     containsDotFile,
     negotiateEncoding,
+    cachedStat,
     ENCODING_BR,
     ENCODING_GZIP
 } = require("./utils.js");
@@ -329,9 +330,10 @@ function twinsOf(filePath, ttl) {
  * @param {string} filePath absolute path of the file that was asked for
  * @param {string|undefined} accept the request's Accept-Encoding
  * @param {number} ttl how long the twin cache holds an answer, 0 to ask the disk every time
+ * @param {number} statTtl how long the twin's own stat stays good, from the "stat cache" setting
  * @returns {{suffix: string, encoding: string, stat: import("fs").Stats}|undefined}
  */
-function pickPrecompressed(filePath, accept, ttl) {
+function pickPrecompressed(filePath, accept, ttl, statTtl) {
     if (!accept || !hasTwins(filePath.slice(filePath.lastIndexOf(".")))) {
         return undefined;
     }
@@ -346,7 +348,7 @@ function pickPrecompressed(filePath, accept, ttl) {
         }
         if (known === undefined || known[variant.encoding === "br" ? "br" : "gz"] !== false) {
             try {
-                const stat = fs.statSync(filePath + variant.suffix);
+                const stat = cachedStat(filePath + variant.suffix, statTtl);
                 if (!stat.isDirectory()) {
                     if (known !== undefined) known[variant.encoding === "br" ? "br" : "gz"] = true;
                     return { suffix: variant.suffix, encoding: variant.encoding, stat };
@@ -532,14 +534,19 @@ function serveStatic(root, options) {
         // decides those is the stat of the thing that was asked for.
         let twin;
         if (options.preCompressed && !rawPath.endsWith("/") && !req.endsWithSlash) {
-            twin = pickPrecompressed(filePath, req.headers["accept-encoding"], twinTtl);
+            twin = pickPrecompressed(
+                filePath,
+                req.headers["accept-encoding"],
+                twinTtl,
+                req.app.settings["stat cache ms"]
+            );
             if (twin) {
                 stat = twin.stat;
             }
         }
         try {
             if (stat === undefined) {
-                stat = fs.statSync(statTarget);
+                stat = cachedStat(statTarget, req.app.settings["stat cache ms"]);
             }
         } catch (err) {
             // the one to report when nothing is found: send hands each failed attempt to the next
@@ -647,7 +654,9 @@ function serveStatic(root, options) {
             // told. Said before the lookup, because it is true even when there is no variant
             res.vary("Accept-Encoding");
             // already found before the stat below, on the ordinary path
-            const variant = twin ?? pickPrecompressed(filePath, req.headers["accept-encoding"], twinTtl);
+            const variant =
+                twin ??
+                pickPrecompressed(filePath, req.headers["accept-encoding"], twinTtl, req.app.settings["stat cache ms"]);
             if (variant) {
                 _path += variant.suffix;
                 stat = variant.stat;

package/src/response.js

@@ -37,6 +37,7 @@ const {
     httpError,
     contentTypeFor,
     statTag,
+    cachedStat,
     NullObject
 } = require("./utils.js");
 const { Writable } = require("stream");
@@ -289,12 +290,15 @@ module.exports = class Response extends LazyWritable {
         this.writingChunk = false;
         // timeout=10 is uWS's idle timeout. On the node shim the hosting server enforces its own
         // keepAliveTimeout, so node is left to write the truthful Connection and Keep-Alive itself.
-        this.headers = res._nodeRes
-            ? {}
-            : {
-                  connection: "keep-alive",
-                  "keep-alive": "timeout=10"
-              };
+        // "connection headers" off advertises neither, which Express always does: see below for
+        // the one this still writes.
+        this.headers =
+            res._nodeRes || app.settings["connection headers"] === false
+                ? {}
+                : {
+                      connection: "keep-alive",
+                      "keep-alive": "timeout=10"
+                  };
         // the client asked for the connection to be closed, and uWS closes it, so saying otherwise
         // would be telling the client something the transport contradicts. A declarative response
         // cannot do this, being written once and not per request.
@@ -1045,7 +1049,7 @@ module.exports = class Response extends LazyWritable {
         let stat = options._stat;
         if (!stat) {
             try {
-                stat = fs.statSync(fullpath);
+                stat = cachedStat(fullpath, this.app.settings["stat cache ms"]);
             } catch (err) {
                 // the fs error itself, carrying its errno and path, with send's status written on
                 // it: a missing file is the request's 404, an unreadable one is the server's 500

package/src/types.d.ts

@@ -77,6 +77,18 @@ declare module "fulmine.js" {
             function expectDeclarative(app: Fulmine, patterns: string | string[]): void;
         }
 
+        // Server-Timing, carrying how the request was routed. Express has no such middleware, so
+        // like compression() there is nothing to re-export
+        interface ServerTimingOptions {
+            /** Whether to report how the request was routed. Default true. */
+            routing?: boolean;
+            /** Whether to report the time up to the head. Default true. */
+            total?: boolean;
+            /** What the total is called. Default "total". */
+            name?: string;
+        }
+        export function serverTiming(options?: ServerTimingOptions): e.RequestHandler;
+
         export function compression(options?: CompressionOptions): e.RequestHandler;
         export namespace compression {
             /** The default filter: any compressible content type. */
@@ -184,3 +196,15 @@ declare module "fulmine.js" {
 
     export = express;
 }
+
+// What express.serverTiming() hangs on the response. Express's own Response extends this global
+// interface, which is how a middleware adds to it. They are written per request rather than on the
+// prototype, so a route only has them where that middleware ran, which the optional marks say.
+declare namespace Express {
+    interface Response {
+        /** Adds a mark of your own. A mark with only a description is a legal entry. */
+        timing?(name: string, duration?: number, description?: string): this;
+        /** Times a piece of work under a name. A promise is timed to where it settles. */
+        time?<T>(name: string, work: () => T): T;
+    }
+}

package/src/utils.js

@@ -24,6 +24,8 @@ const qs = require("qs");
 const parseQuery = require("./parse-query.js");
 const crypto = require("crypto");
 const statuses = require("statuses");
+const ms = require("ms");
+const fs = require("fs");
 const { Stats } = require("fs");
 
 const EMPTY_REGEX = new RegExp(``);
@@ -945,12 +947,71 @@ const defaultSettings = {
     // The native µWS router matches bytes, so the compiler in _compileOptimizedRoutes only hands
     // it routes whose earlier siblings it can prove agree under either case rule.
     "declarative responses": true,
+    // off: with a window set, the size and mtime of a file served by sendFile are remembered for
+    // it, which is one syscall less per request and a file that can be served as it was a moment
+    // ago. "stat cache ms" is the window in milliseconds, compiled from it by set()
+    "stat cache": false,
+    "stat cache ms": 0,
     // off, and it is a security setting rather than a compatibility one: with it on, req.ip is the
     // address a PROXY protocol preamble declared. µWS reads that preamble from any client, so this
     // belongs only to a server nothing can reach except the proxy in front of it. See Request#_readRawIp
-    "trust proxy protocol": false
+    "trust proxy protocol": false,
+    // on, because Express sends both on every response. Off, nothing is advertised and only a
+    // connection that is closing says so, which is fewer bytes and one header write less
+    "connection headers": true
 };
 
+// What a file's stat was, for as long as "stat cache" says it stays good. Size and mtime only,
+// never a body, and only when a window was asked for: nginx's open_file_cache makes the same
+// trade, and the worst a stale entry does is answer with the file as it was a moment ago.
+const statCache = new Map();
+const STAT_CACHE_LIMIT = 4096;
+
+/**
+ * The stat of a path, from the cache when a window was asked for and it is still good.
+ *
+ * A failure is never remembered: a file that is not there is not the hot path, and a file that
+ * appears has to be seen at once.
+ *
+ * @param {string} file
+ * @param {number} ttl milliseconds an answer stays good, 0 to ask the disk every time
+ * @returns {import("fs").Stats}
+ */
+function cachedStat(file, ttl) {
+    if (ttl <= 0) {
+        return fs.statSync(file);
+    }
+    const now = Date.now();
+    const known = statCache.get(file);
+    if (known !== undefined && known.until > now) {
+        return known.stat;
+    }
+    const stat = fs.statSync(file);
+    // cleared rather than evicted one by one, as twinsOf does: a directory big enough to reach
+    // the limit is being served by something other than an application server anyway
+    if (statCache.size >= STAT_CACHE_LIMIT) {
+        statCache.clear();
+    }
+    statCache.set(file, { stat, until: now + ttl });
+    return stat;
+}
+
+/**
+ * A duration setting as milliseconds: false is off, a string is read by ms, a number is itself.
+ *
+ * @param {any} value
+ * @param {string} name for the error, which names the setting the application wrote
+ * @returns {number}
+ */
+function durationSetting(value, name) {
+    const parsed =
+        value === false || value === undefined ? 0 : typeof value === "string" ? ms(/** @type {any} */ (value)) : value;
+    if (typeof parsed !== "number" || !(parsed >= 0)) {
+        throw new TypeError(`${name} must be a duration`);
+    }
+    return parsed;
+}
+
 /**
  * Turns whatever "trust proxy" was set to into the function proxy-addr wants: a predicate saying
  * whether the address at hop i is trusted. true trusts everything, a number trusts that many hops,
@@ -1417,6 +1478,8 @@ const NullObject = /** @type {any} */ (function () {});
 NullObject.prototype = Object.create(null);
 
 module.exports = {
+    cachedStat,
+    durationSetting,
     removeDuplicateSlashes,
     patternToRegex,
     escapePathLiteral,

package/src/verify.js

@@ -38,6 +38,12 @@ const path = require("path");
 // file and then fails on a symbol, which is a worse error than not finding it at all.
 const MIN_GLIBC = "2.38";
 
+// The oldest node this package runs on, and the image to name when something older is found. Both
+// follow engines rather than being written out here, so raising it moves every message with it.
+const MIN_NODE = require("../package.json").engines.node.replace(/[^0-9.]/g, "");
+const MIN_NODE_MAJOR = MIN_NODE.split(".")[0];
+const SWAP_IMAGE = `node:${MIN_NODE_MAJOR}-trixie-slim`;
+
 // What a project may carry that needs a different API here rather than none. Everything that just
 // works, and everything that only wants a faster built-in, is `npx fulmine migrate`'s business.
 const NEEDS_A_LOOK = {
@@ -139,7 +145,7 @@ function checkLibc(platform, glibc) {
         return result(
             "no",
             `glibc ${glibc}`,
-            `the binaries need ${MIN_GLIBC} or newer. A newer base image is the fix: node:22-trixie-slim.`
+            `the binaries need ${MIN_GLIBC} or newer. A newer base image is the fix: ${SWAP_IMAGE}.`
         );
     }
     return result("ok", `glibc ${glibc}`);
@@ -238,13 +244,13 @@ function checkDockerfiles(dir) {
             const where = `${name}: ${image}`;
             if (/alpine|musl/i.test(image)) {
                 results.push(
-                    result("no", where, "musl, and there is no musl build: node:22-trixie-slim is the closest swap.")
+                    result("no", where, `musl, and there is no musl build: ${SWAP_IMAGE} is the closest swap.`)
                 );
                 continue;
             }
             const node = /^node:(\d+)/.exec(image);
-            if (node && Number(node[1]) < 22) {
-                results.push(result("no", where, `this package needs node 22 or newer: node:22-trixie-slim.`));
+            if (node && Number(node[1]) < Number(MIN_NODE_MAJOR)) {
+                results.push(result("no", where, `this package needs node ${MIN_NODE_MAJOR} or newer: ${SWAP_IMAGE}.`));
                 continue;
             }
             results.push(result("ok", where));