fulmine.js 5.1.7 → 5.1.9

package/README.md

@@ -25,6 +25,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
 
 [![npm version](https://img.shields.io/npm/v/fulmine.js)](https://www.npmjs.com/package/fulmine.js)
 [![Node.js >= 22.0.0](https://img.shields.io/badge/Node.js-%3E=22.0.0-green)](https://nodejs.org)
+[![Coverage Status](https://coveralls.io/repos/github/nigrosimone/fulmine.js/badge.svg?branch=main)](https://coveralls.io/github/nigrosimone/fulmine.js?branch=main)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
 ## Why this exists
@@ -55,7 +56,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)** (the link lands filtered on the JavaScript entries): first among the JavaScript entries and second overall across every language on the board. The saved run measures 7.64 million pipelined requests per second, 1.12 million on the json profile, 457 thousand on compressed json and 222 thousand on the Postgres profile.
+- **[HttpArena](https://www.http-arena.com/#sort=rps:-1&q=Js)** (the link lands filtered on the JavaScript entries): first among the JavaScript entries, across fifteen subscribed profiles. The saved runs measure 24.3 million WebSocket echoes per second pipelined and 3.77 million one-at-a-time (past Bun's own dedicated WebSocket entry), 7.3 million pipelined HTTP requests per second, 1.12 million on the json profile with 1.04 million of that surviving TLS, 457 thousand on compressed json, and 359 thousand on the Postgres CRUD profile, within ten percent of the leading Rust and C# entries there.
 - **[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.
@@ -226,9 +227,10 @@ which runs the same file against Express and against Fulmine and compares the ou
 
 ## HTTP/3
 
-HTTP/3 is supported. To use:
+There is an `http3: true` option, inherited from Ultimate Express, that asks µWebSockets.js for its experimental HTTP/3 app. **It is guarded off with the currently pinned µWS build**: asking for it throws a clear error, because the underlying `H3App` segfaults during construction on Linux, verified with µWS alone before a single request is served. On Windows the listener does come up, but nothing answers over QUIC that we could verify, and shipping an option that works on no deployable platform helps nobody. A skipped canary test probes `H3App` on every CI run and will turn red the day µWS ships working QUIC in its prebuilt binaries, which is when the guard goes and this section changes.
 
 ```js
+// what it would look like, once µWS's H3 support actually works
 const app = express({
     http3: true,
     uwsOptions: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.1.7",
+    "version": "5.1.9",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -13,7 +13,7 @@
         "test:types": "tsd --files tests/types/*.test-d.ts",
         "test:express": "node tools/express-suite.js",
         "benchmark:compare": "node benchmark/run.js",
-        "cover": "npm run cover:unit && npm run cover:report",
+        "cover": "npm run cover:full && npm run cover:report",
         "cover:unit": "nyc --silent npm run test",
         "cover:report": "nyc report --reporter=html",
         "lint": "eslint .",
@@ -25,7 +25,9 @@
         "typecheck": "tsc -p tsconfig.typecheck.json",
         "benchmark:ab": "node benchmark/ab.js",
         "benchmark:profile": "node benchmark/profile.js",
-        "release:local": "node tools/release-local.js"
+        "release:local": "node tools/release-local.js",
+        "cover:full": "nyc --silent npm run test && nyc --silent --no-clean npm run test:unit && nyc --silent --no-clean npm run test:express && nyc report",
+        "cover:check": "nyc check-coverage --statements 93 --branches 88 --functions 92 --lines 93"
     },
     "engines": {
         "node": ">=22"

package/src/application.js

@@ -15,10 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// H3App, DeclarativeResponse and _cfg all exist at runtime but are missing from the
-// declaration file the package ships, so the module is read through a loose alias
 const uWS = require("uWebSockets.js");
-const uWSAny = /** @type {any} */ (uWS);
 const Router = require("./router.js");
 const {
     removeDuplicateSlashes,
@@ -102,10 +99,14 @@ class Application extends Router {
         if (settings.uwsApp) {
             this.uwsApp = settings.uwsApp;
         } else if (settings.http3) {
-            if (!settings.uwsOptions.key_file_name || !settings.uwsOptions.cert_file_name) {
-                throw new Error("uwsOptions.key_file_name and uwsOptions.cert_file_name are required for HTTP/3");
-            }
-            this.uwsApp = uWSAny.H3App(settings.uwsOptions);
+            // uWS.H3App exists in the pinned build but its QUIC stack does not: the constructor
+            // segfaults on Linux and hangs forever on Windows before serving a single request,
+            // verified 2026-08-05 with uWS alone. A clear throw beats a native crash; this
+            // branch goes back to H3App once uNetworking ships working QUIC in the prebuilts.
+            throw new Error(
+                "http3 is not usable with the pinned uWebSockets.js build: its H3App crashes " +
+                    "during construction. Track uNetworking/uWebSockets.js for working QUIC support."
+            );
         } else if (settings.uwsOptions.key_file_name && settings.uwsOptions.cert_file_name) {
             this.uwsApp = uWS.SSLApp(settings.uwsOptions);
         } else {
@@ -365,6 +366,7 @@ class Application extends Router {
             if (value !== false && this._skipPresets?.size) {
                 for (const preset of this._skipPresets) {
                     preset.skipHeaders = false;
+                    preset.skipQuery = false;
                 }
                 this._skipPresets.clear();
             }

package/src/declarative.js

@@ -606,6 +606,13 @@ module.exports = function compileDeclarative(cb, app) {
             }
         }
 
+        // a handler that never sends is not a response: Express leaves the request waiting, so
+        // compiling the empty shape would answer a bare 200 where the ordinary path answers
+        // nothing at all. It has to fall back instead.
+        if (!sendUsed && !sendStatusUsed) {
+            return false;
+        }
+
         let decRes = new uWSAny.DeclarativeResponse();
 
         if (statusCode !== 200) {

package/src/request.js

@@ -263,9 +263,16 @@ module.exports = class Request extends Readable {
         this.app = app;
         // both forms are kept, because both are asked for: the query with its "?" goes into
         // req.url, and req.query parses the raw one. Keeping only the first meant slicing the "?"
-        // back off for every request that reads req.query.
-        this._rawQuery = req.getQuery() ?? "";
-        this.urlQuery = this._rawQuery === "" ? "" : "?" + this._rawQuery;
+        // back off for every request that reads req.query. When the chain provably reads
+        // neither, the native call is not made at all: the framework's own answers, the 404
+        // included, are written from the path alone
+        if (skipHolder !== undefined && skipHolder.skipQuery) {
+            this._rawQuery = "";
+            this.urlQuery = "";
+        } else {
+            this._rawQuery = req.getQuery() ?? "";
+            this.urlQuery = this._rawQuery === "" ? "" : "?" + this._rawQuery;
+        }
         if (preset) {
             // the registration's constants: two native crossings and their strings not asked for
             this.path = preset.path;

package/src/router.js

@@ -36,7 +36,7 @@ const compileDeclarative = require("./declarative.js");
 const statuses = require("statuses");
 const { METHODS } = require("http");
 const { isNodeRequest, serveNodeRequest } = require("./node-shim.js");
-const { chainSkipsHeaders } = require("./usage.js");
+const { chainUsage } = require("./usage.js");
 
 // every method the declarative compiler can emit: a patched one must disable compilation, or the
 // patch would be honoured everywhere but on compiled routes
@@ -693,9 +693,10 @@ function nativePreset(path, method, strict) {
         opPath: endsWithSlash && path !== "/" && !strict ? path.slice(0, -1) : path,
         isOptions: method === "OPTIONS",
         isHead: method === "HEAD",
-        // set at registration when the whole chain provably never reads a header; mutable,
-        // because a middleware added after listen has to be able to take it back
-        skipHeaders: false
+        // set at registration when the whole chain provably never reads a header, or never
+        // reads the query; mutable, because a middleware added after listen takes them back
+        skipHeaders: false,
+        skipQuery: false
     };
 }
 
@@ -1148,6 +1149,7 @@ module.exports = class Router extends EventEmitter {
         if (this._skipPresets?.size) {
             for (const preset of this._skipPresets) {
                 preset.skipHeaders = false;
+                preset.skipQuery = false;
             }
             this._skipPresets.clear();
         }
@@ -1469,8 +1471,8 @@ module.exports = class Router extends EventEmitter {
             // listen can take it back: a literal registration's preset doubles as it, and a
             // parameterised one, which has no preset, gets a holder of its own
             let skipHolder = preset;
-            if (skipHolder === undefined && skips) {
-                skipHolder = { skipHeaders: true };
+            if (skipHolder === undefined && (skips.skipHeaders || skips.skipQuery)) {
+                skipHolder = { skipHeaders: skips.skipHeaders, skipQuery: skips.skipQuery };
                 (this._skipPresets ??= new Set()).add(skipHolder);
             }
             // all three are registration-time constants: computing them in the handler was a
@@ -1532,8 +1534,9 @@ module.exports = class Router extends EventEmitter {
         // headers), no error middleware may exist anywhere (a throw hands the request to code
         // the analysis never saw), and every callback in the chain has to pass the source
         // analysis in usage.js, whose default answer is no.
-        let getSkips = false;
-        let headSkips = false;
+        const NO_SKIPS = { skipHeaders: false, skipQuery: false };
+        let getSkips = NO_SKIPS;
+        let headSkips = NO_SKIPS;
         if (route.method === "GET" && this.get("etag") === false) {
             let hasErr = this._hasErrMwCache;
             if (hasErr === undefined) {
@@ -1544,15 +1547,16 @@ module.exports = class Router extends EventEmitter {
                 // route may be able to catch the same path
                 const owner = route.owner ?? this;
                 const noLaterMatch = !owner._isFollowedByAnOverlap.call(owner, route, owner._routes);
-                getSkips = chainSkipsHeaders(getChain, noLaterMatch);
-                headSkips = headChain === getChain ? getSkips : chainSkipsHeaders(headChain, noLaterMatch);
+                getSkips = chainUsage(getChain, noLaterMatch);
+                headSkips = headChain === getChain ? getSkips : chainUsage(headChain, noLaterMatch);
             }
         }
         // remembered so a middleware or setting arriving after listen can take the skips back
         const makePreset = (path, method, skips) => {
             const preset = nativePreset(path, method, strictHere);
-            if (skips) {
-                preset.skipHeaders = true;
+            if (skips.skipHeaders || skips.skipQuery) {
+                preset.skipHeaders = skips.skipHeaders;
+                preset.skipQuery = skips.skipQuery;
                 (this._skipPresets ??= new Set()).add(preset);
             }
             return preset;

package/src/usage.js

@@ -13,6 +13,13 @@ const kGetSafe = Symbol("fulmine.getSafe");
 // the parameter, so anything that can reach another object could reach headers through it.
 const REQ_OK = new Set(["query", "params", "body", "method", "path", "url", "baseUrl", "originalUrl", "route"]);
 
+// Reading any of these needs the query string fetched: req.url and req.originalUrl carry it
+const REQ_QUERY = new Set(["query", "url", "originalUrl"]);
+
+// Writing any of these re-enters routing: dispatch treats a changed req.url as a rewrite and
+// walks routes nobody analyzed, so an assignment is as disqualifying as an unknown call
+const REQ_NO_WRITE = new Set(["url", "originalUrl", "path", "baseUrl", "method"]);
+
 // What a handler may do with `res`: writing the response. Anything that negotiates against
 // request headers (format, redirect, sendFile, jsonp) is deliberately absent.
 const RES_OK = new Set([
@@ -38,25 +45,26 @@ const RES_OK = new Set([
     "cork"
 ]);
 
-// what the analysis can say about one callback
-const NO = 0; // could read headers, or could not be read at all
-const SAFE = 1; // never reads a header, never touches next
-const SAFE_NEXT = 2; // never reads a header, calls next: fine mid-chain, and at the end of
-// the chain only when no later route could catch the fall-through
+// what the analysis can say about one callback, as independent facts
+const UNKNOWN = 1; // a shape the walk cannot vouch for: could do anything
+const NEXT_PLAIN = 2; // calls next() bare: advances the chain, may fall off its end
+const NEXT_ERROR = 4; // calls next(err): lands in the framework's own error answer
+const QUERY = 8; // reads req.query, req.url or req.originalUrl
 
 const verdicts = new WeakMap();
 
 /**
- * What one callback provably does. The default is NO: any shape this walk does not understand
- * and any alias of req, res or next keeps the header copy. That inversion is what makes
- * source analysis sound to act on.
+ * What one callback provably does, as a mask of the facts above. The default is UNKNOWN: any
+ * shape this walk does not understand and any alias of req, res or next could do anything.
+ * That inversion is what makes source analysis sound to act on.
  *
  * @param {Function} fn
- * @returns {number} NO, SAFE or SAFE_NEXT
+ * @returns {number}
  */
-function callbackSkipsHeaders(fn) {
+function callbackUsage(fn) {
     if (fn[kGetSafe]) {
-        return SAFE_NEXT;
+        // the body parsers: they advance the chain and read nothing a skip would miss
+        return NEXT_PLAIN;
     }
     let verdict = verdicts.get(fn);
     if (verdict === undefined) {
@@ -68,7 +76,13 @@ function callbackSkipsHeaders(fn) {
 
 /** @param {Function} fn @returns {number} */
 function analyze(fn) {
-    let code = fn.toString();
+    // toString is application-controlled and may throw or answer anything: unreadable is unknown
+    let code;
+    try {
+        code = String(fn.toString());
+    } catch {
+        return UNKNOWN;
+    }
     if (code.startsWith("function") || code.startsWith("async function")) {
         code = code.replace(/function *\(/, "function __cb(");
     }
@@ -77,11 +91,11 @@ function analyze(fn) {
         tree = acorn.parse(code, { ecmaVersion: "latest" });
     } catch {
         // class methods and native functions do not parse alone, and unread code is unknown code
-        return NO;
+        return UNKNOWN;
     }
     let root = /** @type {any} */ (tree.body[0]);
     if (!root) {
-        return NO;
+        return UNKNOWN;
     }
     if (root.type === "ExpressionStatement") {
         root = root.expression;
@@ -91,14 +105,14 @@ function analyze(fn) {
         root.type !== "ArrowFunctionExpression" &&
         root.type !== "FunctionExpression"
     ) {
-        return NO;
+        return UNKNOWN;
     }
 
     const params = /** @type {any[]} */ (root.params);
     // rest or destructured parameters alias the objects somewhere the walk cannot follow
     for (const p of params) {
         if (p.type !== "Identifier") {
-            return NO;
+            return UNKNOWN;
         }
     }
     const reqName = params[0] ? params[0].name : null;
@@ -108,15 +122,38 @@ function analyze(fn) {
     // Every appearance of the three names in the whole body is judged, nested functions
     // included: an inner binding that shadows one of them only makes this stricter, never
     // looser, so scope tracking is not needed for soundness.
-    let ok = true;
-    let usesNext = false;
+    let mask = 0;
     walk(root.body, null, (node, parent) => {
-        if (!ok || node.type !== "Identifier") {
+        if (mask & UNKNOWN) {
+            return;
+        }
+        if (node.type === "MemberExpression" && !node.computed && node.object.type === "Identifier") {
+            const owner = node.object.name;
+            if (owner !== reqName) {
+                return;
+            }
+            const member = node.property.name;
+            if (REQ_QUERY.has(member)) {
+                mask |= QUERY;
+            }
+            // an assignment, an update or a delete on the routing members re-enters dispatch
+            if (
+                REQ_NO_WRITE.has(member) &&
+                parent &&
+                ((parent.type === "AssignmentExpression" && parent.left === node) ||
+                    (parent.type === "UpdateExpression" && parent.argument === node) ||
+                    (parent.type === "UnaryExpression" && parent.operator === "delete" && parent.argument === node))
+            ) {
+                mask |= UNKNOWN;
+            }
+            return;
+        }
+        if (node.type !== "Identifier") {
             return;
         }
         const name = node.name;
         if (name === "eval" || name === "arguments") {
-            ok = false;
+            mask |= UNKNOWN;
             return;
         }
         if (name !== reqName && name !== resName && name !== nextName) {
@@ -140,17 +177,17 @@ function analyze(fn) {
         }
         if (name === nextName) {
             // calling next is how a chain advances, and past its end or with an error the
-            // request lands in the framework's own final handler, which the constructor's
+            // request lands in the framework's own final answer, which the constructor's
             // accept pre-read covers. Anything but a direct call aliases the continuation,
             // and an argument that could be the string "route" would leave the chain for
             // routes nobody analyzed, so only shapes that cannot be a string pass.
             if (!parent || parent.type !== "CallExpression" || parent.callee !== node) {
-                ok = false;
+                mask |= UNKNOWN;
                 return;
             }
-            usesNext = true;
             const args = parent.arguments;
             if (args.length === 0) {
+                mask |= NEXT_PLAIN;
                 return;
             }
             const arg = args[0];
@@ -160,20 +197,22 @@ function analyze(fn) {
                     arg.type !== "ObjectExpression" &&
                     !(arg.type === "Literal" && typeof arg.value !== "string"))
             ) {
-                ok = false;
+                mask |= UNKNOWN;
+                return;
             }
+            mask |= NEXT_ERROR;
             return;
         }
         if (!parent || parent.type !== "MemberExpression" || parent.object !== node || parent.computed) {
-            ok = false;
+            mask |= UNKNOWN;
             return;
         }
         const member = parent.property.name;
         if (name === reqName ? !REQ_OK.has(member) : !RES_OK.has(member)) {
-            ok = false;
+            mask |= UNKNOWN;
         }
     });
-    return ok ? (usesNext ? SAFE_NEXT : SAFE) : NO;
+    return mask;
 }
 
 /**
@@ -207,41 +246,47 @@ function walk(node, parent, visit) {
 }
 
 /**
- * Whether a native literal route's whole chain provably never reads a request header, so the
- * request constructor may skip copying them and read the few framing headers directly.
+ * What a native route's whole chain provably never does, so the request constructor may leave
+ * that work undone: skipHeaders spares the header copy, skipQuery the query fetch.
  *
- * A callback that calls next passes anywhere but in the terminal route, where next would fall
- * out of the chain: there it only passes when the caller established that no later route
- * could catch the fall-through.
+ * A callback that calls next() bare passes anywhere but in the terminal route, where it would
+ * fall out of the chain: there it only passes when the caller established that no later route
+ * could catch the fall-through. The framework's own 404 answers with the path alone, so the
+ * fall-through itself needs neither headers nor query.
  *
  * @param {any[]} chain the routes the native handler runs, in order, this route last
  * @param {boolean} allowTerminalNext whether a fall-through past the chain lands only in the
- *   framework's own final handler
- * @returns {boolean}
+ *   framework's own final answer
+ * @returns {{skipHeaders: boolean, skipQuery: boolean}}
  */
-function chainSkipsHeaders(chain, allowTerminalNext) {
+function chainUsage(chain, allowTerminalNext) {
+    const none = { skipHeaders: false, skipQuery: false };
+    let query = false;
     for (let i = 0; i < chain.length; i++) {
         const entry = chain[i];
         const callbacks = entry.callbacks;
         if (!Array.isArray(callbacks)) {
-            return false;
+            return none;
         }
         const terminal = i === chain.length - 1;
         for (const cb of callbacks) {
             if (typeof cb !== "function") {
-                return false;
+                return none;
+            }
+            const mask = callbackUsage(cb);
+            if (mask & UNKNOWN || (mask & NEXT_PLAIN && terminal && !allowTerminalNext)) {
+                return none;
             }
-            const verdict = callbackSkipsHeaders(cb);
-            if (verdict === NO || (verdict === SAFE_NEXT && terminal && !allowTerminalNext)) {
-                return false;
+            if (mask & QUERY) {
+                query = true;
             }
         }
         // a param callback runs code this walk never saw
         if (entry.paramCallbacks && entry.paramCallbacks.size > 0) {
-            return false;
+            return none;
         }
     }
-    return true;
+    return { skipHeaders: true, skipQuery: !query };
 }
 
-module.exports = { chainSkipsHeaders, callbackSkipsHeaders, kGetSafe };
+module.exports = { chainUsage, callbackUsage, kGetSafe, UNKNOWN, NEXT_PLAIN, NEXT_ERROR, QUERY };