fulmine.js 5.7.0 → 5.9.0

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/index.js

@@ -49,7 +49,9 @@ try {
  *   response: object,
  *   application: object,
  *   static: Function,
+ *   testing: object,
  *   compression: Function,
+ *   serverTiming: Function,
  *   json: Function,
  *   urlencoded: Function,
  *   text: Function,
@@ -73,9 +75,15 @@ module.exports.response = Response.prototype;
 module.exports.application = Application.Application.prototype;
 
 module.exports.static = middlewares.static;
+// what listen() decided about each route, as something a test can assert on rather than something
+// to read in a terminal. See src/testing.js
+module.exports.testing = require("./testing.js");
 // not one of express's, since express has none: the compression module is what everyone installs
 // instead, and this is that middleware's options and behaviour without the install
 module.exports.compression = require("./compression.js");
+// Server-Timing with the routing verdict in it, which no other framework can report because no
+// other framework has two routes to tell apart. See src/server-timing.js
+module.exports.serverTiming = require("./server-timing.js");
 module.exports.json = middlewares.json;
 module.exports.urlencoded = middlewares.urlencoded;
 module.exports.text = middlewares.text;

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/server-shape.js

@@ -0,0 +1,157 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// What makes an application answer the questions a library asks about an http.Server.
+//
+// `app.listen()` returns the app, and there is no node server under it: the socket belongs to µWS.
+// That is the one place where a drop-in stops being a drop-in, because the graceful shutdown
+// libraries, the connection trackers and the health check wrappers do not use a server, they
+// *recognise* one: `server instanceof http.Server`, then close(), address(), getConnections() and
+// the events around them. Everything they need can be answered honestly here.
+//
+// Two halves, and the second is the delicate one:
+//
+//   - the members. close(), address(), listening and the events already exist on the application,
+//     because Express hands back an http.Server and code written for Express uses them. What was
+//     missing is the rest of the net.Server surface, added below.
+//   - the recognition. An application cannot inherit from http.Server: its prototype chain already
+//     runs through Router and this project's own EventEmitter, and http.Server.prototype has a
+//     chain of its own that cannot be spliced into it without re-parenting node's classes for the
+//     whole process. So instanceof is taught about applications instead, through the hook the
+//     language provides for exactly this: Symbol.hasInstance. The patch is additive. Everything
+//     that was an http.Server before still is, and the only new answer is for an application.
+//
+// What this deliberately does not do is pretend the plumbing is there. Nothing emits 'request',
+// 'connection' or 'upgrade', because those carry node sockets and there are none: a library that
+// counts connections through them counts zero, and socket.io still wants app.uwsApp. The shape is
+// honest about what is behind it, which is why getConnections answers with the requests in flight
+// rather than with a number nobody could stand behind.
+
+const http = require("http");
+const net = require("net");
+
+// what marks an application, read by the instanceof hook below. A symbol rather than a property
+// name, so nothing can be mistaken for an application by carrying the wrong field
+const kIsApplication = Symbol.for("fulmine.application");
+
+/**
+ * Teaches `instanceof` that an application is a server, once per class. The original answer is
+ * asked first and is never overruled: this only adds an answer for objects carrying the mark.
+ *
+ * @param {Function} klass http.Server or net.Server
+ */
+function acceptApplications(klass) {
+    const previous = /** @type {any} */ (klass)[Symbol.hasInstance];
+    // already taught, which happens when two copies of this package share one process
+    if (/** @type {any} */ (klass)[kIsApplication] === true) {
+        return;
+    }
+    Object.defineProperty(klass, Symbol.hasInstance, {
+        /** @param {any} value @returns {boolean} */
+        value: function (value) {
+            if (previous.call(this, value)) {
+                return true;
+            }
+            // an application is a function, and a property read works on one; the guard is for the
+            // primitives and the nulls that reach any instanceof
+            return value != null && /** @type {any} */ (value)[kIsApplication] === true;
+        },
+        configurable: true,
+        writable: true
+    });
+    Object.defineProperty(klass, kIsApplication, { value: true, configurable: true });
+}
+
+acceptApplications(http.Server);
+acceptApplications(net.Server);
+
+/**
+ * The net.Server members an application does not get from Express's side of the API, defined on
+ * the application prototype. Each one answers for µWS rather than for a socket node does not have.
+ *
+ * @param {any} prototype Application.prototype
+ */
+function addServerMembers(prototype) {
+    Object.defineProperty(prototype, kIsApplication, { value: true, configurable: true });
+
+    /**
+     * How many requests this application is serving right now.
+     *
+     * node counts sockets; there are none to count here, and the number a graceful shutdown is
+     * waiting for is this one anyway: it reaches zero when the last answer has gone out. An idle
+     * keep-alive connection is not counted, and closing does not wait for one either.
+     *
+     * @param {(err: Error|null, count: number) => void} callback
+     */
+    prototype.getConnections = function getConnections(callback) {
+        let count = 0;
+        for (let response = this._pending.head; response !== null; response = response._pendingNext) {
+            count++;
+        }
+        // node answers this one asynchronously, and a caller written against it may rely on that
+        process.nextTick(callback, null, count);
+    };
+
+    /**
+     * node's, for a handle this does not own: µWS's loop is what keeps the process alive, and it
+     * is not something a caller may unref. Both are no-ops that hand the server back, so a chain
+     * written against node's API keeps working.
+     *
+     * @returns {any}
+     */
+    prototype.ref = function ref() {
+        return this;
+    };
+
+    /** @returns {any} */
+    prototype.unref = function unref() {
+        return this;
+    };
+
+    /**
+     * Registers the callback the way node's does and remembers the value, which is all a caller
+     * can observe. The timeout itself belongs to µWS and is set through uwsOptions.idleTimeout.
+     *
+     * @this {any}
+     * @param {number} [msecs]
+     * @param {() => void} [callback]
+     * @returns {any}
+     */
+    prototype.setTimeout = function setTimeout(msecs, callback) {
+        this.timeout = msecs;
+        if (callback) {
+            this.on("timeout", callback);
+        }
+        return this;
+    };
+
+    // The numbers node's http.Server carries and a caller may read or write. They are inert here,
+    // and they are declared rather than left undefined because reading one is how a library works
+    // out what it is talking to: `server.keepAliveTimeout` undefined has been read as "not a
+    // server" before now.
+    for (const [name, value] of /** @type {[string, any][]} */ ([
+        ["timeout", 0],
+        ["keepAliveTimeout", 5000],
+        ["headersTimeout", 60000],
+        ["requestTimeout", 300000],
+        ["maxHeadersCount", null],
+        ["maxRequestsPerSocket", 0]
+    ])) {
+        Object.defineProperty(prototype, name, { value, writable: true, configurable: true, enumerable: false });
+    }
+}
+
+module.exports = { addServerMembers, kIsApplication };

package/src/server-timing.js

@@ -0,0 +1,180 @@
+/*
+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.serverTiming(): Server-Timing, with the two things only this framework can put in it.
+//
+// A stopwatch middleware is nothing new, and there are several on npm. What none of them can add
+// is how the request was routed, because in every other framework there is only one way:
+//
+//     Server-Timing: route;desc="native", hdr;desc="not copied", total;dur=0.42
+//
+// `route;desc="native"` means µWS matched the path in C++ and handed over a chain worked out at
+// startup. `route;desc="router"` means this request was matched here, in javascript, layer by
+// layer. That is the difference between the two halves of this project, per request, in the
+// browser's network panel, for someone who would never run a CLI.
+//
+// What it cannot show is the route that is faster still: a handler compiled into a response never
+// enters javascript, so no middleware runs on it and there is nothing to time. `npx fulmine
+// profile` is where those are counted.
+//
+// The duration ends where the header does. Server-Timing goes out with the head, so `total` covers
+// everything up to the moment the answer starts leaving, and not the body after it. Every stopwatch
+// middleware has that boundary; this one says so.
+
+"use strict";
+
+/**
+ * A duration in milliseconds, as Server-Timing writes them: two decimals, which is a hundredth of
+ * a millisecond and finer than anything above it is worth.
+ *
+ * @param {bigint} nanoseconds
+ * @returns {string}
+ */
+function millis(nanoseconds) {
+    return (Number(nanoseconds) / 1e6).toFixed(2);
+}
+
+/**
+ * Escapes a description for the quoted-string it goes in.
+ * @param {string} text
+ * @returns {string}
+ */
+function describe(text) {
+    return `"${String(text).replace(/["\\]/g, "")}"`;
+}
+
+/**
+ * Measures the request and answers with Server-Timing.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.routing] whether to report how the request was routed. Default true.
+ * @param {boolean} [options.total] whether to report the time up to the head. Default true.
+ * @param {string} [options.name] what the total is called. Default "total".
+ * @returns {(req: any, res: any, next: (err?: any) => void) => void}
+ */
+function serverTiming(options) {
+    const opts = options || {};
+    const routing = opts.routing !== false;
+    const wantsTotal = opts.total !== false;
+    const totalName = opts.name || "total";
+
+    return function serverTiming(req, res, next) {
+        const started = process.hrtime.bigint();
+        /** @type {string[]} */
+        const marks = [];
+
+        /**
+         * Adds a mark of the caller's own, which is what the rest of Server-Timing is for: the
+         * query, the upstream call, the render. A duration is optional, since a mark with only a
+         * description is a legal entry and is how a cache hit is usually reported.
+         *
+         * @param {string} name a token: letters, digits, dash and underscore
+         * @param {number} [duration] milliseconds
+         * @param {string} [description]
+         * @returns {any} the response, so calls chain
+         */
+        res.timing = function timing(name, duration, description) {
+            let mark = String(name).replace(/[^\w-]/g, "");
+            if (typeof duration === "number") {
+                mark += `;dur=${duration.toFixed(2)}`;
+            }
+            if (description) {
+                mark += `;desc=${describe(description)}`;
+            }
+            marks.push(mark);
+            return this;
+        };
+
+        /**
+         * Times a piece of work under a name, whatever it is: the value comes back, and a promise
+         * is timed to where it settles.
+         *
+         * @param {string} name
+         * @param {() => any} work
+         * @returns {any} whatever the work returned
+         */
+        res.time = function time(name, work) {
+            const from = process.hrtime.bigint();
+            const done = () => res.timing(name, Number(process.hrtime.bigint() - from) / 1e6);
+            let value;
+            try {
+                value = work();
+            } catch (err) {
+                done();
+                throw err;
+            }
+            if (value && typeof value.then === "function") {
+                return value.then(
+                    /** @param {any} resolved */ (resolved) => {
+                        done();
+                        return resolved;
+                    },
+                    /** @param {any} err */ (err) => {
+                        done();
+                        throw err;
+                    }
+                );
+            }
+            done();
+            return value;
+        };
+
+        const _write = res.write;
+        const _end = res.end;
+        let written = false;
+
+        /** Writes the header, once, just before the head goes out with the first byte of body. */
+        const stamp = () => {
+            if (written || res.headersSent) {
+                return;
+            }
+            written = true;
+            const entries = [];
+            if (routing) {
+                // what the router decided about the route this request ran, which is the same
+                // verdict npx fulmine profile prints for it
+                const native = req.route?._native;
+                entries.push(`route;desc=${describe(native ? "native" : "router")}`);
+                if (native) {
+                    entries.push(`hdr;desc=${describe(native.skipHeaders ? "not copied" : "copied")}`);
+                    if (native.skipQuery) {
+                        entries.push(`query;desc=${describe("not parsed")}`);
+                    }
+                }
+            }
+            entries.push(...marks);
+            if (wantsTotal) {
+                entries.push(`${totalName};dur=${millis(process.hrtime.bigint() - started)}`);
+            }
+            if (entries.length !== 0) {
+                res.append("Server-Timing", entries.join(", "));
+            }
+        };
+
+        res.write = function write(chunk, encoding, callback) {
+            stamp();
+            return _write.call(this, chunk, encoding, callback);
+        };
+        res.end = function end(chunk, encoding, callback) {
+            stamp();
+            return _end.call(this, chunk, encoding, callback);
+        };
+
+        next();
+    };
+}
+
+module.exports = serverTiming;