fulmine.js 5.7.0 → 5.8.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, not an `http.Server`, because there is no node server underneath: the socket belongs to µWS. The app answers as one anyway, which is what the graceful shutdown wrappers and the connection trackers look for. `app instanceof http.Server` is true, and `close()`, `address()`, `listening`, `getConnections()`, `ref()`, `unref()`, `setTimeout()` and the `keepAliveTimeout` family are all there. What is not there is the plumbing that carries node sockets: 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.
@@ -519,8 +572,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 +614,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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.7.0",
+    "version": "5.8.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,7 @@ 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 cpuCount = os.cpus().length;
 
@@ -871,3 +872,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:

package/src/index.js

@@ -49,7 +49,9 @@ try {
  *   response: object,
  *   application: object,
  *   static: Function,
+ *   testing: object,
  *   compression: Function,
+ *   serverTiming: Function,
  *   json: Function,
  *   urlencoded: Function,
  *   text: Function,
@@ -73,9 +75,15 @@ module.exports.response = Response.prototype;
 module.exports.application = Application.Application.prototype;
 
 module.exports.static = middlewares.static;
+// what listen() decided about each route, as something a test can assert on rather than something
+// to read in a terminal. See src/testing.js
+module.exports.testing = require("./testing.js");
 // not one of express's, since express has none: the compression module is what everyone installs
 // instead, and this is that middleware's options and behaviour without the install
 module.exports.compression = require("./compression.js");
+// Server-Timing with the routing verdict in it, which no other framework can report because no
+// other framework has two routes to tell apart. See src/server-timing.js
+module.exports.serverTiming = require("./server-timing.js");
 module.exports.json = middlewares.json;
 module.exports.urlencoded = middlewares.urlencoded;
 module.exports.text = middlewares.text;

package/src/server-shape.js

@@ -0,0 +1,157 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// What makes an application answer the questions a library asks about an http.Server.
+//
+// `app.listen()` returns the app, and there is no node server under it: the socket belongs to µWS.
+// That is the one place where a drop-in stops being a drop-in, because the graceful shutdown
+// libraries, the connection trackers and the health check wrappers do not use a server, they
+// *recognise* one: `server instanceof http.Server`, then close(), address(), getConnections() and
+// the events around them. Everything they need can be answered honestly here.
+//
+// Two halves, and the second is the delicate one:
+//
+//   - the members. close(), address(), listening and the events already exist on the application,
+//     because Express hands back an http.Server and code written for Express uses them. What was
+//     missing is the rest of the net.Server surface, added below.
+//   - the recognition. An application cannot inherit from http.Server: its prototype chain already
+//     runs through Router and this project's own EventEmitter, and http.Server.prototype has a
+//     chain of its own that cannot be spliced into it without re-parenting node's classes for the
+//     whole process. So instanceof is taught about applications instead, through the hook the
+//     language provides for exactly this: Symbol.hasInstance. The patch is additive. Everything
+//     that was an http.Server before still is, and the only new answer is for an application.
+//
+// What this deliberately does not do is pretend the plumbing is there. Nothing emits 'request',
+// 'connection' or 'upgrade', because those carry node sockets and there are none: a library that
+// counts connections through them counts zero, and socket.io still wants app.uwsApp. The shape is
+// honest about what is behind it, which is why getConnections answers with the requests in flight
+// rather than with a number nobody could stand behind.
+
+const http = require("http");
+const net = require("net");
+
+// what marks an application, read by the instanceof hook below. A symbol rather than a property
+// name, so nothing can be mistaken for an application by carrying the wrong field
+const kIsApplication = Symbol.for("fulmine.application");
+
+/**
+ * Teaches `instanceof` that an application is a server, once per class. The original answer is
+ * asked first and is never overruled: this only adds an answer for objects carrying the mark.
+ *
+ * @param {Function} klass http.Server or net.Server
+ */
+function acceptApplications(klass) {
+    const previous = /** @type {any} */ (klass)[Symbol.hasInstance];
+    // already taught, which happens when two copies of this package share one process
+    if (/** @type {any} */ (klass)[kIsApplication] === true) {
+        return;
+    }
+    Object.defineProperty(klass, Symbol.hasInstance, {
+        /** @param {any} value @returns {boolean} */
+        value: function (value) {
+            if (previous.call(this, value)) {
+                return true;
+            }
+            // an application is a function, and a property read works on one; the guard is for the
+            // primitives and the nulls that reach any instanceof
+            return value != null && /** @type {any} */ (value)[kIsApplication] === true;
+        },
+        configurable: true,
+        writable: true
+    });
+    Object.defineProperty(klass, kIsApplication, { value: true, configurable: true });
+}
+
+acceptApplications(http.Server);
+acceptApplications(net.Server);
+
+/**
+ * The net.Server members an application does not get from Express's side of the API, defined on
+ * the application prototype. Each one answers for µWS rather than for a socket node does not have.
+ *
+ * @param {any} prototype Application.prototype
+ */
+function addServerMembers(prototype) {
+    Object.defineProperty(prototype, kIsApplication, { value: true, configurable: true });
+
+    /**
+     * How many requests this application is serving right now.
+     *
+     * node counts sockets; there are none to count here, and the number a graceful shutdown is
+     * waiting for is this one anyway: it reaches zero when the last answer has gone out. An idle
+     * keep-alive connection is not counted, and closing does not wait for one either.
+     *
+     * @param {(err: Error|null, count: number) => void} callback
+     */
+    prototype.getConnections = function getConnections(callback) {
+        let count = 0;
+        for (let response = this._pending.head; response !== null; response = response._pendingNext) {
+            count++;
+        }
+        // node answers this one asynchronously, and a caller written against it may rely on that
+        process.nextTick(callback, null, count);
+    };
+
+    /**
+     * node's, for a handle this does not own: µWS's loop is what keeps the process alive, and it
+     * is not something a caller may unref. Both are no-ops that hand the server back, so a chain
+     * written against node's API keeps working.
+     *
+     * @returns {any}
+     */
+    prototype.ref = function ref() {
+        return this;
+    };
+
+    /** @returns {any} */
+    prototype.unref = function unref() {
+        return this;
+    };
+
+    /**
+     * Registers the callback the way node's does and remembers the value, which is all a caller
+     * can observe. The timeout itself belongs to µWS and is set through uwsOptions.idleTimeout.
+     *
+     * @this {any}
+     * @param {number} [msecs]
+     * @param {() => void} [callback]
+     * @returns {any}
+     */
+    prototype.setTimeout = function setTimeout(msecs, callback) {
+        this.timeout = msecs;
+        if (callback) {
+            this.on("timeout", callback);
+        }
+        return this;
+    };
+
+    // The numbers node's http.Server carries and a caller may read or write. They are inert here,
+    // and they are declared rather than left undefined because reading one is how a library works
+    // out what it is talking to: `server.keepAliveTimeout` undefined has been read as "not a
+    // server" before now.
+    for (const [name, value] of /** @type {[string, any][]} */ ([
+        ["timeout", 0],
+        ["keepAliveTimeout", 5000],
+        ["headersTimeout", 60000],
+        ["requestTimeout", 300000],
+        ["maxHeadersCount", null],
+        ["maxRequestsPerSocket", 0]
+    ])) {
+        Object.defineProperty(prototype, name, { value, writable: true, configurable: true, enumerable: false });
+    }
+}
+
+module.exports = { addServerMembers, kIsApplication };

package/src/server-timing.js

@@ -0,0 +1,180 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// express.serverTiming(): Server-Timing, with the two things only this framework can put in it.
+//
+// A stopwatch middleware is nothing new, and there are several on npm. What none of them can add
+// is how the request was routed, because in every other framework there is only one way:
+//
+//     Server-Timing: route;desc="native", hdr;desc="not copied", total;dur=0.42
+//
+// `route;desc="native"` means µWS matched the path in C++ and handed over a chain worked out at
+// startup. `route;desc="router"` means this request was matched here, in javascript, layer by
+// layer. That is the difference between the two halves of this project, per request, in the
+// browser's network panel, for someone who would never run a CLI.
+//
+// What it cannot show is the route that is faster still: a handler compiled into a response never
+// enters javascript, so no middleware runs on it and there is nothing to time. `npx fulmine
+// profile` is where those are counted.
+//
+// The duration ends where the header does. Server-Timing goes out with the head, so `total` covers
+// everything up to the moment the answer starts leaving, and not the body after it. Every stopwatch
+// middleware has that boundary; this one says so.
+
+"use strict";
+
+/**
+ * A duration in milliseconds, as Server-Timing writes them: two decimals, which is a hundredth of
+ * a millisecond and finer than anything above it is worth.
+ *
+ * @param {bigint} nanoseconds
+ * @returns {string}
+ */
+function millis(nanoseconds) {
+    return (Number(nanoseconds) / 1e6).toFixed(2);
+}
+
+/**
+ * Escapes a description for the quoted-string it goes in.
+ * @param {string} text
+ * @returns {string}
+ */
+function describe(text) {
+    return `"${String(text).replace(/["\\]/g, "")}"`;
+}
+
+/**
+ * Measures the request and answers with Server-Timing.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.routing] whether to report how the request was routed. Default true.
+ * @param {boolean} [options.total] whether to report the time up to the head. Default true.
+ * @param {string} [options.name] what the total is called. Default "total".
+ * @returns {(req: any, res: any, next: (err?: any) => void) => void}
+ */
+function serverTiming(options) {
+    const opts = options || {};
+    const routing = opts.routing !== false;
+    const wantsTotal = opts.total !== false;
+    const totalName = opts.name || "total";
+
+    return function serverTiming(req, res, next) {
+        const started = process.hrtime.bigint();
+        /** @type {string[]} */
+        const marks = [];
+
+        /**
+         * Adds a mark of the caller's own, which is what the rest of Server-Timing is for: the
+         * query, the upstream call, the render. A duration is optional, since a mark with only a
+         * description is a legal entry and is how a cache hit is usually reported.
+         *
+         * @param {string} name a token: letters, digits, dash and underscore
+         * @param {number} [duration] milliseconds
+         * @param {string} [description]
+         * @returns {any} the response, so calls chain
+         */
+        res.timing = function timing(name, duration, description) {
+            let mark = String(name).replace(/[^\w-]/g, "");
+            if (typeof duration === "number") {
+                mark += `;dur=${duration.toFixed(2)}`;
+            }
+            if (description) {
+                mark += `;desc=${describe(description)}`;
+            }
+            marks.push(mark);
+            return this;
+        };
+
+        /**
+         * Times a piece of work under a name, whatever it is: the value comes back, and a promise
+         * is timed to where it settles.
+         *
+         * @param {string} name
+         * @param {() => any} work
+         * @returns {any} whatever the work returned
+         */
+        res.time = function time(name, work) {
+            const from = process.hrtime.bigint();
+            const done = () => res.timing(name, Number(process.hrtime.bigint() - from) / 1e6);
+            let value;
+            try {
+                value = work();
+            } catch (err) {
+                done();
+                throw err;
+            }
+            if (value && typeof value.then === "function") {
+                return value.then(
+                    /** @param {any} resolved */ (resolved) => {
+                        done();
+                        return resolved;
+                    },
+                    /** @param {any} err */ (err) => {
+                        done();
+                        throw err;
+                    }
+                );
+            }
+            done();
+            return value;
+        };
+
+        const _write = res.write;
+        const _end = res.end;
+        let written = false;
+
+        /** Writes the header, once, just before the head goes out with the first byte of body. */
+        const stamp = () => {
+            if (written || res.headersSent) {
+                return;
+            }
+            written = true;
+            const entries = [];
+            if (routing) {
+                // what the router decided about the route this request ran, which is the same
+                // verdict npx fulmine profile prints for it
+                const native = req.route?._native;
+                entries.push(`route;desc=${describe(native ? "native" : "router")}`);
+                if (native) {
+                    entries.push(`hdr;desc=${describe(native.skipHeaders ? "not copied" : "copied")}`);
+                    if (native.skipQuery) {
+                        entries.push(`query;desc=${describe("not parsed")}`);
+                    }
+                }
+            }
+            entries.push(...marks);
+            if (wantsTotal) {
+                entries.push(`${totalName};dur=${millis(process.hrtime.bigint() - started)}`);
+            }
+            if (entries.length !== 0) {
+                res.append("Server-Timing", entries.join(", "));
+            }
+        };
+
+        res.write = function write(chunk, encoding, callback) {
+            stamp();
+            return _write.call(this, chunk, encoding, callback);
+        };
+        res.end = function end(chunk, encoding, callback) {
+            stamp();
+            return _end.call(this, chunk, encoding, callback);
+        };
+
+        next();
+    };
+}
+
+module.exports = serverTiming;

package/src/testing.js

@@ -0,0 +1,201 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// express.testing: what listen() decided about each route, as something a test can assert on.
+//
+// A route is answered by µWS itself only while it stays eligible, and eligibility is not a property
+// of the route alone: a `const` in the wrong place, a middleware that reads a header, a new route
+// written above an old one, and it quietly falls back to the ordinary router. The answer is still
+// correct, which is why nothing complains. What changes is the throughput, and by the time anyone
+// notices, the commit that did it is three weeks back.
+//
+// `npx fulmine profile` prints the same verdicts for a human to read. This is the half a test can
+// hold on to, so a pull request that loses the fast path fails in CI with the reason written out
+// instead of being found in production.
+
+"use strict";
+
+/**
+ * Every route of an application and of the routers mounted under it, each with the path it answers
+ * from the outside.
+ *
+ * @param {any} router
+ * @param {string} prefix
+ * @param {any[]} [into]
+ * @returns {{route: any, full: string}[]}
+ */
+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;
+}
+
+/**
+ * Compiles the routes, which is what listen() does before it binds, without binding anything. Once
+ * per application: a second compilation would register everything with µWS twice.
+ *
+ * @param {any} app
+ */
+function compileOnce(app) {
+    if (app.listenCalled || app._testingCompiled) {
+        return;
+    }
+    app._testingCompiled = true;
+    app._compileOptimizedRoutes();
+}
+
+/**
+ * What compiling the routes decided, one entry per route, in the order they were registered.
+ *
+ * This is the primitive the two assertions below are written on, and it is exported because an
+ * application with rules of its own is better served asserting them itself: how many routes may
+ * fall back, which ones may read headers, that the one route carrying the traffic is declarative.
+ *
+ * @param {any} app an application, listening or not
+ * @returns {{method: string, path: string, native: boolean, declarative: boolean, skipHeaders: boolean,
+ *   skipQuery: boolean, reason: string|undefined}[]}
+ */
+function routeReport(app) {
+    compileOnce(app);
+    return collectRoutes(app, "")
+        .filter(({ route }) => !route.use)
+        .map(({ route, full }) => ({
+            method: String(route.method),
+            path: full,
+            native: Boolean(route._native),
+            declarative: Boolean(route._native?.declarative),
+            skipHeaders: Boolean(route._native?.skipHeaders),
+            skipQuery: Boolean(route._native?.skipQuery),
+            reason: route._native ? undefined : (route._whyGeneric ?? "it was not eligible")
+        }));
+}
+
+/**
+ * Whether one of the patterns given names this route.
+ *
+ * A pattern is a path as it was registered, not a URL: "/api/items/:id" and not "/api/items/7". It
+ * may carry the method, "GET /health", and it may end in "*" to name everything under a prefix.
+ *
+ * @param {{method: string, path: string}} entry
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function names(entry, pattern) {
+    let path = pattern;
+    const space = pattern.indexOf(" ");
+    if (space !== -1) {
+        const method = pattern.slice(0, space).toUpperCase();
+        if (method !== entry.method.toUpperCase()) {
+            return false;
+        }
+        path = pattern.slice(space + 1);
+    }
+    if (path.endsWith("*")) {
+        return entry.path.startsWith(path.slice(0, -1));
+    }
+    return entry.path === path;
+}
+
+/**
+ * The routes the patterns name, refusing a pattern that names none: a test that asserts about a
+ * route it misspelled has to fail rather than pass on an empty list.
+ *
+ * @param {any} app
+ * @param {string|string[]} patterns
+ * @param {string} caller the name in the message
+ * @returns {ReturnType<typeof routeReport>}
+ */
+function select(app, patterns, caller) {
+    const wanted = typeof patterns === "string" ? [patterns] : patterns;
+    if (!Array.isArray(wanted) || wanted.length === 0) {
+        throw new TypeError(`${caller} needs a path, or a list of them, to check`);
+    }
+    const report = routeReport(app);
+    const selected = [];
+    for (const pattern of wanted) {
+        const matched = report.filter((entry) => names(entry, pattern));
+        if (matched.length === 0) {
+            throw new Error(
+                `${caller}: no route is registered as "${pattern}".\n` +
+                    `The paths this application has are:\n` +
+                    report.map((entry) => `  ${entry.method} ${entry.path}`).join("\n")
+            );
+        }
+        for (const entry of matched) {
+            if (!selected.includes(entry)) {
+                selected.push(entry);
+            }
+        }
+    }
+    return selected;
+}
+
+/**
+ * Throws unless every route named is answered by µWS itself.
+ *
+ * The message is the point: it names each route that fell back and why, in the same words
+ * `npx fulmine profile` uses, so the failure says what to change.
+ *
+ * @param {any} app
+ * @param {string|string[]} patterns paths as they were registered, "GET /path" to pin the method,
+ *   a trailing "*" for everything under a prefix
+ */
+function expectNative(app, patterns) {
+    const lost = select(app, patterns, "expectNative").filter((entry) => !entry.native);
+    if (lost.length === 0) {
+        return;
+    }
+    throw new Error(
+        `${lost.length} route(s) are no longer answered by µWS itself:\n\n` +
+            lost.map((entry) => `  ${entry.method} ${entry.path}\n    ${entry.reason}`).join("\n") +
+            `\n\nRun \`npx fulmine profile\` to see the whole picture.`
+    );
+}
+
+/**
+ * Throws unless every route named is answered from a response written at startup, which is the
+ * step past native: µWS answers it without entering javascript at all.
+ *
+ * @param {any} app
+ * @param {string|string[]} patterns as in expectNative
+ */
+function expectDeclarative(app, patterns) {
+    const lost = select(app, patterns, "expectDeclarative").filter((entry) => !entry.declarative);
+    if (lost.length === 0) {
+        return;
+    }
+    throw new Error(
+        `${lost.length} route(s) are no longer compiled into a response:\n\n` +
+            lost
+                .map(
+                    (entry) =>
+                        `  ${entry.method} ${entry.path}\n    ` +
+                        (entry.native
+                            ? "answered by µWS, but the handler is no longer simple enough to compile"
+                            : entry.reason)
+                )
+                .join("\n") +
+            `\n\nRun \`npx fulmine profile\` to see the whole picture.`
+    );
+}
+
+module.exports = { routeReport, expectNative, expectDeclarative, collectRoutes };

