fulmine.js 5.19.2 → 5.19.3

package/src/usage.js

@@ -23,10 +23,9 @@ const acorn = require("acorn");
 // GET alone (and a GET that declares a body falls back to the full header copy).
 const kGetSafe = Symbol("fulmine.getSafe");
 
-// What a handler may do with `req` and still let the header copy be skipped: members whose
-// reads never reach a header. Anything else, computed access included, keeps the copy.
-// req.res and req.app are deliberately absent: the walk judges only the member directly on
-// the parameter, so anything that can reach another object could reach headers through it.
+// What a handler may do with `req` and still let the header copy be skipped: members whose reads
+// never reach a header. Anything else, computed access included, keeps the copy. req.res and
+// req.app are absent because they could reach headers through another object.
 const REQ_OK = new Set(["query", "params", "body", "method", "path", "url", "baseUrl", "originalUrl", "route"]);
 
 // Reading any of these needs the query string fetched: req.url and req.originalUrl carry it
@@ -70,9 +69,8 @@ const QUERY = 8; // reads req.query, req.url or req.originalUrl
 const verdicts = new WeakMap();
 
 /**
- * What one callback provably does, as a mask of the facts above. The default is UNKNOWN: any
- * shape this walk does not understand and any alias of req, res or next could do anything.
- * That inversion is what makes source analysis sound to act on.
+ * What one callback provably does, as a mask of the facts above. The default is UNKNOWN: any shape
+ * this walk does not understand, and any alias of req, res or next, could do anything.
  *
  * @param {Function} fn
  * @returns {number}
@@ -135,9 +133,8 @@ function analyze(fn) {
     const resName = params[1] ? params[1].name : null;
     const nextName = params[2] ? params[2].name : null;
 
-    // Every appearance of the three names in the whole body is judged, nested functions
-    // included: an inner binding that shadows one of them only makes this stricter, never
-    // looser, so scope tracking is not needed for soundness.
+    // Every appearance of the three names is judged, nested functions included. An inner binding
+    // that shadows one only makes this stricter, so no scope tracking is needed.
     let mask = 0;
     walk(root.body, null, (node, parent) => {
         if (mask & UNKNOWN) {
@@ -192,11 +189,10 @@ function analyze(fn) {
             return;
         }
         if (name === nextName) {
-            // calling next is how a chain advances, and past its end or with an error the
-            // request lands in the framework's own final answer, which the constructor's
-            // accept pre-read covers. Anything but a direct call aliases the continuation,
-            // and an argument that could be the string "route" would leave the chain for
-            // routes nobody analyzed, so only shapes that cannot be a string pass.
+            // calling next is how a chain advances, and past its end the request lands in the
+            // framework's own final answer, which the constructor's accept pre-read covers.
+            // Anything but a direct call aliases the continuation, and an argument that could be
+            // the string "route" would leave the chain, so only non-string shapes pass.
             if (!parent || parent.type !== "CallExpression" || parent.callee !== node) {
                 mask |= UNKNOWN;
                 return;
@@ -235,8 +231,8 @@ function analyze(fn) {
  * Walks every node, handing each its parent. Arrays and nested objects are entered, nothing
  * is interpreted: the judging happens in the visitor.
  *
- * @param {any} node
- * @param {any} parent
+ * @param {any} node an acorn AST node. acorn ships no useful node types, and every shape here is checked by hand
+ * @param {any} parent its parent node, or null at the root
  * @param {(node: any, parent: any) => void} visit
  */
 function walk(node, parent, visit) {
@@ -265,10 +261,9 @@ function walk(node, parent, visit) {
  * What a native route's whole chain provably never does, so the request constructor may leave
  * that work undone: skipHeaders spares the header copy, skipQuery the query fetch.
  *
- * A callback that calls next() bare passes anywhere but in the terminal route, where it would
- * fall out of the chain: there it only passes when the caller established that no later route
- * could catch the fall-through. The framework's own 404 answers with the path alone, so the
- * fall-through itself needs neither headers nor query.
+ * A bare next() passes anywhere but in the terminal route, where it falls out of the chain: there
+ * it passes only when no later route could catch the fall-through. The framework's own 404 answers
+ * from the path alone.
  *
  * @param {any[]} chain the routes the native handler runs, in order, this route last
  * @param {boolean} allowTerminalNext whether a fall-through past the chain lands only in the

package/src/utils.js

@@ -28,6 +28,9 @@ const ms = require("ms");
 const fs = require("fs");
 const { Stats } = require("fs");
 
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+
 const EMPTY_REGEX = new RegExp(``);
 
 // what express hands qs for a query string. allowPrototypes keeps a key named "constructor" or
@@ -231,11 +234,9 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
     let lastWildcardEnd = -1;
     // What path-to-regexp calls the wildcard backtrack: the literal text written since the last
     // wildcard. Once a wildcard has eaten slashes, a later one in the same path is held to a single
-    // segment, or the two would divide the path between them in more than one way and the regex
-    // would have to backtrack to find out which. /*a/*b against /x/y/ is the case that shows it:
-    // express refuses it under strict routing, and a second greedy wildcard accepts it.
-    // the text written since the last capture of any kind, and the text written since the last
-    // wildcard, which are the two path-to-regexp weighs
+    // segment, or the two would divide the path in more than one way and the regex would have to
+    // backtrack. /*a/*b against /x/y/ shows it: express refuses it under strict routing.
+    // Two counters: text since the last capture of any kind, and text since the last wildcard
     let backtrack = "";
     let wildcardBacktrack = "";
     let lastCaptureWasWildcard = false;
@@ -405,16 +406,13 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
             i++;
 
             // When a :parameter precedes this group, that parameter is the one that gives ground
-            // while backtracking, so this one must not swallow the separator as well. Express
-            // splits /a.b.c against /:file{.:ext} as file=a.b, ext=c, which only works if ext
-            // cannot contain a dot. After static text there is nothing to give ground, so the
-            // parameter takes everything: /file{.:ext} against /file.tar.gz gives ext=tar.gz.
-            // The whole of it, not its first character: /:foo{abc:bar} against /123abcabc splits as
-            // foo=123 and bar=abc on express, and reading the separator as "a" left bar unable to
-            // match its own text, so the group never matched and foo took the segment whole. More
-            // than one character cannot go in a class, so it is written as a lookahead, and either
-            // way the parameter is still allowed to be exactly the separator, as path-to-regexp
-            // writes it.
+            // while backtracking, so this one must not swallow the separator too. Express splits
+            // /a.b.c against /:file{.:ext} as file=a.b, ext=c, which only works if ext cannot
+            // contain a dot. After static text nothing gives ground, so the parameter takes
+            // everything: /file{.:ext} against /file.tar.gz gives ext=tar.gz.
+            // The whole separator, not its first character: /:foo{abc:bar} against /123abcabc
+            // splits as foo=123 and bar=abc on express, and reading it as "a" left bar unable to
+            // match its own text. More than one character cannot go in a class, so it is a lookahead
             const colon = groupContent.indexOf(":");
             const separator = lastTokenWasParam && colon > 0 ? groupContent.slice(0, colon) : "";
             const escapedSeparator = separator.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -445,13 +443,11 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
                 }
             }
             if (lastWildcard && lastWildcardEnd === regexPattern.length) {
-                // A wildcard immediately before the group. `(?<w>[^]+)(?:group)?` can never let
-                // the group match, because the wildcard is greedy and the group may be empty, and
-                // making the wildcard lazy is not the same thing either: it gives the trailing
-                // slash away, and /*path{.:ext} against /a/b/ then loses the empty last segment.
-                // path-to-regexp writes the two branches out instead, group first and the
-                // wildcard greedy in both, so that is what goes here. The second branch captures
-                // the same parameter under a name of its own, which is what uniqueGroupName is for.
+                // A wildcard immediately before the group. `(?<w>[^]+)(?:group)?` can never let the
+                // group match, because the wildcard is greedy and the group may be empty, and a
+                // lazy wildcard is not the same thing either: it gives the trailing slash away, and
+                // /*path{.:ext} against /a/b/ loses the empty last segment. path-to-regexp writes
+                // the two branches out instead, group first and the wildcard greedy in both
                 const second = uniqueGroupName(lastWildcard.name);
                 wildcardNames.push(second);
                 const withWildcard = regexPattern.slice(lastWildcard.start);
@@ -619,13 +615,13 @@ const NOT_A_LITERAL = /[:*{}\\]/;
  *
  * The answer is structural: no position where two different literals meet, and, when neither path
  * can change length, the same number of segments. `/orders/:id` and `/invoices/:id` cannot both
- * match, `/users/:id` and `/users/me` can. The caller reads "do not know" as yes, so every doubt
- * answers true: saying two paths overlap only costs a native registration, while missing one lets
- * µWS answer a request that belonged to an earlier route.
+ * match, `/users/:id` and `/users/me` can. The caller reads "do not know" as yes: saying two paths
+ * overlap only costs a native registration, while missing one lets uWS answer a request that
+ * belonged to an earlier route.
  *
  * A parameter is not the only shape that matches more than itself. A wildcard and an optional group
- * do too, and reading `{:opt}` or `*splat` as the literal text it is written as reported "cannot
- * overlap" for a route that plainly could, which took the earlier route's turn away.
+ * do too, and reading `{:opt}` or `*splat` as literal text reported "cannot overlap" for a route
+ * that plainly could.
  *
  * @param {string} a
  * @param {string} b
@@ -759,11 +755,8 @@ function acceptParams(str) {
 //
 // The keys are media types, so an application uses a handful and the ceiling is never approached.
 // It is here because application code is free to hand res.type() something a client sent, and an
-// unbounded map keyed on that is a leak the client controls.
-//
-// Clearing beats evicting one entry at a time: the few types an application really uses are back
-// within a few requests, whereas refusing new entries once full would let a flood of invented
-// values lock the real ones out for the life of the process.
+// unbounded map keyed on that is a leak the client controls. Clearing beats evicting one at a
+// time: refusing new entries once full would let a flood of invented values lock the real ones out.
 const MEMO_LIMIT = 512;
 
 /**
@@ -818,7 +811,7 @@ function normalizeType(type) {
  * unicode escapes, so a string in the body cannot close a script tag in an HTML page that embeds
  * the response.
  *
- * @param {any} value
+ * @param {any} value whatever the handler passed to res.json
  * @param {any} [replacer] the "json replacer" setting
  * @param {string|number} [spaces] the "json spaces" setting
  * @param {boolean} [escape] the "json escape" setting
@@ -855,14 +848,12 @@ const ENCODING_ANY = ENCODING_BR | ENCODING_GZIP | ENCODING_DEFLATE | ENCODING_Z
 /**
  * The encoding to answer with, read straight off Accept-Encoding rather than through negotiator:
  * the header is a short list of names with an optional q, and building a Negotiator per response
- * to read it costs more than the scan does.
- *
- * The tie-break is negotiator's, for the list the compression module hands it: brotli first, then
- * gzip, then deflate, and identity last.
+ * costs more than the scan does. The tie-break is negotiator's, for the list the compression module
+ * hands it: brotli first, then gzip, then deflate, and identity last.
  *
- * Only the encodings named in `allowed` are on offer, since the caller may not be able to
- * produce all three: express.static offers the two it can have lying on disk. An uncompressed
- * answer is always on offer, and is what an empty header ends up choosing.
+ * Only the encodings named in `allowed` are on offer, since the caller may not produce all three:
+ * express.static offers the two it can have lying on disk. An uncompressed answer is always on
+ * offer, and is what an empty header chooses.
  *
  * @param {string} accept the header, or "" when the request carried none
  * @param {number} allowed ENCODING_BR, ENCODING_ZSTD, ENCODING_GZIP and ENCODING_DEFLATE, or'd
@@ -989,12 +980,10 @@ const defaultSettings = {
     // The native µWS router matches bytes, so the compiler in _compileOptimizedRoutes only hands
     // it routes whose earlier siblings it can prove agree under either case rule.
     "declarative responses": true,
-    // on. Off hands every request to the ordinary chain instead of letting µWS match what it can,
+    // on. Off hands every request to the ordinary chain instead of letting uWS match what it can,
     // which is slower and answers the same. Not a tuning knob: it exists so one application can be
-    // served both ways and the two sets of answers compared, which tests the optimizer against the
-    // rest of the framework without a second framework to compare with. See
-    // `npm run fuzz -- --self`. A compiled response needs a native registration to hang on, so this
-    // takes "declarative responses" with it.
+    // served both ways and the answers compared, see `npm run fuzz -- --self`. A compiled response
+    // needs a native registration to hang on, so this takes "declarative responses" with it
     "native routes": true,
     // off: with a window set, the size and mtime of a file served by sendFile are remembered for
     // it, which is one syscall less per request and a file that can be served as it was a moment
@@ -1053,7 +1042,7 @@ function cachedStat(file, ttl) {
 /**
  * A duration setting as milliseconds: false is off, a string is read by ms, a number is itself.
  *
- * @param {any} value
+ * @param {any} value the setting as the application wrote it
  * @param {string} name for the error, which names the setting the application wrote
  * @returns {number}
  */
@@ -1274,8 +1263,8 @@ function parseHttpDate(date) {
  * no longer the current one, which is a 412 rather than a 304: the client asked to be stopped if
  * anything had changed.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @returns {boolean}
  */
 function isPreconditionFailure(req, res) {
@@ -1296,7 +1285,8 @@ function isPreconditionFailure(req, res) {
     // if-unmodified-since
     const unmodifiedSince = parseHttpDate(req.headers["if-unmodified-since"]);
     if (!isNaN(unmodifiedSince)) {
-        const lastModified = parseHttpDate(res.get("Last-Modified"));
+        // cast because res.get answers an array for set-cookie, and never for this one
+        const lastModified = parseHttpDate(/** @type {string|undefined} */ (res.get("Last-Modified")));
         return isNaN(lastModified) || lastModified > unmodifiedSince;
     }
 
@@ -1367,8 +1357,8 @@ function createETagGenerator(options) {
  * and sending the whole file. It may carry either an ETag or a date, and a date only counts when
  * it matches Last-Modified exactly.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @returns {boolean}
  */
 function isRangeFresh(req, res) {
@@ -1384,7 +1374,8 @@ function isRangeFresh(req, res) {
     }
 
     // if-range as modified date
-    const lastModified = res.get("Last-Modified");
+    // cast because res.get answers an array for set-cookie, and never for this one
+    const lastModified = /** @type {string|undefined} */ (res.get("Last-Modified"));
     return parseHttpDate(lastModified) <= parseHttpDate(ifRange);
 }
 
@@ -1489,10 +1480,9 @@ const HEADER_VALUE = /[^\t\x20-\x7e\x80-\xff]/;
  * One of node's header errors, built the way node builds it.
  *
  * Assigning the code is not the whole of it. Node also puts the code in the first line of the
- * stack, by naming the error "TypeError [THE_CODE]" while V8 formats that line and then taking
- * the name back off. Whatever prints a stack therefore says which code it was, and the default
- * error page prints exactly that: without this, the same refusal reads "TypeError:" here and
- * "TypeError [ERR_INVALID_CHAR]:" behind Express. Found by fuzzing against express.
+ * stack, by naming the error "TypeError [THE_CODE]" while V8 formats that line and then taking the
+ * name back off. The default error page prints exactly that: without this, the same refusal reads
+ * "TypeError:" here and "TypeError [ERR_INVALID_CHAR]:" behind Express. Found by fuzzing.
  *
  * @param {string} message
  * @param {string} code
@@ -1515,7 +1505,7 @@ function headerError(message, code) {
  * Refuses a header name that is not an HTTP token, the way node's setHeader does and with its
  * error, so an application catching ERR_INVALID_HTTP_TOKEN behind Express catches it here.
  *
- * @param {any} name
+ * @param {any} name whatever a caller passed as a header name, which is what is being checked
  * @returns {void}
  * @throws {TypeError} if the name is not a token, which includes not being a string
  */
@@ -1567,7 +1557,7 @@ function validateHeaderValue(name, value) {
  * again is what turns one bad header into a dead process.
  *
  * @param {string} name
- * @param {any} value
+ * @param {any} value whatever a caller passed as a header value
  * @returns {boolean}
  */
 function headerIsWritable(name, value) {
@@ -1612,7 +1602,7 @@ function httpError(status) {
  *
  * The error itself is returned rather than a new one, so its errno, code, syscall and path survive.
  *
- * @param {any} err
+ * @param {any} err the fs error, which carries its errno and path
  * @returns {any} the same error
  */
 function asStatError(err) {

package/src/verify.js

@@ -16,16 +16,12 @@ limitations under the License.
 
 // npx fulmine verify
 //
-// Whether this machine, and the image it will be deployed in, can run the thing at all. Not
-// whether the application behaves the same, which is what the test suite and `differences` are
-// for: this is the question that comes before it, and it is the one that costs an hour when the
-// answer is no and nobody asked.
+// Whether this machine, and the image it will be deployed in, can run the thing at all. Not whether
+// the application behaves the same, which is the test suite's job.
 //
-// There is a µWebSockets.js binary underneath, and a binary has requirements a package does not:
-// it is built per platform, per architecture and per node ABI, and it is linked against glibc. An
-// Alpine image, a node version the pinned build has no binary for, a musl base chosen by a
-// Dockerfile written before any of this: each one fails at require time, in a container, in CI,
-// with a message about a missing module that says nothing about what to do.
+// There is a uWebSockets.js binary underneath, built per platform, per architecture and per node
+// ABI, and linked against glibc. An Alpine image, a node version with no binary for it, a musl
+// base: each one fails at require time with a message about a missing module.
 //
 // Thirty seconds here instead.
 
@@ -34,7 +30,7 @@ limitations under the License.
 const fs = require("fs");
 const path = require("path");
 
-// The oldest glibc the pinned µWS binaries are built against. A runtime older than this loads the
+// The oldest glibc the pinned uWS binaries are built against. A runtime older than this loads the
 // file and then fails on a symbol, which is a worse error than not finding it at all.
 const MIN_GLIBC = "2.38";
 
@@ -44,8 +40,8 @@ const MIN_NODE = require("../package.json").engines.node.replace(/[^0-9.]/g, "")
 const MIN_NODE_MAJOR = MIN_NODE.split(".")[0];
 const SWAP_IMAGE = `node:${MIN_NODE_MAJOR}-trixie-slim`;
 
-// What a project may carry that needs a different API here rather than none. Everything that just
-// works, and everything that only wants a faster built-in, is `npx fulmine migrate`'s business.
+// What a project may carry that needs a different API here. Everything that just works is
+// `npx fulmine migrate`'s business.
 const NEEDS_A_LOOK = {
     "socket.io": "attach it with io.attachApp(app.uwsApp), not io.attach(server): there is no node socket to take over",
     ws: "the websocket server is µWS's own, through app.ws(path, behavior)",
@@ -55,9 +51,8 @@ const NEEDS_A_LOOK = {
 };
 
 /**
- * One line of the report. Three levels, and only one of them is a failure: an image that cannot
- * load the binary stops the deployment, while a dependency that wants a different call is
- * something to read, not something to fail a pipeline over.
+ * One line of the report. Only "no" is a failure: an image that cannot load the binary stops the
+ * deployment, a dependency that wants a different call does not.
  *
  * @param {"ok"|"note"|"no"} level
  * @param {string} what
@@ -92,9 +87,8 @@ function atLeast(version, minimum) {
 /**
  * The node this is running on, against what the package asks for.
  *
- * The version arrives as an argument rather than being read here, so the answer for a node this
- * machine is not running is testable from the machine it is not running on. Every check below
- * takes what it judges for the same reason.
+ * The version is an argument rather than read here, so a node this machine is not running is still
+ * testable. Every check below takes what it judges for the same reason.
  *
  * @param {string} [running] defaults to the node running this
  * @param {string} [required] defaults to what package.json asks for
@@ -121,9 +115,8 @@ function currentGlibc() {
 /**
  * Whether the C library is the one the binaries are linked against. Only linux has two of them.
  *
- * Both arguments are required, and deliberately: undefined is the answer that means musl, and a
- * default parameter fires on an explicit undefined, so a default here would quietly turn the musl
- * case into whatever this machine happens to run. Reading the machine is the caller's job.
+ * Both arguments are required on purpose: undefined means musl, and a default parameter fires on
+ * an explicit undefined, so a default would turn the musl case into whatever this machine runs.
  *
  * @param {string} platform
  * @param {string|undefined} glibc the runtime glibc, absent on musl
@@ -152,9 +145,8 @@ function checkLibc(platform, glibc) {
 }
 
 /**
- * Whether there is a µWebSockets.js binary for this platform, architecture and node ABI, which is
- * the failure that greets everyone who tries an unusual combination. The file is named rather than
- * loaded first, so the answer says which of the three does not line up.
+ * Whether there is a uWebSockets.js binary for this platform, architecture and node ABI. The file
+ * is named rather than loaded, so the answer says which of the three does not line up.
  *
  * @param {string} [platform]
  * @param {string} [arch]
@@ -218,8 +210,7 @@ function abiToNode(abi) {
 }
 
 /**
- * The base images a Dockerfile names, which is where the musl question is usually answered without
- * anybody meaning to.
+ * The base images a Dockerfile names, which is where the musl question is usually answered.
  *
  * @param {string} dir the project being verified
  * @returns {ReturnType<typeof result>[]}
@@ -309,8 +300,7 @@ function verify(argv) {
             console.log(`        ${detail}`);
         }
     }
-    // only a blocked start is a failure. A dependency that wants a different call is worth
-    // reading and is not worth failing a pipeline over
+    // only a blocked start is a failure, a dependency that wants a different call is not
     const blocking = results.filter((entry) => entry.level === "no").length;
     const notes = results.filter((entry) => entry.level === "note").length;
     console.log(

package/src/view.js

@@ -73,9 +73,8 @@ module.exports = class View {
     }
 
     /**
-     * The first of the configured roots that actually holds this template, or undefined when none
-     * of them does. `views` may be a single directory or a list, and the list is searched in order,
-     * so an application can put its own templates in front of a package's.
+     * The first configured root that holds this template, or undefined. `views` may be one
+     * directory or a list, and the list is searched in order.
      *
      * @param {string} name template file name, relative to a root
      * @returns {string|undefined} absolute path to the file that exists
@@ -100,10 +99,9 @@ module.exports = class View {
     /**
      * Renders the template through its engine.
      *
-     * The callback is always delivered asynchronously, even when the engine answers on the spot.
-     * `sync` is still true only if the engine called back before this function returned, and in
-     * that case the callback is pushed to the next tick, so a caller never has to handle both
-     * orders. Express normalises it the same way.
+     * The callback is always delivered asynchronously, even when the engine answers on the spot:
+     * `sync` is true only if the engine called back before this returned, and then the callback
+     * goes to the next tick. Express does the same.
      *
      * @param {Record<string, any>} options locals and engine options, passed through untouched
      * @param {Function} callback called with whatever the engine passed, which is normally