fulmine.js 5.8.0 → 5.10.0

package/README.md

@@ -18,12 +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
+npx fulmine.js verify              # can this machine and this image even run it
+npx fulmine.js migrate --dry-run   # say what it would change, change nothing
+npx fulmine.js migrate             # do it
+npx fulmine.js differences         # just the list of what to check by hand
+npx fulmine.js profile             # what listen() decided about each route
+npx fulmine.js 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.
@@ -61,6 +61,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
     - [Router](#router)
 - [Tested middlewares](#tested-middlewares)
 - [Tested view engines](#tested-view-engines)
+- [Examples](./examples/README.md)
 - [Working on Fulmine](./CONTRIBUTING.md)
 
 ## Why this exists
@@ -115,22 +116,19 @@ It is likewise not affiliated with the OpenJS Foundation or the Express.js proje
 
 ## Migrating
 
-In a lot of cases, replacing `require("express")` with `require("fulmine.js")` is the whole migration. `npx fulmine migrate` does that across a project:
+In a lot of cases, replacing `require("express")` with `require("fulmine.js")` is the whole migration. `npx fulmine.js migrate` does that across a project:
 
 ```sh
-npx fulmine migrate [dir]       # defaults to the current directory
-npx fulmine migrate --dry-run   # say what it would rewrite and rewrite nothing
-npx fulmine differences         # print the list below and change nothing
+npx fulmine.js migrate [dir]       # defaults to the current directory
+npx fulmine.js migrate --dry-run   # say what it would rewrite and rewrite nothing
+npx fulmine.js differences         # print the list below and change nothing
 ```
 
-The command is installed under both `fulmine` and `fulmine.js`. Use `fulmine`: `npx` cannot run a
-command whose name ends in `.js` on Windows, where it exits without a word.
-
 It also names the middlewares it found that have a faster one built in here, `compression`,
 `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
+`npx fulmine.js 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
@@ -248,7 +246,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`, 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`.
+- `app.listen()` returns the app rather than a separate server object, and the app answers as an `http.Server`: `app instanceof http.Server` is true, which is what the graceful shutdown wrappers and the connection trackers look for. There is still no node server underneath, the socket belongs to µWS, so what is answered is the surface and not the plumbing. There: `close()`, `address()`, `listening`, `getConnections()`, `ref()`, `unref()`, `setTimeout()` and the `keepAliveTimeout` family. Not there: nothing emits `connection`, `request` or `upgrade`, `getConnections()` counts the requests in flight rather than sockets, and the timeouts belong to µWS and are set through `uwsOptions.idleTimeout`. Anything that wants to serve its own protocol on the socket, socket.io being the usual case, still wants `app.uwsApp`. Runnable: [`examples/graceful-shutdown.js`](./examples/graceful-shutdown.js).
 - `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`.
@@ -291,6 +289,8 @@ app.listen(3000, () => {
 });
 ```
 
+Runnable: [`examples/https.js`](./examples/https.js).
+
 - This also applies to non-SSL HTTP too. Use `app.listen()` rather than creating a server by hand. `http.createServer(app)` does work, because the app is a request listener like Express's and answers node's requests through a shim, which is what lets `supertest`, `vhost` and anything else that calls an app keep working. But it serves those requests through `node:http` rather than through µWS, so the speed is Express's. It is there for compatibility, not for production.
 - Node.JS max header size is 16384 bytes, while uWebSockets by default is 4096 bytes, so if you need longer headers set the env variable `UWS_HTTP_MAX_HEADERS_SIZE` to max byte count you need.
 - uWebSockets drops a request whose body arrives slower than 16KB/s, and the timeout is not reachable from JavaScript, while Node.JS waits as long as the client needs. Uploads over very slow connections can therefore fail here and succeed on Express. A body stalled for 5 seconds still completes; one stalled for 12 seconds gets its socket reset at around 11.8 seconds.
@@ -325,7 +325,7 @@ arriving at a handler costs no matching at all:
 That is the whole difference on a large route table: the scan grows with the table and the match
 does not, which is why a thousand routes measure 10x and a handful measure 3x.
 
-Two more things happen on the way in, and `npx fulmine profile` will tell you which of them your
+Two more things happen on the way in, and `npx fulmine.js profile` will tell you which of them your
 routes get:
 
 ```text
@@ -362,11 +362,11 @@ On top of that, a handler simple enough to be read at registration time is compi
 
 `app.set("declarative responses", false)` turns the whole thing off if you would rather have Express's exact framing than the speed.
 
-None of that is guesswork you have to do from the outside. `listen()` decides it all, and `npx fulmine profile` prints what it decided:
+None of that is guesswork you have to do from the outside. `listen()` decides it all, and `npx fulmine.js profile` prints what it decided:
 
 ```sh
-npx fulmine profile              # the file package.json's "main" points at
-npx fulmine profile server.js    # or name it
+npx fulmine.js profile              # the file "main" or the start script points at
+npx fulmine.js profile server.js    # or name it
 ```
 
 ```text
@@ -403,9 +403,9 @@ 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.
+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).
 
-`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.
+`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
 GET /api/items/:id
@@ -425,9 +425,9 @@ 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 profile` is where those are counted.
+`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).
 
-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.
+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).
 
 3. Do not use `body-parser` module. Instead use built-in `express.text()`, `express.json()` etc.
 
@@ -438,6 +438,8 @@ Server-Timing: route;desc="native", hdr;desc="not copied", db;dur=3.62, total;du
 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.
 
 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.
@@ -446,9 +448,26 @@ app.use(express.compression({ threshold: 1024 }));
 
 8. By default, Fulmine creates 1 (or 0 if your CPU has only 1 core) child thread to improve performance of reading files. You can change this number by setting `threads` to a different number in `express()`, or set to 0 to disable thread pool (`express({ threads: 0 })`). Threads are shared between all express() instances, with largest `threads` number being used. Using more threads will not necessarily improve performance. Sometimes not using threads at all is faster, so measure both.
 
+9. One node process uses one core, and this is the setting that changes it. `express({ cluster: "auto" })` forks one process per core and each of them binds the same port with µWS's shared flag, which is `SO_REUSEPORT`: every process has its own listening socket and the kernel decides which one gets each connection. Node's own `cluster` cannot do that with an `http.Server`, so the primary holds the socket and passes each accepted connection to a worker over IPC; here the primary is not in the path at all. On a 16-core machine that is close to 16 times the throughput, and no other setting comes near it.
+
+```js
+// "auto" is one worker per usable core: the cgroup quota is read first, so a 2-core container
+// on a 64-core host forks 2 and not 64. A number instead of "auto" says how many.
+const app = express({ cluster: "auto" });
+
+app.get("/", (req, res) => res.send("hello"));
+
+// The whole file runs again in every worker, which is how cluster works: the code above this
+// line runs once per process. The primary only forks, so the callback runs once per worker too,
+// and a worker that dies is replaced.
+app.listen(3000, () => console.log(`worker ${process.pid} listening`));
+```
+
+Anything held per process is now held per worker: an in-memory cache, a rate-limit counter, a session store or a `Map` of connected sockets is not shared, and needs Redis or something like it to be. `app.close()` in the primary stops the workers, and a `SIGTERM` or `SIGINT` that reaches only the primary, which is what a container sends, is passed on to them. Runnable: [`examples/cluster.js`](./examples/cluster.js).
+
 ## WebSockets
 
-`app.ws()` registers a WebSocket route, served by µWS itself. There is no `http.Server` underneath, so `http.on("upgrade")` and the libraries built on it do not apply; this is the replacement.
+`app.ws()` registers a WebSocket route, served by µWS itself. The upgrade never reaches node, so `server.on("upgrade")` and the libraries built on it have nothing to hear; this is the replacement.
 
 ```js
 app.ws("/room/:id", {
@@ -476,14 +495,14 @@ app.ws("/room/:id", {
 - **Paths are the ones µWS matches**: literal, or with parameters that are a whole segment such as `/room/:id`. Anything else throws where it is written rather than failing to match later.
 - **Broadcasting from outside a socket**: `app.publish(topic, message)` and `app.numSubscribers(topic)`.
 
-A WebSocket route and an ordinary route can share a path: the upgrade goes to the WebSocket route, a plain GET goes through normal routing.
+A WebSocket route and an ordinary route can share a path: the upgrade goes to the WebSocket route, a plain GET goes through normal routing. Runnable, with a page that opens the socket: [`examples/websocket.js`](./examples/websocket.js).
 
 If you would rather use the `ws` module's API, [Ultimate WS](https://github.com/dimdenGD/ultimate-ws) is a drop-in replacement for it written against Ultimate Express, and Fulmine still exposes the mechanism it hooks into, but that combination is not covered by this project's tests. `app.uwsApp` also remains available for anything µWS offers that this does not.
 
 ### socket.io
 
-socket.io normally takes over the upgrade on a node `http.Server`. There isn't one here, so hand it
-the µWS app instead, which socket.io supports natively through `attachApp()`:
+socket.io normally takes over the upgrade on a node `http.Server`. The upgrade here never reaches
+node, so hand it the µWS app instead, which socket.io supports natively through `attachApp()`:
 
 ```js
 const express = require("fulmine.js");
@@ -500,10 +519,14 @@ io.on("connection", (socket) => {
 });
 ```
 
-`attachApp()` works before or after `app.listen()`. What does not work is `new Server(server)` on the
-value `app.listen()` returns: plain HTTP keeps serving, but the WebSocket upgrade fails, because
-that object is not a real `http.Server`. This is covered by `tests/tests/middlewares/socket-io.js`,
-which runs the same file against Express and against Fulmine and compares the output.
+`attachApp()` works before or after `app.listen()`. What does not work is `new Server(app)` on the
+app itself, or on what `app.listen()` returns, which is the same object: socket.io refuses it with
+"You are trying to attach socket.io to an express request handler function", because it checks for a
+function before it checks for a server, and an app here is callable. That refusal is the useful
+answer. Even if it accepted the object, there is no node socket behind it to take an upgrade over,
+so it would have failed later and more quietly. Plain HTTP keeps serving either way. This is covered
+by `tests/tests/middlewares/socket-io.js`, which runs the same file against Express and against
+Fulmine and compares the output. Runnable: [`examples/socket-io.js`](./examples/socket-io.js).
 
 ## HTTP/3
 
@@ -544,7 +567,9 @@ app.set("trust proxy protocol", true);
 
 `trust proxy` and this can both be on. The preamble decides what the connection's address is, and
 `trust proxy` then peels `X-Forwarded-For` off that, so a proxy that sends both is read the way it
-meant.
+meant. It is the binary v2 preamble that µWS reads, not the v1 text line, so a connection starting
+with `PROXY TCP4 ...` is answered as a malformed request. Runnable, with a client that writes one:
+[`examples/proxy-protocol.js`](./examples/proxy-protocol.js).
 
 ## Versioning
 
@@ -792,7 +817,25 @@ Any Express view engine should work. Here's list of engines we include in our te
 - ✅ [express-handlebars](https://npmjs.com/package/express-handlebars)
 - ✅ [swig](https://npmjs.com/package/swig)
 
+## Examples
+
+[`examples/`](./examples/README.md) has one runnable file per thing this does that Express does not:
+the cluster option, `app.ws()`, socket.io through `attachApp`, the pre-compressed twins,
+`express.compression()`, `express.serverTiming()`, TLS through `uwsOptions`, the PROXY protocol,
+what `listen()` decided about each route, and the app answering as an `http.Server`. What an
+Express application already does is documented by Express and is not repeated there.
+
+```sh
+cd examples
+npm install
+node websocket.js
+```
+
 ## Working on Fulmine
 
 How to run the suites, what each of them is for, and how to write a comparison test:
-[`CONTRIBUTING.md`](./CONTRIBUTING.md).
+[`CONTRIBUTING.md`](./CONTRIBUTING.md). What is expected of everyone taking part:
+[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
+
+Found something exploitable? Report it privately rather than in an issue, and see
+[`SECURITY.md`](./SECURITY.md) for what is in scope and what to expect.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.8.0",
+    "version": "5.10.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -29,9 +29,7 @@
         "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 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"
+        "examples:install": "npm --prefix examples install"
     },
     "engines": {
         "node": ">=22"

package/src/application.js

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

package/src/cli.js

@@ -304,7 +304,40 @@ function walk(node, visit) {
 const DEFAULT_ENTRIES = ["server.js", "app.js", "index.js", "src/server.js", "src/app.js", "src/index.js"];
 
 /**
- * The file to load, from the argument, or from package.json's main, or from the usual names.
+ * The file a start script runs, when it runs node on one.
+ *
+ * "main" is about what a package exports, and a service usually exports nothing: the entry of a
+ * deployed application is far more often the one written here, which is also the only place that
+ * knows about a src/ or a bin/ the usual names do not cover.
+ *
+ * @param {unknown} script the "start" script, as package.json wrote it
+ * @returns {string|null}
+ */
+function entryFromScript(script) {
+    if (typeof script !== "string") {
+        return null;
+    }
+    const words = script.split(/\s+/).filter(Boolean);
+    if (!/^(node|nodejs)$/.test(path.basename(words[0] ?? "", ".exe"))) {
+        // ts-node, nodemon, a shell pipeline: what that runs is not a file this can load
+        return null;
+    }
+    for (const word of words.slice(1)) {
+        if (word.startsWith("-")) {
+            continue; // --env-file=.env, --watch, and the rest of node's own flags
+        }
+        const candidate = path.resolve(word);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+        break; // the first thing that is not a flag is the file, and it is not there
+    }
+    return null;
+}
+
+/**
+ * The file to load, from the argument, from package.json's main or start script, or from the
+ * usual names.
  *
  * @param {string|undefined} given
  * @returns {string|null}
@@ -319,6 +352,12 @@ function findEntry(given) {
         if (pkg.main && fs.existsSync(path.resolve(pkg.main))) {
             return path.resolve(pkg.main);
         }
+        // a main that names a file nobody built, dist/server.js in a TypeScript project, is worth
+        // no more than no main at all
+        const started = entryFromScript(pkg.scripts?.start);
+        if (started) {
+            return started;
+        }
     } catch {
         // no package.json, or one that will not parse: the usual names are still worth trying
     }
@@ -331,6 +370,57 @@ function findEntry(given) {
     return null;
 }
 
+/**
+ * Every build of this library the application could load, as the prototype that owns listen().
+ *
+ * The command runs from its own copy, and the application loads whichever one resolves from its
+ * own directory. That is usually the same file and sometimes is not: a global install, an
+ * `npx fulmine.js@version`, a workspace that hoisted a second copy, or the `express` name pointing
+ * here through an override. Patching only this command's copy leaves the application's own listen()
+ * to bind the port, and the command then reports that the file built nothing.
+ *
+ * An app is a callable, so its own prototype is not the one that carries the methods: walk up to
+ * whichever link owns listen.
+ *
+ * @param {string} entry
+ * @returns {any[]} the prototypes to stub, this command's copy first
+ */
+function listenOwners(entry) {
+    const builds = new Set([require("./index.js")]);
+    for (const specifier of [TO, FROM]) {
+        try {
+            builds.add(require(require.resolve(specifier, { paths: [path.dirname(entry), process.cwd()] })));
+        } catch {
+            // not installed next to the application, or not resolvable from there
+        }
+    }
+
+    const owners = [];
+    for (const build of builds) {
+        if (typeof build !== "function") {
+            continue;
+        }
+        let app;
+        try {
+            app = build();
+        } catch {
+            continue; // not an application factory, or one that will not build without arguments
+        }
+        // real express resolves under the same two names, and has none of this to stub
+        if (typeof app._compileOptimizedRoutes !== "function") {
+            continue;
+        }
+        let proto = Object.getPrototypeOf(app);
+        while (proto && !Object.prototype.hasOwnProperty.call(proto, "listen")) {
+            proto = Object.getPrototypeOf(proto);
+        }
+        if (proto && !owners.includes(proto)) {
+            owners.push(proto);
+        }
+    }
+    return owners;
+}
+
 /**
  * The applications a file builds, compiled but not listening.
  *
@@ -348,42 +438,38 @@ function loadApps(argv, command) {
     if (!entry) {
         console.error(
             `Nothing to ${command}: name the file that builds the application, or run this from a
-` + "directory whose package.json main points at it."
+` + "directory whose package.json main or start script points at it."
         );
         return null;
     }
 
-    // the same module instance the application will load, so patching this prototype patches the
-    // application it builds. An app is a callable, so its own prototype is not the one that carries
-    // the methods: walk up to whichever link owns listen
-    const express = require("./index.js");
-    let proto = Object.getPrototypeOf(express());
-    while (proto && !Object.prototype.hasOwnProperty.call(proto, "listen")) {
-        proto = Object.getPrototypeOf(proto);
-    }
-    if (!proto) {
+    const owners = listenOwners(entry);
+    if (owners.length === 0) {
         console.error("This build of fulmine has no listen() to stand in for, which should not happen.");
         return null;
     }
 
     const listened = [];
-    const realListen = proto.listen;
-    proto.listen = function stubbedListen() {
-        this._compileOptimizedRoutes();
-        listened.push(this);
-        return this;
-    };
+    const real = owners.map((proto) => proto.listen);
+    for (const proto of owners) {
+        proto.listen = function stubbedListen() {
+            this._compileOptimizedRoutes();
+            listened.push(this);
+            return this;
+        };
+    }
+    const restore = () => owners.forEach((proto, i) => (proto.listen = real[i]));
 
     try {
         require(entry);
     } catch (e) {
         const error = /** @type {any} */ (e);
-        proto.listen = realListen;
+        restore();
         console.error(`${path.relative(process.cwd(), entry)} could not be loaded:
 ${error.stack ?? error}`);
         return null;
     }
-    proto.listen = realListen;
+    restore();
 
     let apps = listened;
     if (apps.length === 0) {
@@ -400,7 +486,10 @@ ${error.stack ?? error}`);
     if (apps.length === 0) {
         console.error(
             `${path.relative(process.cwd(), entry)} built no application: it neither called listen() nor
-` + "exported one. Point this at the file that does."
+` +
+                `exported one. Point this at the file that does. A listen() that runs after an await is
+` +
+                "not seen either, since this loads the file rather than waiting on what it started."
         );
         return null;
     }

package/src/cluster.js

@@ -0,0 +1,204 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// express({ cluster: "auto" }): one process per core, all on the same port.
+//
+// A node process runs the application on one core, and the other fifteen sit there. The usual
+// answer is the cluster module, where the primary holds the listening socket and hands each
+// accepted connection to a worker over an IPC channel. µWS does not need that: it can bind with
+// the port marked shared, which is SO_REUSEPORT, and then every worker has its own listening
+// socket on the same port and the kernel picks which one gets each connection. No primary in the
+// path, no handle to pass, nothing serialised between processes.
+//
+// The flag has been passed for a while, see Application#listen: a worker binds shared and a lone
+// process binds exclusive. What was missing is the fork, which every application had to write for
+// itself, and an application that does not write it uses one core.
+
+"use strict";
+
+const cluster = require("cluster");
+const fs = require("fs");
+const os = require("os");
+
+/**
+ * @param {string} file
+ * @returns {string}
+ */
+function readFile(file) {
+    return fs.readFileSync(file, "utf8");
+}
+
+/**
+ * How many cores the operating system says are usable.
+ *
+ * @returns {number}
+ */
+function parallelism() {
+    return os.availableParallelism ? os.availableParallelism() : os.cpus().length;
+}
+
+/**
+ * The CPU quota a cgroup puts on this process, in cores, or undefined where there is none.
+ *
+ * This is the number that matters in a container: os.availableParallelism() reports the machine,
+ * not the share of it the orchestrator gave away, so a 2-core pod on a 64-core node would fork 64
+ * processes that fight over two cores. Both cgroup layouts are read, v2 first.
+ *
+ * @param {(file: string) => string} [read] the file reader, for a test that has no cgroup
+ * @returns {number|undefined}
+ */
+function cgroupCores(read = readFile) {
+    try {
+        const [quota, period] = read("/sys/fs/cgroup/cpu.max").trim().split(/\s+/);
+        // "max" is the word for no quota at all, and it is not a number
+        if (quota !== "max" && Number(period) > 0) {
+            return Number(quota) / Number(period);
+        }
+    } catch {
+        // no cgroup v2 here, try the older layout
+    }
+    try {
+        const quota = Number(read("/sys/fs/cgroup/cpu/cpu.cfs_quota_us"));
+        const period = Number(read("/sys/fs/cgroup/cpu/cpu.cfs_period_us"));
+        if (quota > 0 && period > 0) {
+            return quota / period;
+        }
+    } catch {
+        // nor v1: this is a plain machine
+    }
+    return undefined;
+}
+
+/**
+ * The cores this process may actually use: what the machine has, capped by what the cgroup allows.
+ *
+ * @param {(file: string) => string} [read]
+ * @param {() => number} [cores]
+ * @returns {number}
+ */
+function availableCores(read = readFile, cores = parallelism) {
+    const machine = cores();
+    const quota = cgroupCores(read);
+    if (quota === undefined || !(quota > 0)) {
+        return machine;
+    }
+    // floored, never rounded up: half a core of headroom is not a process
+    return Math.max(1, Math.min(machine, Math.floor(quota)));
+}
+
+/**
+ * How many workers a `cluster` setting asks for. Zero means the setting is off and the process
+ * serves by itself, which is the default.
+ *
+ * A value nobody can read is a throw rather than a quiet zero: `cluster: "atuo"` running on one
+ * core in production, with nothing said about it, is the failure this whole thing is against.
+ *
+ * @param {boolean|number|"auto"|undefined} setting
+ * @param {number} [cores] counted only when the setting asks for it: every application calls this,
+ *   and almost none of them wants the cgroup read
+ * @returns {number}
+ */
+function workerCount(setting, cores) {
+    if (setting === undefined || setting === false || setting === 0) {
+        return 0;
+    }
+    if (setting === true || setting === "auto") {
+        return Math.max(1, cores ?? availableCores());
+    }
+    if (typeof setting === "number" && Number.isFinite(setting) && setting > 0) {
+        return Math.floor(setting);
+    }
+    throw new TypeError(`cluster must be "auto", a boolean or a positive number, not ${JSON.stringify(setting)}`);
+}
+
+// Whether this process has forked workers, and so serves nothing itself. An application carries
+// the setting, but the answer is about the process: an entry with a second app on a TLS port would
+// otherwise bind that one here, exclusively, and every worker would fail on it.
+let supervising = false;
+
+/**
+ * Whether this process forked workers and left the serving to them.
+ *
+ * @returns {boolean}
+ */
+function isSupervising() {
+    return supervising;
+}
+
+/**
+ * Says this process is the primary of a clustered application, before it has forked anything.
+ *
+ * Written when the application is constructed and not when it listens, because the order is the
+ * application's to choose: an entry that listens on its TLS port first would otherwise have taken
+ * that port here, exclusively, a line before the fork.
+ *
+ * @returns {void}
+ */
+function becomeSupervisor() {
+    supervising = true;
+}
+
+/**
+ * Forks the workers and keeps that many of them alive.
+ *
+ * A worker that dies is replaced, and there is nothing to rebuild when it comes back: it binds the
+ * shared port again and the kernel starts handing it connections. A signal that reaches the
+ * primary alone, which is what a container sends, is passed on rather than leaving the workers
+ * running with nobody watching them.
+ *
+ * @param {number} count
+ * @returns {{stop: () => void}}
+ */
+function forkWorkers(count) {
+    let stopping = false;
+    supervising = true;
+    /** @param {any} worker @param {number} code @param {string} signal */
+    const onExit = (worker, code, signal) => {
+        if (!stopping) {
+            console.error(`worker ${worker.process.pid} exited (${signal || code}), starting another`);
+            cluster.fork();
+        }
+    };
+    cluster.on("exit", onExit);
+    for (let i = 0; i < count; i++) {
+        cluster.fork();
+    }
+    const stop = () => {
+        stopping = true;
+        supervising = false;
+        cluster.off("exit", onExit);
+        for (const id of Object.keys(cluster.workers ?? {})) {
+            /** @type {any} */ (cluster.workers)[id]?.kill();
+        }
+    };
+    for (const signal of ["SIGTERM", "SIGINT"]) {
+        process.on(signal, () => {
+            stop();
+            // the primary exits on its own once the last IPC channel closes; this only makes sure
+            // it does, and being unref'd it never keeps the process up by itself
+            const done = setInterval(() => {
+                if (Object.keys(cluster.workers ?? {}).length === 0) {
+                    clearInterval(done);
+                    process.exit(0);
+                }
+            }, 20);
+            done.unref();
+        });
+    }
+    return { stop };
+}
+
+module.exports = { availableCores, cgroupCores, workerCount, forkWorkers, isSupervising, becomeSupervisor };

package/src/middlewares.js

@@ -418,6 +418,8 @@ function serveStatic(root, options) {
         }
     }
     options.root = root;
+    // resolved once here rather than on every request: the root cannot change under a mount
+    const resolvedRoot = path.resolve(root);
     // serve-static decides this for itself and never asks the app, so a static file keeps its
     // ETag under app.set("etag", false) and only { etag: false } here turns it off. res.sendFile
     // takes the app's setting instead, which is why this has to be said out loud.
@@ -469,7 +471,19 @@ function serveStatic(root, options) {
             } else return next();
         }
         let _path = url;
-        const fullpath = path.resolve(path.join(root, url));
+        // Joined against the root and not normalised on its own first, which is the difference
+        // between "/mount/../package.json" being refused and being served: a ".." has to climb
+        // relative to the root so the check below can see it leave, and normalizing the url alone
+        // clamps it at "/" where nothing has left anywhere. Absolute because resolvedRoot is, so
+        // nothing here resolves against the working directory per request either.
+        // and without the trailing separator join keeps and resolve does not, because statTarget
+        // below puts it back only where it belongs: linux refuses a file asked for as a directory,
+        // so a mount whose root is a file answers nothing at all if the separator stays here.
+        // Windows stats it either way, which is why only the CI said so.
+        let fullpath = path.join(resolvedRoot, url);
+        if (fullpath.length > resolvedRoot.length && fullpath.endsWith(path.sep)) {
+            fullpath = fullpath.slice(0, -1);
+        }
         // the same file as _path, absolute: the two move together through the index and extension
         // rules below, and only the precompressed lookup needs the absolute one
         let filePath = fullpath;
@@ -483,7 +497,7 @@ function serveStatic(root, options) {
         // is what an error handler prints when fallthrough is off.
         const mountRelative = rawPath === "/" && !req.endsWithSlash ? "" : url;
         const statTarget = mountRelative.endsWith("/") && !fullpath.endsWith(path.sep) ? fullpath + path.sep : fullpath;
-        if (root && !fullpath.startsWith(path.resolve(root))) {
+        if (root && !fullpath.startsWith(resolvedRoot)) {
             if (!options.fallthrough) {
                 res.status(403);
                 return next(httpError(403));
@@ -496,7 +510,10 @@ function serveStatic(root, options) {
         // reaches it only for paths that do exist.
         // normalized first, as send normalizes before it judges: a ".." segment is not a hidden
         // file, and resolving it away is what tells the two apart
-        if (containsDotFile(path.normalize(url).split(/[\\/]/))) {
+        // and these are the segments path.normalize(url) would have produced, taken off the joined
+        // path rather than walked again: the check above has just proved it starts with the root,
+        // so what follows the root is the url in normal form
+        if (containsDotFile(fullpath.slice(resolvedRoot.length).split(/[\\/]/))) {
             const refusal = options.dotfiles === "deny" ? 403 : options.dotfiles === "allow" ? 0 : 404;
             if (refusal !== 0 && !(options.dotfiles === "ignore_files" && !path.basename(url).startsWith("."))) {
                 if (!options.fallthrough) {

package/src/types.d.ts

@@ -22,6 +22,7 @@ declare module "fulmine.js" {
     type Settings = {
         uwsOptions?: uWS.AppOptions;
         threads?: number;
+        cluster?: boolean | number | "auto";
         http3?: boolean;
         uwsApp?: uWS.TemplatedApp;
     };
@@ -76,6 +77,18 @@ declare module "fulmine.js" {
             function expectDeclarative(app: Fulmine, patterns: string | string[]): void;
         }
 
+        // Server-Timing, carrying how the request was routed. Express has no such middleware, so
+        // like compression() there is nothing to re-export
+        interface ServerTimingOptions {
+            /** Whether to report how the request was routed. Default true. */
+            routing?: boolean;
+            /** Whether to report the time up to the head. Default true. */
+            total?: boolean;
+            /** What the total is called. Default "total". */
+            name?: string;
+        }
+        export function serverTiming(options?: ServerTimingOptions): e.RequestHandler;
+
         export function compression(options?: CompressionOptions): e.RequestHandler;
         export namespace compression {
             /** The default filter: any compressible content type. */
@@ -183,3 +196,15 @@ declare module "fulmine.js" {
 
     export = express;
 }
+
+// What express.serverTiming() hangs on the response. Express's own Response extends this global
+// interface, which is how a middleware adds to it. They are written per request rather than on the
+// prototype, so a route only has them where that middleware ran, which the optional marks say.
+declare namespace Express {
+    interface Response {
+        /** Adds a mark of your own. A mark with only a description is a legal entry. */
+        timing?(name: string, duration?: number, description?: string): this;
+        /** Times a piece of work under a name. A promise is timed to where it settles. */
+        time?<T>(name: string, work: () => T): T;
+    }
+}

package/src/verify.js

@@ -103,18 +103,27 @@ function checkNode(running = process.versions.node, required = require("../packa
 }
 
 /**
- * Whether the C library is the one the binaries are linked against. Only linux has two of them,
- * and node reports the glibc it is running against; a musl build reports none, which is what
- * Alpine looks like from in here.
+ * The glibc this process is running against, or undefined when there is none to report, which is
+ * what a musl build looks like from in here.
  *
- * @param {string} [platform]
- * @param {string|undefined} [glibc] the runtime glibc, absent on musl
+ * @returns {string|undefined}
+ */
+function currentGlibc() {
+    return /** @type {any} */ (process.report.getReport()).header.glibcVersionRuntime;
+}
+
+/**
+ * Whether the C library is the one the binaries are linked against. Only linux has two of them.
+ *
+ * Both arguments are required, and deliberately: undefined is the answer that means musl, and a
+ * default parameter fires on an explicit undefined, so a default here would quietly turn the musl
+ * case into whatever this machine happens to run. Reading the machine is the caller's job.
+ *
+ * @param {string} platform
+ * @param {string|undefined} glibc the runtime glibc, absent on musl
  * @returns {ReturnType<typeof result>|undefined} undefined where the question does not arise
  */
-function checkLibc(
-    platform = process.platform,
-    glibc = /** @type {any} */ (process.report.getReport()).header.glibcVersionRuntime
-) {
+function checkLibc(platform, glibc) {
     if (platform !== "linux") {
         return undefined;
     }
@@ -280,7 +289,7 @@ function verify(argv) {
     const dir = path.resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
     /** @type {ReturnType<typeof result>[]} */
     const results = [checkNode()];
-    const libc = checkLibc();
+    const libc = checkLibc(process.platform, currentGlibc());
     if (libc) {
         results.push(libc);
     }
@@ -306,4 +315,4 @@ function verify(argv) {
     return blocking === 0 ? 0 : 1;
 }
 
-module.exports = { verify, checkNode, checkLibc, checkBinary, checkDockerfiles, checkDependencies };
+module.exports = { verify, checkNode, checkLibc, currentGlibc, checkBinary, checkDockerfiles, checkDependencies };