fulmine.js 5.19.8 → 5.20.0

package/src/utils.js

@@ -208,6 +208,9 @@ function getPatternMeta(pattern) {
  * A bare `*`, an unnamed parameter, an inline regex like :id(\\d+) and the `+`, `?`, `()` operators
  * throw: a route that quietly stops matching is worse than one that fails at startup. The names it
  * captures go in a WeakMap beside the regex, see PatternMeta.
+ *
+ * @param {string|RegExp} pattern
+ * @returns {RegExp}
  */
 function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict = false) {
     if (pattern instanceof RegExp) {
@@ -222,11 +225,12 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
     let regexPattern = "";
     let i = 0;
     const len = pattern.length;
-    const wildcardNames = [];
+    const wildcardNames = /** @type {string[]} */ ([]);
     // express takes /:a/:a, and two capture groups cannot share a name, so a repeat is compiled
     // under a spelling of its own and mapped back when the parameters are read out. Reading them
     // in order then leaves the last occurrence in place, which is the value express reports
-    const groupOutputName = new Map();
+    const groupOutputName = /** @type {Map<string, string>} */ (new Map());
+    /** @param {string} name */
     const uniqueGroupName = (name) => {
         if (!groupOutputName.has(name)) {
             groupOutputName.set(name, name);
@@ -255,7 +259,11 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
     let lastCaptureWasWildcard = false;
     let wildcardInSegment = false;
     let paramInSegment = false;
-    /** Records literal text as it is emitted, which is what the rules above are written against. */
+    /**
+     * Records literal text as it is emitted, which is what the rules above are written against.
+     *
+     * @param {string} text
+     */
     const literal = (text) => {
         backtrack += text;
         if (lastCaptureWasWildcard) {
@@ -750,7 +758,8 @@ function acceptParams(str) {
     const length = str.length;
     const colonIndex = str.indexOf(";");
     let index = colonIndex === -1 ? length : colonIndex;
-    const ret = { value: str.slice(0, index).trim(), quality: 1, params: {} };
+    const params = /** @type {Record<string, string>} */ ({});
+    const ret = { value: str.slice(0, index).trim(), quality: 1, params };
 
     while (index < length) {
         const splitIndex = str.indexOf("=", index);
@@ -1098,13 +1107,20 @@ function durationSetting(value, name) {
     return parsed;
 }
 
+/**
+ * The predicate "trust proxy" compiles to: whether the address at hop i is trusted. The address is
+ * undefined over a unix socket, see Request#parsedIp.
+ *
+ * @typedef {(addr: string|undefined, i: number) => boolean} TrustFn
+ */
+
 /**
  * Turns whatever "trust proxy" was set to into the function proxy-addr wants: a predicate saying
  * whether the address at hop i is trusted. true trusts everything, a number trusts that many hops,
  * and a string or a list is read as addresses and subnet names.
  *
- * @param {boolean|number|string|string[]|Function} val
- * @returns {Function}
+ * @param {boolean|number|string|string[]|TrustFn} val
+ * @returns {TrustFn}
  */
 function compileTrust(val) {
     if (typeof val === "function") return val;
@@ -1118,8 +1134,9 @@ function compileTrust(val) {
 
     if (typeof val === "number") {
         // Support trusting hop count
-        return function (a, i) {
-            return i < val;
+        const hops = val;
+        return function (/** @type {string|undefined} */ a, /** @type {number} */ i) {
+            return i < hops;
         };
     }
 
@@ -1130,7 +1147,9 @@ function compileTrust(val) {
         });
     }
 
-    return proxyaddr.compile(val || []);
+    // proxy-addr answers false to an address it cannot parse, undefined included, though its
+    // typing does not admit one
+    return /** @type {TrustFn} */ (proxyaddr.compile(val || []));
 }
 
 const shownWarnings = new Set();

package/src/verify.js

@@ -29,6 +29,7 @@ limitations under the License.
 
 const fs = require("fs");
 const path = require("path");
+const { detectManager, UWS_SPEC, UWS_OVERRIDE } = require("./adopt.js");
 
 // 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.
@@ -251,6 +252,20 @@ function checkDockerfiles(dir) {
     return results;
 }
 
+/**
+ * The project's package.json, or nothing where there is none to read.
+ *
+ * @param {string} dir
+ * @returns {any}
+ */
+function readPackage(dir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    } catch {
+        return undefined;
+    }
+}
+
 /**
  * The dependencies that need a different API here. Read from package.json rather than from
  * node_modules, so a project is answered before it installs anything.
@@ -261,12 +276,8 @@ function checkDockerfiles(dir) {
 function checkDependencies(dir) {
     /** @type {ReturnType<typeof result>[]} */
     const results = [];
-    let pkg;
-    try {
-        pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
-    } catch {
-        return results;
-    }
+    const pkg = readPackage(dir);
+    if (!pkg) return results;
     const installed = { ...pkg.dependencies, ...pkg.devDependencies };
     for (const name of Object.keys(NEEDS_A_LOOK)) {
         if (installed[name]) {
@@ -276,6 +287,83 @@ function checkDependencies(dir) {
     return results;
 }
 
+// pnpm refuses a git dependency of a dependency since this version, and µWebSockets.js is one
+const PNPM_BLOCKS_GIT_SUBDEPS = [10, 26];
+
+/**
+ * Whether the package manager will install this at all. pnpm 10.26 and later refuse a dependency
+ * of a dependency that comes from git, which µWebSockets.js does, so `pnpm add fulmine.js` fails
+ * before anything runs. What lets it through is readable from the project: the two lines
+ * `npx fulmine.js pnpm` writes, the setting turned off, or an override taking µWebSockets.js from
+ * a registry. pnpm 11 reads its settings from pnpm-workspace.yaml only, so that is what is read.
+ *
+ * @param {string} dir
+ * @param {any} pkg the parsed package.json
+ * @returns {ReturnType<typeof result>|undefined} nothing to say for npm and yarn
+ */
+function checkPackageManager(dir, pkg) {
+    const { manager, why } = detectManager(dir, pkg);
+    if (manager !== "pnpm") return undefined;
+
+    const declared = /^pnpm@(\d+)\.(\d+)/.exec(pkg.packageManager ?? "");
+    if (declared) {
+        const [major, minor] = [Number(declared[1]), Number(declared[2])];
+        const [blockMajor, blockMinor] = PNPM_BLOCKS_GIT_SUBDEPS;
+        if (major < blockMajor || (major === blockMajor && minor < blockMinor)) {
+            return result("ok", `pnpm ${declared[1]}.${declared[2]} installs a git dependency of a dependency`);
+        }
+    }
+
+    let workspace = "";
+    try {
+        workspace = fs.readFileSync(path.join(dir, "pnpm-workspace.yaml"), "utf8");
+    } catch {
+        // no workspace file, so every setting is at its default
+    }
+
+    // the recipe: the project owns the git dependency, and the copy this package asks for is dropped
+    const dropped = new RegExp(`^\\s*["']?${UWS_OVERRIDE.replace(/\./g, "\\.")}["']?:\\s*["']?-["']?\\s*$`, "m").test(
+        workspace
+    );
+    const own = pkg.dependencies?.["uWebSockets.js"];
+    if (dropped && typeof own === "string") {
+        if (own === UWS_SPEC) {
+            return result(
+                "ok",
+                "pnpm, with µWebSockets.js as the project's own dependency at the pin this package uses"
+            );
+        }
+        return result(
+            "note",
+            `pnpm, with µWebSockets.js as the project's own dependency at ${own}`,
+            `this package pins ${UWS_SPEC} and was tested against it. \`npx fulmine.js pnpm\` writes the pin.`
+        );
+    }
+    if (dropped) {
+        return result(
+            "no",
+            "pnpm-workspace.yaml drops µWebSockets.js from this package, and the project does not declare it",
+            `nothing would install it. \`npx fulmine.js pnpm\` adds "uWebSockets.js": "${UWS_SPEC}" to dependencies.`
+        );
+    }
+
+    if (/^\s*blockExoticSubdeps:\s*false\s*$/m.test(workspace)) {
+        return result("ok", "pnpm, with blockExoticSubdeps off in pnpm-workspace.yaml");
+    }
+    const registry = /^\s*["']?uWebSockets\.js["']?:\s*["']?([~^]?\d[^"'\s]*)/m.exec(workspace);
+    if (registry) {
+        return result("ok", `pnpm, with µWebSockets.js overridden to ${registry[1]} from a registry`);
+    }
+
+    return result(
+        "no",
+        `pnpm (${why}) will refuse to install this`,
+        "pnpm 10.26 and later block a git dependency of a dependency, and µWebSockets.js is one:\n" +
+            "        pnpm add fulmine.js fails with ERR_PNPM_EXOTIC_SUBDEP. `npx fulmine.js pnpm` writes the two\n" +
+            "        lines that let it through, see docs/deployment.md."
+    );
+}
+
 /**
  * Runs every check and prints the report. Anything that would stop the application from starting
  * is a failure and the command exits non-zero, so it can be a step in a pipeline.
@@ -292,6 +380,10 @@ function verify(argv) {
         results.push(libc);
     }
     results.push(checkBinary(), ...checkDockerfiles(dir), ...checkDependencies(dir));
+    const manager = checkPackageManager(dir, readPackage(dir) ?? {});
+    if (manager) {
+        results.push(manager);
+    }
 
     console.log(`\nWhether this machine and this project can run fulmine.js\n`);
     const label = { ok: "ok  ", note: "note", no: "NO  " };
@@ -312,4 +404,13 @@ function verify(argv) {
     return blocking === 0 ? 0 : 1;
 }
 
-module.exports = { verify, checkNode, checkLibc, currentGlibc, checkBinary, checkDockerfiles, checkDependencies };
+module.exports = {
+    verify,
+    checkNode,
+    checkLibc,
+    currentGlibc,
+    checkBinary,
+    checkDockerfiles,
+    checkDependencies,
+    checkPackageManager
+};

package/src/walk.js

@@ -79,6 +79,7 @@ class Walk {
         //
         // Null here and bound on the first route with more than one callback, the only shape that
         // reads it: a request that never meets one paid a bind for nothing
+        /** @type {((err?: unknown) => void)|null} */
         this.leaveRoute = null;
     }
 
@@ -103,6 +104,7 @@ class Walk {
      * a chain of N middlewares costs one promise instead of N nested ones.
      *
      * @param {number} startIndex where to resume the scan
+     * @returns {void}
      */
     dispatch(startIndex) {
         const req = this.req;
@@ -226,7 +228,7 @@ class Walk {
                 .then((resumed) => this.runRoute(resumed))
                 // wrapped so the native pair keeps the walk as receiver; a promise's reject
                 // would not have cared
-                .catch((err) => this.reject(err));
+                .catch((/** @type {unknown} */ err) => this.reject(err));
             return;
         }
         return this.runRoute(continueRoute);
@@ -291,6 +293,7 @@ class Walk {
      * way in, and then the route's callbacks run one after another through next().
      *
      * @param {true|"route"} continueRoute what _preprocessRequest decided: true to run, "route" to skip
+     * @returns {void}
      */
     runRoute(continueRoute) {
         const req = this.req;
@@ -347,6 +350,7 @@ class Walk {
      *
      * @param {number} kind what the callback is, one of the CALLBACK_ constants
      * @param {Function} callback
+     * @returns {void}
      */
     errorHop(kind, callback) {
         const req = this.req;
@@ -441,6 +445,7 @@ class Walk {
      * leave the route; with anything else, remember it as the error and carry on.
      *
      * @param {unknown} thingamabob what next() was called with: nothing, "route", or an error
+     * @returns {void}
      */
     step(thingamabob) {
         const req = this.req;
@@ -492,7 +497,7 @@ class Walk {
             }
             callback
                 ._routeRequest(req, res, 0)
-                .then((routed) => {
+                .then((/** @type {RouteEntry|false} */ routed) => {
                     // the child's params are scoped to it, and must not leak into the routes after
                     if (pushedParams) {
                         req._paramStack.pop();
@@ -531,7 +536,7 @@ class Walk {
                 // a rejection out of the nested walk, or a throw above, must reject this one
                 // instead of dying as an unhandled rejection; wrapped for the native pair's
                 // receiver
-                .catch((err) => this.reject(err));
+                .catch((/** @type {unknown} */ err) => this.reject(err));
         } else {
             // errors and error handlers live out of line: this is the cold path, and its size
             // was pushing step past the inlining threshold

package/src/websocket.js

@@ -208,7 +208,7 @@ function makeUpgradeHandler(app, path, behavior) {
  * @param {Application} app
  */
 function registerWebSocketRoutes(app) {
-    const routes = [];
+    const routes = /** @type {WsRoute[]} */ ([]);
     collectRoutes(app, "", routes, new Set());
     for (const route of routes) {
         const uwsBehavior = { ...route.behavior };