fulmine.js 5.17.0 → 5.18.1

package/README.md

@@ -2,7 +2,7 @@
 
 # Fulmine.js
 
-Fulmine - means lightning ⚡ in Italian - is a drop-in replacement for Express 5, running on [µWebSockets.js](https://github.com/uNetworking/uWebSockets.js) instead of `node:http`. Your existing middleware keeps working.
+Fulmine - means lightning ⚡ in Italian - is a blazing-fast drop-in replacement for Express 5, running on [µWebSockets.js](https://github.com/uNetworking/uWebSockets.js) instead of `node:http`. Your existing middleware keeps working.
 
 ```js
 const express = require("fulmine.js"); // instead of require("express")
@@ -50,6 +50,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
     - [NestJS](#nestjs)
     - [When Express is somebody else's dependency](#when-express-is-somebody-elses-dependency)
 - [Docker](#docker)
+- [Behind a private registry](#behind-a-private-registry)
 - [Differences from Express](#differences-from-express)
 - [Performance tips](#performance-tips)
 - [WebSockets](#websockets)
@@ -294,6 +295,79 @@ CMD ["node", "server.js"]
 
 A single-stage `node:26-trixie-slim` image works too if you `apt-get install -y git ca-certificates` before `npm ci`. Prebuilt binaries exist for x64 and arm64 on Linux, macOS and Windows, so nothing is compiled at install time either way.
 
+## Behind a private registry
+
+µWebSockets.js is not on npm, it is installed from GitHub, and npm allows that by default, so an
+ordinary `npm install fulmine.js` needs nothing from this section. It is here for the builds that
+have turned git dependencies off, or that cannot reach github.com at all:
+
+```
+allow-git=none   npm error code EALLOWGIT
+                 npm error Fetching packages of type "git" have been disabled
+                 npm error Refusing to fetch "uWebSockets.js@github:uNetworking/uWebSockets.js#v20.69.0"
+
+allow-git=root   npm error code EALLOWGIT
+                 npm error Fetching non-root packages of type "git" have been disabled
+```
+
+`root` is the one that surprises people: it allows a git dependency your own `package.json` asks
+for, and still refuses this one, because it is asked for by fulmine rather than by you.
+
+The answer is to put µWebSockets.js in your own registry and point at it from there. Three steps,
+and nothing is compiled on the way: the tarball is what uNetworking already publishes on the tag,
+prebuilt binaries included.
+
+**1. Pack the tag.** No clone needed, npm takes the git spec directly:
+
+```sh
+npm pack "github:uNetworking/uWebSockets.js#v20.69.0"
+```
+
+Read the version out of [`package.json`](./package.json) rather than copying the one above, since
+it moves with each release of this package.
+
+**2. Publish it to your registry.**
+
+```sh
+npm publish uWebSockets.js-20.69.0.tgz --registry https://registry.internal/
+```
+
+The tarball is around 33 MB, because it carries a binary for every Node ABI and platform, and that
+is larger than several defaults along the way. Verdaccio refuses it at `max_body_size: 10mb`,
+and an nginx in front of any registry refuses it at `client_max_body_size 1m`. Both answer
+`413 Payload Too Large` without ever naming µWebSockets.js, so raise them before deciding the
+tarball is broken:
+
+```yaml
+# verdaccio config.yaml
+max_body_size: 200mb
+```
+
+**3. Override the git spec in your application.** The version is the same one you packed:
+
+```json
+{
+    "dependencies": { "fulmine.js": "5.17.0" },
+    "overrides": { "uWebSockets.js": "20.69.0" }
+}
+```
+
+`npm install` and `npm ci` both work from here with git off, and the lockfile resolves to your
+registry with an integrity hash, so nothing reaches for git at install time:
+
+```json
+"node_modules/uWebSockets.js": {
+    "version": "20.69.0",
+    "resolved": "https://registry.internal/uWebSockets.js/-/uWebSockets.js-20.69.0.tgz",
+    "integrity": "sha512-kO7bcc/Hy3K6YnAVKBCu9ffYC1tl/ccDzDJqVK/GAO81XRRL+R1VmJP8mReg..."
+}
+```
+
+One thing to tell your security team before their scanner does: the lockfile still contains the
+line `"uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.69.0"`. That is fulmine's declared
+range, not a resolution, and a scanner that reads what is declared rather than what was installed
+will report a git dependency that the install never used.
+
 ## Differences from Express
 
 What the two servers answer on the wire, probed from outside, malformed input and smuggling
@@ -469,6 +543,20 @@ 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. Runnable: [`examples/fast-routes.js`](./examples/fast-routes.js).
 
+A route can stay native and still slow down request by request, because most of what makes this fast is work that does not happen: the request is not turned into a `Readable`, the response is not turned into a `Writable`, `req.headers` is not folded into an object, the query is not parsed, no socket stand-in is allocated. A middleware that reads `req.headers.host` puts one of those back on every request, and nothing fails. `expectLazy` is the assertion for that half, asked from inside a handler:
+
+```js
+const { workReport, expectLazy } = require("fulmine.js").testing;
+
+app.post("/items", (req, res) => {
+    expectLazy(req, res, { allow: ["body"] }); // throws naming what else was built
+    workReport(req, res); // { native, declarative, headers, query, body, requestStream, ... }
+    res.json(req.body);
+});
+```
+
+Asking costs a property read: every field is state the framework already keeps, nothing is counted or wrapped to make it readable.
+
 `npx fulmine.js explain /api/items/:id` answers the other question, the one about a single endpoint rather than about the table: how it is matched, what is copied out of the request, what runs and what each layer costs the route.
 
 ```text
@@ -489,7 +577,7 @@ The same verdict reaches the browser, per request, with `express.serverTiming()`
 Server-Timing: route;desc="native", hdr;desc="not copied", db;dur=3.62, total;dur=4.66
 ```
 
-`route;desc="native"` means µWS matched the path in C++ and the chain was worked out at startup; `route;desc="router"` means this one was matched here, layer by layer. `res.timing(name, ms, desc)` and `res.time(name, fn)` add marks of your own, and `fn` may return a promise. The duration ends where the header does, since Server-Timing goes out with the head. A route compiled into a response never enters JavaScript, so nothing times it: `npx fulmine.js profile` is where those are counted. Runnable: [`examples/server-timing.js`](./examples/server-timing.js).
+`route;desc="native"` means µWS matched the path in C++ and the chain was worked out at startup; `route;desc="router"` means this one was matched here, layer by layer. `res.timing(name, ms, desc)` and `res.time(name, fn)` add marks of your own, and `fn` may return a promise. The duration ends where the header does, since Server-Timing goes out with the head. A route compiled into a response never enters JavaScript, so nothing times it: `npx fulmine.js profile` is where those are counted. The same middleware writes `work;desc="headers, query"` when the request built something a fast one does not, the fields `expectLazy` checks, and writes nothing when it built none of them. `serverTiming({ work: false })` turns that off. Runnable: [`examples/server-timing.js`](./examples/server-timing.js).
 
 2. Do not use external `serve-static` module. Instead use built-in `express.static()` middleware, which is optimized for Fulmine. If your build already writes `.br` and `.gz` files next to the originals, `express.static(dir, { preCompressed: true })` serves those to the clients that accept them, so nothing is compressed at request time and a fraction of the bytes goes out: on a 4KB script with a brotli twin, 12 times fewer. It costs no more than serving the file itself, one `stat` per request, because the twin is looked for before the file and its own `stat` is the only one the request needs. A type that is already compressed, a woff2 or a webp, is not looked up at all, and which twins a path has is remembered for a second: `{ cache: false }` asks the disk every time, `{ cache: "5s" }` sets the window. Only their presence is remembered, never their size or mtime, so nothing is ever described by a stale number. `Vary: Accept-Encoding` is sent whether or not a twin is found, the content type stays the one the requested name implies, and each variant carries its own ETag. Runnable: [`examples/static-precompressed.js`](./examples/static-precompressed.js).
 
@@ -677,7 +765,7 @@ In general, basically all features and options are supported. Use the [Express 5
 - ✅ 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.testing. Fulmine's own: `expectNative`, `expectDeclarative`, `routeReport`, `expectLazy` and `workReport`, 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)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.17.0",
+    "version": "5.18.1",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "exports": {

package/src/compression.js

@@ -26,6 +26,9 @@ limitations under the License.
 //     write produce the same deflate output.
 //   - partial content is left alone. The compression module compresses a 206 as well, and the
 //     result is a byte range of the file described as gzip, which no client can decode.
+//   - zstd is on offer, which the compression module cannot do at all. It is ranked below brotli,
+//     so a client that takes both is answered exactly as it was before, and above gzip, which it
+//     beats on ratio and on time. A Node whose zlib has no zstd never offers it.
 //
 // The streaming half is the module's own design, because it is the right one: a transform stream,
 // its output written as it comes, and the drain listeners moved onto it so a pipe that fills up
@@ -42,18 +45,27 @@ const {
     ENCODING_BR,
     ENCODING_GZIP,
     ENCODING_DEFLATE,
+    ENCODING_ZSTD,
     memoizeByString
 } = require("./utils.js");
 
+// zstd arrived in node's zlib during the range of versions this supports, so whether it can be
+// answered at all is a question about the runtime rather than about the options
+const HAS_ZSTD = typeof zlib.zstdCompressSync === "function";
+
 // what the `encodings` option may name, and the mask each name contributes. identity is 0: an
 // uncompressed answer is always on offer, naming it only makes the list read complete
 const ENCODING_MASKS = new Map([
     ["br", ENCODING_BR],
+    ["zstd", ENCODING_ZSTD],
     ["gzip", ENCODING_GZIP],
     ["deflate", ENCODING_DEFLATE],
     ["identity", 0]
 ]);
 
+// everything on offer, which is everything the runtime can produce
+const ENCODING_DEFAULT = HAS_ZSTD ? ENCODING_ANY : ENCODING_ANY & ~ENCODING_ZSTD;
+
 // Cache-Control: no-transform forbids recoding the body, which is what this does
 const NO_TRANSFORM = /(?:^|,)\s*?no-transform\s*?(?:,|$)/;
 
@@ -77,8 +89,11 @@ function addVary(res) {
  */
 function noFlush() {}
 
-// what enforceEncoding is allowed to name, the compression module's list
+// what enforceEncoding is allowed to name, the compression module's list and ours
 const ENFORCEABLE = new Set(["gzip", "deflate", "identity", "br"]);
+if (HAS_ZSTD) {
+    ENFORCEABLE.add("zstd");
+}
 
 // Up to this many bytes a whole body is compressed on this thread, and above it on the libuv pool.
 // One call either way; what changes is who waits. A small body pays more for the hop onto the pool
@@ -87,6 +102,100 @@ const ENFORCEABLE = new Set(["gzip", "deflate", "identity", "br"]);
 // wins by 43% at 1.4KB and by 22% at 16KB, and loses by 32% at 32KB and by 90% at 78KB.
 const SYNC_LIMIT = 24 * 1024;
 
+const noop = () => {};
+
+/**
+ * A whole-body compressor that keeps one stream instead of letting zlib build and throw one away
+ * per call, which on a body under the sync limit costs more than the compression does. Same bytes,
+ * a third of the time.
+ *
+ * It is private node, and two things have to be held in place for it: close, because the FINISH
+ * that ends the member would otherwise take the binding with it, and the handle, which that same
+ * FINISH drops off the stream before returning. The probe then compresses each body twice and
+ * gives the whole thing up unless every answer matches `oneShot` exactly, so a node that does any
+ * of this differently gets the public API back and loses nothing but the speed.
+ *
+ * Only for the deflate formats. A brotli stream carries context across a reset and answers the
+ * second body with bytes that depend on the first.
+ *
+ * @param {() => any} create
+ * @param {number} finishFlag
+ * @param {(body: Buffer) => Buffer} oneShot
+ * @returns {(body: Buffer) => Buffer}
+ */
+function reusableCompressor(create, finishFlag, oneShot) {
+    let stream;
+    try {
+        stream = create();
+    } catch {
+        return oneShot;
+    }
+    const handle = stream._handle;
+    if (
+        typeof stream._processChunk !== "function" ||
+        typeof stream.reset !== "function" ||
+        !handle ||
+        typeof handle.close !== "function"
+    ) {
+        return oneShot;
+    }
+    const realClose = stream.close;
+    const realHandleClose = handle.close;
+    let broken = false;
+    // a compression is sync from its first byte to its last, so a second body can only arrive
+    // here from inside the first one; that one is answered the ordinary way
+    let busy = false;
+
+    // a stream given up on is left half finished, and an abandoned zlib handle emits later on its
+    // own: an uncaught "buffer error" and a dead process
+    const giveUp = () => {
+        broken = true;
+        try {
+            stream.on("error", noop);
+            stream.destroy();
+        } catch {
+            // it is on its way out either way
+        }
+        return oneShot;
+    };
+
+    const compress = (body) => {
+        if (broken || busy) {
+            return oneShot(body);
+        }
+        busy = true;
+        stream.close = noop;
+        handle.close = noop;
+        try {
+            // FINISH hands the member back and drops the handle off the stream on its way out,
+            // so the stream is only whole again once it is put back, and only reusable once reset
+            const out = Buffer.from(stream._processChunk(body, finishFlag));
+            stream._handle = handle;
+            stream.reset();
+            return out;
+        } catch {
+            stream._handle = handle;
+            giveUp();
+            return oneShot(body);
+        } finally {
+            stream.close = realClose;
+            handle.close = realHandleClose;
+            stream.removeAllListeners("error");
+            busy = false;
+        }
+    };
+
+    // twice per probe, because a stream that keeps state answers the first body correctly and the
+    // second one differently
+    for (const probe of [Buffer.alloc(64, 0x61), Buffer.from("{}".repeat(600))]) {
+        const expected = oneShot(probe);
+        if (!compress(probe).equals(expected) || !compress(probe).equals(expected)) {
+            return giveUp();
+        }
+    }
+    return compress;
+}
+
 /**
  * The default filter: whether the content type is worth compressing at all. A response with no
  * type is left alone, since nothing says what its bytes are.
@@ -151,11 +260,13 @@ function toBuffer(chunk, encoding) {
  * @param {string} [options.enforceEncoding] what to use when the request carries no
  *   Accept-Encoding at all. Default "identity", which is to say nothing is compressed.
  * @param {object} [options.brotli] brotli options, `params` included. The default quality is 4.
+ * @param {object} [options.zstd] zstd options, `params` included, node's own defaults otherwise.
  * @param {string[]} [options.encodings] the encodings this middleware may answer with, out of
- *   "br", "gzip" and "deflate". What is not named is never used, however the client ranks it: a
- *   server that prefers cheap gzip over brotli passes ["gzip", "deflate"]. An uncompressed answer
- *   is always on offer, and enforceEncoding stays its own explicit choice, outside this list.
- *   This option is fulmine's own, the compression module has no equivalent.
+ *   "br", "zstd", "gzip" and "deflate". What is not named is never used, however the client ranks
+ *   it: a server that prefers cheap gzip over brotli passes ["gzip", "deflate"], one that would
+ *   rather answer zstd than brotli passes ["zstd", "gzip"]. An uncompressed answer is always on
+ *   offer, and enforceEncoding stays its own explicit choice, outside this list. This option is
+ *   fulmine's own, the compression module has no equivalent.
  * @param {number} [options.level] zlib compression level, for gzip and deflate.
  * @param {number} [options.chunkSize] zlib chunk size.
  * @param {number} [options.memLevel] zlib memory level.
@@ -173,6 +284,9 @@ function compression(options) {
         [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
         ...(opts.brotli && /** @type {any} */ (opts.brotli).params)
     };
+    // node's default level, unlike brotli above: zstd at its default is already in the band where
+    // this middleware wants to be, and dropping it further buys nothing worth the ratio
+    const zstdOptions = { ...opts.zstd };
     const filter = opts.filter || shouldCompress;
     const enforceEncoding = opts.enforceEncoding || "identity";
     // bytes.parse reads "1kb" and hands back null for anything it cannot, an absent option
@@ -180,7 +294,7 @@ function compression(options) {
     const threshold = bytes.parse(/** @type {any} */ (opts.threshold)) ?? 1024;
     // the mask handed to the negotiation, built once here: a name nobody knows is a config
     // mistake and throws now rather than serving the wrong bytes later
-    let allowed = ENCODING_ANY;
+    let allowed = ENCODING_DEFAULT;
     if (opts.encodings !== undefined) {
         if (!Array.isArray(opts.encodings)) {
             throw new TypeError("encodings must be an array of encoding names");
@@ -191,10 +305,17 @@ function compression(options) {
             if (mask === undefined) {
                 throw new TypeError(`unknown encoding "${name}" in encodings`);
             }
+            if (mask === ENCODING_ZSTD && !HAS_ZSTD) {
+                throw new TypeError(`"zstd" needs a node whose zlib has zstd, and this one does not`);
+            }
             allowed |= mask;
         }
     }
 
+    // built on first use, so an application that never answers gzip keeps no stream alive
+    let gzipWhole;
+    let deflateWhole;
+
     /**
      * A whole body, compressed on this thread. Blocks the event loop for as long as it takes,
      * which is why only a small one comes here, see SYNC_LIMIT.
@@ -205,12 +326,25 @@ function compression(options) {
      */
     function compressWhole(method, body) {
         if (method === "gzip") {
-            return zlib.gzipSync(body, zlibOptions);
+            gzipWhole ??= reusableCompressor(
+                () => zlib.createGzip(zlibOptions),
+                zlib.constants.Z_FINISH,
+                (b) => zlib.gzipSync(b, zlibOptions)
+            );
+            return gzipWhole(body);
         }
         if (method === "br") {
             return zlib.brotliCompressSync(body, brotliOptions);
         }
-        return zlib.deflateSync(body, zlibOptions);
+        if (method === "zstd") {
+            return zlib.zstdCompressSync(body, zstdOptions);
+        }
+        deflateWhole ??= reusableCompressor(
+            () => zlib.createDeflate(zlibOptions),
+            zlib.constants.Z_FINISH,
+            (b) => zlib.deflateSync(b, zlibOptions)
+        );
+        return deflateWhole(body);
     }
 
     /**
@@ -225,6 +359,8 @@ function compression(options) {
             zlib.gzip(body, zlibOptions, done);
         } else if (method === "br") {
             zlib.brotliCompress(body, brotliOptions, done);
+        } else if (method === "zstd") {
+            zlib.zstdCompress(body, zstdOptions, done);
         } else {
             zlib.deflate(body, zlibOptions, done);
         }
@@ -241,6 +377,9 @@ function compression(options) {
         if (method === "br") {
             return zlib.createBrotliCompress(brotliOptions);
         }
+        if (method === "zstd") {
+            return zlib.createZstdCompress(zstdOptions);
+        }
         return zlib.createDeflate(zlibOptions);
     }
 

package/src/request.js

@@ -914,9 +914,11 @@ module.exports = class Request extends LazyReadable {
             if (this.#responseEnded) {
                 return;
             }
-            // ab.slice(0) copies the ArrayBuffer; uWS neuters `ab` after this callback,
-            // so a Buffer.from(ab) view would corrupt data left in the Readable queue.
-            const chunk = Buffer.from(ab.slice(0));
+            // The bytes are copied because uWS neuters `ab` when this callback returns, and a
+            // view of it would corrupt whatever is still queued. Buffer.from over a view rather
+            // than ab.slice(0): the slice allocates an ArrayBuffer of its own for every chunk,
+            // which on a small body costs several times the copying it is there to do.
+            const chunk = Buffer.from(new Uint8Array(ab));
             const accepted = this.push(chunk);
             // push() may synchronously end the response via a flowing-mode listener.
             if (!accepted && !isLast && !this.#responseEnded) {
@@ -1371,6 +1373,11 @@ module.exports = class Request extends LazyReadable {
             this._querySnap = capture.invalid === true ? false : capture;
             return out;
         }
+        // The other two parsers keep no snapshot, so they only leave the mark that says a parse
+        // happened: false is "there is nothing to replay", which is what the branch above already
+        // does for a query it cannot replay. Two stores next to two allocations.
+        this._querySnapRaw = this._rawQuery;
+        this._querySnap = false;
         if (qp === fastQueryParse) {
             return Object.assign(Object.create(null), fastQueryParse(this._rawQuery));
         }
@@ -1841,6 +1848,36 @@ module.exports = class Request extends LazyReadable {
         // would let a caller rewrite what routing reads
         return this.#rawHeadersEntries.slice();
     }
+
+    // The three below report work this request was made to do, for src/work.js: they exist because
+    // the state that answers them is private, and they compute nothing that was not already there.
+    // Reading one costs a load; not reading one costs nothing at all, which is the point.
+
+    /**
+     * Whether the folded `req.headers` object has been built. Most requests never ask for it, and
+     * a middleware that does puts it back on all of them.
+     * @returns {boolean}
+     */
+    get _headersBuilt() {
+        return this.#cachedHeaders !== null || this.#cachedDistinctHeaders !== null;
+    }
+
+    /**
+     * Whether the query string has been parsed. `req.query` caches nothing, so this says a parse
+     * happened and not how many.
+     * @returns {boolean}
+     */
+    get _queryParsed() {
+        return this._querySnapRaw !== undefined;
+    }
+
+    /**
+     * Whether the socket stand-in `req.connection` was allocated.
+     * @returns {boolean}
+     */
+    get _socketBuilt() {
+        return Boolean(this.#cachedConnection);
+    }
 };
 
 // req.header is req.get under Express's other name. On the prototype rather than an instance

package/src/response.js

@@ -470,6 +470,15 @@ module.exports = class Response extends LazyWritable {
         return this.#socket;
     }
 
+    /**
+     * Whether that socket was ever built, for src/work.js. `socket` itself answers null once the
+     * response is over, so it cannot be asked after the fact; this reads the field.
+     * @returns {boolean}
+     */
+    get _socketBuilt() {
+        return this.#socket !== null;
+    }
+
     /**
      * Hands everything queued to uWS as one write, which is where the saving is, and keeps the
      * backpressure the single write used to do.

package/src/router.js

@@ -708,7 +708,7 @@ function nativeDone(matched) {
                 this.router._endUnmatched(this.req, response);
             } catch (err) {
                 if (response.aborted || response.finished) {
-                    console.error(err);
+                    logError(this.router, err);
                 } else {
                     this.router._handleError(err, null, this.req, response);
                 }
@@ -731,7 +731,7 @@ function nativeFail(err) {
     queueMicrotask(() => {
         const response = this.res;
         if (response.aborted || response.finished) {
-            console.error(err);
+            logError(this.router, err);
         } else {
             this.router._handleError(err, null, this.req, response);
         }
@@ -1025,6 +1025,22 @@ function adoptPlainRequest(req, router) {
     req.app = req.app ?? router;
 }
 
+/**
+ * What express's logerror does. Its final handler prints the error it is about to answer with,
+ * unless the application runs under `env: "test"`, which is how its own suite stays quiet, and it
+ * prints the stack rather than the object. A falsy throw is not printed at all, since finalhandler
+ * only calls onerror when there is an error to call it with.
+ *
+ * @param {any} router the router whose settings decide it
+ * @param {any} err
+ * @returns {void}
+ */
+function logError(router, err) {
+    if (err && router.get("env") !== "test") {
+        console.error(err.stack || err.toString());
+    }
+}
+
 /**
  * The uWS onAborted handler, bound to the response: a closure here captured two locals and cost
  * a context plus a function per request, for a path that only ever runs on a client abort.
@@ -2832,7 +2848,7 @@ module.exports = class Router extends EventEmitter {
                 return request.next(thrown);
             }
         }
-        console.error(err);
+        logError(this, err);
         if (response.statusCode === 200) {
             // the status the error carries, as express's own final handler reads it: a body that
             // was too large or a request cut short is the client's 4xx, not a 500 from here

package/src/server-timing.js

@@ -30,12 +30,20 @@ limitations under the License.
 // enters javascript, so no middleware runs on it and there is nothing to time. `npx fulmine
 // profile` is where those are counted.
 //
+// The other field only this framework can write is `work`, which names what the request was made to
+// build: the folded headers object, the parsed query, the body, the Readable, the Writable, the
+// socket stand-in. A fast request builds none of them and the field is absent, so it appears
+// exactly when something is worth looking at. See src/work.js.
+//
 // 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.
+// everything up to the moment the answer starts leaving, and not the body after it, and `work` has
+// the same boundary: a stream built by the write that carries the head is built after this is
+// written. Every stopwatch middleware has that boundary; this one says so.
 
 "use strict";
 
+const { work, names } = require("./work.js");
+
 /**
  * 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.
@@ -61,6 +69,8 @@ function describe(text) {
  *
  * @param {object} [options]
  * @param {boolean} [options.routing] whether to report how the request was routed. Default true.
+ * @param {boolean} [options.work] whether to report what the request was made to build. Default
+ *   true. Nothing is written for a request that built none of it, which is the usual one.
  * @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}
@@ -68,6 +78,7 @@ function describe(text) {
 function serverTiming(options) {
     const opts = options || {};
     const routing = opts.routing !== false;
+    const wantsWork = opts.work !== false;
     const wantsTotal = opts.total !== false;
     const totalName = opts.name || "total";
 
@@ -155,6 +166,16 @@ function serverTiming(options) {
                     }
                 }
             }
+            if (wantsWork) {
+                // what this one request made the framework build, which the route verdict above
+                // cannot say: a native route still folds the headers if a middleware reads them,
+                // and that is per request, not per route. Read at the head, so it covers the
+                // chain and not the body written after it, the same boundary as the total.
+                const listed = names(work(req, res));
+                if (listed.length !== 0) {
+                    entries.push(`work;desc=${describe(listed.join(", "))}`);
+                }
+            }
             entries.push(...marks);
             if (wantsTotal) {
                 entries.push(`${totalName};dur=${millis(process.hrtime.bigint() - started)}`);

package/src/testing.js

@@ -28,6 +28,8 @@ limitations under the License.
 
 "use strict";
 
+const { work, names: workNames } = require("./work.js");
+
 /**
  * Every route of an application and of the routers mounted under it, each with the path it answers
  * from the outside.
@@ -222,4 +224,58 @@ function expectDeclarative(app, patterns) {
     );
 }
 
-module.exports = { routeReport, expectNative, expectDeclarative, collectRoutes };
+/**
+ * What this one request made the framework do, asked from inside a handler or from a `finish`
+ * listener. See src/work.js for what each field means and why asking is free.
+ *
+ * @param {any} req
+ * @param {any} res
+ * @returns {import("./work.js").Work}
+ */
+function workReport(req, res) {
+    return work(req, res);
+}
+
+// The work a fast request does none of, which is what expectLazy is about. The route verdict is
+// not in here: expectNative and expectDeclarative are what assert on that.
+const LAZY = ["headers", "query", "body", "requestStream", "responseStream", "socket"];
+
+/**
+ * Throws if this request built anything it did not have to.
+ *
+ * The route verdict is a property of the application and holds for every request; this is the
+ * other half, which holds for one. A route can stay native and still slow down request by request,
+ * because a middleware read `req.headers.host` or piped instead of sending: the answer stays
+ * correct, the route report stays green, and the throughput does not.
+ *
+ * `allow` names what is fine here, which is most of the point: a route that parses a body is
+ * asserted as one that parses a body and nothing else.
+ *
+ * @param {any} req
+ * @param {any} res
+ * @param {object} [options]
+ * @param {string[]} [options.allow] fields of the report this route is expected to do anyway
+ */
+function expectLazy(req, res, options) {
+    const allowed = options?.allow ?? [];
+    for (const field of allowed) {
+        if (!LAZY.includes(field)) {
+            throw new TypeError(`expectLazy: "${field}" is not one of ${LAZY.join(", ")}`);
+        }
+    }
+    const done = work(req, res);
+    const unwanted = { ...done };
+    for (const field of allowed) {
+        /** @type {any} */ (unwanted)[field] = false;
+    }
+    const listed = workNames(unwanted);
+    if (listed.length === 0) {
+        return;
+    }
+    throw new Error(
+        `${req.method} ${req.originalUrl} did work a fast request does not: ${listed.join(", ")}.\n` +
+            `Run \`npx fulmine explain ${req.route?.path ?? req.path}\` to see what the chain asks for.`
+    );
+}
+
+module.exports = { routeReport, expectNative, expectDeclarative, collectRoutes, workReport, expectLazy };

package/src/types.d.ts

@@ -41,6 +41,17 @@ declare module "fulmine.js" {
 
         // express has no compression middleware, so there is nothing to re-export: these are the
         // compression module's options, which this one takes as they are
+        /**
+         * What zlib takes for zstd, written out here rather than imported from "zlib": the type
+         * arrived in @types/node only when node grew zstd, and the version of that is the
+         * consumer's, so importing it would stop an older one from compiling at all.
+         */
+        interface ZstdCompressOptions {
+            chunkSize?: number;
+            maxOutputLength?: number;
+            /** zlib.constants.ZSTD_c_* to their values, ZSTD_c_compressionLevel included. */
+            params?: Record<number, number>;
+        }
         interface CompressionOptions extends ZlibOptions {
             /** The smallest body worth compressing, in bytes or as "1kb". Default 1024. */
             threshold?: number | string;
@@ -50,12 +61,14 @@ declare module "fulmine.js" {
             enforceEncoding?: string;
             /** Brotli options. The default quality is 4. */
             brotli?: BrotliOptions;
+            /** Zstd options. Node's own defaults. Offered only where zlib has zstd. */
+            zstd?: ZstdCompressOptions;
             /**
              * The encodings this middleware may answer with; what is not named is never used,
              * however the client ranks it. Fulmine's own option, the compression module has no
              * equivalent. An uncompressed answer is always on offer.
              */
-            encodings?: ("br" | "gzip" | "deflate" | "identity")[];
+            encodings?: ("br" | "zstd" | "gzip" | "deflate" | "identity")[];
         }
         // what listen() decided about each route, for a test to hold on to
         interface RouteVerdict {
@@ -74,6 +87,26 @@ declare module "fulmine.js" {
             /** Why it fell back to the ordinary router, when it did. */
             reason?: string;
         }
+        // what one request was made to build, none of which a fast request builds
+        interface WorkReport {
+            /** Whether µWS matched this route itself. */
+            native: boolean;
+            /** Whether it was compiled into a response written at startup. */
+            declarative: boolean;
+            /** Whether the folded `req.headers` object was built. */
+            headers: boolean;
+            /** Whether the query string was parsed. */
+            query: boolean;
+            /** Whether a body parser put something on `req.body`. */
+            body: boolean;
+            /** Whether the request became a real Readable. */
+            requestStream: boolean;
+            /** Whether the response became a real Writable. */
+            responseStream: boolean;
+            /** Whether a socket stand-in was allocated. */
+            socket: boolean;
+        }
+        type WorkField = "headers" | "query" | "body" | "requestStream" | "responseStream" | "socket";
         export namespace testing {
             /** Every route, with what compiling it decided. */
             function routeReport(app: Fulmine): RouteVerdict[];
@@ -81,6 +114,10 @@ declare module "fulmine.js" {
             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;
+            /** What this one request was made to build, asked from a handler or a finish listener. */
+            function workReport(req: e.Request, res: e.Response): WorkReport;
+            /** Throws if this request built anything `allow` does not name. */
+            function expectLazy(req: e.Request, res: e.Response, options?: { allow?: WorkField[] }): void;
         }
 
         // Server-Timing, carrying how the request was routed. Express has no such middleware, so
@@ -88,6 +125,11 @@ declare module "fulmine.js" {
         interface ServerTimingOptions {
             /** Whether to report how the request was routed. Default true. */
             routing?: boolean;
+            /**
+             * Whether to report what the request was made to build. Default true. A request that
+             * built none of it writes no such field.
+             */
+            work?: boolean;
             /** Whether to report the time up to the head. Default true. */
             total?: boolean;
             /** What the total is called. Default "total". */

package/src/utils.js

@@ -849,7 +849,8 @@ function stringify(value, replacer, spaces, escape) {
 const ENCODING_BR = 1;
 const ENCODING_GZIP = 2;
 const ENCODING_DEFLATE = 4;
-const ENCODING_ANY = ENCODING_BR | ENCODING_GZIP | ENCODING_DEFLATE;
+const ENCODING_ZSTD = 8;
+const ENCODING_ANY = ENCODING_BR | ENCODING_GZIP | ENCODING_DEFLATE | ENCODING_ZSTD;
 
 /**
  * The encoding to answer with, read straight off Accept-Encoding rather than through negotiator:
@@ -864,12 +865,15 @@ const ENCODING_ANY = ENCODING_BR | ENCODING_GZIP | ENCODING_DEFLATE;
  * answer is always on offer, and is what an empty header ends up choosing.
  *
  * @param {string} accept the header, or "" when the request carried none
- * @param {number} allowed ENCODING_BR, ENCODING_GZIP and ENCODING_DEFLATE, or'd together
- * @returns {string} "br", "gzip", "deflate", "identity", or "" when nothing is acceptable
+ * @param {number} allowed ENCODING_BR, ENCODING_ZSTD, ENCODING_GZIP and ENCODING_DEFLATE, or'd
+ *   together
+ * @returns {string} "br", "zstd", "gzip", "deflate", "identity", or "" when nothing is
+ *   acceptable
  */
 function negotiateEncoding(accept, allowed) {
     // -1 while a name has not appeared: q=0 is a refusal and has to be told apart from silence
     let br = -1;
+    let zstd = -1;
     let gzip = -1;
     let deflate = -1;
     let identity = -1;
@@ -907,6 +911,9 @@ function negotiateEncoding(accept, allowed) {
             case "gzip":
                 gzip = q;
                 break;
+            case "zstd":
+                zstd = q;
+                break;
             case "deflate":
                 deflate = q;
                 break;
@@ -920,6 +927,7 @@ function negotiateEncoding(accept, allowed) {
         index = end + 1;
     }
     if (br < 0) br = star;
+    if (zstd < 0) zstd = star;
     if (gzip < 0) gzip = star;
     if (deflate < 0) deflate = star;
     // An uncompressed answer that the request did not name is worth the lowest q it named
@@ -929,6 +937,7 @@ function negotiateEncoding(accept, allowed) {
     if (identity < 0) identity = star < 0 ? minQuality : star;
 
     if (!(allowed & ENCODING_BR)) br = -1;
+    if (!(allowed & ENCODING_ZSTD)) zstd = -1;
     if (!(allowed & ENCODING_GZIP)) gzip = -1;
     if (!(allowed & ENCODING_DEFLATE)) deflate = -1;
 
@@ -938,6 +947,12 @@ function negotiateEncoding(accept, allowed) {
         best = "br";
         bestQ = br;
     }
+    // Below brotli on a tie, on purpose: a client that takes both is answered the way it was
+    // answered before zstd was on the list. Above gzip, which it beats on both counts.
+    if (zstd > bestQ) {
+        best = "zstd";
+        bestQ = zstd;
+    }
     if (gzip > bestQ) {
         best = "gzip";
         bestQ = gzip;
@@ -1645,6 +1660,7 @@ module.exports = {
     ENCODING_BR,
     ENCODING_GZIP,
     ENCODING_DEFLATE,
+    ENCODING_ZSTD,
     ENCODING_ANY,
     memoizeByString,
     isRangeFresh,

package/src/work.js

@@ -0,0 +1,102 @@
+/*
+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 one request actually made this framework do, read from state it already keeps.
+//
+// Most of what makes this faster than Express is work that does not happen: the Readable and the
+// Writable are not built, the headers are not folded into an object, the query is not parsed, the
+// socket stand-in is not allocated. None of that is visible from the outside, and all of it is one
+// careless middleware away from coming back: a `req.headers.host` where `req.get("host")` would do
+// puts the folded object back on every request, and the answer stays correct, so nothing fails.
+//
+// Every field below is a property this framework already had to keep for its own reasons, so
+// asking costs a load and nothing is counted, stamped or wrapped for the sake of being asked. That
+// is the whole design rule here: a probe that charges the requests nobody is probing would be
+// paid for by everyone, forever, to be read once.
+//
+// What is deliberately not here is whether the constructor copied the headers out of µWS. That is
+// a decision about the chain rather than about the request, `routeReport().skipHeaders` reports it
+// already, and the one case where the two differ, a granted route whose request declares a body,
+// would cost a flag written on every request to be read on almost none.
+//
+// The two readers are `express.testing.expectLazy`, which fails a build that lost one of these,
+// and `express.serverTiming()`, which writes them into the header for a browser to show.
+
+"use strict";
+
+/**
+ * @typedef {object} Work
+ * @property {boolean} native whether µWS matched this route itself
+ * @property {boolean} declarative whether the route was compiled into a response at startup
+ * @property {boolean} headers whether the folded `req.headers` object was built
+ * @property {boolean} query whether the query string was parsed
+ * @property {boolean} body whether a body parser put something on `req.body`
+ * @property {boolean} requestStream whether the request became a real Readable
+ * @property {boolean} responseStream whether the response became a real Writable
+ * @property {boolean} socket whether a socket stand-in was allocated
+ */
+
+/**
+ * What this request did, as it stands right now: the answer changes while the chain runs, so a
+ * reader that wants the whole picture asks at the end of it.
+ *
+ * @param {any} req
+ * @param {any} res the response, since half of this is about the response
+ * @returns {Work}
+ */
+function work(req, res) {
+    const native = req.route?._native;
+    return {
+        native: Boolean(native),
+        declarative: Boolean(native?.declarative),
+        headers: req._headersBuilt,
+        query: req._queryParsed,
+        body: req.body !== undefined,
+        requestStream: req._readableState !== undefined,
+        responseStream: res._writableState !== undefined,
+        socket: req._socketBuilt || res._socketBuilt
+    };
+}
+
+// The order the two readers list them in: what the request was made to do, cheapest first, so a
+// header and a failure message read the same way.
+const NAMES = [
+    ["headers", "headers"],
+    ["query", "query"],
+    ["body", "body"],
+    ["requestStream", "req stream"],
+    ["responseStream", "res stream"],
+    ["socket", "socket"]
+];
+
+/**
+ * The names of everything that did happen, for a message or a header. Empty for the request that
+ * did none of it, which is the one this framework is built to serve.
+ *
+ * @param {Work} done
+ * @returns {string[]}
+ */
+function names(done) {
+    const listed = [];
+    for (const [key, name] of NAMES) {
+        if (/** @type {any} */ (done)[key]) {
+            listed.push(name);
+        }
+    }
+    return listed;
+}
+
+module.exports = { work, names };