fulmine.js 5.21.2 → 5.21.4

package/README.md

@@ -1,6 +1,6 @@
 <img src="./assets/logo-mark.svg" alt="" width="88" align="right">
 
-# Fulmine.js: the drop-in Express 5 replacement, up to 20x faster
+# Fulmine.js: the drop-in Express 5 replacement, up to 22x faster
 
 **Fulmine** (lightning in Italian ⚡) is an Express 5 compatible web framework for Node.js, built on
 [µWebSockets.js](https://github.com/uNetworking/uWebSockets.js) instead of `node:http`. Same API, same
@@ -24,8 +24,8 @@ const express = require("fulmine.js"); // instead of require("express")
 
 ## Why Fulmine
 
-- **Faster than Express, measured.** 1.3x to 4.9x on plain routing, 2x to 5x on a request with a body,
-  7x to 20x on a large route table. Routes are matched in C++ by µWS's own router,
+- **Faster than Express, measured.** 1.2x to 4.5x on plain routing, 1.7x to 5x on a request with a body,
+  7x to 22x on a large route table. Routes are matched in C++ by µWS's own router,
   and a simple enough handler is answered without running any JavaScript at all.
 - **Zero rewrite.** `helmet`, `cors`, `passport`, `morgan`, `multer`, `express-session` and the rest of
   the Express ecosystem keep working. Not "mostly": every test runs against real Express first and the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.21.2",
+    "version": "5.21.4",
     "description": "Drop-in Express 5 replacement on uWebSockets.js, up to 20x faster. Same API, your middleware and framework keep working.",
     "main": "src/index.js",
     "exports": {
@@ -20,6 +20,7 @@
     },
     "scripts": {
         "test": "node tests/index.js",
+        "gates": "node tools/gates.js",
         "test:unit": "node --expose-gc --test --test-timeout=120000 \"tests/unit/*.test.js\"",
         "test:types": "tsd --files tests/types/*.test-d.ts",
         "test:express": "node tools/express-suite.js",
@@ -137,10 +138,13 @@
         "@release-it/conventional-changelog": "^12.0.0",
         "@types/accepts": "^1.3.7",
         "@types/bytes": "^3.1.5",
+        "@types/compressible": "^2.0.3",
         "@types/content-disposition": "^0.5.9",
+        "@types/cookie": "^0.6.0",
         "@types/cookie-signature": "^1.1.2",
         "@types/encodeurl": "^1.0.3",
         "@types/etag": "^1.8.4",
+        "@types/fast-decode-uri-component": "^1.0.0",
         "@types/fresh": "^0.5.3",
         "@types/mime-types": "^3.0.1",
         "@types/ms": "^2.1.0",

package/src/adopt.js

@@ -36,7 +36,10 @@ const UWS_SPEC = /** @type {string} */ (require("../package.json").dependencies[
 /** The pnpm override that drops this package's own copy, so the project's direct one is the only one. */
 const UWS_OVERRIDE = `${SELF}>${UWS}`;
 
-/** Where each manager keeps its substitutions, and what to call it when telling someone. */
+/**
+ * Where each manager keeps its substitutions, and what to call it when telling someone.
+ * @type {Record<string, {keys: string[], reinstall: string}>}
+ */
 const MANAGERS = {
     npm: { keys: ["overrides"], reinstall: "npm install" },
     pnpm: { keys: ["pnpm", "overrides"], reinstall: "pnpm install" },

package/src/application.js

@@ -41,6 +41,9 @@ const { registerWebSocketRoutes } = require("./websocket.js");
 const { addServerMembers } = require("./server-shape.js");
 const { workerCount, forkWorkers, isSupervising, becomeSupervisor } = require("./cluster.js");
 
+/** @typedef {import("uWebSockets.js").HttpRequest} UwsRequest */
+/** @typedef {import("uWebSockets.js").HttpResponse} UwsResponse */
+
 const cpuCount = os.cpus().length;
 
 // marks a "trust proxy" the application never set, under express's key, so a sub-app may inherit
@@ -95,12 +98,14 @@ class Application extends Router {
     /**
      * A mounted app's settings chain onto its parent's, as in express.
      *
+     * @override
      * @type {boolean}
      */
     _inheritsSettings = true;
 
     /**
      * See Router#_isApplication.
+     * @override
      * @type {boolean}
      */
     _isApplication = true;
@@ -141,7 +146,7 @@ class Application extends Router {
     /** @type {Response} */
     response;
 
-    /** @type {boolean} */
+    /** @override @type {boolean} */
     listenCalled = false;
 
     /** @type {FSWorker[]} */
@@ -487,6 +492,7 @@ class Application extends Router {
      * @param {import("./router-utils.js").NativePreset} [preset] see nativePreset
      * @param {import("./router-utils.js").SkipHolder} [skipHolder] forwarded whole, dropping it
      *   silently turned every skip off
+     * @override
      * @returns {Request} the request, with the response as request.res
      */
     handleRequest(res, req, preset, skipHolder) {
@@ -509,6 +515,7 @@ class Application extends Router {
      * The µWS app, for what µWS offers that this does not (socket.io attaches to it). Made on
      * first ask, so an app served through node's http never loads the binary, see src/uws.js.
      *
+     * @override
      * @returns {any}
      */
     get uwsApp() {
@@ -521,7 +528,9 @@ class Application extends Router {
 
     /** The catch-all uWS handler, for every request no native route took. */
     _createRequestHandler() {
-        this.uwsApp.any("/*", (res, req) => this._serveGeneric(res, req));
+        this.uwsApp.any("/*", (/** @type {UwsResponse} */ res, /** @type {UwsRequest} */ req) =>
+            this._serveGeneric(res, req)
+        );
     }
 
     /**

package/src/cli.js

@@ -41,6 +41,7 @@ const TO = "fulmine.js";
 
 // modules this has a faster version of, reported and not rewritten: the replacement lives on the
 // express import, which may not be in scope where these are required
+/** @type {Record<string, string>} */
 const BUILT_IN_INSTEAD = {
     compression: "express.compression(), which takes the same options",
     "serve-static": "express.static()",

package/src/compression.js

@@ -20,6 +20,12 @@ limitations under the License.
  * What res.on was given, parked until there is a compressor to hang it on.
  * @typedef {Parameters<import("stream").Writable["on"]>} OnArgs
  */
+/**
+ * What the hooks below take: writeHead's arguments in node's two shapes, see applyWriteHead, and
+ * the callback write() and end() may carry in place of the encoding.
+ * @typedef {Parameters<Response["writeHead"]>} WriteHeadArgs
+ * @typedef {(err?: Error|null) => void} WriteCallback
+ */
 
 // express.compression(): the compression module's options, defaults and decision order, with three
 // differences: a whole body (res.send, res.json) is compressed in one call and goes out with a
@@ -229,8 +235,10 @@ function toBuffer(chunk, encoding) {
  *   compressed at all. The default says yes to any compressible content type.
  * @param {string} [options.enforceEncoding] what to use when the request carries no
  *   Accept-Encoding at all. Default "identity", which is to say nothing is compressed.
- * @param {object} [options.brotli] brotli options, `params` included. The default quality is 4.
- * @param {object} [options.zstd] zstd options, `params` included, node's own defaults otherwise.
+ * @param {import("zlib").BrotliOptions} [options.brotli] brotli options, `params` included. The
+ *   default quality is 4.
+ * @param {import("zlib").ZstdOptions} [options.zstd] zstd options, `params` included, node's own
+ *   defaults otherwise.
  * @param {string[]} [options.encodings] the encodings this middleware may answer with, out of
  *   "br", "zstd", "gzip" and "deflate". What is not named is never used, however the client ranks
  *   it. An uncompressed answer is always on offer, and enforceEncoding is outside this list. This
@@ -251,7 +259,7 @@ function compression(options) {
     const brotliOptions = { ...opts.brotli };
     brotliOptions.params = {
         [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
-        ...(opts.brotli && /** @type {import("zlib").BrotliOptions} */ (opts.brotli).params)
+        ...(opts.brotli && opts.brotli.params)
     };
     // zstd at node's default level is already in the band this middleware wants
     const zstdOptions = { ...opts.zstd };
@@ -380,11 +388,21 @@ function compression(options) {
                 }
             };
             // at writeHead too, its headers applied first as on-headers orders it
+            /**
+             * @param {WriteHeadArgs[0]} statusCode
+             * @param {WriteHeadArgs[1]} [statusMessage]
+             * @param {WriteHeadArgs[2]} [headers]
+             */
             res.writeHead = function writeHead(statusCode, statusMessage, headers) {
                 const reason = applyWriteHead(this, statusMessage, headers);
                 vary();
                 return _plainWriteHead.call(this, statusCode, reason);
             };
+            /**
+             * @param {any} [chunk]
+             * @param {BufferEncoding|WriteCallback} [encoding]
+             * @param {WriteCallback} [callback]
+             */
             res.end = function end(chunk, encoding, callback) {
                 vary();
                 return _plainEnd.call(this, chunk, encoding, callback);
@@ -492,6 +510,11 @@ function compression(options) {
         }
 
         // decided at writeHead too, its headers applied first as on-headers orders it
+        /**
+         * @param {WriteHeadArgs[0]} statusCode
+         * @param {WriteHeadArgs[1]} [statusMessage]
+         * @param {WriteHeadArgs[2]} [headers]
+         */
         res.writeHead = function writeHead(statusCode, statusMessage, headers) {
             const reason = applyWriteHead(this, statusMessage, headers);
             if (!decided) {
@@ -500,6 +523,11 @@ function compression(options) {
             return _writeHead.call(this, statusCode, reason);
         };
 
+        /**
+         * @param {any} chunk
+         * @param {BufferEncoding|WriteCallback} [encoding]
+         * @param {WriteCallback} [callback]
+         */
         res.write = function write(chunk, encoding, callback) {
             if (typeof encoding === "function") {
                 callback = encoding;
@@ -520,6 +548,11 @@ function compression(options) {
             return _write.call(this, chunk, encoding, callback);
         };
 
+        /**
+         * @param {any} [chunk]
+         * @param {BufferEncoding|WriteCallback} [encoding]
+         * @param {WriteCallback} [callback]
+         */
         res.end = function end(chunk, encoding, callback) {
             if (typeof chunk === "function") {
                 callback = chunk;
@@ -575,6 +608,10 @@ function compression(options) {
             return _end.call(this, chunk, callback);
         };
 
+        /**
+         * @param {OnArgs[0]} type
+         * @param {OnArgs[1]} listener
+         */
         res.on = function on(type, listener) {
             if (!listeners || type !== "drain") {
                 return _on.call(this, type, listener);

package/src/declarative.js

@@ -144,6 +144,7 @@ function literalValue(node) {
                 return literalValue(element);
             });
         case "ObjectExpression": {
+            /** @type {Record<string, unknown>} */
             const out = {};
             for (const property of node.properties) {
                 if (property.type !== "Property" || property.computed || property.kind !== "init") {
@@ -236,6 +237,11 @@ function readStatusAndHeaders(callExprs, headers) {
 
             for (let [header, value] of pairs) {
                 const name = String(header).toLowerCase();
+                // a chunked framing the handler asked for: a compiled response is one end() with a
+                // length, the ordinary path frames it through write(), see Response#writeHeaders
+                if (name === "transfer-encoding") {
+                    return null;
+                }
                 // res.set resolves a content-type through the mime database, setHeader does not
                 if (call.obj.propertyName !== "setHeader" && name === "content-type") {
                     const resolved = contentTypeSet(String(value));
@@ -266,6 +272,9 @@ function readStatusAndHeaders(callExprs, headers) {
             if (call.arguments[0].type !== "Literal" || call.arguments[1].type !== "Literal") {
                 return null;
             }
+            if (String(call.arguments[0].value).toLowerCase() === "transfer-encoding") {
+                return null;
+            }
             if (!headerIsWritable(String(call.arguments[0].value), String(call.arguments[1].value))) {
                 return null;
             }
@@ -289,8 +298,8 @@ function readStatusAndHeaders(callExprs, headers) {
  * @param {[string, string][]} headers written to
  * @param {any[]} body written to, a literal's value kept as it is
  * @param {Application|Router} app for the json settings
- * @param {string[]} queries names bound by a destructured req.query
- * @param {string[]} params names bound by a destructured req.params
+ * @param {Binding[]} queries what a destructured req.query bound
+ * @param {Binding[]} params what a destructured req.params bound
  * @returns {{sendUsed: boolean, bodyFromSend: boolean}|null}
  */
 function readBody(callExprs, headers, body, app, queries, params) {
@@ -383,10 +392,14 @@ function readBody(callExprs, headers, body, app, queries, params) {
                             }
                             body.push({ type, value: expr.property.name });
                         } else if (expr.type === "Identifier") {
-                            if (queries.includes(expr.name)) {
-                                body.push({ type: "query", value: expr.name });
-                            } else if (params.includes(expr.name)) {
-                                body.push({ type: "params", value: expr.name });
+                            // the key, not the local name: a minifier renames the local and uWS
+                            // would be asked for a parameter that does not exist
+                            const query = queries.find((binding) => binding.local === expr.name);
+                            const param = params.find((binding) => binding.local === expr.name);
+                            if (query) {
+                                body.push({ type: "query", value: query.key });
+                            } else if (param) {
+                                body.push({ type: "params", value: param.key });
                             } else {
                                 return null;
                             }
@@ -525,7 +538,8 @@ function readHandler(cb) {
         }
     }
 
-    const args = fn.params.map((param) => param.name);
+    // undefined for a destructured one, which readParamNames reads by hand
+    const args = fn.params.map((/** @type {any} */ param) => param.name);
 
     if (args.length < 2) {
         return null;
@@ -550,9 +564,40 @@ function readHandler(cb) {
  * @property {string} res
  * @property {string|undefined} queryName
  * @property {string|undefined} paramsName
- * @property {string[]} queries
- * @property {string[]} params
+ * @property {Binding[]} queries
+ * @property {Binding[]} params
+ */
+
+/**
+ * One name a destructured req.query or req.params bound, with the key it stands for: the same
+ * word in `{ id }`, two after a minifier has been through (`{ id: c }`).
+ * @typedef {object} Binding
+ * @property {string} local
+ * @property {string} key
+ */
+
+/**
+ * The bindings of one destructuring pattern, `{ id, name: n }`. False for a shape this cannot
+ * read: a computed key, a rest element, a default value or a nested pattern.
+ *
+ * @param {any} pattern an ObjectPattern node
+ * @param {Binding[]} into
+ * @returns {boolean}
  */
+function readBindings(pattern, into) {
+    for (const prop of pattern.properties) {
+        if (
+            prop.type !== "Property" ||
+            prop.computed ||
+            prop.key.type !== "Identifier" ||
+            prop.value.type !== "Identifier"
+        ) {
+            return false;
+        }
+        into.push({ local: prop.value.name, key: prop.key.name });
+    }
+    return true;
+}
 
 /**
  * The names a destructured `req` binds for query and params; null for a pattern this cannot read.
@@ -564,21 +609,20 @@ function readHandler(cb) {
 function readParamNames(fn, args) {
     const [req, res] = args;
     let queryName, paramsName;
-    const queries = [],
-        params = [];
+    /** @type {Binding[]} */
+    const queries = [];
+    /** @type {Binding[]} */
+    const params = [];
 
     if (fn.params[0].type === "ObjectPattern") {
-        const query = fn.params[0].properties.find((prop) => prop.key.name === "query");
-        const param = fn.params[0].properties.find((prop) => prop.key.name === "params");
+        const query = fn.params[0].properties.find((/** @type {any} */ prop) => prop.key.name === "query");
+        const param = fn.params[0].properties.find((/** @type {any} */ prop) => prop.key.name === "params");
 
         if (query?.value?.type === "Identifier") {
             queryName = query.value.name;
         } else if (query?.value?.type === "ObjectPattern") {
-            for (const prop of query.value.properties) {
-                if (prop.value.type !== "Identifier") {
-                    return null;
-                }
-                queries.push(prop.value.name);
+            if (!readBindings(query.value, queries)) {
+                return null;
             }
         } else {
             return null;
@@ -587,11 +631,8 @@ function readParamNames(fn, args) {
         if (param?.value?.type === "Identifier") {
             paramsName = param.value.name;
         } else if (param?.value?.type === "ObjectPattern") {
-            for (const prop of param.value.properties) {
-                if (prop.value.type !== "Identifier") {
-                    return null;
-                }
-                params.push(prop.value.name);
+            if (!readBindings(param.value, params)) {
+                return null;
             }
         } else {
             return null;
@@ -698,8 +739,8 @@ function identifiersAllowed(fn, args, names) {
             (identifiers[i - 2] === req && identifiers[i - 1] === "query") ||
             id === queryName ||
             id === paramsName ||
-            queries.includes(id) ||
-            params.includes(id)
+            queries.some((binding) => binding.local === id) ||
+            params.some((binding) => binding.local === id)
     );
 }
 // A uWS declarative response never enters node, so it is very fast. Only a handler that is simple

package/src/lazy-readable.js

@@ -71,21 +71,21 @@ for (const member of [
     } else if (descriptor.get || descriptor.set) {
         const innerGet = descriptor.get;
         const innerSet = descriptor.set;
-        Object.defineProperty(LazyReadableBase.prototype, member, {
-            ...descriptor,
-            get: innerGet
-                ? /** @this {import("stream").Readable} */ function () {
-                      materialise(this);
-                      return innerGet.call(this);
-                  }
-                : undefined,
-            set: innerSet
-                ? /** @this {import("stream").Readable} @param {unknown} value */ function (value) {
-                      materialise(this);
-                      innerSet.call(this, value);
-                  }
-                : undefined
-        });
+        // the original's accessor pair, each half wrapped where there is one
+        const wrapped = { ...descriptor };
+        if (innerGet) {
+            wrapped.get = /** @this {import("stream").Readable} */ function () {
+                materialise(this);
+                return innerGet.call(this);
+            };
+        }
+        if (innerSet) {
+            wrapped.set = /** @this {import("stream").Readable} @param {unknown} value */ function (value) {
+                materialise(this);
+                innerSet.call(this, value);
+            };
+        }
+        Object.defineProperty(LazyReadableBase.prototype, member, wrapped);
     }
 }
 

package/src/lazy-writable.js

@@ -65,21 +65,21 @@ for (const member of [
     } else if (descriptor.get || descriptor.set) {
         const innerGet = descriptor.get;
         const innerSet = descriptor.set;
-        Object.defineProperty(LazyWritableBase.prototype, member, {
-            ...descriptor,
-            get: innerGet
-                ? /** @this {import("stream").Writable} */ function () {
-                      materialiseWritable(this);
-                      return innerGet.call(this);
-                  }
-                : undefined,
-            set: innerSet
-                ? /** @this {import("stream").Writable} @param {unknown} value */ function (value) {
-                      materialiseWritable(this);
-                      innerSet.call(this, value);
-                  }
-                : undefined
-        });
+        // the original's accessor pair, each half wrapped where there is one
+        const wrapped = { ...descriptor };
+        if (innerGet) {
+            wrapped.get = /** @this {import("stream").Writable} */ function () {
+                materialiseWritable(this);
+                return innerGet.call(this);
+            };
+        }
+        if (innerSet) {
+            wrapped.set = /** @this {import("stream").Writable} @param {unknown} value */ function (value) {
+                materialiseWritable(this);
+                innerSet.call(this, value);
+            };
+        }
+        Object.defineProperty(LazyWritableBase.prototype, member, wrapped);
     }
 }
 

package/src/middlewares.js

@@ -720,7 +720,7 @@ function inflateError(inflate, err) {
  *
  * @param {string|undefined} rawContentEncoding
  * @param {any} options the parser's options, read loosely: only inflate is looked at
- * @returns {{inflate?: Inflater, error?: HttpError}}
+ * @returns {{inflate?: Inflater|undefined, error?: HttpError}}
  */
 function encodingFor(rawContentEncoding, options) {
     if (!options.inflate) {
@@ -799,11 +799,16 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             checkOptions(options);
         }
         // bytes.parse only on a string: bytes(1024) formats it to "1KB" and no comparison held
-        if (typeof options.limit === "undefined") {
-            options.limit = /** @type {number} */ (bytes.parse("100kb"));
+        if (options.limit === undefined || options.limit === null) {
+            options.limit = 100 * 1024;
         } else if (typeof options.limit !== "number") {
-            // null for a size it cannot read, as body-parser passes it along
-            options.limit = /** @type {number} */ (bytes.parse(options.limit));
+            // a size it cannot read is refused here, as body-parser 2.3 does: passed along as
+            // null it disabled the limit (CVE-2026-12590)
+            const parsed = bytes.parse(options.limit);
+            if (parsed === null) {
+                throw new TypeError(`option limit "${String(options.limit)}" is invalid`);
+            }
+            options.limit = parsed;
         }
 
         const limit = /** @type {number} */ (options.limit);
@@ -836,6 +841,11 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
         /** @type {string[]|null|undefined} the "body methods" setting, read on the first request */
         let additionalMethods;
 
+        /**
+         * @param {Request & {body?: unknown}} req
+         * @param {Response} res
+         * @param {(err?: unknown) => void} next
+         */
         const parserMiddleware = (req, res, next) => {
             // the prologue is synchronous, bindContext waits for the read (1.4us of nothing here)
 
@@ -867,8 +877,11 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             }
 
             if (options.simpleType) {
-                const semicolonIndex = type.indexOf(";");
-                const clearType = semicolonIndex !== -1 ? type.substring(0, semicolonIndex) : type;
+                // only a type function lets a request without a content-type past the check above,
+                // and simpleType is never set beside one
+                const header = /** @type {string} */ (type);
+                const semicolonIndex = header.indexOf(";");
+                const clearType = semicolonIndex !== -1 ? header.substring(0, semicolonIndex) : header;
                 // the trim and lowercase only when the exact compare fails
                 if (clearType !== options.simpleType && clearType.trim().toLowerCase() !== options.simpleType) {
                     return next();
@@ -879,7 +892,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                         return next();
                     }
                 } else {
-                    if (!claimsType(type)) {
+                    if (!claimsType(/** @type {string} */ (type))) {
                         return next();
                     }
                 }
@@ -1102,11 +1115,11 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                     }
                 }
                 // fewer bytes than content-length promised; not when inflating, it counts the compressed ones
-                if (!inflate && length !== undefined && !isNaN(length) && totalSize !== Number(length)) {
+                if (!inflate && !Number.isNaN(lengthNumber) && totalSize !== lengthNumber) {
                     return next(
                         bodyError("request size did not match content length", 400, "request.size.invalid", {
-                            expected: Number(length),
-                            length: Number(length),
+                            expected: lengthNumber,
+                            length: lengthNumber,
                             received: totalSize
                         })
                     );

package/src/nest.js

@@ -56,6 +56,7 @@ class FulmineExpressAdapter extends ExpressAdapter {
     /**
      * The app is the server. Nest calls this once, from NestApplication's constructor.
      *
+     * @override
      * @param {import("@nestjs/common").NestApplicationOptions} [options] the options NestFactory.create was given
      * @returns {void}
      */
@@ -84,6 +85,7 @@ class FulmineExpressAdapter extends ExpressAdapter {
      * for them in `app.router.stack`; there is no such array here, so a second call was putting a
      * second pair in front of every request.
      *
+     * @override
      * @param {string} [prefix]
      * @param {boolean} [rawBody]
      * @returns {void}