fulmine.js 5.19.3 → 5.19.4

package/package.json

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

package/src/application.js

@@ -163,11 +163,11 @@ class Application extends Router {
             /**
              * The base constructor's arguments, written out rather than spread. See Request.
              *
-             * @param {any} req uWS request
-             * @param {any} res uWS response
-             * @param {any} app the application this request arrived at
-             * @param {any} [preset] a literal registration's constants
-             * @param {any} [skipHolder] where a granted header skip lives
+             * @param {import("uWebSockets.js").HttpRequest} req uWS request
+             * @param {import("uWebSockets.js").HttpResponse} res uWS response
+             * @param {Application} app the application this request arrived at
+             * @param {import("./router-utils.js").NativePreset} [preset] a literal registration's constants
+             * @param {import("./router-utils.js").SkipHolder} [skipHolder] where a granted header skip lives
              */
             constructor(req, res, app, preset, skipHolder) {
                 super(req, res, app, preset, skipHolder);
@@ -177,27 +177,13 @@ class Application extends Router {
             /**
              * The base constructor's arguments, written out rather than spread. See Response.
              *
-             * @param {any} res uWS response
-             * @param {any} req the Request, already built
-             * @param {any} app the application this request arrived at
+             * @param {import("uWebSockets.js").HttpResponse} res uWS response
+             * @param {Request} req the Request, already built
+             * @param {Application} app the application this request arrived at
              */
             constructor(res, req, app) {
                 super(res, req, app);
             }
-
-            /**
-             * Node counts an explicit writeHead as the head gone out; remembered here so the
-             * automatic OPTIONS reply can refuse to add headers after it, as express's does.
-             *
-             * @param {number} statusCode
-             * @param {string|Record<string, any>} [statusMessage]
-             * @param {Record<string, any>} [headers]
-             * @returns {this}
-             */
-            writeHead(statusCode, statusMessage, headers) {
-                this._headWritten = true;
-                return super.writeHead(statusCode, statusMessage, headers);
-            }
         };
         this.request = this._request.prototype;
         this.response = this._response.prototype;
@@ -253,9 +239,9 @@ class Application extends Router {
         // stores where a Set paid identity hashing and table upkeep per request. A holder object
         // rather than a bare field, because the callable app copies own scalars by value and two
         // copies of a head would disagree; an object rides by reference, the way the Set did
-        this._pending = /** @type {{ head: any }} */ ({ head: null });
+        this._pending = /** @type {{ head: Response|null }} */ ({ head: null });
         // on the per-app prototype layer, not per response, same as the Set was
-        /** @type {any} */ (this.response)._pendingIn = this._pending;
+        /** @type {{_pendingIn?: {head: Response|null}}} */ (this.response)._pendingIn = this._pending;
         this._draining = false;
         // read here, at construction, the way express does; an empty NODE_ENV means development,
         // which the ?? in the shared default would miss
@@ -285,8 +271,8 @@ class Application extends Router {
      * message carries data and not closures. The counter wraps rather than growing without bound,
      * a million tasks being far more than can be outstanding at once.
      *
-     * @param {(value: any) => void} resolve
-     * @param {(err: any) => void} reject
+     * @param {(value: Buffer) => void} resolve
+     * @param {(err: Error) => void} reject
      * @returns {number} the key to send to the worker
      */
     createWorkerTask(resolve, reject) {
@@ -493,12 +479,14 @@ class Application extends Router {
      * is held in a set until it finishes, so close() knows when the last one is done. Native
      * routes and the catch-all both come through here, since both call it on the app.
      *
-     * @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
-     * @param {any} [skipHolder] where a granted header skip lives, forwarded whole: dropping
-     *   it here silently turned every skip off, since the native closures call this override
-     * @returns {any} the request, with the response reachable as request.res
+     * @param {import("uWebSockets.js").HttpResponse} res uWS response
+     * @param {import("uWebSockets.js").HttpRequest} req uWS request, readable only during this call
+     * @param {import("./router-utils.js").NativePreset} [preset] a literal registration's constants,
+     *   see nativePreset in the router
+     * @param {import("./router-utils.js").SkipHolder} [skipHolder] where a granted header skip lives,
+     *   forwarded whole: dropping it here silently turned every skip off, since the native closures
+     *   call this override
+     * @returns {Request} the request, with the response reachable as request.res
      */
     handleRequest(res, req, preset, skipHolder) {
         const request = super.handleRequest(res, req, preset, skipHolder);
@@ -532,8 +520,8 @@ class Application extends Router {
      * what the catch-all runs, and also what a native registration falls back to when it sees a
      * request it must not answer itself, see the case guard in Router#_registerUwsRoute.
      *
-     * @param {any} res the uWS response
-     * @param {any} req the uWS request
+     * @param {import("uWebSockets.js").HttpResponse} res the uWS response
+     * @param {import("uWebSockets.js").HttpRequest} req the uWS request
      */
     _serveGeneric(res, req) {
         const request = this.handleRequest(res, req);
@@ -768,13 +756,14 @@ class Application extends Router {
      * otherwise. A function in the options position is taken as the callback.
      *
      * @param {string} name view name, resolved against the "views" setting
-     * @param {Record<string, any>} [options] locals for the view
+     * @param {Record<string, any>|((err: Error|null, html?: string) => void)} [options] locals for
+     *   the view, or the callback in its place
      * @param {(err: Error|null, html?: string) => void} [callback] receives the rendered view. It
      *   is what render is for, so leaving it out throws, as it does in Express
      */
     render(name, options, callback) {
         if (typeof options === "function") {
-            callback = /** @type {any} */ (options);
+            callback = /** @type {(err: Error|null, html?: string) => void} */ (options);
             options = new NullObject();
         }
         // render exists to hand the result somewhere, so there is always a callback by this point:

package/src/cli.js

@@ -46,6 +46,9 @@ const { collectRoutes } = require("./testing.js");
 const { verify } = require("./verify.js");
 const { override, angular } = require("./adopt.js");
 
+/** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
+
 const FROM = "express";
 const TO = "fulmine.js";
 
@@ -187,7 +190,7 @@ function loadTypeScript(target) {
  *
  * @param {string} source
  * @param {string} fileName decides whether JSX is allowed, so a .tsx angle bracket is not a cast
- * @param {any} ts the compiler
+ * @param {typeof import("typescript")} ts the compiler
  * @param {Set<string>} [seen] as in findSpecifiers
  * @returns {{start: number, end: number}[]}
  */
@@ -202,7 +205,7 @@ function findSpecifiersTypeScript(source, fileName, ts, seen) {
 
     /** @type {{start: number, end: number}[]} */
     const found = [];
-    /** @param {any} node a string literal naming a module */
+    /** @param {import("typescript").StringLiteral} node a string literal naming a module */
     const take = (node) => {
         if (node.text === FROM) {
             found.push({ start: node.getStart(sourceFile), end: node.getEnd() });
@@ -249,7 +252,8 @@ function findSpecifiersTypeScript(source, fileName, ts, seen) {
  *
  * @param {string} source
  * @param {string} fileName decides whether JSX is allowed, as above
- * @param {any} ts the scanner and the two enums loadTypeScript kept
+ * @param {any} ts the scanner and the two enums loadTypeScript kept, from typescript 7's unstable
+ *   API, which the typings this project compiles against do not describe
  * @param {Set<string>} [seen] as in findSpecifiers
  * @returns {{start: number, end: number}[]}
  */
@@ -300,7 +304,7 @@ function findSpecifiersScanner(source, fileName, ts, seen) {
  * @returns {{start: number, end: number}[]|null} null when the file does not parse
  */
 function findSpecifiers(source, seen) {
-    /** @type {any} */
+    /** @type {import("acorn").Program|null|undefined} */
     let tree;
     // A file is either a module or a script and the parser has to be told which. Try module first,
     // since it also accepts everything a script can contain except a bare `return`.
@@ -308,7 +312,7 @@ function findSpecifiers(source, seen) {
         try {
             tree = acorn.parse(source, {
                 ecmaVersion: "latest",
-                sourceType: /** @type {any} */ (sourceType),
+                sourceType: /** @type {"module"|"script"} */ (sourceType),
                 allowReturnOutsideFunction: true,
                 allowAwaitOutsideFunction: true,
                 allowHashBang: true
@@ -324,7 +328,7 @@ function findSpecifiers(source, seen) {
 
     /** @type {{start: number, end: number}[]} */
     const found = [];
-    /** @param {any} node a string literal naming a module */
+    /** @param {import("acorn").Literal & {value: string}} node a string literal naming a module */
     const record = (node) => {
         if (node.value === FROM) {
             found.push({ start: node.start, end: node.end });
@@ -361,8 +365,10 @@ function findSpecifiers(source, seen) {
  * Visits every node. acorn produces plain objects, so the shape is walked rather than dispatched
  * on: a table of node types would have to be kept in step with the parser, and being out of step
  * would mean silently skipping an import.
- * @param {any} node an acorn AST node. acorn ships no useful node types, and every shape here is checked by hand
- * @param {(node: any) => void} visit
+ * @param {any} node an acorn node, or an array or a scalar under one: walked by key, so no shape
+ *   is assumed
+ * @param {(node: any) => void} visit handed every node, loose because the visitor reads edges of
+ *   its own off each
  */
 function walk(node, visit) {
     if (!node || typeof node !== "object") return;
@@ -459,7 +465,7 @@ function findEntry(given) {
  * owns listen.
  *
  * @param {string} entry
- * @returns {any[]} the prototypes to stub, this command's copy first
+ * @returns {object[]} the prototypes to stub, this command's copy first
  */
 function listenOwners(entry) {
     const builds = new Set([require("./index.js")]);
@@ -507,7 +513,7 @@ function listenOwners(entry) {
  *
  * @param {string[]} argv
  * @param {string} command the word for the message when there is nothing to load
- * @returns {{apps: any[], entry: string}|null} null once the reason has been printed
+ * @returns {{apps: Application[], entry: string}|null} null once the reason has been printed
  */
 function loadApps(argv, command) {
     const entry = findEntry(argv.find((arg) => !arg.startsWith("--")));
@@ -539,7 +545,7 @@ function loadApps(argv, command) {
     try {
         require(entry);
     } catch (e) {
-        const error = /** @type {any} */ (e);
+        const error = /** @type {Error} */ (e);
         restore();
         console.error(`${path.relative(process.cwd(), entry)} could not be loaded:
 ${error.stack ?? error}`);
@@ -584,7 +590,7 @@ ${error.stack ?? error}`);
  *
  * Best effort throughout: a build with no workers, or a worker already gone, is not an error.
  *
- * @param {any[]} apps
+ * @param {Application[]} apps
  * @returns {void}
  */
 function stopFileWorkers(apps) {
@@ -762,9 +768,9 @@ function matchesWanted(full, method, wanted) {
  * application with a thousand cold routes and one hot one that fell back would score well and
  * serve badly. What is printed is counted rather than judged.
  *
- * @param {any[]} routes
- * @param {any[]} native
- * @param {any[]} declarative
+ * @param {{route: RouteEntry, full: string}[]} routes
+ * @param {{route: RouteEntry, full: string}[]} native
+ * @param {{route: RouteEntry, full: string}[]} declarative
  */
 function printSummary(routes, native, declarative) {
     console.log("\nWhat this adds up to\n");
@@ -809,7 +815,7 @@ function printSummary(routes, native, declarative) {
 }
 
 /**
- * @param {any} app the application the entry file built
+ * @param {Application} app the application the entry file built
  * @param {boolean} several whether to say which application this is
  */
 function printProfile(app, several) {

package/src/cluster.js

@@ -156,7 +156,7 @@ function becomeSupervisor() {
 function forkWorkers(count) {
     let stopping = false;
     supervising = true;
-    /** @param {any} worker @param {number} code @param {string} signal */
+    /** @param {import("cluster").Worker} worker @param {number} code @param {string} signal */
     const onExit = (worker, code, signal) => {
         if (!stopping) {
             console.error(`worker ${worker.process.pid} exited (${signal || code}), starting another`);
@@ -172,7 +172,7 @@ function forkWorkers(count) {
         supervising = false;
         cluster.off("exit", onExit);
         for (const id of Object.keys(cluster.workers ?? {})) {
-            /** @type {any} */ (cluster.workers)[id]?.kill();
+            /** @type {NodeJS.Dict<import("cluster").Worker>} */ (cluster.workers)[id]?.kill();
         }
     };
     for (const signal of ["SIGTERM", "SIGINT"]) {

package/src/compression.js

@@ -16,6 +16,10 @@ limitations under the License.
 
 /** @typedef {import("./request.js")} Request */
 /** @typedef {import("./response.js")} Response */
+/**
+ * What res.on was given, parked until there is a compressor to hang it on.
+ * @typedef {Parameters<import("stream").Writable["on"]>} OnArgs
+ */
 
 // express.compression(), which answers with a compressed body when the client asked for one.
 //
@@ -46,7 +50,8 @@ const {
     ENCODING_GZIP,
     ENCODING_DEFLATE,
     ENCODING_ZSTD,
-    memoizeByString
+    memoizeByString,
+    applyWriteHead
 } = require("./utils.js");
 
 // zstd arrived in node's zlib during the range of versions this supports, so whether it can be
@@ -114,7 +119,8 @@ const noop = () => {};
  *
  * Only for the deflate formats. A brotli stream carries context across a reset.
  *
- * @param {() => any} create
+ * @param {() => any} create makes the stream. Loose because what is checked below is node's zlib
+ *   internals, which its typings do not declare
  * @param {number} finishFlag
  * @param {(body: Buffer) => Buffer} oneShot
  * @returns {(body: Buffer) => Buffer}
@@ -251,7 +257,7 @@ function toBuffer(chunk, encoding) {
  * @param {object} [options]
  * @param {number|string} [options.threshold] the smallest body worth compressing, bytes or "1kb".
  *   Default 1024. A response whose size is not known in advance is compressed whatever its size.
- * @param {(req: any, res: any) => boolean} [options.filter] whether this response should be
+ * @param {(req: Request, res: Response) => boolean} [options.filter] whether this response should be
  *   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.
@@ -266,17 +272,19 @@ function toBuffer(chunk, encoding) {
  * @param {number} [options.memLevel] zlib memory level.
  * @param {number} [options.strategy] zlib strategy.
  * @param {number} [options.windowBits] zlib window size.
- * @returns {(req: any, res: any, next: (err?: any) => void) => void} the middleware
+ * @returns {(req: any, res: any, next: (err?: unknown) => void) => void} the middleware. The pair is
+ *   loose because this is written against node's end() and write() shapes, which this project's
+ *   own narrow
  */
 function compression(options) {
     const opts = options || {};
     // the whole bag goes to zlib, as the compression module does: level, memLevel, strategy,
     // windowBits and chunkSize arrive under their own names and zlib ignores the rest
-    const zlibOptions = /** @type {any} */ (opts);
+    const zlibOptions = /** @type {import("zlib").ZlibOptions} */ (opts);
     const brotliOptions = { ...opts.brotli };
     brotliOptions.params = {
         [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
-        ...(opts.brotli && /** @type {any} */ (opts.brotli).params)
+        ...(opts.brotli && /** @type {import("zlib").BrotliOptions} */ (opts.brotli).params)
     };
     // node's default level, unlike brotli above: zstd at its default is already in the band where
     // this middleware wants to be, and dropping it further buys nothing worth the ratio
@@ -285,7 +293,7 @@ function compression(options) {
     const enforceEncoding = opts.enforceEncoding || "identity";
     // bytes.parse reads "1kb" and hands back null for anything it cannot, an absent option
     // included, which is where the default comes in
-    const threshold = bytes.parse(/** @type {any} */ (opts.threshold)) ?? 1024;
+    const threshold = bytes.parse(/** @type {string|number} */ (opts.threshold)) ?? 1024;
     // the mask handed to the negotiation, built once here: a name nobody knows is a config
     // mistake and throws now rather than serving the wrong bytes later
     let allowed = ENCODING_DEFAULT;
@@ -362,7 +370,8 @@ function compression(options) {
 
     /**
      * @param {string} method
-     * @returns {any} the transform stream for a body that arrives in pieces
+     * @returns {import("stream").Transform & import("zlib").Zlib} the transform stream for a body that
+     *   arrives in pieces
      */
     function compressStream(method) {
         if (method === "gzip") {
@@ -393,19 +402,32 @@ function compression(options) {
         if (!chosen || chosen === "identity" || req.method === "HEAD") {
             res.flush = noFlush;
             const _plainEnd = res.end;
+            const _plainWriteHead = res.writeHead;
             let varied = false;
-            res.end = function end(chunk, encoding, callback) {
-                if (!varied) {
-                    varied = true;
-                    const cacheControl = res.headersSent ? undefined : res.getHeader("Cache-Control");
-                    if (
-                        !res.headersSent &&
-                        filter(req, res) &&
-                        !(cacheControl && NO_TRANSFORM.test(String(cacheControl)))
-                    ) {
-                        addVary(res);
-                    }
+            /** Says the answer varies, once, before the head is settled. */
+            const vary = () => {
+                if (varied) {
+                    return;
+                }
+                varied = true;
+                const cacheControl = res.headersSent ? undefined : res.getHeader("Cache-Control");
+                if (
+                    !res.headersSent &&
+                    filter(req, res) &&
+                    !(cacheControl && NO_TRANSFORM.test(String(cacheControl)))
+                ) {
+                    addVary(res);
                 }
+            };
+            // writeHead settles the head, so a handler that calls it is answered there, with the
+            // headers it carries applied first, as on-headers orders it for the compression module
+            res.writeHead = function writeHead(statusCode, statusMessage, headers) {
+                const reason = applyWriteHead(this, statusMessage, headers);
+                vary();
+                return _plainWriteHead.call(this, statusCode, reason);
+            };
+            res.end = function end(chunk, encoding, callback) {
+                vary();
                 return _plainEnd.call(this, chunk, encoding, callback);
             };
             return next();
@@ -414,15 +436,18 @@ function compression(options) {
         const _write = res.write;
         const _end = res.end;
         const _on = res.on;
+        const _writeHead = res.writeHead;
 
         /** drain listeners parked until there is a compressor to hang them on, see res.on below */
-        let listeners = /** @type {any[][]|null} */ ([]);
-        /** @type {any} */
+        let listeners = /** @type {OnArgs[]|null} */ ([]);
+        /** @type {(import("stream").Transform & import("zlib").Zlib)|null} */
         let stream = null;
         let decided = false;
+        // the encoding decided on, "" for none; the compressor itself starts with the first byte
+        let method = "";
         let ended = false;
         /** what end() was given to call back, held until the compressor has finished */
-        let endCallback = /** @type {any} */ (undefined);
+        let endCallback = /** @type {(() => void)|undefined} */ (undefined);
 
         // the compression module adds this, and code written against it calls it: an SSE feed
         // pushes its event out with res.flush(). Nothing to flush before there is a compressor
@@ -497,27 +522,39 @@ function compression(options) {
          * @param {string} method
          */
         function startStream(method) {
-            stream = compressStream(method);
+            // the closures below read the local: inside them the checker forgets the field is set
+            const compressor = (stream = compressStream(method));
             // The parked listeners, and the list itself stays rather than being emptied: res.on
             // reads it to know a drain listener belongs on the compressor from here on. A pipe
             // registers its own the first time write() says to slow down, which is after this
-            for (const listener of /** @type {any[][]} */ (listeners)) {
-                stream.on(listener[0], listener[1]);
+            for (const listener of /** @type {OnArgs[]} */ (listeners)) {
+                compressor.on(listener[0], listener[1]);
             }
-            stream.on("data", (chunk) => {
+            compressor.on("data", (chunk) => {
                 if (_write.call(res, chunk) === false) {
-                    stream.pause();
+                    compressor.pause();
                 }
             });
-            stream.on("end", () => {
+            compressor.on("end", () => {
                 _end.call(res, endCallback);
             });
-            _on.call(res, "drain", () => stream.resume());
+            _on.call(res, "drain", () => compressor.resume());
             // an aborted response never reaches the end of the stream, and the zlib context behind
             // it is native memory that a garbage collector is in no hurry to reach
-            _on.call(res, "close", () => stream.destroy());
+            _on.call(res, "close", () => compressor.destroy());
         }
 
+        // writeHead settles the head, so the decision is taken there when a handler calls it, as
+        // on-headers takes it for the compression module: with the headers it carries applied
+        // first, since a Content-Length among them is what the decision removes
+        res.writeHead = function writeHead(statusCode, statusMessage, headers) {
+            const reason = applyWriteHead(this, statusMessage, headers);
+            if (!decided) {
+                method = decide();
+            }
+            return _writeHead.call(this, statusCode, reason);
+        };
+
         res.write = function write(chunk, encoding, callback) {
             if (typeof encoding === "function") {
                 callback = encoding;
@@ -527,10 +564,10 @@ function compression(options) {
                 return false;
             }
             if (!decided) {
-                const method = decide();
-                if (method) {
-                    startStream(method);
-                }
+                method = decide();
+            }
+            if (method && !stream) {
+                startStream(method);
             }
             if (stream) {
                 return stream.write(toBuffer(chunk, encoding), callback);
@@ -539,8 +576,7 @@ function compression(options) {
         };
 
         res.end = function end(chunk, encoding, callback) {
-            // node's shapes, of which this project's own end() takes (data, cb): the third
-            // argument only arrives from code written against node's ServerResponse
+            // node's shapes: the callback may sit in either position
             if (typeof chunk === "function") {
                 callback = chunk;
                 chunk = undefined;
@@ -552,6 +588,14 @@ function compression(options) {
             if (ended) {
                 return this;
             }
+            if (!decided) {
+                method = decide(chunkLength(chunk, encoding));
+            }
+            // a head settled by writeHead can no longer take the length the whole-body answer
+            // below sets, so the body goes out in pieces, as node's does after one
+            if (method && !stream && res.headersSent) {
+                startStream(method);
+            }
             if (stream) {
                 ended = true;
                 endCallback = callback;
@@ -562,32 +606,29 @@ function compression(options) {
                 }
                 return this;
             }
-            if (!decided) {
-                const method = decide(chunkLength(chunk, encoding));
-                if (method) {
-                    // the whole answer is here, so it is compressed in one call rather than
-                    // through a stream, and goes out with the length it ended up being
-                    ended = true;
-                    const input = toBuffer(chunk, encoding);
-                    if (input.length <= SYNC_LIMIT) {
-                        const body = compressWhole(method, input);
-                        res.setHeader("Content-Length", String(body.length));
-                        return _end.call(this, body, callback);
-                    }
-                    compressWholeAsync(method, input, (err, body) => {
-                        // the client can leave while the pool is working, and writing to a
-                        // response that is already gone is not something uWS survives
-                        if (res.aborted || res.finished) {
-                            return;
-                        }
-                        if (err) {
-                            return res.destroy(err);
-                        }
-                        res.setHeader("Content-Length", String(body.length));
-                        _end.call(res, body, callback);
-                    });
-                    return this;
+            if (method) {
+                // the whole answer is here, so it is compressed in one call rather than through a
+                // stream, and goes out with the length it ended up being
+                ended = true;
+                const input = toBuffer(chunk, encoding);
+                if (input.length <= SYNC_LIMIT) {
+                    const body = compressWhole(method, input);
+                    res.setHeader("Content-Length", String(body.length));
+                    return _end.call(this, body, callback);
                 }
+                compressWholeAsync(method, input, (err, body) => {
+                    // the client can leave while the pool is working, and writing to a response
+                    // that is already gone is not something uWS survives
+                    if (res.aborted || res.finished) {
+                        return;
+                    }
+                    if (err) {
+                        return res.destroy(err);
+                    }
+                    res.setHeader("Content-Length", String(body.length));
+                    _end.call(res, body, callback);
+                });
+                return this;
             }
             ended = true;
             return _end.call(this, chunk, callback);