fulmine.js 5.1.0 → 5.1.2

package/README.md

@@ -37,7 +37,7 @@ Compatibility here is not a claim, it is a test suite. Every test runs against r
 
 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. Plain routing lands between 1.9x and 3.9x: hello-world 1.9x to 2.7x, an API endpoint with params and a query 3x to 3.8x, five route shapes served by one process 2.7x to 3.9x, nested routers 2.2x to 2.8x, a urlencoded body 3.2x to 3.8x, a thousand concurrent connections 2.7x to 3x. Route tables are where the native router shows: a thousand routes 9.8x to 12.7x, with a parameter in every one of them 9.9x to 14.3x, a parameterised route in a mounted router 7.4x 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.35x to 1.55x after the per-request allocation work of August 2026.
+**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. Plain routing lands between 1.9x and 4.3x: hello-world 1.9x to 2.2x, an API endpoint with params and a query 3.2x to 4.3x, five route shapes served by one process 2.5x to 3.3x, nested routers 2.1x to 3.1x, a urlencoded body 3.4x to 4.1x, a thousand concurrent connections 2.7x to 3.2x. Route tables are where the native router shows: a thousand routes 9.7x to 12.9x, with a parameter in every one of them 10.4x to 14x, a parameterised route in a mounted router 7.1x to 8.3x. 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.5x to 1.7x after the per-request work of August 2026.
 
 **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 around 1.0x to 1.2x, and no amount of work on either server moves it. The benchmark labels those rows rather than quietly publishing them as if the two were equivalent.
 
@@ -51,6 +51,15 @@ and posts the result where it belongs: as a comment on the commit or the pull re
 `benchmark-summary` artifact on the run, see [`benchmark/README.md`](./benchmark/README.md)
 to run it yourself.
 
