fulmine.js 5.2.0 → 5.3.0

package/src/cli.js

@@ -20,6 +20,12 @@ limitations under the License.
 // 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.
+//
+// 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.
 
 const fs = require("fs");
 const path = require("path");
@@ -259,6 +265,285 @@ function walk(node, visit) {
     }
 }
 
+/** Where an application usually is, when the command was given no entry to load. */
+const DEFAULT_ENTRIES = ["server.js", "app.js", "index.js", "src/server.js", "src/app.js", "src/index.js"];
+
+/**
+ * The file to load, from the argument, or from package.json's main, or from the usual names.
+ *
+ * @param {string|undefined} given
+ * @returns {string|null}
+ */
+function findEntry(given) {
+    if (given) {
+        const resolved = path.resolve(given);
+        return fs.existsSync(resolved) ? resolved : null;
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.resolve("package.json"), "utf8"));
+        if (pkg.main && fs.existsSync(path.resolve(pkg.main))) {
+            return path.resolve(pkg.main);
+        }
+    } catch {
+        // no package.json, or one that will not parse: the usual names are still worth trying
+    }
+    for (const name of DEFAULT_ENTRIES) {
+        const resolved = path.resolve(name);
+        if (fs.existsSync(resolved)) {
+            return resolved;
+        }
+    }
+    return null;
+}
+
+/**
+ * Every route of an application and of the routers under it, each with the router it belongs to
+ * and the path it answers from the outside.
+ *
+ * @param {any} router
+ * @param {string} prefix
+ * @param {any[]} [into]
+ * @returns {any[]}
+ */
+function collectRoutes(router, prefix, into = []) {
+    for (const route of router._routes ?? []) {
+        const full = prefix + (typeof route.path === "string" ? route.path : String(route.pattern)) || "/";
+        into.push({ route, full });
+        const mounted = route.callbacks?.[0];
+        if (mounted && Array.isArray(mounted._routes)) {
+            collectRoutes(mounted, typeof route.path === "string" ? prefix + route.path : prefix, into);
+        }
+    }
+    return into;
+}
+
+/**
+ * Loads an application without letting it listen, and prints what compiling its routes decided.
+ *
+ * listen() is where the routes are compiled and also where the port is bound, and only the first
+ * of those is wanted here: an application that answered on its port while being profiled would be
+ * a surprise, and a second copy of a running service is worse than a surprise. So listen is
+ * replaced by the half that matters. The callback it was given is not run, for the same reason.
+ *
+ * @param {string[]} argv
+ * @returns {number} exit code
+ */
+function profile(argv) {
+    const entry = findEntry(argv.find((arg) => !arg.startsWith("--")));
+    if (!entry) {
+        console.error(
+            "Nothing to profile: name the file that builds the application, or run this from a\n" +
+                "directory whose package.json main points at it."
+        );
+        return 1;
+    }
+
+    // the same module instance the application will load, so patching this prototype patches the
+    // application it builds. An app is a callable, so its own prototype is not the one that carries
+    // the methods: walk up to whichever link owns listen
+    const express = require("./index.js");
+    let proto = Object.getPrototypeOf(express());
+    while (proto && !Object.prototype.hasOwnProperty.call(proto, "listen")) {
+        proto = Object.getPrototypeOf(proto);
+    }
+    if (!proto) {
+        console.error("This build of fulmine has no listen() to stand in for, which should not happen.");
+        return 1;
+    }
+
+    const listened = [];
+    const realListen = proto.listen;
+    proto.listen = function stubbedListen() {
+        this._compileOptimizedRoutes();
+        listened.push(this);
+        return this;
+    };
+
+    try {
+        require(entry);
+    } catch (e) {
+        const error = /** @type {any} */ (e);
+        proto.listen = realListen;
+        console.error(`${path.relative(process.cwd(), entry)} could not be loaded:\n${error.stack ?? error}`);
+        return 1;
+    }
+    proto.listen = realListen;
+
+    let apps = listened;
+    if (apps.length === 0) {
+        // an application that exports itself rather than listening, which is how a testable one is
+        // usually written. Compiling it here is the same work listen() would have done
+        const exported = require(entry);
+        const candidate = exported?.default ?? exported?.app ?? exported;
+        if (candidate && Array.isArray(candidate._routes)) {
+            candidate._compileOptimizedRoutes();
+            apps = [candidate];
+        }
+    }
+
+    if (apps.length === 0) {
+        console.error(
+            `${path.relative(process.cwd(), entry)} built no application: it neither called listen() nor\n` +
+                "exported one. Point this at the file that does."
+        );
+        return 1;
+    }
+
+    for (const app of apps) {
+        printProfile(app, apps.length > 1);
+    }
+    return 0;
+}
+
+// what a reason means for whoever wrote the route, when it means anything they can act on. A
+// method µWS does not serve, or a path only a regular expression can match, is not something to
+// go and fix; an ordering that costs the native match is.
+/** @type {[RegExp, (match: RegExpExecArray) => string][]} */
+const ADVICE = [
+    [
+        /^the parameter route (.+) is written before it$/,
+        (match) =>
+            `write it above ${match[1]}. Express answers whichever matches first, so the order is` +
+            ` already what decides,\n    and with the literal first µWS can match it in C++ as well.`
+    ],
+    [
+        /^something before it in the same router overlaps its paths$/,
+        () =>
+            "something registered earlier answers some of the same paths, so the chain that would" +
+            " reach this route\n    cannot be worked out ahead of time. Narrowing the earlier path, or moving this one above it, frees it."
+    ],
+    [
+        /^a route after it in the same mounted router could answer the same paths$/,
+        () =>
+            "a route below it in the same mounted router overlaps it. Inside a mount the later one" +
+            " has to be able to win,\n    which a precomputed chain cannot express. Narrowing either path frees it."
+    ]
+];
+
+/**
+ * A summary that says how much of this application the native router carries, and what could be
+ * changed to make it carry more.
+ *
+ * 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.
+ *
+ * @param {any[]} routes
+ * @param {any[]} native
+ * @param {any[]} declarative
+ */
+function printSummary(routes, native, declarative) {
+    console.log("\nWhat this adds up to\n");
+    console.log(`  ${native.length} of ${routes.length} route(s) matched by µWS in C++`);
+    if (declarative.length > 0) {
+        console.log(`  ${declarative.length} answered from a response written at startup, running no javascript`);
+    }
+
+    const skipHeaders = native.filter(({ route }) => route._native.skipHeaders).length;
+    const skipQuery = native.filter(({ route }) => route._native.skipQuery).length;
+    if (skipHeaders || skipQuery) {
+        console.log(
+            `  ${skipHeaders} copy no request headers, ${skipQuery} read no query: the analysis proved nothing asks for them`
+        );
+    }
+
+    if (native.length > 0) {
+        const ahead = native.map(({ route }) => route._native.ahead);
+        const total = ahead.reduce((sum, n) => sum + n, 0);
+        console.log(
+            `  layers in front of a compiled handler: ${Math.min(...ahead)} at least, ${Math.max(...ahead)} at most,` +
+                ` ${(total / ahead.length).toFixed(1)} on average`
+        );
+    }
+
+    // the routes whose reason somebody can do something about
+    const worth = [];
+    for (const { route, full } of routes) {
+        if (route._native || !route._whyGeneric) continue;
+        for (const [pattern, say] of ADVICE) {
+            const match = pattern.exec(route._whyGeneric);
+            if (match) {
+                worth.push(`  ${route.method} ${full}\n    ${say(match)}`);
+                break;
+            }
+        }
+    }
+    if (worth.length > 0) {
+        console.log(`\nWorth changing, if these are routes that carry traffic\n`);
+        console.log(worth.join("\n\n"));
+    }
+}
+
+/**
+ * @param {any} app
+ * @param {boolean} several whether to say which application this is
+ */
+function printProfile(app, several) {
+    const entries = collectRoutes(app, "");
+    const routes = entries.filter(({ route }) => !route.use);
+    const mounts = entries.filter(({ route }) => route.use);
+    const native = routes.filter(({ route }) => route._native);
+    const declarative = native.filter(({ route }) => route._native.declarative);
+
+    if (several) {
+        console.log(`\n=== an application listening on ${app._listenHost ?? "its own port"} ===`);
+    }
+    console.log(
+        `\n${routes.length} route(s), ${native.length} answered by µWS itself` +
+            `${declarative.length ? `, ${declarative.length} of them without running any javascript` : ""}\n`
+    );
+
+    for (const { route, full } of routes) {
+        const method = String(route.method).padEnd(7);
+        const where = full.padEnd(34);
+        if (route._native) {
+            const notes = [];
+            if (route._native.declarative) notes.push("compiled to a response");
+            if (route._native.ahead) notes.push(`${route._native.ahead} in front of it in its chain`);
+            if (route._native.guards) notes.push(`${route._native.guards} case guard(s)`);
+            if (route._native.skipHeaders) notes.push("copies no request headers");
+            if (route._native.skipQuery) notes.push("reads no query");
+            console.log(
+                `  ${method}${where}µWS  ${route._native.path}${notes.length ? `  (${notes.join(", ")})` : ""}`
+            );
+        } else {
+            console.log(`  ${method}${where}router: ${route._whyGeneric ?? "it was not eligible"}`);
+        }
+    }
+
+    // a mount holding a router is one the compiler could have walked into; anything else is
+    // middleware, and listing every helmet and cors as a mount that "was not walked into" says
+    // nothing anyone can act on
+    const routers = mounts.filter(
+        ({ route }) => route.callbacks?.length === 1 && Array.isArray(route.callbacks[0]?._routes)
+    );
+    const missed = routers.filter(({ route }) => !route._walkedInto);
+    if (missed.length > 0) {
+        console.log(`\n${missed.length} mounted router(s) the compiler did not walk into:\n`);
+        for (const { route, full } of missed) {
+            console.log(`  ${(full || "/").padEnd(40)}${route._whyGeneric ?? "it was not eligible"}`);
+        }
+    }
+
+    const middleware = mounts.length - routers.length;
+    if (middleware > 0) {
+        console.log(
+            `\n${middleware} middleware in front of them. Every request walks the ones whose path it` +
+                ` matches,\nand a compiled route walks them from a list worked out at startup rather than by matching.`
+        );
+    }
+
+    printSummary(routes, native, declarative);
+
+    console.log(
+        "\nA route answered by µWS is matched in C++ and reaches javascript with its chain already\n" +
+            "known. One that fell back is matched here, in order, the way Express does it: correct\n" +
+            "either way, and the reason is printed so it can be changed if it is worth changing.\n" +
+            "The server was not started and its listen callback was not run."
+    );
+}
+
 /**
  * @param {string[]} argv
  */
