fulmine.js 5.7.0 → 5.9.0

package/README.md

@@ -18,10 +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
 ```
 
 See [Migrating](#migrating) for what it handles and what it deliberately does not.
@@ -128,6 +130,23 @@ It also names the middlewares it found that have a faster one built in here, `co
 `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
+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
+years ago: each one fails at require time, in a container, with a message about a missing module.
+This says so in thirty seconds, and exits non-zero when something would stop the start.
+
+```text
+  ok    Node 22.15.0
+  ok    glibc 2.39
+  ok    µWebSockets.js binary for linux x64, node ABI 127
+  NO    Dockerfile: node:20-alpine
+        musl, and there is no musl build: node:22-trixie-slim is the closest swap.
+  note  socket.io needs a different API here
+        attach it with io.attachApp(app.uwsApp), not io.attach(server)
+```
+
 ### Angular SSR
 
 The `server.ts` that `ng add @angular/ssr` generates is an ordinary Express application, so the same
@@ -229,7 +248,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, not an `http.Server`. There is no node server underneath, so `server.close()`, `server.address()` and anything that attaches itself to a real `http.Server` need a look. `app.close()`, `app.address()` and `app.listening` are there and do what you would expect.
+- `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`.
 - `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`.
@@ -374,6 +393,40 @@ Worth changing, if these are routes that carry traffic
 
 It loads the application with `listen()` replaced by the half that compiles the routes, so nothing binds a port and the listen callback does not run: profiling a running service does not start a second copy of it. There is no score, on purpose. A percentage of routes is not a percentage of traffic, and an application with a thousand cold routes and one hot one that fell back would score well and serve badly.
 
+The same verdicts are readable from a test, which is where they belong for the routes that carry the traffic. A route stays on the fast path only while it stays eligible, and nothing complains when it stops: the answer is still correct, only slower, and the commit that did it is found weeks later.
+
+```js
+const { expectNative, expectDeclarative, routeReport } = require("fulmine.js").testing;
+
+expectNative(app, ["/api/*", "GET /health"]); // throws, naming the route and the reason
+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.
+
+`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.
+
+```text
+GET /api/items/:id
+
+  route      native (µWS matched /api/items/:x and dispatched by method)
+  headers    copied out of µWS (something in the chain reads them)
+  query      parsed when something asks for it
+  chain      2 layer(s), 1 mounted layer(s) in front of it
+    logger                readable at registration, reads the query
+    (anonymous)           readable at registration
+  body       read for POST, PUT, PATCH and QUERY, when one is declared
+```
+
+The same verdict reaches the browser, per request, with `express.serverTiming()`:
+
+```text
+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.
+
 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.
 
 3. Do not use `body-parser` module. Instead use built-in `express.text()`, `express.json()` etc.
@@ -393,9 +446,26 @@ app.use(express.compression({ threshold: 1024 }));
 
 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.
 
