fulmine.js 5.18.1 → 5.19.0

package/README.md

@@ -84,7 +84,7 @@ It started as a fork of [Ultimate Express](https://github.com/dimdenGD/ultimate-
 
 Fulmine is faster than Express where the framework itself is doing the work, and the same speed where it is not. Both halves of that sentence matter, so here is the honest version.
 
-**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. The spreads below are the last nine CI runs, which landed on three different runner shapes, all on Node 26. Plain routing lands between 1.8x and 4.9x: hello-world 1.8x to 2.9x, an API endpoint with params and a query 3.1x to 4.9x, five route shapes served by one process 2.4x to 4.0x, nested routers 2.0x to 3.4x, a urlencoded body 3.3x to 4.6x, a thousand concurrent connections 2.6x to 3.7x. Route tables are where the native router shows: a thousand routes 9.7x to 17.4x, with a parameter in every one of them 10x to 21.2x, a parameterised route in a mounted router 6.8x to 8.8x. Those routes go to µWS's own router instead of being scanned, so the gap grows with the table instead of shrinking. Even the chain of 100 middlewares, for a long time the one routing row that stayed even because its cost is calling application code a hundred times, sits at 1.7x to 2.1x after the per-request work of August 2026.
+**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. The spreads below are the last twelve CI runs, which landed on four different runner shapes, all on Node 26. Plain routing lands between 1.3x and 4.9x: hello-world 1.3x to 3.2x, an API endpoint with params and a query 1.9x to 4.9x, five route shapes served by one process 1.6x to 4.1x, nested routers 1.5x to 3.6x, a urlencoded body 2.1x to 5.6x, a thousand concurrent connections 2.2x to 3.6x. Route tables are where the native router shows: a thousand routes 7.5x to 16.4x, with a parameter in every one of them 7.7x to 19.9x, a parameterised route in a mounted router 4.3x to 8.8x. Those routes go to µWS's own router instead of being scanned, so the gap grows with the table instead of shrinking. Even the chain of 100 middlewares, for a long time the one routing row that stayed even because its cost is calling application code a hundred times, sits at 1.8x to 2.5x after the per-request work of August 2026. Those spreads are wider than they were: the newest runners are much faster for Express, which moves the ratio without either server changing, and the low end of every row now comes from one of them.
 
 **Where it is a wash.** Any request whose cost is dominated by work both servers hand to the same library. A 512 KiB JSON body is `JSON.parse`, a gzipped response is zlib, a hashed upload is OpenSSL, a 5 MiB stream is memory bandwidth. On those the ratio is capped by arithmetic somewhere between 1.0x and 1.5x, depending on how much of the request is the shared work, and no amount of effort on either server moves it. The benchmark labels those rows rather than quietly publishing them as if the two were equivalent.
 
@@ -103,7 +103,7 @@ to run it yourself.
 Numbers produced by a project about itself deserve suspicion, so Fulmine also stands in public arenas, run by their own rigs under their own rules:
 
 - **[HttpArena](https://www.http-arena.com/#sort=rps:-1&q=Js)**: thirty profiles on 64-core dedicated hardware, same conditions for every entry, rerun whenever one of them changes. The link lands filtered on the JavaScript entries. No figures are copied here on purpose: the board is the current one and this page would not be.
-- **[web-frameworks](https://web-frameworks-benchmark.netlify.app/result?l=javascript)**: entry merged, numbers arrive with their next published round.
+- **[web-frameworks](https://web-frameworks-benchmark.netlify.app/result?l=javascript)**: in the published round, ranked with the other sixty-odd JavaScript entries on their own hardware. Same rule as above, no figures copied here.
 
 More to come as their maintainers take the entries in.
 

package/package.json

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

package/src/application.js

@@ -687,6 +687,17 @@ class Application extends Router {
         return this.uwsApp.numSubscribers(topic);
     }
 
+    /**
+     * The router the application routes through, which express 5 hands out so that a caller can
+     * walk `app.router.stack`. Here the application is the router, so it hands back itself and the
+     * walk finds the same layers.
+     *
+     * @returns {this}
+     */
+    get router() {
+        return this;
+    }
+
     /**
      * The bound address, or null when not listening.
      * @returns {{address: string, family: string, port: number}|null}

package/src/middlewares.js

@@ -898,8 +898,12 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // context is still intact and an AsyncResource here would be 1.4 microseconds of
             // nothing. The bind happens below, only once a real read is about to go async.
 
-            // skip reading body twice
-            if (req.bodyRead) {
+            // skip reading body twice. The second half is what body-parser asks on-finished
+            // before it reads, said in this project's own terms: the body has all arrived and
+            // the stream is no longer readable, so whoever read it left nothing to wait for.
+            // Not readableEnded, which is one of the wrapped Readable members and would build
+            // the stream this parser exists to avoid building
+            if (req.bodyRead || (req.complete === true && req.readable === false)) {
                 return next();
             }
 
@@ -1052,6 +1056,11 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             const declaresLength = !Number.isNaN(declared) && declared > 0;
             if (!req.receivedData && !inflate && req._res.collectBody && (declaresLength || isNaN(declared))) {
                 req.bodyRead = true;
+                // µWS hands the whole body over here and the Readable never runs, so the
+                // request has to look read anyway: a parser after this one asks the stream,
+                // not us, and would wait for an end that is never coming
+                req.complete = true;
+                req.readable = false;
                 req._res.collectBody(limit, (body) => {
                     if (body === null) {
                         // over maxSize: uWS refused it natively
@@ -1246,6 +1255,11 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 req._res.onData((ab, isLast) => {
                     onData(ab);
                     if (isLast) {
+                        // this subscription replaced the Readable's own, so the stream will
+                        // never end by itself. What an ended one leaves behind is set here
+                        // instead, since that is what the next parser looks at
+                        req.complete = true;
+                        req.readable = false;
                         onEnd();
                     }
                 });

package/src/node-shim.js

@@ -222,7 +222,9 @@ class NodeHttpResponse {
      */
     writeHeader(key, value) {
         if (!this._nodeRes.headersSent) {
-            this._nodeRes.appendHeader(key, String(value));
+            // String() because writeHeaders hands the recurring names and values over as
+            // Buffers for the uWS crossing, and node's appendHeader wants strings
+            this._nodeRes.appendHeader(String(key), String(value));
         }
         return this;
     }

package/src/request.js

@@ -875,6 +875,10 @@ module.exports = class Request extends LazyReadable {
         // application, so handing back puts the one that was current back, see rememberApp
         this._appStack = undefined;
         this.receivedData = false;
+        // node's IncomingMessage flag: false until the whole body has arrived. on-finished
+        // reads it to decide a request is done with, and body-parser asks on-finished before
+        // it reads, so a parser running after another one has to find it here
+        this.complete = false;
         // reading ip is very slow in UWS, so its better to not do it unless truly needed
         if (app.needsIpAfterResponse) {
             // an app that has been seen asking after the response reads it now, because by then
@@ -896,6 +900,7 @@ module.exports = class Request extends LazyReadable {
             this._subscribeBody();
         } else {
             this.receivedData = true;
+            this.complete = true;
             // not pushed here: ending a Readable costs a scheduled tick and its bookkeeping,
             // and on a bodyless request nobody may ever look. The null goes out from _read(),
             // which is where every consumer arrives
@@ -926,6 +931,7 @@ module.exports = class Request extends LazyReadable {
                 this.#paused = true;
             }
             if (isLast) {
+                this.complete = true;
                 this.push(null);
             }
         });
@@ -1518,25 +1524,14 @@ module.exports = class Request extends LazyReadable {
     #cachedConnection = null;
 
     /**
-     * Enough of a node socket for the middleware that reaches for one. Built on first read and
-     * kept, so req.socket keeps its identity across reads as node's does. remotePort hides behind
-     * its own getter because it is a native uWS call almost no caller makes.
-     * @returns {{remoteAddress: string|undefined, remotePort: number, localPort: number|undefined, encrypted: boolean, end: (body?: any) => void}}
+     * The socket node would have handed over, which is the same object as `res.socket`: one
+     * stand-in for the pair, as node has one socket for both. Built on first read and kept, so it
+     * keeps its identity across reads, and kept here as well so that it still answers once the
+     * response is over and `res.socket` has gone null.
+     * @returns {any}
      */
     get connection() {
-        if (this.#cachedConnection) {
-            return this.#cachedConnection;
-        }
-        const uwsRes = this._res;
-        return (this.#cachedConnection = {
-            remoteAddress: this.parsedIp,
-            get remotePort() {
-                return uwsRes.getRemotePort();
-            },
-            localPort: this.app.port,
-            encrypted: this.app.ssl,
-            end: (body) => this.res.end(body)
-        });
+        return (this.#cachedConnection ??= this.res._socketShim());
     }
 
     /**

package/src/response.js

@@ -83,6 +83,32 @@ const kShapeMode =
 // request are one Map hit. Insert-only after validation, bounded; only setHeader may insert,
 // the never-throwing readers keep their plain toLowerCase
 const VALIDATED_HEADER_NAMES = new Map();
+// The names and values that recur on every response, kept as Buffers for the uWS crossing: a
+// Buffer is memcpy'd as it is, a string pays a UTF-8 scan and copy per call. A header that is
+// not here just misses the lookup and crosses as the string it was. Names must stay lowercase,
+// which is how writeHeaders receives them.
+const HEADER_NAME_BUF = { __proto__: null };
+const HEADER_VALUE_BUF = { __proto__: null };
+for (const s of ["connection", "keep-alive", "content-type", "vary", "x-powered-by", "content-encoding"]) {
+    HEADER_NAME_BUF[s] = Buffer.from(s);
+}
+for (const s of [
+    "keep-alive",
+    "timeout=10",
+    "close",
+    "Fulmine",
+    "Accept-Encoding",
+    "text/html; charset=utf-8",
+    "text/plain; charset=utf-8",
+    "application/json; charset=utf-8",
+    "application/octet-stream",
+    "gzip",
+    "br",
+    "deflate",
+    "zstd"
+]) {
+    HEADER_VALUE_BUF[s] = Buffer.from(s);
+}
 const HIGH_WATERMARK = 128 * 1024;
 // the exact string json() writes, so send() can skip recomputing the charset on it
 const JSON_UTF8 = "application/json; charset=utf-8";
@@ -113,6 +139,13 @@ class Socket extends EventEmitter {
         super();
         this.response = response;
         this[kShapeMode] = true;
+        // middleware assigns to this one, which is why it is a field rather than a getter: express
+        // reads socket.encrypted for req.protocol and a proxy shim writes it
+        this.encrypted = response.req.app.ssl;
+        this.localPort = response.req.app.port;
+        // on-finished reads socket.readable before anything else, and a socket without one reads
+        // as a request that is already over
+        this.readable = true;
 
         // shared, not an arrow: one per process instead of one per materialized socket
         this.on("error", Socket._onError);
@@ -123,6 +156,37 @@ class Socket extends EventEmitter {
         return !this.response.finished;
     }
 
+    /** The peer, as node reports it. Reading it out of µWS is slow, so the request caches it. */
+    get remoteAddress() {
+        return this.response.req.parsedIp;
+    }
+
+    /** A native µWS call almost no caller makes, so it stays behind its getter. */
+    get remotePort() {
+        return this.response.req._res.getRemotePort();
+    }
+
+    /**
+     * node's socket carries these three and applications call them on a request they mean to hold
+     * open, almost always to take the timeout off. µWS has no per socket timeout reachable from
+     * javascript, so they do nothing and hand the socket back the way node's do. n8n's chat trigger
+     * calls setTimeout on every webhook, and without it the workflow answered 500.
+     * @returns {this}
+     */
+    setTimeout() {
+        return this;
+    }
+
+    /** @returns {this} */
+    setKeepAlive() {
+        return this;
+    }
+
+    /** @returns {this} */
+    setNoDelay() {
+        return this;
+    }
+
     /**
      * Finishes the response through the socket, which is how the middleware that only knows
      * about sockets ends one.
@@ -132,6 +196,100 @@ class Socket extends EventEmitter {
         this.response.end(body);
     }
 
+    /**
+     * What a server side socket answers about itself. µWS owns the connection, so these follow the
+     * response: it is open until the response is over, and it was never a socket being dialled.
+     */
+    get destroyed() {
+        return this.response.finished === true;
+    }
+
+    /** @returns {string} "open" until the response is over, as a served socket reads. */
+    get readyState() {
+        return this.response.finished === true ? "closed" : "open";
+    }
+
+    /** @returns {boolean} never: this end was accepted, not dialled. */
+    get connecting() {
+        return false;
+    }
+
+    /** @returns {boolean} never, for the same reason. */
+    get pending() {
+        return false;
+    }
+
+    /**
+     * The end of the connection node reports here. There is no address to read back from µWS, so
+     * this is the port the application bound and the family the peer arrived on.
+     * @returns {{address: string|undefined, family: string, port: number|undefined}}
+     */
+    address() {
+        const remote = this.response.req.parsedIp;
+        return {
+            address: this.response.req.app._listenHost,
+            family: remote?.includes(":") ? "IPv6" : "IPv4",
+            port: this.localPort
+        };
+    }
+
+    /**
+     * Drops the connection, which is what an application does to a client it will not serve. node
+     * takes an error and re-emits it; this closes and says so through 'close', since there is no
+     * socket underneath to carry an error of its own.
+     * @returns {this}
+     */
+    destroy() {
+        this.close();
+        return this;
+    }
+
+    /** @returns {this} */
+    destroySoon() {
+        this.close();
+        return this;
+    }
+
+    /**
+     * Holds and resumes the body arriving on this connection, which is the only half of node's
+     * pause() that means anything here: the response is written when the application writes it.
+     * @returns {this}
+     */
+    pause() {
+        this.response.req.pause();
+        return this;
+    }
+
+    /** @returns {this} */
+    resume() {
+        this.response.req.resume();
+        return this;
+    }
+
+    /**
+     * node writes these bytes past the response, straight onto the connection. There is no way
+     * past µWS's framing here, so they go through the response instead, which is what the
+     * middleware writing to a socket means by it.
+     *
+     * @param {any} chunk
+     * @param {any} [encoding]
+     * @param {any} [callback]
+     * @returns {boolean}
+     */
+    write(chunk, encoding, callback) {
+        return this.response.write(chunk, encoding, callback);
+    }
+
+    /** The event loop is µWS's, so there is nothing to hold open or let go. @returns {this} */
+    ref() {
+        return this;
+    }
+
+    /** @returns {this} */
+    unref() {
+        return this;
+    }
+
     /** Closes the connection outright, without finishing a response first. */
     close() {
         if (this.response.finished) {
@@ -395,6 +553,30 @@ module.exports = class Response extends LazyWritable {
         this._unlinkPending();
     }
 
+    /**
+     * Drops the connection, which is how an application abandons a response it cannot finish: a
+     * download whose source dies mid-transfer has to leave the client with a reset rather than a
+     * truncated body it would take for the whole file. node destroys the socket here and µWS's
+     * close() is the same thing; without it the client waited for bytes that were never coming and
+     * the request hung until its own timeout. LibreChat's download route is written exactly that
+     * way, `stream.on("error", () => res.destroy())`.
+     *
+     * A response that is over, or one whose client is already gone, only tears the stream down:
+     * there is nothing left to close, and touching an aborted µWS response is a use after free.
+     * One difference from node stays: writableEnded reads true after this, because it is answered
+     * from the same finished flag the close sets, where node leaves it false until end() is called.
+     *
+     * @param {any} [error]
+     * @returns {this}
+     */
+    destroy(error) {
+        if (this.finished !== true && this.aborted !== true) {
+            this.finished = true;
+            this._res.close();
+        }
+        return super.destroy(error);
+    }
+
     /**
      * on(), not once(), so this must stay idempotent: end() emits 'close' by hand and a later
      * destroy() makes Writable emit it again.
@@ -464,6 +646,17 @@ module.exports = class Response extends LazyWritable {
      */
     get socket() {
         if (this.#ended) return null;
+        return this._socketShim();
+    }
+
+    /**
+     * The stand-in itself, built on first ask and kept. `socket` answers null once the response is
+     * over, as node's does; the request's `socket` is the same object and stays, so it comes
+     * through here instead.
+     *
+     * @returns {any}
+     */
+    _socketShim() {
         if (!this.#socket) {
             this.#socket = new Socket(this);
         }
@@ -714,12 +907,15 @@ module.exports = class Response extends LazyWritable {
                 this.totalSize = parseInt(value);
                 continue;
             }
+            // the recurring names and values cross as cached Buffers, see HEADER_NAME_BUF; a
+            // miss is two failed lookups and the string goes as it came
+            const name = HEADER_NAME_BUF[header] || header;
             if (Array.isArray(value)) {
                 for (const val of value) {
-                    res.writeHeader(header, val);
+                    res.writeHeader(name, HEADER_VALUE_BUF[val] || val);
                 }
             } else {
-                res.writeHeader(header, value);
+                res.writeHeader(name, HEADER_VALUE_BUF[value] || value);
             }
         }
         this.headersSent = true;
@@ -2166,6 +2362,19 @@ module.exports = class Response extends LazyWritable {
     get writableFinished() {
         return this.finished;
     }
+
+    /**
+     * Whether end() has been called. node sets this one there and writableFinished later, once the
+     * bytes are out; here end() hands the whole response to µWS, so the two are the same moment.
+     * Without it the base property answered false forever, and an application that asks whether it
+     * has already answered - LibreChat's agent stream does, before it decides whether to keep a
+     * subscription - carried on writing to a response that was over.
+     */
+    // @ts-expect-error TS2611, the accessor replacing the base property is deliberate. Expect
+    // rather than ignore, so it fails loudly if it ever stops applying.
+    get writableEnded() {
+        return this.finished;
+    }
 };
 
 // res.contentType is res.type under express's other name. On the prototype rather than an instance

package/src/router.js

@@ -142,6 +142,66 @@ let routeKey = 0;
  * A nested router gets its own walk, through its own _routeRequest, so req.next belongs to whoever
  * is running the request at that moment.
  */
+/**
+ * The layer Express makes for one mounted handler. `name` is what a caller matches on: a function's
+ * own name, "router" for a mounted router, and "<anonymous>" for the rest, exactly as express reads
+ * them off the handle.
+ *
+ * @param {any} route
+ * @param {any} callback
+ * @returns {any}
+ */
+function layerFor(route, callback) {
+    const layer = {
+        handle: callback,
+        // express reads the name off the handle, and its own handles are named: a mounted
+        // application is "app" and a mounted router "router", whatever this project happens
+        // to call the function underneath
+        name: Array.isArray(callback._routes)
+            ? callback._isApplication
+                ? "app"
+                : "router"
+            : callback.name || "<anonymous>",
+        params: undefined,
+        path: undefined,
+        keys: [],
+        route: undefined
+    };
+    route._layers.set(callback, layer);
+    return layer;
+}
+
+/**
+ * The layer Express makes for a route, whose handle runs the route's own handlers one after
+ * another. Express calls that handle `handle`, and a caller that looks for a route layer looks for
+ * that name.
+ *
+ * @param {any} route
+ * @returns {any}
+ */
+function routeLayer(route) {
+    const handle = function handle(req, res, next) {
+        let index = 0;
+        const step = (err) => {
+            const callback = route.callbacks[index++];
+            if (callback === undefined) {
+                return next(err);
+            }
+            const isErrorHandler = callback.length === 4;
+            if ((err === undefined || err === null) === isErrorHandler) {
+                return step(err);
+            }
+            try {
+                return isErrorHandler ? callback(err, req, res, step) : callback(req, res, step);
+            } catch (thrown) {
+                return step(thrown);
+            }
+        };
+        step();
+    };
+    return { handle, name: "handle", params: undefined, path: undefined, keys: [], route: route.exposed };
+}
+
 class Walk {
     /**
      * @param {any} router
@@ -1976,6 +2036,33 @@ module.exports = class Router extends EventEmitter {
         return pattern.test(path);
     }
 
+    /**
+     * The layers Express keeps on a router, in Express's own shape: one per middleware, one per
+     * route, and the route's own handlers under `route.stack`. Libraries that list an
+     * application's endpoints walk this, and so do tests that reach in for a single handler by
+     * name, which is how LibreChat pulls one middleware out of its router to exercise it.
+     *
+     * A view, built from the routes this router holds and rebuilt on every read, so it follows
+     * what has been registered. It is not the router's own storage: pushing a layer onto it, or
+     * splicing one out, moves nothing. The layer objects themselves are kept, so a caller that
+     * compares identities across two reads gets the same answer Express gives.
+     *
+     * @returns {any[]}
+     */
+    get stack() {
+        const layers = [];
+        for (const route of this._routes) {
+            if (route.use) {
+                for (const callback of route.callbacks) {
+                    layers.push((route._layers ??= new Map()).get(callback) ?? layerFor(route, callback));
+                }
+            } else {
+                layers.push((route._routeLayer ??= routeLayer(route)));
+            }
+        }
+        return layers;
+    }
+
     /**
      * Registers a route, which every method helper and use() funnel into. Several paths at once
      * become several routes sharing the callbacks, as Express allows. Paths are normalised here and

package/src/types.d.ts

@@ -234,6 +234,15 @@ declare module "fulmine.js" {
 
         readonly uwsApp: uWS.TemplatedApp;
 
+        /**
+         * The layers the application routes through, in express's shape: one per middleware, one
+         * per route with the route's own handlers under it. Express keeps this on the router it
+         * builds and hands out as `app.router`, which is here too and is the application itself,
+         * so `app.stack` and `app.router.stack` are the same walk. Read-only: it is rebuilt from
+         * the registered routes on every read, so putting a layer into it moves nothing.
+         */
+        readonly stack: any[];
+
         /**
          * Binds, and calls back the way Express 5 does: with nothing when the socket is listening,
          * and with the error when the bind failed, since Express registers the listen callback on