fulmine.js 5.19.2 → 5.19.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.19.2",
+    "version": "5.19.3",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "exports": {
@@ -149,6 +149,7 @@
         "eslint": "^10.8.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-jsdoc": "^64.1.0",
+        "eslint-plugin-sonarjs": "^4.2.0",
         "etag": "^1.8.1",
         "eventsource": "^5.0.0",
         "exit-hook": "^5.1.0",

package/src/adopt.js

@@ -17,15 +17,14 @@ limitations under the License.
 // The two commands that edit a config file rather than source: `npx fulmine.js override` and
 // `npx fulmine.js angular`.
 //
-// `migrate` rewrites `require("express")` in your own files, which is all an application needs. The
-// two cases it cannot reach are both a line in a JSON file that nobody remembers the shape of:
+// `migrate` rewrites `require("express")` in your own files. The two cases it cannot reach are
+// both a line in a JSON file:
 //
-//   override   A framework built on Express does not require it in your code, it requires it in its
-//              own, so there is no specifier to rewrite. Every package manager can answer `express`
-//              with this package instead, for the whole tree, and each one spells it differently.
+//   override   A framework built on Express requires it in its own code, so there is no specifier
+//              to rewrite. Every package manager can answer `express` with this package instead,
+//              and each one spells it differently.
 //   angular    An Angular server bundle is built with esbuild, which inlines every dependency and
-//              cannot load µWS's native binary. Two names in `externalDependencies` fix it, and
-//              nothing in the error message it fails with says so.
+//              cannot load uWS's native binary. Two names in `externalDependencies` fix it.
 
 "use strict";
 
@@ -72,9 +71,9 @@ function indentOf(source) {
 /**
  * Reads a JSON file, or explains why it could not be read rather than throwing a parser error.
  *
- * The read is attempted rather than guarded by an existence check. Both commands go on to write the
- * file they read, and a check on a path followed by a write to the same path is the shape of a race
- * whatever the odds of losing it. `code` is what a caller names the missing file by.
+ * The read is attempted rather than guarded by an existence check: both commands write the file
+ * they read, and a check followed by a write to the same path is a race. `code` is what a caller
+ * names the missing file by.
  *
  * @param {string} file
  * @returns {{data: any, source: string}|{error: string, code: string|undefined}}
@@ -121,7 +120,7 @@ function detectManager(dir, pkg) {
 /**
  * Reads a nested key, and answers undefined rather than throwing on a missing level.
  *
- * @param {any} object
+ * @param {any} object parsed JSON, so its shape is whatever the file held
  * @param {string[]} keys
  * @returns {any}
  */
@@ -137,9 +136,9 @@ function readPath(object, keys) {
 /**
  * Writes a nested key, making the levels above it as it goes.
  *
- * @param {any} object
+ * @param {any} object parsed JSON, so its shape is whatever the file held
  * @param {string[]} keys
- * @param {any} value
+ * @param {any} value whatever belongs at that key
  * @returns {void}
  */
 function writePath(object, keys, value) {
@@ -155,9 +154,7 @@ function writePath(object, keys, value) {
  * npx fulmine.js override [dir] [--dry-run]
  *
  * Puts the substitution in package.json where this project's package manager reads it, and says
- * what to run next. It deliberately does not run the install: the reinstall throws away
- * node_modules, and that is not something a command should do to somebody's working tree without
- * being watched.
+ * what to run next. It does not run the install itself: that throws away node_modules.
  *
  * @param {string[]} argv everything after the command name
  * @returns {number} exit code
@@ -235,9 +232,8 @@ function override(argv) {
 /**
  * Every build target in an angular.json that produces a server bundle.
  *
- * A browser-only build has nothing to declare external: the bundle it makes never loads µWS. What
- * marks a server build is `ssr`, `server` or `outputMode` in its options, which is what `ng add
- * @angular/ssr` writes.
+ * A browser-only build never loads uWS. What marks a server build is `ssr`, `server` or
+ * `outputMode` in its options, which is what `ng add @angular/ssr` writes.
  *
  * @param {any} config the parsed angular.json
  * @returns {{name: string, options: any}[]}
@@ -257,8 +253,8 @@ function serverBuilds(config) {
 /**
  * npx fulmine.js angular [dir] [--dry-run]
  *
- * Declares this package and µWebSockets.js external in every server build, which is what stops
- * esbuild trying to inline a native binary it cannot read.
+ * Declares this package and uWebSockets.js external in every server build, which stops esbuild
+ * trying to inline a native binary it cannot read.
  *
  * @param {string[]} argv everything after the command name
  * @returns {number} exit code
@@ -267,11 +263,9 @@ function angular(argv) {
     const dryRun = argv.includes("--dry-run");
     const given = path.resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
 
-    // The argument is either the file or the directory holding it, and which one comes out of
-    // reading it rather than out of a stat: a directory reads as EISDIR and a missing path as
-    // ENOENT, and in both cases the file to look for is angular.json inside it. Asked this way
-    // round because this function goes on to write the file it read, and a check on a path followed
-    // by a write to the same path is the shape of a race whatever the odds of losing it.
+    // The argument is either the file or the directory holding it, told apart by reading it and not
+    // by a stat: a directory reads EISDIR, a missing path ENOENT, and in both cases the file to
+    // look for is angular.json inside it. A stat followed by a write to the same path is a race.
     let file = given;
     let read = readJson(file);
     if ("error" in read && (read.code === "EISDIR" || read.code === "ENOENT")) {

package/src/application.js

@@ -103,6 +103,13 @@ class Application extends Router {
      */
     _isApplication = true;
 
+    /**
+     * Whether express.testing already compiled the routes of this app. Written there and nowhere
+     * else: a second compilation would register everything with uWS twice. See src/testing.js.
+     * @type {boolean|undefined}
+     */
+    _testingCompiled;
+
     /**
      * @param {object} [settings] the options express() takes. uwsOptions goes to uWS and decides
      *   between an HTTP, an HTTPS and an HTTP/3 server; threads sizes the file-reading pool, and 0
@@ -154,11 +161,13 @@ class Application extends Router {
         // was an allocation on every request
         this._request = class extends Request {
             /**
-             * @param {any} req
-             * @param {any} res
-             * @param {any} app
-             * @param {any} [preset]
-             * @param {any} [skipHolder]
+             * 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
              */
             constructor(req, res, app, preset, skipHolder) {
                 super(req, res, app, preset, skipHolder);
@@ -166,9 +175,11 @@ class Application extends Router {
         };
         this._response = class extends Response {
             /**
-             * @param {any} res
-             * @param {any} req
-             * @param {any} app
+             * 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
              */
             constructor(res, req, app) {
                 super(res, req, app);
@@ -306,11 +317,10 @@ class Application extends Router {
 
     /**
      * A small file through the worker pool, with two things on top: concurrent asks for the same
-     * path share one read, and the bytes of an unchanged file come from a bounded cache,
-     * validated against the stat the caller already paid for, so a touched file is re-read.
-     * A hit completes on a macrotask, which is when a worker's answer would have arrived; code
-     * that passed the suites against worker timing keeps passing against this.
-     * `app.set("file cache", false)` turns the cache off; the shared read stays.
+     * path share one read, and the bytes of an unchanged file come from a bounded cache, validated
+     * against the stat the caller already paid for, so a touched file is re-read. A hit completes
+     * on a macrotask, which is when a worker's answer would have arrived.
+     * `app.set("file cache", false)` turns the cache off, the shared read stays.
      *
      * @param {string} fullpath
      * @param {import("fs").Stats} stat
@@ -407,12 +417,11 @@ class Application extends Router {
             }
             value = value == null ? undefined : value.map((m) => m.toUpperCase());
         } else if (key === "etag") {
-            // The skips are not taken back here. They used to be, because send consults freshness
-            // and the skip branch looked like it had not copied the headers for it, but that
-            // branch reads if-none-match, if-modified-since and cache-control by name whatever
-            // this setting says, see request.js:527, and req.fresh reads nothing else off the
-            // request. Registering a route or a middleware after listen still takes them back,
-            // see router.js:1615: that is a different question, about code the analysis never saw.
+            // The skips are not taken back here. They used to be, because send consults freshness,
+            // but that branch reads if-none-match, if-modified-since and cache-control by name
+            // whatever this setting says, and req.fresh reads nothing else off the request.
+            // Registering a route after listen still takes them back: that is a different
+            // question, about code the analysis never saw
             if (typeof value === "function") {
                 this._settings["etag fn"] = value;
             } else {
@@ -551,9 +560,8 @@ class Application extends Router {
      *
      * Returns the app and not an `http.Server`, since there is no node server underneath. The app
      * carries `address()`, `close()`, `listening` and the 'listening' and 'close' events; anything
-     * needing a real server, socket.io being the usual case, wants `app.uwsApp`. The callback runs
-     * on the next tick with the bind error, if there was one. A path instead of a port is a unix
-     * socket.
+     * needing a real server, socket.io being the usual case, wants `app.uwsApp`. A path instead of
+     * a port is a unix socket.
      *
      * @param {number|string} [port] port, or a unix socket path; 0 picks a free port
      * @param {string} [host] interface to bind; every interface when omitted
@@ -563,14 +571,12 @@ class Application extends Router {
      */
     listen(port, host, backlog, callback) {
         // With { cluster } the primary has nothing to bind. Each worker binds this same port with
-        // µWS's shared flag, which is SO_REUSEPORT, so the kernel hands each connection to one of
-        // them and the primary is not in the path at all: it forks, replaces a worker that dies,
-        // and nothing else. Everything below this runs in the workers, listen callback included,
-        // so it runs once per worker rather than once.
+        // uWS's shared flag, SO_REUSEPORT, so the kernel hands each connection to one of them and
+        // the primary only forks and replaces a worker that dies. Everything below this runs in the
+        // workers, listen callback included, so once per worker rather than once.
         //
-        // The test is the process and not this app: a second app on a TLS port, one without a
-        // cluster setting of its own, would otherwise take that port here, exclusively, and every
-        // worker would fail on it.
+        // The test is the process and not this app: a second app on a TLS port, without a cluster
+        // setting of its own, would take that port here exclusively and every worker would fail
         if (cluster.isPrimary && isSupervising()) {
             if (this._clusterWorkers > 0 && !this._clusterHandle) {
                 this._clusterHandle = forkWorkers(this._clusterWorkers);
@@ -758,10 +764,8 @@ class Application extends Router {
      * `res.render()` is the one that responds.
      *
      * `app.locals` and `options._locals` are merged into the options, in that order, so a
-     * per-request local wins over an application-wide one. Caching follows the "view cache"
-     * setting unless `options.cache` says otherwise.
-     *
-     * A function in the options position is taken as the callback.
+     * per-request local wins. Caching follows the "view cache" setting unless `options.cache` says
+     * 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
@@ -844,15 +848,13 @@ class Application extends Router {
     /**
      * Stops accepting connections, lets in-flight requests finish, then emits 'close'.
      *
-     * Node's server.close(), which Express hands back from listen(), only closes the listen
-     * socket and waits for what is being served; uWS's close() forcefully terminates every
-     * connection, so calling it first aborted whatever a graceful shutdown was waiting for.
-     * It still runs, but only once the last pending response is done, to drop the idle
-     * keep-alive connections nothing else would close.
+     * Node's server.close() only closes the listen socket and waits for what is being served; uWS's
+     * close() terminates every connection, so calling it first aborted whatever a graceful shutdown
+     * was waiting for. It still runs, but only once the last pending response is done, to drop the
+     * idle keep-alive connections nothing else would close.
      *
-     * The callback is the first 'close' listener, so it runs before any added afterwards. Closing
-     * a server that was not listening still calls back, with an ERR_SERVER_NOT_RUNNING error, the
-     * way node does.
+     * The callback is the first 'close' listener. Closing a server that was not listening still
+     * calls back with ERR_SERVER_NOT_RUNNING, the way node does.
      *
      * @param {(err?: Error) => void} [callback] called once closed
      * @returns {this} the app, for chaining
@@ -932,10 +934,9 @@ class Application extends Router {
 // carries. Middleware that takes a whole app and calls it, vhost being the one everybody meets, was
 // given something it could not call.
 //
-// This was tried once before and reverted the same day, because a callable app broke supertest:
-// `request(app)` reads `typeof app === "function"` and wraps whatever it finds in
-// http.createServer, and there was nothing underneath that could serve node's IncomingMessage, so
-// every call timed out. src/node-shim.js is what closes that hole, and it is why this is safe now.
+// Tried once before and reverted the same day, because a callable app broke supertest: `request(app)`
+// reads `typeof app === "function"` and wraps what it finds in http.createServer, and there was
+// nothing underneath that could serve node's IncomingMessage. src/node-shim.js closes that hole.
 module.exports = function (options) {
     return new Application(options)._asCallable();
 };

package/src/cli.js

@@ -18,26 +18,25 @@ limitations under the License.
 // npx fulmine migrate [dir]
 //
 // Rewrites the module specifier and nothing else. An Express 5 app is a Fulmine app already, so
-// there is no code to translate: what there is instead is a short list of things that behave
-// differently, printed at the end, because no rewrite can find those for you.
+// there is no code to translate. The short list of things that behave differently is printed at
+// the end, because no rewrite can find those for you.
 //
 // npx fulmine profile [entry]
 //
-// Prints what listen() worked out about each route and normally keeps to itself: which ones µWS
-// answers on its own, which ones fell back to the ordinary router and why, and which ones were
-// compiled all the way down to a response written at startup.
+// Prints what listen() worked out about each route: which ones uWS answers on its own, which ones
+// fell back to the ordinary router and why, and which ones were compiled into a response.
 //
 // npx fulmine verify [dir]
 //
 // Whether this machine and this project can run it at all: the node version, the C library, the
-// µWebSockets.js binary, the base image a Dockerfile names. See src/verify.js.
+// uWebSockets.js binary, the base image a Dockerfile names. See src/verify.js.
 //
 // npx fulmine override [dir]
 // npx fulmine angular [dir]
 //
-// The two things a project needs that are a line in a JSON file rather than a specifier in a source
-// file: the package manager substitution, for a framework that requires express in its own code,
-// and angular.json's externalDependencies. See src/adopt.js.
+// The two things a project needs that are a line in a JSON file rather than a specifier in a
+// source file: the package manager substitution, for a framework that requires express in its own
+// code, and angular.json's externalDependencies. See src/adopt.js.
 
 const fs = require("fs");
 const path = require("path");
@@ -146,14 +145,12 @@ function collectFiles(dir) {
  * A reader for the .ts files of the project being migrated, or null when it has no TypeScript.
  *
  * acorn cannot read TypeScript, and shipping a parser that can would put megabytes into this
- * package for a command most people run once. A TypeScript project already has the compiler, so
- * it is resolved from there. A project without one is told its .ts files were left alone rather
- * than having them quietly skipped, which is what happened before they were looked at at all.
+ * package for a command most people run once. A TypeScript project already has the compiler, so it
+ * is resolved from there. A project without one is told its .ts files were left alone.
  *
- * typescript 7 is the compiler rewritten in Go, and it publishes no JavaScript parser any more:
- * require("typescript") gives back a version number and nothing else. Its scanner survives, on an
- * ESM-only subpath that require() reads on every node this package supports, so 7 gets the token
- * walk and 6 keeps the tree.
+ * typescript 7 is the compiler rewritten in Go and publishes no JavaScript parser any more:
+ * require("typescript") gives back a version number and nothing else. Its scanner survives on an
+ * ESM-only subpath that require() reads, so 7 gets the token walk and 6 keeps the tree.
  *
  * @param {string} target directory being migrated
  * @returns {((source: string, fileName: string, seen?: Set<string>) => {start: number, end: number}[])|null}
@@ -364,7 +361,7 @@ 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
+ * @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
  */
 function walk(node, visit) {
@@ -453,14 +450,13 @@ function findEntry(given) {
 /**
  * Every build of this library the application could load, as the prototype that owns listen().
  *
- * The command runs from its own copy, and the application loads whichever one resolves from its
- * own directory. That is usually the same file and sometimes is not: a global install, an
- * `npx fulmine.js@version`, a workspace that hoisted a second copy, or the `express` name pointing
- * here through an override. Patching only this command's copy leaves the application's own listen()
- * to bind the port, and the command then reports that the file built nothing.
+ * The command runs from its own copy, and the application loads whichever one resolves from its own
+ * directory. That is usually the same file and sometimes not: a global install, an
+ * `npx fulmine.js@version`, a hoisted second copy, or `express` pointing here through an override.
+ * Patching only this command's copy leaves the application's own listen() to bind the port.
  *
- * An app is a callable, so its own prototype is not the one that carries the methods: walk up to
- * whichever link owns listen.
+ * An app is a callable, so its own prototype does not carry the methods: walk up to whichever link
+ * owns listen.
  *
  * @param {string} entry
  * @returns {any[]} the prototypes to stub, this command's copy first
@@ -580,14 +576,13 @@ ${error.stack ?? error}`);
 /**
  * Ends the file-reading threads that building an application started.
  *
- * An Application starts one per `threads` in its constructor, and these commands only ever read
- * what compiling the routes decided: nothing here serves a file, so nothing here needs a thread.
- * They are unref'd, so leaving them would not hang the process, but they are threads holding the
- * library the application loaded, and this command is often not the whole process. It also stops
- * them outliving the directory they were loaded from, which is how a test that profiles a copy and
- * then removes it saw "Cannot find module .../src/worker.js" arrive after it had finished.
+ * An Application starts one per `threads` in its constructor, and these commands only read what
+ * compiling the routes decided. They are unref'd, so leaving them would not hang the process, but
+ * they hold the library the application loaded, and this command is often not the whole process.
+ * It also stops them outliving the directory they were loaded from, which is how a test that
+ * profiles a copy and then removes it saw "Cannot find module .../src/worker.js".
  *
- * Best effort throughout: a build with no workers, or a worker already gone, is not an error here.
+ * Best effort throughout: a build with no workers, or a worker already gone, is not an error.
  *
  * @param {any[]} apps
  * @returns {void}
@@ -765,8 +760,7 @@ function matchesWanted(full, method, wanted) {
  *
  * There is no score here on purpose. A percentage of routes is not a percentage of traffic: an
  * application with a thousand cold routes and one hot one that fell back would score well and
- * serve badly. What is printed instead is counted rather than judged, and the advice is only
- * printed for the reasons somebody can actually act on.
+ * serve badly. What is printed is counted rather than judged.
  *
  * @param {any[]} routes
  * @param {any[]} native
@@ -815,7 +809,7 @@ function printSummary(routes, native, declarative) {
 }
 
 /**
- * @param {any} app
+ * @param {any} 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

@@ -16,16 +16,12 @@ limitations under the License.
 
 // express({ cluster: "auto" }): one process per core, all on the same port.
 //
-// A node process runs the application on one core, and the other fifteen sit there. The usual
-// answer is the cluster module, where the primary holds the listening socket and hands each
-// accepted connection to a worker over an IPC channel. µWS does not need that: it can bind with
-// the port marked shared, which is SO_REUSEPORT, and then every worker has its own listening
-// socket on the same port and the kernel picks which one gets each connection. No primary in the
-// path, no handle to pass, nothing serialised between processes.
+// The usual answer is the cluster module, where the primary holds the listening socket and passes
+// each accepted connection to a worker over IPC. uWS does not need that: it binds with the port
+// marked shared, which is SO_REUSEPORT, so every worker has its own listening socket on the same
+// port and the kernel picks who gets each connection. No primary in the path, nothing serialised.
 //
-// The flag has been passed for a while, see Application#listen: a worker binds shared and a lone
-// process binds exclusive. What was missing is the fork, which every application had to write for
-// itself, and an application that does not write it uses one core.
+// Application#listen already passes the flag. What was missing is the fork.
 
 "use strict";
 
@@ -54,8 +50,7 @@ function parallelism() {
  * The CPU quota a cgroup puts on this process, in cores, or undefined where there is none.
  *
  * This is the number that matters in a container: os.availableParallelism() reports the machine,
- * not the share of it the orchestrator gave away, so a 2-core pod on a 64-core node would fork 64
- * processes that fight over two cores. Both cgroup layouts are read, v2 first.
+ * so a 2-core pod on a 64-core node would fork 64 processes. Both cgroup layouts are read, v2 first.
  *
  * @param {(file: string) => string} [read] the file reader, for a test that has no cgroup
  * @returns {number|undefined}
@@ -103,8 +98,8 @@ function availableCores(read = readFile, cores = parallelism) {
  * How many workers a `cluster` setting asks for. Zero means the setting is off and the process
  * serves by itself, which is the default.
  *
- * A value nobody can read is a throw rather than a quiet zero: `cluster: "atuo"` running on one
- * core in production, with nothing said about it, is the failure this whole thing is against.
+ * A value nobody can read throws instead of quietly meaning zero: `cluster: "atuo"` would run on
+ * one core in production and say nothing about it.
  *
  * @param {boolean|number|"auto"|undefined} setting
  * @param {number} [cores] counted only when the setting asks for it: every application calls this,
@@ -124,9 +119,8 @@ function workerCount(setting, cores) {
     throw new TypeError(`cluster must be "auto", a boolean or a positive number, not ${JSON.stringify(setting)}`);
 }
 
-// Whether this process has forked workers, and so serves nothing itself. An application carries
-// the setting, but the answer is about the process: an entry with a second app on a TLS port would
-// otherwise bind that one here, exclusively, and every worker would fail on it.
+// Whether this process forked workers and serves nothing itself. About the process, not the app:
+// an entry with a second app on a TLS port would bind that one here and every worker would fail.
 let supervising = false;
 
 /**
@@ -141,9 +135,8 @@ function isSupervising() {
 /**
  * Says this process is the primary of a clustered application, before it has forked anything.
  *
- * Written when the application is constructed and not when it listens, because the order is the
- * application's to choose: an entry that listens on its TLS port first would otherwise have taken
- * that port here, exclusively, a line before the fork.
+ * Written when the application is constructed, not when it listens: an entry that listens on its
+ * TLS port first would take that port here, exclusively, one line before the fork.
  *
  * @returns {void}
  */
@@ -154,10 +147,8 @@ function becomeSupervisor() {
 /**
  * Forks the workers and keeps that many of them alive.
  *
- * A worker that dies is replaced, and there is nothing to rebuild when it comes back: it binds the
- * shared port again and the kernel starts handing it connections. A signal that reaches the
- * primary alone, which is what a container sends, is passed on rather than leaving the workers
- * running with nobody watching them.
+ * A dead worker is replaced and has nothing to rebuild, it binds the shared port again. A signal
+ * that reaches only the primary, which is what a container sends, is passed on to the workers.
  *
  * @param {number} count
  * @returns {{stop: () => void}}
@@ -187,8 +178,8 @@ function forkWorkers(count) {
     for (const signal of ["SIGTERM", "SIGINT"]) {
         process.on(signal, () => {
             stop();
-            // the primary exits on its own once the last IPC channel closes; this only makes sure
-            // it does, and being unref'd it never keeps the process up by itself
+            // the primary exits on its own once the last IPC channel closes, this only makes sure
+            // it does. Unref'd, so it never keeps the process up by itself
             const done = setInterval(() => {
                 if (Object.keys(cluster.workers ?? {}).length === 0) {
                     clearInterval(done);