fulmine.js 5.8.0 → 5.9.0

package/README.md

@@ -248,7 +248,7 @@ A single-stage `node:26-trixie-slim` image works too if you `apt-get install -y
 
 ## Differences from Express
 
-- `app.listen()` returns the app, not an `http.Server`, 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`.
 - `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`.
@@ -446,9 +446,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.
+
 ## 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", {
@@ -482,8 +499,8 @@ If you would rather use the `ws` module's API, [Ultimate WS](https://github.com/
 
 ### 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 +517,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.
 
 ## HTTP/3
 
@@ -795,4 +816,8 @@ Any Express view engine should work. Here's list of engines we include in our te
 ## 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.9.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {

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/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;
     };

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 };