fulmine.js 5.10.0 → 5.11.1

package/README.md

@@ -43,6 +43,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
 - [Difference from similar projects](#difference-from-similar-projects)
 - [Migrating](#migrating)
     - [Angular SSR](#angular-ssr)
+    - [NestJS](#nestjs)
     - [When Express is somebody else's dependency](#when-express-is-somebody-elses-dependency)
 - [Docker](#docker)
 - [Differences from Express](#differences-from-express)
@@ -172,6 +173,38 @@ that runs on Express and here alike, and the same measurement says a page costs
 stores only the body makes the server hash the whole document again on every hit, and measures level
 with no cache at all on the serving side.
 
+### NestJS
+
+`@nestjs/platform-express` takes an Express instance, so it takes this one, and everything in a Nest
+application keeps working. One line stands between that and the speed: the adapter wraps whatever
+instance it is given in `http.createServer()` and listens on that, which is the shim, so every
+request goes through `node:http` and the application runs at Express's pace. The app here already
+answers as an `http.Server`, so it can be the server rather than being wrapped in one:
+
+```ts
+import { NestFactory } from "@nestjs/core";
+import { ExpressAdapter } from "@nestjs/platform-express";
+import fulmine from "fulmine.js";
+
+class FulmineAdapter extends ExpressAdapter {
+    initHttpServer() {
+        // instead of http.createServer(instance): listen() and close() are then µWS's
+        (this as any).httpServer = this.getInstance();
+    }
+}
+
+const app = await NestFactory.create(AppModule, new FulmineAdapter(fulmine()));
+await app.listen(3000);
+```
+
+Measured on the same Nest application, controllers, pipes and body parsing unchanged: **1.2x on a
+route answering text and 1.9x on one answering JSON with a route parameter**. `app.close()` closes
+the port, as it does on the shim.
+
+Two things to know. `forceCloseConnections` has nothing to destroy, since the sockets belong to µWS
+and nothing emits `connection`, and Nest looks at `app.router.stack` to decide whether it has
+already added its body parsers, which is not there, so it adds them once more than it would.
+
 ### When Express is somebody else's dependency
 
 A framework built on Express does not `require("express")` in your code, it requires it in its own,
@@ -349,15 +382,15 @@ routes get:
 
 1. Fulmine tries to optimize routing as much as possible, but it's only possible if:
 
-- the path is a plain string, or its parameters are whole segments: `/users/:id` and `/a/:b/c/:d` qualify, `/flights/:from-:to` does not, and neither does a `*splat` or a `{}` group. Routing is case-insensitive by default, as in Express; a request in the registered case is still served natively, any other case takes the ordinary path, and a route whose overlap with an earlier one leans on a cased literal goes the ordinary way for every request.
+- the path is a plain string, or its parameters are whole segments: `/users/:id` and `/a/:b/c/:d` qualify, `/flights/:from-:to` does not, and neither does a `*splat` or a `{}` group. Routing is case-insensitive by default, as in Express; a request in the registered case is still served natively, any other case takes the ordinary path, and a route whose overlap with an earlier one leans on a cased literal goes the ordinary way for every request. That last one is worth knowing about: `app.set("case sensitive routing", true)` is Express's own setting, and with it `/Users/list` no longer overlaps `/users/:id`, so both are matched by µWS instead of one of them falling back.
 - inside a mounted router, nothing registered after the route in that router could match the same path. `/orders/:id`, `/orders/:id/items` and `/invoices/:id` are all optimized together, since no request reaches two of them. `/users/:id` followed by `/users/me` is not: Express answers `/users/me` with the first of the two and the native router would answer it with the second, so both go the ordinary way.
 
 Optimized routes can be up to 10 times faster than normal routes, as they're using native uWS router and have pre-calculated path.
 
-On top of that, a handler simple enough to be read at registration time is compiled into a uWS declarative response and answered natively, without entering JavaScript at all. That needs the route to have nothing in front of it, not a middleware and not a `Router` it was mounted under, and a single handler that only calls `res.status`, `res.set`, `res.append`, `res.send`, `res.json`, `res.sendStatus` or `res.end` with literal arguments, plus `req.params` and `req.query`. Anything else, a variable, a call, an `if`, falls back to ordinary routing. `return res.send(...)` compiles, `res.send(...)` does too, and so does an object or an array of literals however deeply nested. Mounting a `Router` costs only this: the routes inside one are still registered on the native uWS router with their full path, and are as fast as any other optimized route. Three things follow from the response being static:
+On top of that, a handler simple enough to be read at registration time is compiled into a uWS declarative response and answered natively, without entering JavaScript at all. That needs the route to have nothing in front of it, not a middleware and not a `Router` it was mounted under, and a single handler that only calls `res.status`, `res.set`, `res.type`, `res.append`, `res.send`, `res.json`, `res.sendStatus` or `res.end` with literal arguments, plus `req.params` and `req.query`. `res.set` takes a pair or a whole object of them, and `res.type` takes what it takes anywhere, since a media type is a lookup on a literal. Anything else, a variable, a call, an `if`, falls back to ordinary routing. `return res.send(...)` compiles, `res.send(...)` does too, and so does an object or an array of literals however deeply nested. Mounting a `Router` costs only this: the routes inside one are still registered on the native uWS router with their full path, and are as fast as any other optimized route. Three things follow from the response being static:
 
 - it cannot answer `304 Not Modified`. The ETag is still sent, so caches keep working, but a conditional request gets the whole body back rather than an empty 304. Express replies 304 there.
-- it is framed as `Transfer-Encoding: chunked` and carries no `Content-Length`, because uWS writes that framing itself.
+- it carries a `Content-Length` while its body is literal all the way through. A body with a piece taken from the request, `res.send(req.params.id)`, has no length until the request arrives, so that one is framed as `Transfer-Encoding: chunked`. uWS writes the framing either way, which is why neither header can be set by hand.
 - it answers `Connection: keep-alive` even to a request that asked for `Connection: close`. The connection is still closed, since uWS decides that itself, and a client that asked to close is closing anyway.
 
 `app.set("declarative responses", false)` turns the whole thing off if you would rather have Express's exact framing than the speed.
@@ -440,11 +473,11 @@ app.use(express.compression({ threshold: 1024 }));
 
 Runnable: [`examples/compression.js`](./examples/compression.js).
 
-5. If a route answers with a JSON shape you know in advance, [express-fast-json-stringify](https://www.npmjs.com/package/express-fast-json-stringify) compiles that shape into a serializer and `res.fastJson()` replaces `res.json()`. `JSON.stringify()` has to walk an object it knows nothing about; a compiled serializer does not.
+5. If a route answers with a JSON shape you know in advance, [express-fast-json-stringify](https://www.npmjs.com/package/express-fast-json-stringify) compiles that shape into a serializer and `res.fastJson()` replaces `res.json()`. `JSON.stringify()` has to walk an object it knows nothing about; a compiled serializer does not. It is worth reaching for, and a CPU profile says why: on a route answering 3.6KB of JSON, serialising it is about 25% of the time that is not spent waiting, ahead of the ETag at 19% and of everything the framework does to route the request and build its request and response objects.
 
 6. Do not set `body methods` to read body of requests with GET method or other methods that don't need a body. Reading body makes endpoint about 15% slower.
 
-7. `app.set("etag", false)` is worth about 8% on small responses, measured on both Fulmine and Express, which pay it almost identically. Know what you are trading: without an ETag a client cannot make a conditional request, so there are no `304 Not Modified` replies and every response is downloaded in full. On anything cacheable the bandwidth a 304 saves is usually worth far more than the 8%. It is left on by default for that reason. Turn it off for an API whose responses are never revalidated.
+7. `app.set("etag", false)` is worth about 8% on small responses, measured on both Fulmine and Express, which pay it almost identically. It is the single biggest thing an ordinary route does: in a CPU profile of one, hashing the body and building the tag are about 21% of the time that is not spent waiting, more than writing the headers and more than building the request and the response together. Know what you are trading: without an ETag a client cannot make a conditional request, so there are no `304 Not Modified` replies and every response is downloaded in full. On anything cacheable the bandwidth a 304 saves is usually worth far more than the 8%. It is left on by default for that reason. Turn it off for an API whose responses are never revalidated.
 
 8. By default, Fulmine creates 1 (or 0 if your CPU has only 1 core) child thread to improve performance of reading files. You can change this number by setting `threads` to a different number in `express()`, or set to 0 to disable thread pool (`express({ threads: 0 })`). Threads are shared between all express() instances, with largest `threads` number being used. Using more threads will not necessarily improve performance. Sometimes not using threads at all is faster, so measure both.
 
@@ -667,10 +700,12 @@ Two of these keep a compiled form alongside the value, which you can also set di
 - `etag fn`, the function that produces an ETag. Setting `etag` compiles one; setting this replaces it.
 - `query parser fn`, likewise for `query parser`.
 
-Fulmine adds three of its own:
+Fulmine adds five of its own:
 
 - `declarative responses`, on by default. Lets a simple enough handler be compiled into a native uWS response, described under [Performance tips](#performance-tips).
+- `connection headers`, on by default. Express sends `Connection: keep-alive` and `Keep-Alive` on every response, and so does this. Turn it off and neither goes out, while a connection the client asked to close still answers `Connection: close`: it is the advertisement that goes, not the truth. Worth 2% to 3.5% here on a route that is not compiled, plus the bytes.
 - `file cache`, on by default. Small files served by `res.sendFile` come from a bounded in-process cache, checked against the file's `stat` on every request, so an edited file is never served stale. Turn it off where every request has to reach the disk, which is what a public benchmark asks of a standard entry: it was worth about 4% on a 4KB file here, so the cost of turning it off is small.
+- `stat cache`, off by default. Takes a duration, `app.set("stat cache", "1s")`. The size and mtime of a file served by `res.sendFile` or `express.static` are remembered for that long, so a file that is asked for again inside the window costs no syscall at all. It was worth 15% on a 3KB file and 3% on a 200KB one, where the bytes are the work. What it costs is the one promise the `file cache` keeps: inside the window an edited file is served as it was, so keep the window shorter than you would notice.
 - `trust proxy protocol`, off by default. Takes `req.ip` from a PROXY protocol preamble, described under [Behind a proxy](#behind-a-proxy). Read the warning there before turning it on.
 
 ### Request

package/package.json

@@ -1,11 +1,10 @@
 {
     "name": "fulmine.js",
-    "version": "5.10.0",
+    "version": "5.11.1",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
-        "fulmine": "src/cli.js",
-        "fulmine.js": "src/cli.js"
+        "fulmine": "src/cli.js"
     },
     "scripts": {
         "test": "node tests/index.js",

package/src/application.js

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

package/src/declarative.js

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

package/src/middlewares.js

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

package/src/response.js

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

package/src/utils.js

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

package/src/verify.js

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