@@ -268,13 +553,18 @@ function main(argv) {
         printDifferences();
         return 0;
     }
+    if (command === "profile") {
+        return profile(argv.slice(1));
+    }
     if (command !== "migrate") {
         console.log(`Usage:
-  npx ${TO} migrate [dir]    rewrite require("${FROM}") and import from "${FROM}" to "${TO}"
-  npx ${TO} differences      print what behaves differently, without changing anything
+  npx ${TO} migrate [dir]      rewrite require("${FROM}") and import from "${FROM}" to "${TO}"
+  npx ${TO} profile [entry]    load an application without listening and print what compiling
+                               its routes decided, route by route
+  npx ${TO} differences        print what behaves differently, without changing anything
 
 Options:
-  --dry-run                  say what would change and change nothing`);
+  --dry-run                    migrate: say what would change and change nothing`);
         return command ? 1 : 0;
     }
 
@@ -363,7 +653,14 @@ function printDifferences() {
 }
 
 if (require.main === module) {
-    process.exitCode = main(process.argv.slice(2));
+    const code = main(process.argv.slice(2));
+    if (process.argv[2] === "profile") {
+        // profile loaded somebody's application, and loading it may have opened a database handle,
+        // a timer or a µWS app of its own. None of that is ours to unwind, and there is nothing
+        // left to print. Only here, so the command itself stays a function a test can call
+        process.exit(code);
+    }
+    process.exitCode = code;
 }
 
-module.exports = { main, findSpecifiers, collectFiles, DIFFERENCES };
+module.exports = { main, findSpecifiers, collectFiles, findEntry, collectRoutes, profile, DIFFERENCES };

package/src/declarative.js

@@ -1,3 +1,22 @@
+/*
+Copyright 2024 dimden.dev
+Copyright 2026 Nigro Simone
+
+This file is derived from Ultimate Express and has been modified.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
 const acorn = require("acorn");
 const { stringify, withDefaultCharset, withUtf8Charset } = require("./utils.js");
 // H3App, DeclarativeResponse and _cfg all exist at runtime but are missing from the

package/src/index.js

@@ -2,6 +2,8 @@
 Copyright 2024 dimden.dev
 Copyright 2026 Nigro Simone
 
+This file is derived from Ultimate Express and has been modified.
+
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

package/src/middlewares.js

@@ -2,6 +2,8 @@
 Copyright 2024 dimden.dev
 Copyright 2026 Nigro Simone
 
+This file is derived from Ultimate Express and has been modified.
+
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
@@ -24,7 +26,7 @@ const qs = require("qs");
 const parseQuery = require("./parse-query.js");
 const { kGetSafe } = require("./usage.js");
 const { AsyncResource } = require("async_hooks");
-const { fastQueryParse, NullObject, asStatError, httpError, memoizeByString } = require("./utils.js");
+const { fastQueryParse, NullObject, asStatError, httpError, memoizeByString, containsDotFile } = require("./utils.js");
 
 // largest content-length we will allocate a body buffer for up front. above this the body is
 // collected chunk by chunk instead, so a declared-but-unsent body cannot pin more memory than a
@@ -309,9 +311,13 @@ function serveStatic(root, options) {
 
         const iq = req.url.indexOf("?");
         let url;
+        // the path as it was written, before decoding: whether it names a directory is decided on
+        // this and not on what the escapes turn into, which is how send decides it. "/a/%2F" asks
+        // for a file called "/" inside "a", and not for the index of a directory
+        const rawPath = iq !== -1 ? req.url.substring(0, iq) : req.url;
 
         try {
-            url = decodeURIComponent(iq !== -1 ? req.url.substring(0, iq) : req.url);
+            url = decodeURIComponent(rawPath);
         } catch (e) {
             // 400 and not 404: send answers a path it cannot decode with a Bad Request, since
             // nothing was asked for that could be missing
@@ -320,8 +326,27 @@ function serveStatic(root, options) {
                 return next(httpError(400));
             } else return next();
         }
+        // A decoded NUL is a bad request and not a missing file, which is how send reads it too.
+        // Without this the byte reaches fs, and what comes back is node's own complaint with the
+        // absolute path of the root inside it, so a request could ask the server where it lives.
+        if (url.indexOf("\0") !== -1) {
+            if (!options.fallthrough) {
+                res.status(400);
+                return next(httpError(400));
+            } else return next();
+        }
         let _path = url;
         const fullpath = path.resolve(path.join(root, url));
+        // What serve-static hands send is this path, except that a bare "/" under a mount the
+        // request did not write with one becomes "": without that rule a mount whose root is a file
+        // would ask the disk for a directory and could never answer at all.
+        //
+        // Send then stats `normalize(join(root, path))`, and both of those keep a trailing
+        // separator where `resolve` takes it off. The separator is not decoration: the disk refuses
+        // a file that is asked for as a directory, and the name inside the error carries it, which
+        // is what an error handler prints when fallthrough is off.
+        const mountRelative = rawPath === "/" && !req.endsWithSlash ? "" : url;
+        const statTarget = mountRelative.endsWith("/") && !fullpath.endsWith(path.sep) ? fullpath + path.sep : fullpath;
         if (root && !fullpath.startsWith(path.resolve(root))) {
             if (!options.fallthrough) {
                 res.status(403);
@@ -329,19 +354,55 @@ function serveStatic(root, options) {
             } else return next();
         }
 
+        // Before the stat, because send judges the path before it looks at the disk: a hidden
+        // segment anywhere in a path that does not exist answers what the dotfiles rule says and
+        // not the ENOENT the disk would have given. sendFile applies the same rule below, and
+        // reaches it only for paths that do exist.
+        // normalized first, as send normalizes before it judges: a ".." segment is not a hidden
+        // file, and resolving it away is what tells the two apart
+        if (containsDotFile(path.normalize(url).split(/[\\/]/))) {
+            const refusal = options.dotfiles === "deny" ? 403 : options.dotfiles === "allow" ? 0 : 404;
+            if (refusal !== 0 && !(options.dotfiles === "ignore_files" && !path.basename(url).startsWith("."))) {
+                if (!options.fallthrough) {
+                    res.status(refusal);
+                    return next(httpError(refusal));
+                }
+                return next();
+            }
+        }
+
         let stat;
         try {
-            stat = fs.statSync(fullpath);
+            stat = fs.statSync(statTarget);
         } catch (err) {
+            // the one to report when nothing is found: send hands each failed attempt to the next
+            // one and reports whichever came last, so an extensions option that also missed names
+            // the file it looked for and not the bare path
+            let statError = err;
+            // a path written with a trailing slash asks for a directory, and send answers that by
+            // looking for the index inside it. With nothing there, the file it names is that
+            // index and not the directory that does not exist either
+            if (rawPath.endsWith("/") && options.index) {
+                try {
+                    fs.statSync(path.join(fullpath, options.index));
+                } catch (indexError) {
+                    statError = indexError;
+                }
+            }
             const ext = path.extname(fullpath);
             let i = 0;
-            if (ext === "" && options.extensions) {
+            // a path that resolves to a directory gets no extension hung off it. The test is on the
+            // decoded url and not on fullpath, because resolve() has already taken the trailing
+            // separator off that one, and not on the raw path either: send tries the extension on
+            // what the escapes decoded to, while it looks for an index on the path as written
+            if (ext === "" && !url.endsWith("/") && options.extensions) {
                 while (i < options.extensions.length) {
                     try {
                         stat = fs.statSync(fullpath + "." + options.extensions[i]);
                         _path = url + "." + options.extensions[i];
                         break;
-                    } catch (err) {
+                    } catch (extensionError) {
+                        statError = extensionError;
                         i++;
                     }
                 }
@@ -353,7 +414,7 @@ function serveStatic(root, options) {
                     // error handler with its errno, code, syscall and path still on it, and an
                     // error handler doing res.send(err) sends those as JSON. Passing the string
                     // sent an HTML page instead.
-                    return next(asStatError(err));
+                    return next(asStatError(statError));
                 } else return next();
             }
         }

package/src/node-shim.js

@@ -100,8 +100,10 @@ class NodeHttpRequest {
         const url = req.url || "/";
         const question = url.indexOf("?");
         this._path = question === -1 ? url : url.slice(0, question);
-        // uWS answers the query without its "?", and an empty string when there is none
-        this._query = question === -1 ? "" : url.slice(question + 1);
+        // uWS answers the query without its "?", undefined when the url carries none and "" when
+        // it carries an empty one, and req.url keeps that difference
+        /** @type {string|undefined} */
+        this._query = question === -1 ? undefined : url.slice(question + 1);
     }
 
     /** The path, without the query, which is what uWS answers here. */
@@ -109,7 +111,7 @@ class NodeHttpRequest {
         return this._path;
     }
 
-    /** The query string without its "?", empty when there is none, as uWS reports it. */
+    /** The query string without its "?", undefined when the url has none, as uWS reports it. */
     getQuery() {
         return this._query;
     }

package/src/options.d.ts

@@ -1,3 +1,19 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
 // The option bags the file-serving and body-parsing paths take, written once and referenced from
 // the JSDoc of the functions that read them. They live in a declaration file rather than as
 // @typedef blocks in the sources because those sources export classes, and a typedef hanging off

package/src/parse-query.js

@@ -1,8 +1,25 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
 "use strict";
 
 /*
-The parser from fast-querystring 1.1.x (MIT, Copyright (c) Yagiz Nizipli,
-https://github.com/anonrig/fast-querystring), vendored for one change: the result is a bare
+The parser from fast-querystring 1.1.x (https://github.com/anonrig/fast-querystring), Copyright
+(c) 2022 Yagiz Nizipli, MIT, whose permission notice is reproduced in full in NOTICE at the root
+of this package. Vendored for one change: the result is a bare
 Object.create(null) instead of the library's Empty-constructor trick. The trick is faster to
 construct but node inspects it as "Empty <[Object: null prototype] {}>", where Express shows
 "[Object: null prototype]", and matching that used to cost an Object.assign copy of every parse