fulmine.js 5.6.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,7 +393,41 @@ 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.
 
-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. It costs one more `stat` per request and sends a fraction of the bytes: on a 4KB script with a brotli twin, 12 times fewer. `Vary: Accept-Encoding` is sent whether or not a variant is found, the content type stays the one the requested name implies, and each variant carries its own ETag.
+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.6.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/compression.js

@@ -36,11 +36,31 @@ limitations under the License.
 const zlib = require("zlib");
 const bytes = require("bytes");
 const compressible = require("compressible");
-const { negotiateEncoding, ENCODING_ANY } = require("./utils.js");
+const { negotiateEncoding, ENCODING_ANY, memoizeByString } = require("./utils.js");
 
 // Cache-Control: no-transform forbids recoding the body, which is what this does
 const NO_TRANSFORM = /(?:^|,)\s*?no-transform\s*?(?:,|$)/;
 
+/**
+ * Says the answer depends on Accept-Encoding. res.vary() parses what is there and merges, which on
+ * the usual response is parsing an absent header: only a response that already varies pays for it.
+ *
+ * @param {any} res
+ */
+function addVary(res) {
+    if (res.getHeader("Vary") === undefined) {
+        res.setHeader("Vary", "Accept-Encoding");
+        return;
+    }
+    res.vary("Accept-Encoding");
+}
+
+/**
+ * res.flush for a response that is not being compressed. The compression module puts a function
+ * there on every response it sees, and code written against it calls one without asking first.
+ */
+function noFlush() {}
+
 // what enforceEncoding is allowed to name, the compression module's list
 const ENFORCEABLE = new Set(["gzip", "deflate", "identity", "br"]);
 
@@ -61,12 +81,16 @@ const SYNC_LIMIT = 24 * 1024;
  */
 function shouldCompress(req, res) {
     const type = res.getHeader("Content-Type");
-    if (type === undefined || !compressible(String(type))) {
+    if (type === undefined) {
         return false;
     }
-    return true;
+    // memoized, because an application answers with two or three content-types and compressible
+    // splits the parameters off and searches the mime database to reach the same answer each time
+    return isCompressible(typeof type === "string" ? type : String(type));
 }
 
+const isCompressible = memoizeByString((type) => compressible(type) === true);
+
 /**
  * How many bytes a chunk is, which is what the threshold is compared against.
  *
@@ -184,6 +208,37 @@ function compression(options) {
     }
 
     return function compression(req, res, next) {
+        // Negotiated here rather than when the body arrives, because the answer to "could this
+        // request take a compressed body at all" decides how much of this middleware the response
+        // has to carry. Most requests to most routes cannot: a client that sent no Accept-Encoding,
+        // one that refused everything, a HEAD. Those get the Vary and nothing else, since the
+        // answer still depends on the header even when this particular client did not ask.
+        const accept = req.headers["accept-encoding"];
+        let chosen = negotiateEncoding(accept === undefined ? "" : accept, ENCODING_ANY);
+        if (accept === undefined && ENFORCEABLE.has(enforceEncoding)) {
+            chosen = enforceEncoding;
+        }
+        if (!chosen || chosen === "identity" || req.method === "HEAD") {
+            res.flush = noFlush;
+            const _plainEnd = res.end;
+            let varied = false;
+            res.end = function end(chunk, encoding, callback) {
+                if (!varied) {
+                    varied = true;
+                    const cacheControl = res.headersSent ? undefined : res.getHeader("Cache-Control");
+                    if (
+                        !res.headersSent &&
+                        filter(req, res) &&
+                        !(cacheControl && NO_TRANSFORM.test(String(cacheControl)))
+                    ) {
+                        addVary(res);
+                    }
+                }
+                return _plainEnd.call(this, chunk, encoding, callback);
+            };
+            return next();
+        }
+
         const _write = res.write;
         const _end = res.end;
         const _on = res.on;
@@ -243,7 +298,7 @@ function compression(options) {
             if (cacheControl && NO_TRANSFORM.test(String(cacheControl))) {
                 return noCompress();
             }
-            res.vary("Accept-Encoding");
+            addVary(res);
             // NaN when there is no Content-Length, and a comparison against NaN is false: a body
             // whose size is not known yet is compressed whatever the threshold says
             if (Number(res.getHeader("Content-Length")) < threshold || Number(length) < threshold) {
@@ -253,27 +308,17 @@ function compression(options) {
             if (already && already !== "identity") {
                 return noCompress();
             }
-            if (req.method === "HEAD") {
-                return noCompress();
-            }
             // a range is a window into the bytes on disk, and a client that asked for one cannot
             // decode a compressed answer to it
             if (res.statusCode === 206 || res.getHeader("Content-Range") !== undefined) {
                 return noCompress();
             }
-            const accept = req.headers["accept-encoding"];
-            let method = negotiateEncoding(accept === undefined ? "" : accept, ENCODING_ANY);
-            if (accept === undefined && ENFORCEABLE.has(enforceEncoding)) {
-                method = enforceEncoding;
-            }
-            if (!method || method === "identity") {
-                return noCompress();
-            }
-            res.setHeader("Content-Encoding", method);
+            // HEAD never reaches here: it took the Vary-only path above
+            res.setHeader("Content-Encoding", chosen);
             // what it says is the size of the body before this middleware saw it. The whole-body
             // path below puts the right one back; the streaming one cannot know it in advance
             res.removeHeader("Content-Length");
-            return method;
+            return chosen;
         }
 
         /**

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;