+## Public benchmarks
+
+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)** (the link lands filtered on the JavaScript entries): the saved run measures 5.89 million pipelined requests per second, 1.12 million on baseline and 1.04 million on the json profile, ahead of every JavaScript entry on the board.
+- **[web-frameworks](https://github.com/the-benchmarker/web-frameworks)**: entry merged, numbers arrive with their next published round.
+
+More to come as their maintainers take the entries in.
+
 ## Attribution
 
 Fulmine is a derivative work of [Ultimate Express](https://github.com/dimdenGD/ultimate-express) by [@dimdenGD](https://github.com/dimdenGD), used under the Apache License 2.0. The full commit history is preserved, so the original authorship is visible in the repository itself.

package/package.json

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

package/src/application.js

@@ -120,9 +120,10 @@ class Application extends Router {
              * @param {any} req
              * @param {any} res
              * @param {any} app
+             * @param {any} [preset]
              */
-            constructor(req, res, app) {
-                super(req, res, app);
+            constructor(req, res, app, preset) {
+                super(req, res, app, preset);
             }
         };
         this._response = class extends Response {
@@ -365,10 +366,11 @@ class Application extends Router {
      *
      * @param {any} res uWS response
      * @param {any} req uWS request, readable only during this call
+     * @param {any} [preset] a literal registration's constants, see nativePreset in the router
      * @returns {any} the request, with the response reachable as request.res
      */
-    handleRequest(res, req) {
-        const request = super.handleRequest(res, req);
+    handleRequest(res, req, preset) {
+        const request = super.handleRequest(res, req, preset);
         // removal rides the close listener the Response constructor already has, since a second
         // once() per request measured a tenth of a microsecond on the hot path.
         // An aborted response only flips its flags without emitting 'close', which is why
@@ -388,7 +390,11 @@ class Application extends Router {
             const response = request.res;
 
             try {
-                const matchedRoute = await this._routeRequest(request, response);
+                const routed = this._routeRequest(request, response);
+                // dispatch has run its synchronous stretch inside _routeRequest by now, still
+                // under the cork uWS holds for this callback; the await below leaves it
+                response._corkNeeded = true;
+                const matchedRoute = await routed;
                 if (!matchedRoute && !response.headersSent && !response.aborted) {
                     this._endUnmatched(request, response);
                 }

package/src/request.js

@@ -140,7 +140,8 @@ module.exports = class Request extends Readable {
 
     // Flat, name then value: an array of pairs meant one array allocated per header on every
     // request, and a request carries eight or ten of them. Everything that reads this walks it two
-    // at a time.
+    // at a time. The names are lowercase by contract: uWS lowers them on the wire and the node
+    // shim lowers them in its forEach, so readers compare without lowering again.
     #rawHeadersEntries = [];
 
     /** @type {string|undefined|null} */
@@ -148,6 +149,9 @@ module.exports = class Request extends Readable {
 
     #paused = false;
 
+    // a bodyless request whose empty end has not been delivered yet, see the constructor
+    #emptyBody = false;
+
     body;
 
     res;
@@ -168,7 +172,9 @@ module.exports = class Request extends Readable {
         ) {
             r._connectionClose = true;
         } else if (
-            (headerKey.length === 14 && headerKey === "content-length") ||
+            // content-length: 0 declares that there is nothing, which is the same as declaring
+            // nothing: the stream ends empty either way, without the onData subscription
+            (headerKey.length === 14 && headerKey === "content-length" && value !== "0") ||
             (headerKey.length === 17 && headerKey === "transfer-encoding")
         ) {
             // noticed here so the body decision in the constructor does not build the headers object
@@ -190,8 +196,11 @@ module.exports = class Request extends Readable {
      * @param {any} req the uWS request, readable only during this call
      * @param {any} res the uWS response
      * @param {any} app the application or router this request arrived at
+     * @param {any} [preset] a literal native registration's constants: µWS matched the URL byte
+     *   for byte against that exact pattern and dispatched by method, so path, method and what
+     *   derives from them are known without asking
      */
-    constructor(req, res, app) {
+    constructor(req, res, app, preset) {
         // the same object every time: Readable reads these options and never writes to them
         super(READABLE_OPTIONS);
         this._res = res;
@@ -211,25 +220,39 @@ module.exports = class Request extends Readable {
         // back off for every request that reads req.query.
         this._rawQuery = req.getQuery() ?? "";
         this.urlQuery = this._rawQuery === "" ? "" : "?" + this._rawQuery;
-        // getUrl() is the path already, so the query is joined on and then not split off again.
-        // Building originalUrl and picking the path back out of it with indexOf and substring was
-        // a search and a second string for something uWS had just handed over.
-        this.path = req.getUrl();
-        this.originalUrl = this.path + this.urlQuery;
-        this.url = this.originalUrl;
-        // what the router last wrote to req.url. A middleware assigning something else is a
-        // rewrite, which express honours, and dispatch compares against this to notice it
-        this._lastUrl = this.originalUrl;
-        // charCodeAt rather than indexing: s[i] builds a one character string to throw away
-        this.endsWithSlash = this.path.charCodeAt(this.path.length - 1) === 0x2f;
-        this._opPath = this.path;
-        this._originalPath = this.path;
-        if (this.endsWithSlash && this.path !== "/" && !this.app.get("strict routing")) {
-            this._opPath = this._opPath.slice(0, -1);
-        }
-        this.method = req.getCaseSensitiveMethod().toUpperCase();
-        this._isOptions = this.method === "OPTIONS";
-        this._isHead = this.method === "HEAD";
+        if (preset) {
+            // the registration's constants: two native crossings and their strings not asked for
+            this.path = preset.path;
+            this.originalUrl = preset.path + this.urlQuery;
+            this.url = this.originalUrl;
+            this._lastUrl = this.originalUrl;
+            this.endsWithSlash = preset.endsWithSlash;
+            this._opPath = preset.opPath;
+            this._originalPath = preset.path;
+            this.method = preset.method;
+            this._isOptions = preset.isOptions;
+            this._isHead = preset.isHead;
+        } else {
+            // getUrl() is the path already, so the query is joined on and then not split off
+            // again. Building originalUrl and picking the path back out of it with indexOf and
+            // substring was a search and a second string for something uWS had just handed over.
+            this.path = req.getUrl();
+            this.originalUrl = this.path + this.urlQuery;
+            this.url = this.originalUrl;
+            // what the router last wrote to req.url. A middleware assigning something else is a
+            // rewrite, which express honours, and dispatch compares against this to notice it
+            this._lastUrl = this.originalUrl;
+            // charCodeAt rather than indexing: s[i] builds a one character string to throw away
+            this.endsWithSlash = this.path.charCodeAt(this.path.length - 1) === 0x2f;
+            this._opPath = this.path;
+            this._originalPath = this.path;
+            if (this.endsWithSlash && this.path !== "/" && !this.app.get("strict routing")) {
+                this._opPath = this._opPath.slice(0, -1);
+            }
+            this.method = req.getCaseSensitiveMethod().toUpperCase();
+            this._isOptions = this.method === "OPTIONS";
+            this._isHead = this.method === "HEAD";
+        }
         this.params = {};
 
         // Two Sets per request, for two things almost no request needs.
@@ -258,25 +281,19 @@ module.exports = class Request extends Readable {
             this.rawIp = this._res.getRemoteAddress();
         }
 
-        const additionalMethods = this.app.get("body methods");
-        // skip reading body for non-POST requests
-        // this makes it +10k req/sec faster
-        if (
-            this.method === "POST" ||
-            this.method === "PUT" ||
-            this.method === "PATCH" ||
-            this.method === "QUERY" ||
-            (additionalMethods && additionalMethods.includes(this.method)) ||
-            // any request that declares a body carries one, whatever the verb: a GET with
-            // content-length left unread would end this stream empty and poison the keep-alive
-            // connection with its unconsumed bytes. uWS itself discards GET bodies, so this is
-            // the node shim's path
-            /** @type {any} */ (this)._declaresBody
-        ) {
+        // A body exists on the wire only when the request declares one, content-length or
+        // transfer-encoding, whatever the verb, and that evidence was spotted during the header
+        // copy. The verb list and the "body methods" settings read this branch used to pay per
+        // request said nothing the headers had not already said; the setting still gates the
+        // body parsers, which is where it matters
+        if (/** @type {any} */ (this)._declaresBody) {
             this._subscribeBody();
         } else {
             this.receivedData = true;
-            this.push(null);
+            // 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
+            this.#emptyBody = true;
         }
     }
 
@@ -319,6 +336,13 @@ module.exports = class Request extends Readable {
      * lift the backpressure that a full queue put on it.
      */
     _read() {
+        // first, so a bodyless stream still ends for a consumer that arrives after the
+        // response finished, which express allows
+        if (this.#emptyBody) {
+            this.#emptyBody = false;
+            this.push(null);
+            return;
+        }
         if (this.#paused && !this.#responseEnded) {
             this.#paused = false;
             this._res.resume();
@@ -665,10 +689,10 @@ module.exports = class Request extends Readable {
                 const entries = this.#rawHeadersEntries;
                 for (let i = 0, len = entries.length; i < len; i += 2) {
                     const key = entries[i];
-                    // 'if-none-match'.length === 13, 'if-modified-since'.length === 17
+                    // 'if-none-match'.length === 13, 'if-modified-since'.length === 17; the
+                    // entries carry lowercase names by contract, so this compares them as they are
                     if (key.length === 13 || key.length === 17) {
-                        const lower = key.toLowerCase();
-                        if (lower === "if-none-match" || lower === "if-modified-since") {
+                        if (key === "if-none-match" || key === "if-modified-since") {
                             hasConditional = true;
                             break;
                         }
@@ -852,7 +876,8 @@ module.exports = class Request extends Readable {
         const entries = this.#rawHeadersEntries;
         for (let index = 0, len = entries.length; index < len; index += 2) {
             const value = entries[index + 1];
-            const key = entries[index].toLowerCase();
+            // lowercase by the entries' contract, see the field declaration
+            const key = entries[index];
             if (Object.hasOwn(headers, key)) {
                 if (discardedDuplicates.has(key)) {
                     continue;

package/src/response.js

@@ -175,6 +175,9 @@ module.exports = class Response extends Writable {
         }
 
         this.body = undefined;
+        // false while the uWS route handler is still in its synchronous window, where uWS holds
+        // the socket corked itself; the two uWS entry points flip it once that window closes
+        this._corkNeeded = false;
         // shared methods, not arrows: two closures and a once() wrapper here were four
         // allocations per request. EventEmitter calls listeners with this = the emitter.
         this.on("error", this._onAbortError);
@@ -272,14 +275,17 @@ module.exports = class Response extends Writable {
             if (!this.headersSent) {
                 this.writeHead(this.statusCode);
                 // "unknown" and not the bare number: node writes that reason phrase for a code it
-                // has no message for, so the raw status lines match
-                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+                // has no message for, so the raw status lines match. The default 200 with no
+                // phrase is uWS's own head, byte for byte, so it is not written at all
+                if (this.statusCode !== 200 || this.statusText !== undefined) {
+                    this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+                }
                 this.writeHeaders(typeof chunk === "string");
             }
 
             if (!Buffer.isBuffer(chunk) && !(chunk instanceof ArrayBuffer)) {
+                // the Buffer view is enough, uWS reads its offset and length itself
                 chunk = Buffer.from(chunk);
-                chunk = chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength);
             }
 
             if (this.chunkedTransfer) {
@@ -475,47 +481,66 @@ module.exports = class Response extends Writable {
             return this;
         }
         this.writeHead(this.statusCode);
-        this._res.cork(() => {
-            if (!this.headersSent) {
-                // freshness is not decided here. node's end() knows nothing about conditional
-                // requests, and Express answers 304 from send() and from sendFile(), each of
-                // which strips the entity headers first. Deciding it here meant res.end("body")
-                // answered 304 and dropped the body that the caller had just written.
-                // "unknown" for a code without a message, as node's status line has it
+        // uWS holds the socket corked for the synchronous window of its route handler, and
+        // cork inside cork is a passthrough: the wrapper and its closure are only paid once the
+        // answer has outlived that window, which is what _corkNeeded records
+        if (this._corkNeeded) {
+            this._res.cork(() => this._finish(data, cb));
+        } else {
+            this._finish(data, cb);
+        }
+        return this;
+    }
+
+    /**
+     * The corked tail of end(): status, headers, body and the finish events. Split out so a
+     * synchronous answer calls it straight, already inside uWS's own cork.
+     *
+     * @param {any} data
+     * @param {any} cb
+     */
+    _finish(data, cb) {
+        if (!this.headersSent) {
+            // freshness is not decided here. node's end() knows nothing about conditional
+            // requests, and Express answers 304 from send() and from sendFile(), each of
+            // which strips the entity headers first. Deciding it here meant res.end("body")
+            // answered 304 and dropped the body that the caller had just written.
+            // "unknown" for a code without a message, as node's status line has it.
+            // The default 200 with no phrase is not written at all: uWS emits the identical
+            // "HTTP/1.1 200 OK" head on its own, and the crossing costs more than it says
+            if (this.statusCode !== 200 || this.statusText !== undefined) {
                 this._res.writeStatus(statusLine(this.statusCode, this.statusText));
-                this.writeHeaders(true);
             }
-            const contentLength = this.headers["content-length"];
-            if (STATUSES_WITHOUT_BODY.has(this.statusCode) || this.statusCode < 200) {
-                // no body and no length describing one, whatever the caller passed. node decides
-                // this the same way, from the status alone, so res.status(304).end("x") sends the
-                // status and nothing else on either.
-                this._res.endWithoutBody();
-            } else if (!data && contentLength) {
-                this._res.endWithoutBody(contentLength.toString());
+            this.writeHeaders(true);
+        }
+        const contentLength = this.headers["content-length"];
+        if (STATUSES_WITHOUT_BODY.has(this.statusCode) || this.statusCode < 200) {
+            // no body and no length describing one, whatever the caller passed. node decides
+            // this the same way, from the status alone, so res.status(304).end("x") sends the
+            // status and nothing else on either.
+            this._res.endWithoutBody();
+        } else if (!data && contentLength) {
+            this._res.endWithoutBody(contentLength.toString());
+        } else {
+            // a Buffer goes to uWS as the view it is: copying it into a fresh ArrayBuffer was
+            // an allocation per body, and uWS reads the view's own offset and length
+            if (this.req.method === "HEAD") {
+                const length = Buffer.byteLength(data ?? "");
+                this._res.endWithoutBody(length.toString());
             } else {
-                if (data instanceof Buffer) {
-                    data = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
-                }
-                if (this.req.method === "HEAD") {
-                    const length = Buffer.byteLength(data ?? "");
-                    this._res.endWithoutBody(length.toString());
-                } else {
-                    this._res.end(data);
-                }
+                this._res.end(data);
             }
+        }
 
-            this.finished = true;
-            this.#socket?.emit("close");
-            this.emit("finish");
-            this.emit("close");
-            cb &&
-                queueMicrotask(() => {
-                    this.#ended = true;
-                    cb();
-                });
-        });
-        return this;
+        this.finished = true;
+        this.#socket?.emit("close");
+        this.emit("finish");
+        this.emit("close");
+        cb &&
+            queueMicrotask(() => {
+                this.#ended = true;
+                cb();
+            });
     }
 
     /**

package/src/router.js

@@ -671,6 +671,30 @@ function onNativeAborted() {
     response.socket?.emit("error", err);
 }
 
+/**
+ *
+ */
+/**
+ * The per-request constants of a fully literal native registration. µWS matched the URL byte for
+ * byte against this exact pattern and dispatches by method, so the request constructor can take
+ * these as given instead of asking uWS and recomputing them on every request.
+ *
+ * @param {string} path the registered pattern, which is what getUrl() would have answered
+ * @param {string} method uppercase, fixed by which uWS verb the registration used
+ * @param {boolean} strict the owner's strict routing, frozen here like the twin registration is
+ */
+function nativePreset(path, method, strict) {
+    const endsWithSlash = path.charCodeAt(path.length - 1) === 0x2f;
+    return {
+        path,
+        method,
+        endsWithSlash,
+        opPath: endsWithSlash && path !== "/" && !strict ? path.slice(0, -1) : path,
+        isOptions: method === "OPTIONS",
+        isHead: method === "HEAD"
+    };
+}
+
 /**
  *
  */
@@ -1313,10 +1337,11 @@ module.exports = class Router extends EventEmitter {
      *
      * @param {any} res uWS response
      * @param {any} req uWS request, readable only during this call
+     * @param {any} [preset] a literal registration's constants, see nativePreset
      * @returns {any} the request, with the response reachable as request.res
      */
-    handleRequest(res, req) {
-        const request = new this._request(req, res, this);
+    handleRequest(res, req, preset) {
+        const request = new this._request(req, res, this, preset);
         const response = new this._response(res, request, this);
         request.res = response;
         response.req = request;
@@ -1381,7 +1406,7 @@ module.exports = class Router extends EventEmitter {
         if (route.path.includes(":")) {
             route.optimizedParams = route.path.match(regExParam).map((p) => p.slice(1));
         }
-        const makeHandler = (chain) => {
+        const makeHandler = (chain, preset) => {
             // all three are registration-time constants: computing them in the handler was a
             // closure and a scan of the chain on every native request.
             // Falling back resumes after the mount, not after the router's leaf: the leaf can have
@@ -1394,7 +1419,7 @@ module.exports = class Router extends EventEmitter {
             // and this one never did. nativeDone and nativeFail defer their epilogues to a
             // microtask, which is where the await used to resume, so the visible order holds
             return (res, req) => {
-                const request = this.handleRequest(res, req);
+                const request = this.handleRequest(res, req, preset);
                 const response = request.res;
                 if (optimizedParams) {
                     request.optimizedParams = new NullObject();
@@ -1408,6 +1433,10 @@ module.exports = class Router extends EventEmitter {
                 } catch (err) {
                     // what a throw inside a promise executor did: reject, once
                     nativeFail.call(walk, err);
+                } finally {
+                    // whatever runs after this line is outside the cork uWS held for this
+                    // callback, so later writes have to open their own
+                    response._corkNeeded = true;
                 }
             };
         };
@@ -1415,12 +1444,22 @@ module.exports = class Router extends EventEmitter {
         // chain runs without re-matching the method, so the get registration must not see it
         const getChain =
             route.method === "GET" ? optimizedPath.filter((r) => r.all || r.method !== "HEAD") : optimizedPath;
-        let fn = makeHandler(getChain);
         route.optimizedPath = optimizedPath;
 
+        // A fully literal registration knows path and method here, so each registration site
+        // hands the request constructor its own constants. An "any" registration serves every
+        // verb and a parameterised one matches paths it cannot spell, so both stay dynamic
+        const canPreset = !route.optimizedParams && method !== "any";
+        // the route's own router decides, not the app running the registration: a router created
+        // with { strict: true } and mounted on an app without it does not answer /things/, and
+        // registering that path here is the only way it could
+        const strictHere = Boolean((route.owner ?? this).get("strict routing"));
+
+        let fn = makeHandler(getChain, canPreset ? nativePreset(route.path, route.method, strictHere) : undefined);
+        const jsFn = fn;
+
         let replacedPath = route.path;
-        const realFn = fn;
-        const headFn = getChain.length === optimizedPath.length ? realFn : makeHandler(optimizedPath);
+        const headChain = getChain.length === optimizedPath.length ? getChain : optimizedPath;
 
         // the response prototype the route will really run under: its own app's, which sees a
         // method patched there or inherited from a parent app, falling back to the registering app
@@ -1443,17 +1482,29 @@ module.exports = class Router extends EventEmitter {
         }
 
         this.uwsApp[method](replacedPath, fn);
-        // the route's own router decides, not the app running the registration: a router created
-        // with { strict: true } and mounted on an app without it does not answer /things/, and
-        // registering that path here is the only way it could
-        if (!(route.owner ?? this).get("strict routing") && route.path[route.path.length - 1] !== "/") {
-            this.uwsApp[method](replacedPath + "/", fn);
+        if (!strictHere && route.path[route.path.length - 1] !== "/") {
+            // a declarative response answers the twin as itself; a preset handler cannot be
+            // shared, since the twin's path is its own constant
+            const slashFn =
+                fn !== jsFn
+                    ? fn
+                    : canPreset
+                      ? makeHandler(getChain, nativePreset(route.path + "/", route.method, strictHere))
+                      : fn;
+            this.uwsApp[method](replacedPath + "/", slashFn);
             if (method === "get") {
-                this.uwsApp.head(replacedPath + "/", headFn);
+                this.uwsApp.head(
+                    replacedPath + "/",
+                    makeHandler(headChain, canPreset ? nativePreset(route.path + "/", "HEAD", strictHere) : undefined)
+                );
             }
         }
         if (method === "get") {
-            this.uwsApp.head(replacedPath, headFn);
+            // its own handler always: the shared one would carry the GET registration's method
+            this.uwsApp.head(
+                replacedPath,
+                makeHandler(headChain, canPreset ? nativePreset(route.path, "HEAD", strictHere) : undefined)
+            );
         }
     }