package/src/types.d.ts

@@ -50,6 +50,32 @@ declare module "fulmine.js" {
             /** Brotli options. The default quality is 4. */
             brotli?: BrotliOptions;
         }
+        // what listen() decided about each route, for a test to hold on to
+        interface RouteVerdict {
+            /** The method as it was registered, "GET". */
+            method: string;
+            /** The path as it was registered, "/users/:id". */
+            path: string;
+            /** Whether µWS matches this route itself. */
+            native: boolean;
+            /** Whether it was compiled into a response written at startup. */
+            declarative: boolean;
+            /** Whether the chain provably reads no request header. */
+            skipHeaders: boolean;
+            /** Whether the chain provably reads no query. */
+            skipQuery: boolean;
+            /** Why it fell back to the ordinary router, when it did. */
+            reason?: string;
+        }
+        export namespace testing {
+            /** Every route, with what compiling it decided. */
+            function routeReport(app: Fulmine): RouteVerdict[];
+            /** Throws unless µWS answers every route named. A trailing "*" names a prefix. */
+            function expectNative(app: Fulmine, patterns: string | string[]): void;
+            /** Throws unless every route named was compiled into a response. */
+            function expectDeclarative(app: Fulmine, patterns: string | string[]): void;
+        }
+
         export function compression(options?: CompressionOptions): e.RequestHandler;
         export namespace compression {
             /** The default filter: any compressible content type. */

package/src/verify.js

@@ -0,0 +1,309 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// npx fulmine verify
+//
+// Whether this machine, and the image it will be deployed in, can run the thing at all. Not
+// whether the application behaves the same, which is what the test suite and `differences` are
+// for: this is the question that comes before it, and it is the one that costs an hour when the
+// answer is no and nobody asked.
+//
+// There is a µWebSockets.js binary underneath, and a binary has requirements a package does not:
+// it is built per platform, per architecture and per node ABI, and it is linked against glibc. An
+// Alpine image, a node version the pinned build has no binary for, a musl base chosen by a
+// Dockerfile written before any of this: each one fails at require time, in a container, in CI,
+// with a message about a missing module that says nothing about what to do.
+//
+// Thirty seconds here instead.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// The oldest glibc the pinned µWS binaries are built against. A runtime older than this loads the
+// file and then fails on a symbol, which is a worse error than not finding it at all.
+const MIN_GLIBC = "2.38";
+
+// 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 = {
+    "socket.io": "attach it with io.attachApp(app.uwsApp), not io.attach(server): there is no node socket to take over",
+    ws: "the websocket server is µWS's own, through app.ws(path, behavior)",
+    "express-ws": "the same: app.ws(path, behavior) is built in",
+    spdy: "no spdy here; TLS is configured through express({ uwsOptions: { key_file_name, cert_file_name } })",
+    "http2-express-bridge": "no HTTP/2 server to bridge to"
+};
+
+/**
+ * One line of the report. Three levels, and only one of them is a failure: an image that cannot
+ * load the binary stops the deployment, while a dependency that wants a different call is
+ * something to read, not something to fail a pipeline over.
+ *
+ * @param {"ok"|"note"|"no"} level
+ * @param {string} what
+ * @param {string} [detail] what to do about it
+ * @returns {{level: "ok"|"note"|"no", what: string, detail: string|undefined}}
+ */
+function result(level, what, detail) {
+    return { level, what, detail };
+}
+
+/**
+ * Whether a version string is at least the other, compared piece by piece so "2.38" and "2.9"
+ * order the way versions do rather than the way strings do.
+ *
+ * @param {string} version
+ * @param {string} minimum
+ * @returns {boolean}
+ */
+function atLeast(version, minimum) {
+    const left = version.split(".").map(Number);
+    const right = minimum.split(".").map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const a = left[i] ?? 0;
+        const b = right[i] ?? 0;
+        if (a !== b) {
+            return a > b;
+        }
+    }
+    return true;
+}
+
+/**
+ * The node this is running on, against what the package asks for.
+ *
+ * The version arrives as an argument rather than being read here, so the answer for a node this
+ * machine is not running is testable from the machine it is not running on. Every check below
+ * takes what it judges for the same reason.
+ *
+ * @param {string} [running] defaults to the node running this
+ * @param {string} [required] defaults to what package.json asks for
+ * @returns {ReturnType<typeof result>}
+ */
+function checkNode(running = process.versions.node, required = require("../package.json").engines.node) {
+    const minimum = required.replace(/[^0-9.]/g, "");
+    if (atLeast(running, minimum)) {
+        return result("ok", `Node ${running}`);
+    }
+    return result("no", `Node ${running}`, `this package needs ${required}. Upgrade node, or pin an older fulmine.`);
+}
+
+/**
+ * Whether the C library is the one the binaries are linked against. Only linux has two of them,
+ * and node reports the glibc it is running against; a musl build reports none, which is what
+ * Alpine looks like from in here.
+ *
+ * @param {string} [platform]
+ * @param {string|undefined} [glibc] the runtime glibc, absent on musl
+ * @returns {ReturnType<typeof result>|undefined} undefined where the question does not arise
+ */
+function checkLibc(
+    platform = process.platform,
+    glibc = /** @type {any} */ (process.report.getReport()).header.glibcVersionRuntime
+) {
+    if (platform !== "linux") {
+        return undefined;
+    }
+    if (!glibc) {
+        return result(
+            "no",
+            "musl libc, which the µWebSockets.js binaries are not built for",
+            "this is Alpine, or another musl distribution. Use a glibc image: node:22-trixie-slim, " +
+                "node:24-bookworm-slim\n    or the plain node:22. There is no musl build to install."
+        );
+    }
+    if (!atLeast(glibc, MIN_GLIBC)) {
+        return result(
+            "no",
+            `glibc ${glibc}`,
+            `the binaries need ${MIN_GLIBC} or newer. A newer base image is the fix: node:22-trixie-slim.`
+        );
+    }
+    return result("ok", `glibc ${glibc}`);
+}
+
+/**
+ * Whether there is a µWebSockets.js binary for this platform, architecture and node ABI, which is
+ * the failure that greets everyone who tries an unusual combination. The file is named rather than
+ * loaded first, so the answer says which of the three does not line up.
+ *
+ * @param {string} [platform]
+ * @param {string} [arch]
+ * @param {string} [abi]
+ * @param {string} [from] the directory holding the binaries, for a test that has no real one
+ * @returns {ReturnType<typeof result>}
+ */
+function checkBinary(platform = process.platform, arch = process.arch, abi = process.versions.modules, from) {
+    const name = `uws_${platform}_${arch}_${abi}.node`;
+    let dir = from;
+    if (dir === undefined) {
+        try {
+            dir = path.dirname(require.resolve("uWebSockets.js"));
+        } catch {
+            return result("no", "uWebSockets.js is not installed", "run npm install.");
+        }
+    }
+    if (fs.existsSync(path.join(dir, name))) {
+        // named and present, so the only thing left is whether it loads
+        try {
+            require("uWebSockets.js");
+            return result("ok", `µWebSockets.js binary for ${platform} ${arch}, node ABI ${abi}`);
+        } catch (err) {
+            return result(
+                "no",
+                `${name} is there and will not load`,
+                `${/** @type {Error} */ (err).message}\n    On linux this is nearly always the C library, see the line above.`
+            );
+        }
+    }
+    const prefix = `uws_${platform}_${arch}_`;
+    const shipped = fs
+        .readdirSync(dir)
+        .filter((file) => file.startsWith(prefix) && file.endsWith(".node"))
+        .map((file) => file.slice(prefix.length, -".node".length));
+    if (shipped.length === 0) {
+        return result(
+            "no",
+            `no µWebSockets.js binary for ${platform} ${arch}`,
+            "this platform is not one the pinned build ships. Linux, macOS and Windows on x64 or arm64 are."
+        );
+    }
+    return result(
+        "no",
+        `no µWebSockets.js binary for node ABI ${abi}`,
+        `this build ships ABI ${shipped.join(", ")}, which is node ${shipped.map(abiToNode).join(", ")}.\n` +
+            `    Run one of those, or wait for a fulmine that pins a newer µWebSockets.js.`
+    );
+}
+
+/**
+ * The node release line an ABI number belongs to, for the versions this package can meet. An
+ * unknown one is reported as itself rather than guessed at.
+ *
+ * @param {string} abi
+ * @returns {string}
+ */
+function abiToNode(abi) {
+    const known = { 108: "18", 115: "20", 127: "22", 131: "23", 137: "24", 147: "26" };
+    return /** @type {any} */ (known)[abi] ?? `ABI ${abi}`;
+}
+
+/**
+ * The base images a Dockerfile names, which is where the musl question is usually answered without
+ * anybody meaning to.
+ *
+ * @param {string} dir the project being verified
+ * @returns {ReturnType<typeof result>[]}
+ */
+function checkDockerfiles(dir) {
+    /** @type {ReturnType<typeof result>[]} */
+    const results = [];
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((file) => file === "Dockerfile" || file.startsWith("Dockerfile."));
+    } catch {
+        return results;
+    }
+    for (const name of names) {
+        const source = fs.readFileSync(path.join(dir, name), "utf8");
+        for (const line of source.split("\n")) {
+            const match = /^\s*FROM\s+(\S+)/i.exec(line);
+            if (!match) {
+                continue;
+            }
+            const image = match[1];
+            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.")
+                );
+                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.`));
+                continue;
+            }
+            results.push(result("ok", where));
+        }
+    }
+    return results;
+}
+
+/**
+ * The dependencies that need a different API here. Read from package.json rather than from
+ * node_modules, so a project is answered before it installs anything.
+ *
+ * @param {string} dir
+ * @returns {ReturnType<typeof result>[]}
+ */
+function checkDependencies(dir) {
+    /** @type {ReturnType<typeof result>[]} */
+    const results = [];
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    } catch {
+        return results;
+    }
+    const installed = { ...pkg.dependencies, ...pkg.devDependencies };
+    for (const name of Object.keys(NEEDS_A_LOOK)) {
+        if (installed[name]) {
+            results.push(result("note", `${name} needs a different API here`, /** @type {any} */ (NEEDS_A_LOOK)[name]));
+        }
+    }
+    return results;
+}
+
+/**
+ * Runs every check and prints the report. Anything that would stop the application from starting
+ * is a failure and the command exits non-zero, so it can be a step in a pipeline.
+ *
+ * @param {string[]} argv
+ * @returns {number} exit code
+ */
+function verify(argv) {
+    const dir = path.resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
+    /** @type {ReturnType<typeof result>[]} */
+    const results = [checkNode()];
+    const libc = checkLibc();
+    if (libc) {
+        results.push(libc);
+    }
+    results.push(checkBinary(), ...checkDockerfiles(dir), ...checkDependencies(dir));
+
+    console.log(`\nWhether this machine and this project can run fulmine.js\n`);
+    const label = { ok: "ok  ", note: "note", no: "NO  " };
+    for (const { level, what, detail } of results) {
+        console.log(`  ${label[level]}  ${what}`);
+        if (level !== "ok" && detail) {
+            console.log(`        ${detail}`);
+        }
+    }
+    // only a blocked start is a failure. A dependency that wants a different call is worth
+    // reading and is not worth failing a pipeline over
+    const blocking = results.filter((entry) => entry.level === "no").length;
+    const notes = results.filter((entry) => entry.level === "note").length;
+    console.log(
+        blocking === 0
+            ? `\nNothing in the way${notes ? `, ${notes} thing(s) worth reading` : ""}.\n`
+            : `\n${blocking} thing(s) stop this from running.\n`
+    );
+    return blocking === 0 ? 0 : 1;
+}
+
+module.exports = { verify, checkNode, checkLibc, checkBinary, checkDockerfiles, checkDependencies };