fulmine.js 5.21.3 → 5.21.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.21.3",
+    "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") {
@@ -537,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;
@@ -607,12 +609,14 @@ function readBindings(pattern, into) {
 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;

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) {
@@ -841,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)
 
@@ -872,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();
@@ -884,7 +892,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                         return next();
                     }
                 } else {
-                    if (!claimsType(type)) {
+                    if (!claimsType(/** @type {string} */ (type))) {
                         return next();
                     }
                 }
@@ -1107,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}

package/src/optimizer.js

@@ -20,6 +20,8 @@ limitations under the License.
 /** @typedef {import("./router.js")} Router */
 /** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
 /** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("uWebSockets.js").HttpRequest} UwsRequest */
+/** @typedef {import("uWebSockets.js").HttpResponse} UwsResponse */
 
 const {
     patternToRegex,
@@ -44,6 +46,7 @@ const {
     hasErrorMiddleware,
     couldAnswer,
     shadowsLeaf,
+    headEntersGuard,
     guardsInside,
     supportedUwsMethods,
     regExParam
@@ -79,6 +82,8 @@ function optimizeRoute(router, route, routes) {
     const strictHere = (route.owner ?? router)._strictRouting();
     /** @type {string[]|null} earlier literals a case variant could smuggle a request past */
     let caseGuards = null;
+    // whether the HEAD twin has to stay generic, see headEnters
+    let headGeneric = false;
 
     for (let i = 0; i < routes.length; i++) {
         const r = routes[i];
@@ -95,6 +100,12 @@ function optimizeRoute(router, route, routes) {
                 if (route.use && typeof route.path === "string" && couldAnswer(r, route.path)) {
                     return false;
                 }
+                // Express exempts HEAD from the method check: a HEAD enters a matching route of
+                // any verb and its param() callbacks run, as the generic walk does. The chain
+                // cannot say whether such a route matches, so the HEAD twin stays generic
+                if (route.method === "GET" && headEnters(r, route, caseSensitive, strictHere)) {
+                    headGeneric = true;
+                }
                 continue;
             }
         }
@@ -115,7 +126,7 @@ function optimizeRoute(router, route, routes) {
                 route.path.slice(0, matched[0].length) === matched[0] &&
                 (route.path.length === matched[0].length || route.path[matched[0].length] === "/");
             if (runsAlways) {
-                if (r.callbacks.some((c) => c instanceof Router)) {
+                if (r.callbacks.some((/** @type {unknown} */ c) => c instanceof Router)) {
                     return false;
                 }
                 optimizedPath.push(r);
@@ -137,7 +148,7 @@ function optimizeRoute(router, route, routes) {
                     (!caseSensitive && r.pattern.toLowerCase() === routePathFolded) ||
                     r.pattern === "/*"))
         ) {
-            if (r.callbacks.some((c) => c instanceof Router)) {
+            if (r.callbacks.some((/** @type {unknown} */ c) => c instanceof Router)) {
                 return false;
             }
             optimizedPath.push(r);
@@ -164,7 +175,7 @@ function optimizeRoute(router, route, routes) {
         }
         // the same path lands on the same µWS registration, so the earlier route runs from the chain
         if (rPathFolded === routePathFolded) {
-            if (r.callbacks.some((c) => c instanceof Router)) {
+            if (r.callbacks.some((/** @type {unknown} */ c) => c instanceof Router)) {
                 return false;
             }
             optimizedPath.push(r);
@@ -186,10 +197,45 @@ function optimizeRoute(router, route, routes) {
     }
     optimizedPath.push(route);
     route._caseGuards = caseGuards;
+    route._headGeneric = headGeneric;
 
     return optimizedPath;
 }
 
+/**
+ * Whether a HEAD of some path this GET route answers would enter the earlier route of another
+ * verb for its param() callbacks: the router has callbacks and the paths can meet. A wrong yes
+ * costs the HEAD twin its native registration and nothing else.
+ *
+ * @param {RouteEntry} r the earlier route, of another verb
+ * @param {RouteEntry} route the GET route
+ * @param {boolean} caseSensitive
+ * @param {boolean} strictHere
+ * @returns {boolean}
+ */
+function headEnters(r, route, caseSensitive, strictHere) {
+    if (r.paramCallbacks.size === 0 || typeof route.path !== "string") {
+        return false;
+    }
+    if (!route.path.includes(":")) {
+        if (typeof r.pattern === "string") {
+            return (
+                r.pattern === "/*" ||
+                (caseSensitive ? r.pattern === route.path : r.patternLower === route.path.toLowerCase())
+            );
+        }
+        return r.pattern.test(route.path) || (!strictHere && r.pattern.test(route.path + "/"));
+    }
+    if (typeof r.path !== "string" || !canBeOptimizedWithParams(r.path)) {
+        return true;
+    }
+    return pathsCanOverlap(
+        caseSensitive ? r.path : r.path.toLowerCase(),
+        caseSensitive ? route.path : route.path.toLowerCase(),
+        r.use
+    );
+}
+
 /**
  * Hands every route reachable by path alone to the native uWS router, walking into mounted
  * routers with their prefix. Runs once, at listen.
@@ -284,6 +330,16 @@ function compileOptimizedRoutes(root) {
                     route._whyGeneric = "something before it in the same router overlaps its paths";
                     continue;
                 }
+                // a route of another verb before the mount that a HEAD would enter, see headEnters
+                if (
+                    !route._headGeneric &&
+                    route.method === "GET" &&
+                    outerGuards.length > 0 &&
+                    typeof route.path === "string" &&
+                    outerGuards.some((g) => headEntersGuard(g, pathPrefix + route.path))
+                ) {
+                    route._headGeneric = true;
+                }
                 // an earlier parameter route in the same router would take this literal path
                 if (leafPath.length > 1) {
                     const shadow = leafPath[leafPath.length - 2];
@@ -360,6 +416,7 @@ function registerUwsRoute(router, route, optimizedPath) {
      * @param {import("./router-utils.js").NativePreset|undefined} preset
      * @param {{skipHeaders: boolean, skipQuery: boolean}} skips
      * @param {string|null} wireMethod
+     * @returns {(res: UwsResponse, req: UwsRequest) => unknown} what µWS calls
      */
     const makeHandler = (chain, preset, skips, wireMethod) => {
         // where a granted skip lives, so a middleware added after listen can take it back: the
@@ -395,10 +452,11 @@ function registerUwsRoute(router, route, optimizedPath) {
                 return router._refuseRequest(response);
             }
             if (optimizedParams) {
-                // slicing them out of the path instead measured a wash
+                // slicing them out of the path instead measured a wash. The index is one the
+                // registered path declares, so the value is never undefined
                 request.optimizedParams = new NullObject();
                 for (let i = 0; i < optimizedParams.length; i++) {
-                    request.optimizedParams[optimizedParams[i]] = req.getParameter(i);
+                    request.optimizedParams[optimizedParams[i]] = /** @type {string} */ (req.getParameter(i));
                 }
             }
             const walk = new Walk(router, request, response, chain, true, skipUntil, nativeDone, nativeFail);
@@ -513,7 +571,7 @@ function registerUwsRoute(router, route, optimizedPath) {
                   ? makeHandler(getChain, makePreset(route.path + "/", route.method, getSkips), getSkips, wireMethod)
                   : fn;
         router.uwsApp[method](replacedPath + "/", slashFn);
-        if (method === "get") {
+        if (method === "get" && !route._headGeneric) {
             router.uwsApp.head(
                 replacedPath + "/",
                 makeHandler(
@@ -525,7 +583,7 @@ function registerUwsRoute(router, route, optimizedPath) {
             );
         }
     }
-    if (method === "get") {
+    if (method === "get" && !route._headGeneric) {
         // its own handler, the shared one would carry GET
         router.uwsApp.head(
             replacedPath,

package/src/options.d.ts

@@ -43,7 +43,7 @@ export interface SendFileOptions {
     /** Extra headers for the response. */
     headers?: Record<string, string>;
     /** Internal: express.static's setHeaders, which res.sendFile itself does not take. */
-    _setHeaders?: (res: any, path: string, stat: any) => void;
+    _setHeaders?: ((res: any, path: string, stat: any) => void) | undefined;
     /** First byte of the window to send. */
     start?: number;
     /** Last byte of the window to send. */