+9. One node process uses one core, and this is the setting that changes it. `express({ cluster: "auto" })` forks one process per core and each of them binds the same port with µWS's shared flag, which is `SO_REUSEPORT`: every process has its own listening socket and the kernel decides which one gets each connection. Node's own `cluster` cannot do that with an `http.Server`, so the primary holds the socket and passes each accepted connection to a worker over IPC; here the primary is not in the path at all. On a 16-core machine that is close to 16 times the throughput, and no other setting comes near it.
+
+```js
+// "auto" is one worker per usable core: the cgroup quota is read first, so a 2-core container
+// on a 64-core host forks 2 and not 64. A number instead of "auto" says how many.
+const app = express({ cluster: "auto" });
+
+app.get("/", (req, res) => res.send("hello"));
+
+// The whole file runs again in every worker, which is how cluster works: the code above this
+// line runs once per process. The primary only forks, so the callback runs once per worker too,
+// and a worker that dies is replaced.
+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.
+
 ## WebSockets
 
-`app.ws()` registers a WebSocket route, served by µWS itself. There is no `http.Server` underneath, so `http.on("upgrade")` and the libraries built on it do not apply; this is the replacement.
+`app.ws()` registers a WebSocket route, served by µWS itself. The upgrade never reaches node, so `server.on("upgrade")` and the libraries built on it have nothing to hear; this is the replacement.
 
 ```js
 app.ws("/room/:id", {
@@ -429,8 +499,8 @@ If you would rather use the `ws` module's API, [Ultimate WS](https://github.com/
 
 ### socket.io
 
-socket.io normally takes over the upgrade on a node `http.Server`. There isn't one here, so hand it
-the µWS app instead, which socket.io supports natively through `attachApp()`:
+socket.io normally takes over the upgrade on a node `http.Server`. The upgrade here never reaches
+node, so hand it the µWS app instead, which socket.io supports natively through `attachApp()`:
 
 ```js
 const express = require("fulmine.js");
@@ -447,10 +517,14 @@ io.on("connection", (socket) => {
 });
 ```
 
-`attachApp()` works before or after `app.listen()`. What does not work is `new Server(server)` on the
-value `app.listen()` returns: plain HTTP keeps serving, but the WebSocket upgrade fails, because
-that object is not a real `http.Server`. This is covered by `tests/tests/middlewares/socket-io.js`,
-which runs the same file against Express and against Fulmine and compares the output.
+`attachApp()` works before or after `app.listen()`. What does not work is `new Server(app)` on the
+app itself, or on what `app.listen()` returns, which is the same object: socket.io refuses it with
+"You are trying to attach socket.io to an express request handler function", because it checks for a
+function before it checks for a server, and an app here is callable. That refusal is the useful
+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.
 
 ## HTTP/3
 
@@ -519,8 +593,15 @@ In general, basically all features and options are supported. Use the [Express 5
 - ✅ express.json()
 - ✅ express.urlencoded()
 - ✅ express.static()
+-   - ✅ options.index, options.redirect, options.fallthrough, options.extensions
+-   - ✅ options.dotfiles, plus `"ignore_files"`, which is Fulmine's own: it hides a dotfile that is the last segment while letting a dotted directory through
+-   - ✅ options.setHeaders, options.headers
+-   - ✅ options.etag, options.lastModified, options.maxAge, options.immutable, options.cacheControl, options.acceptRanges
+-   - ✅ options.preCompressed, Fulmine's own: serve the `.br` or `.gz` twin on disk, described under [Performance tips](#performance-tips)
 - ✅ express.text()
 - ✅ express.raw()
+- ✅ express.serverTiming(). Fulmine's own: Server-Timing carrying how the request was routed, described under [Performance tips](#performance-tips).
+- ✅ express.testing. Fulmine's own: `expectNative`, `expectDeclarative` and `routeReport`, described under [Performance tips](#performance-tips).
 - ✅ express.compression(). Fulmine's own, since Express has none: it is the [compression](https://npmjs.com/package/compression) module's options and behaviour built in, described under [Performance tips](#performance-tips).
 - 🚧 express.request (this is not a constructor but a prototype for replacing methods)
 - 🚧 express.response (this is not a constructor but a prototype for replacing methods)
@@ -554,6 +635,11 @@ In general, basically all features and options are supported. Use the [Express 5
 - ✅ OPTIONS method
 - ✅ QUERY method
 
+What `listen()` hands back is the app, and it answers as an `http.Server` so the shutdown wrappers
+recognise it: `app.close()`, `app.address()`, `app.listening`, `app.getConnections()`, `app.ref()`,
+`app.unref()`, `app.setTimeout()` and the `keepAliveTimeout` family. See
+[Differences from Express](#differences-from-express) for what is behind them and what is not.
+
 ### Application settings
 
 - ✅ case sensitive routing
@@ -730,4 +816,8 @@ Any Express view engine should work. Here's list of engines we include in our te
 ## Working on Fulmine
 
 How to run the suites, what each of them is for, and how to write a comparison test:
-[`CONTRIBUTING.md`](./CONTRIBUTING.md).
+[`CONTRIBUTING.md`](./CONTRIBUTING.md). What is expected of everyone taking part:
+[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
+
+Found something exploitable? Report it privately rather than in an issue, and see
+[`SECURITY.md`](./SECURITY.md) for what is in scope and what to expect.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.7.0",
+    "version": "5.9.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -28,7 +28,7 @@
         "benchmark:profile": "node benchmark/profile.js",
         "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 93 --branches 88 --functions 92 --lines 93",
+        "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"

package/src/application.js

@@ -36,6 +36,8 @@ const os = require("os");
 const { Worker } = require("worker_threads");
 const cluster = require("cluster");
 const { registerWebSocketRoutes } = require("./websocket.js");
+const { addServerMembers } = require("./server-shape.js");
+const { workerCount, forkWorkers, isSupervising, becomeSupervisor } = require("./cluster.js");
 
 const cpuCount = os.cpus().length;
 
@@ -102,8 +104,9 @@ class Application extends Router {
     /**
      * @param {object} [settings] the options express() takes. uwsOptions goes to uWS and decides
      *   between an HTTP, an HTTPS and an HTTP/3 server; threads sizes the file-reading pool, and 0
-     *   turns it off; uwsApp adopts an existing uWS app instead of making one. Everything else is
-     *   an application setting and lands next to the defaults.
+     *   turns it off; cluster forks one process per core over the same port; uwsApp adopts an
+     *   existing uWS app instead of making one. Everything else is an application setting and
+     *   lands next to the defaults.
      */
     constructor(settings = new NullObject()) {
         super(settings);
@@ -113,6 +116,13 @@ class Application extends Router {
         if (typeof settings.threads !== "number") {
             settings.threads = cpuCount > 1 ? 1 : 0;
         }
+        // how many processes listen() should fork, counted here so a setting nobody can read is a
+        // throw where the application is written and not where it is started. Saying it here also
+        // settles it for the whole process before any app has listened, see becomeSupervisor
+        this._clusterWorkers = workerCount(settings.cluster);
+        if (this._clusterWorkers > 0 && cluster.isPrimary) {
+            becomeSupervisor();
+        }
         if (settings.uwsApp) {
             this.uwsApp = settings.uwsApp;
         } else if (settings.http3) {
@@ -219,6 +229,9 @@ class Application extends Router {
         // the uWS listen socket, and the responses being served right now: close() stops the
         // first and waits for the second, the way node's server.close() does
         this._listenSocket = undefined;
+        // the fork supervisor, in the primary of a clustered app and nowhere else
+        /** @type {{stop: () => void}|undefined} */
+        this._clusterHandle = undefined;
         // readSmallFile's cache and its in-flight reads, see the method
         this._fileCache = new Map();
         this._fileCacheBytes = 0;
@@ -528,6 +541,21 @@ class Application extends Router {
      * @returns {this} the app, which doubles as the server handle
      */
     listen(port, host, backlog, callback) {
+        // With { cluster } the primary has nothing to bind. Each worker binds this same port with
+        // µWS's shared flag, which is SO_REUSEPORT, so the kernel hands each connection to one of
+        // them and the primary is not in the path at all: it forks, replaces a worker that dies,
+        // and nothing else. Everything below this runs in the workers, listen callback included,
+        // so it runs once per worker rather than once.
+        //
+        // The test is the process and not this app: a second app on a TLS port, one without a
+        // cluster setting of its own, would otherwise take that port here, exclusively, and every
+        // worker would fail on it.
+        if (cluster.isPrimary && isSupervising()) {
+            if (this._clusterWorkers > 0 && !this._clusterHandle) {
+                this._clusterHandle = forkWorkers(this._clusterWorkers);
+            }
+            return this;
+        }
         this._compileOptimizedRoutes();
         // before the catch-all: µWS sends an upgrade to the websocket route even when a
         // catch-all covers the same path, so the two coexist and the order is only tidiness
@@ -798,6 +826,18 @@ class Application extends Router {
      * @returns {this} the app, for chaining
      */
     close(callback) {
+        // the primary of a clustered app never bound anything, so closing it means stopping the
+        // workers. They are killed rather than drained: each one holds its own listening socket
+        // and drains itself when the signal reaches it
+        if (this._clusterHandle) {
+            this._clusterHandle.stop();
+            this._clusterHandle = undefined;
+            if (callback) {
+                this.once("close", () => callback());
+            }
+            process.nextTick(() => this.emit("close"));
+            return this;
+        }
         const wasListening = this.listening;
         this.listening = false;
         // in Express the close callback is nothing more than the first 'close' listener, and a
@@ -871,3 +911,7 @@ module.exports = function (options) {
 // the class itself, so index.js can expose its prototype as express.application does. Adding a
 // method to that prototype adds it to every app, which is what the property is for.
 module.exports.Application = Application;
+
+// and what makes an application answer as an http.Server, since that is what a library handed the
+// result of listen() looks for. See server-shape.js for what is answered and what is not.
+addServerMembers(Application.prototype);

package/src/cli.js

@@ -26,10 +26,18 @@ limitations under the License.
 // Prints what listen() worked out about each route and normally keeps to itself: which ones µWS
 // answers on its own, which ones fell back to the ordinary router and why, and which ones were
 // compiled all the way down to a response written at startup.
+//
+// npx fulmine verify [dir]
+//
+// Whether this machine and this project can run it at all: the node version, the C library, the
+// µWebSockets.js binary, the base image a Dockerfile names. See src/verify.js.
 
 const fs = require("fs");
 const path = require("path");
 const acorn = require("acorn");
+// the same walk express.testing asserts on, so the command and the assertions cannot drift
+const { collectRoutes } = require("./testing.js");
+const { verify } = require("./verify.js");
 
 const FROM = "express";
 const TO = "fulmine.js";
@@ -53,9 +61,10 @@ const TYPESCRIPT_EXTENSIONS = new Set([".ts", ".mts", ".cts", ".tsx"]);
 const DIFFERENCES = [
     [
         "app.listen() returns the app, not an http.Server",
-        "There is no node http server underneath, so anything doing `const server = app.listen(...)` and then\n" +
-            "reaching for server.close(), server.address() or attaching a websocket library to it needs a look.\n" +
-            "app.close(), app.address() and app.listening exist and do what you would expect."
+        "The app answers as one: instanceof http.Server is true, and close(), address(), listening,\n" +
+            "getConnections(), ref(), unref() and setTimeout() are all there. What is missing is the plumbing\n" +
+            "that carries node sockets, so nothing emits connection, request or upgrade, and a library that\n" +
+            "serves its own protocol on the socket, socket.io being the usual one, wants app.uwsApp instead."
     ],
     [
         "an HTTPS server is configured through express(), not https.createServer()",
@@ -323,45 +332,25 @@ function findEntry(given) {
 }
 
 /**
- * Every route of an application and of the routers under it, each with the router it belongs to
- * and the path it answers from the outside.
- *
- * @param {any} router
- * @param {string} prefix
- * @param {any[]} [into]
- * @returns {any[]}
- */
-function collectRoutes(router, prefix, into = []) {
-    for (const route of router._routes ?? []) {
-        const full = prefix + (typeof route.path === "string" ? route.path : String(route.pattern)) || "/";
-        into.push({ route, full });
-        const mounted = route.callbacks?.[0];
-        if (mounted && Array.isArray(mounted._routes)) {
-            collectRoutes(mounted, typeof route.path === "string" ? prefix + route.path : prefix, into);
-        }
-    }
-    return into;
-}
-
-/**
- * Loads an application without letting it listen, and prints what compiling its routes decided.
+ * The applications a file builds, compiled but not listening.
  *
  * listen() is where the routes are compiled and also where the port is bound, and only the first
- * of those is wanted here: an application that answered on its port while being profiled would be
- * a surprise, and a second copy of a running service is worse than a surprise. So listen is
- * replaced by the half that matters. The callback it was given is not run, for the same reason.
+ * of those is wanted here: an application that answered on its port while being read would be a
+ * surprise, and a second copy of a running service is worse than a surprise. So listen is replaced
+ * by the half that matters, and the callback it was given is not run for the same reason.
  *
  * @param {string[]} argv
- * @returns {number} exit code
+ * @param {string} command the word for the message when there is nothing to load
+ * @returns {{apps: any[], entry: string}|null} null once the reason has been printed
  */
-function profile(argv) {
+function loadApps(argv, command) {
     const entry = findEntry(argv.find((arg) => !arg.startsWith("--")));
     if (!entry) {
         console.error(
-            "Nothing to profile: name the file that builds the application, or run this from a\n" +
-                "directory whose package.json main points at it."
+            `Nothing to ${command}: name the file that builds the application, or run this from a
+` + "directory whose package.json main points at it."
         );
-        return 1;
+        return null;
     }
 
     // the same module instance the application will load, so patching this prototype patches the
@@ -374,7 +363,7 @@ function profile(argv) {
     }
     if (!proto) {
         console.error("This build of fulmine has no listen() to stand in for, which should not happen.");
-        return 1;
+        return null;
     }
 
     const listened = [];
@@ -390,8 +379,9 @@ function profile(argv) {
     } catch (e) {
         const error = /** @type {any} */ (e);
         proto.listen = realListen;
-        console.error(`${path.relative(process.cwd(), entry)} could not be loaded:\n${error.stack ?? error}`);
-        return 1;
+        console.error(`${path.relative(process.cwd(), entry)} could not be loaded:
+${error.stack ?? error}`);
+        return null;
     }
     proto.listen = realListen;
 
@@ -409,14 +399,32 @@ function profile(argv) {
 
     if (apps.length === 0) {
         console.error(
-            `${path.relative(process.cwd(), entry)} built no application: it neither called listen() nor\n` +
-                "exported one. Point this at the file that does."
+            `${path.relative(process.cwd(), entry)} built no application: it neither called listen() nor
+` + "exported one. Point this at the file that does."
         );
-        return 1;
+        return null;
     }
+    return { apps, entry };
+}
 
-    for (const app of apps) {
-        printProfile(app, apps.length > 1);
+/**
+ * Loads an application without letting it listen, and prints what compiling its routes decided.
+ *
+ * listen() is where the routes are compiled and also where the port is bound, and only the first
+ * of those is wanted here: an application that answered on its port while being profiled would be
+ * a surprise, and a second copy of a running service is worse than a surprise. So listen is
+ * replaced by the half that matters. The callback it was given is not run, for the same reason.
+ *
+ * @param {string[]} argv
+ * @returns {number} exit code
+ */
+function profile(argv) {
+    const loaded = loadApps(argv, "profile");
+    if (!loaded) {
+        return 1;
+    }
+    for (const app of loaded.apps) {
+        printProfile(app, loaded.apps.length > 1);
     }
     return 0;
 }
@@ -446,6 +454,108 @@ const ADVICE = [
     ]
 ];
 
+/**
+ * The plan for one route, the way a database explains a query.
+ *
+ * `profile` answers "how much of this application is on the fast path", which is a question about
+ * the whole table. This one answers "what happens when this request arrives", which is the question
+ * somebody has when one endpoint is slower than they expected: how it is matched, what is copied
+ * out of it, what runs, and what each layer costs the route.
+ *
+ * @param {string[]} argv the path to explain, then the entry
+ * @returns {number} exit code
+ */
+function explain(argv) {
+    const args = argv.filter((arg) => !arg.startsWith("--"));
+    const wanted = args[0];
+    if (!wanted) {
+        console.error(`Name the route to explain: npx ${TO} explain /api/items`);
+        return 1;
+    }
+    const loaded = loadApps(args.slice(1), "explain");
+    if (!loaded) {
+        return 1;
+    }
+
+    const { callbackUsage, UNKNOWN, QUERY } = require("./usage.js");
+    let found = 0;
+    for (const app of loaded.apps) {
+        const entries = collectRoutes(app, "").filter(({ route }) => !route.use);
+        for (const { route, full } of entries) {
+            if (!matchesWanted(full, route.method, wanted)) {
+                continue;
+            }
+            found++;
+            const native = route._native;
+            console.log(`
+${String(route.method).toUpperCase()} ${full}
+`);
+            console.log(
+                `  route      ${native ? `native (µWS matched ${native.path} and dispatched by method)` : `router (matched here, layer by layer: ${route._whyGeneric ?? "it was not eligible"})`}`
+            );
+            if (native) {
+                console.log(
+                    `  headers    ${native.skipHeaders ? "not copied (nothing in the chain reads one)" : "copied out of µWS (something in the chain reads them)"}`
+                );
+                console.log(
+                    `  query      ${native.skipQuery ? "not parsed (nothing in the chain reads it)" : "parsed when something asks for it"}`
+                );
+                if (native.guards) {
+                    console.log(`  guards     ${native.guards} case guard(s) in front of it`);
+                }
+            }
+
+            const chain = route.callbacks ?? [];
+            const ahead = native?.ahead ? `, ${native.ahead} mounted layer(s) in front of it` : "";
+            console.log(
+                `  chain      ${chain.length} layer(s)${ahead}${native?.declarative ? ", compiled into a response written at startup" : ""}`
+            );
+            for (const fn of chain) {
+                const usage = callbackUsage(fn);
+                const name = fn.name || "(anonymous)";
+                const notes = [];
+                if (usage & UNKNOWN) {
+                    notes.push("not readable at registration: it keeps the route off the compiled path");
+                } else {
+                    notes.push("readable at registration");
+                    if (usage & QUERY) notes.push("reads the query");
+                }
+                console.log(`    ${name.padEnd(22)}${notes.join(", ")}`);
+            }
+            console.log(
+                `  body       ${route.bodyMethods ? `read for ${route.bodyMethods.join(", ")}` : "read for POST, PUT, PATCH and QUERY, when one is declared"}`
+            );
+        }
+    }
+
+    if (found === 0) {
+        console.error(`No route is registered as "${wanted}". Run \`npx ${TO} profile\` to see the ones that are.`);
+        return 1;
+    }
+    return 0;
+}
+
+/**
+ * Whether a route answers to the name given on the command line: the path as registered, with an
+ * optional method in front and an optional "*" at the end for a prefix.
+ *
+ * @param {string} full
+ * @param {string} method
+ * @param {string} wanted
+ * @returns {boolean}
+ */
+function matchesWanted(full, method, wanted) {
+    let path = wanted;
+    const space = wanted.indexOf(" ");
+    if (space !== -1) {
+        if (wanted.slice(0, space).toUpperCase() !== String(method).toUpperCase()) {
+            return false;
+        }
+        path = wanted.slice(space + 1);
+    }
+    return path.endsWith("*") ? full.startsWith(path.slice(0, -1)) : full === path;
+}
+
 /**
  * A summary that says how much of this application the native router carries, and what could be
  * changed to make it carry more.
@@ -582,11 +692,19 @@ function main(argv) {
     if (command === "profile") {
         return profile(argv.slice(1));
     }
+    if (command === "verify") {
+        return verify(argv.slice(1));
+    }
+    if (command === "explain") {
+        return explain(argv.slice(1));
+    }
     if (command !== "migrate") {
         console.log(`Usage:
   npx ${TO} migrate [dir]      rewrite require("${FROM}") and import from "${FROM}" to "${TO}"
   npx ${TO} profile [entry]    load an application without listening and print what compiling
                                its routes decided, route by route
+  npx ${TO} explain <route>    what happens when a request for that route arrives
+  npx ${TO} verify [dir]       check that this machine and this project can run it at all
   npx ${TO} differences        print what behaves differently, without changing anything
 
 Options: