fulmine.js 5.2.0 → 5.3.0

package/src/types.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.
+*/
+
 declare module "fulmine.js" {
     import e from "express";
     import uWS from "uWebSockets.js";

package/src/usage.js

@@ -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.
+*/
+
 "use strict";
 
 const acorn = require("acorn");

package/src/utils.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
@@ -26,6 +28,12 @@ const { Stats } = require("fs");
 
 const EMPTY_REGEX = new RegExp(``);
 
+// what express hands qs for a query string. allowPrototypes keeps a key named "constructor" or
+// "toString" instead of dropping it, and it is safe here for the reason it is safe there: the
+// result below sits on a null prototype, so such a key is inert data. A caller with options of its
+// own, the extended body parser, passes them and does not get these.
+const QUERY_QS_OPTIONS = { allowPrototypes: true };
+
 /**
  * Parses a query string the way the "extended" parser is expected to, which means qs and its
  * support for nested keys, but without paying for qs on the strings that cannot need it. A short
@@ -45,12 +53,29 @@ function fastQueryParse(query, options) {
         return Object.create(null);
     }
     if (len <= 128) {
-        if (!query.includes("[") && !query.includes("%5B") && !query.includes(".") && !query.includes("%2E")) {
+        // An empty name is the other place the two disagree: "=v" and "a=1&=2" are a pair under
+        // the empty key to fast-querystring, and nothing at all to qs. A query carrying one goes
+        // the slow way, which is what makes the shortcut above safe to take for the rest.
+        if (
+            !query.includes("[") &&
+            !query.includes("%5B") &&
+            !query.includes(".") &&
+            !query.includes("%2E") &&
+            query.charCodeAt(0) !== 0x3d &&
+            !query.includes("&=")
+        ) {
             // already on a bare null prototype, no copy needed, see parse-query.js
-            return parseQuery(query);
+            const parsed = parseQuery(query);
+            // qs drops a "__proto__" key whatever allowPrototypes says, and a null prototype makes
+            // this one an ordinary own property rather than the setter, so reading it is a plain
+            // load and the encoded spelling is covered too: the name is decoded before it lands
+            if (parsed.__proto__ !== undefined) {
+                delete parsed.__proto__;
+            }
+            return parsed;
         }
     }
-    return Object.assign(Object.create(null), qs.parse(query, options));
+    return Object.assign(Object.create(null), qs.parse(query, options ?? QUERY_QS_OPTIONS));
 }
 
 /**
@@ -64,6 +89,69 @@ function removeDuplicateSlashes(path) {
     return path.replace(/\/{2,}/g, "/");
 }
 
+// What path-to-regexp takes as a parameter name, which is a javascript identifier: /:café and
+// /:año are names to express and were a dead route here, because \w stops at ASCII. A named
+// capture group accepts the same spellings, so the compiled pattern still carries the name.
+const ID_START = /[$_\p{ID_Start}]/u;
+// the two joiners are written as escapes on purpose: as themselves they are invisible here
+const ID_CONTINUE = /[$\u200c\u200d\p{ID_Continue}]/u;
+
+/**
+ * Reads a parameter name out of a pattern. Walks code points rather than code units, so a name
+ * starting outside the basic plane is read whole instead of as half a surrogate pair.
+ *
+ * @param {string} text the pattern, or the contents of one optional group
+ * @param {number} from the index just past the ":" or the "*"
+ * @returns {{name: string, next: number}} the name, empty when there is none, and where it ended
+ */
+function readParamName(text, from) {
+    let i = from;
+    let name = "";
+    while (i < text.length) {
+        const char = String.fromCodePoint(/** @type {number} */ (text.codePointAt(i)));
+        if (!(name === "" ? ID_START : ID_CONTINUE).test(char)) {
+            break;
+        }
+        name += char;
+        i += char.length;
+    }
+    return { name, next: i };
+}
+
+/**
+ * Escapes a string for use inside a regular expression, as path-to-regexp escapes it.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeRe(str) {
+    return str.replace(/[.+*?^${}()[\]|/\\]/g, "\\$&");
+}
+
+/**
+ * A character class that matches anything except what these two strings could start, which is how
+ * path-to-regexp stops a capture from backtracking over the literal text that follows it. Ported
+ * from its negate(), so the patterns compiled here agree with the ones express matches.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {string}
+ */
+function negate(a, b) {
+    if (b.length > a.length) {
+        return negate(b, a);
+    }
+    if (a === b) {
+        b = "";
+    }
+    if (b.length > 1) {
+        return `(?:(?!${escapeRe(a)}|${escapeRe(b)})[^])`;
+    }
+    if (a.length > 1) {
+        return `(?:(?!${escapeRe(a)})[^${escapeRe(b)}])`;
+    }
+    return `[^${escapeRe(a + b)}]`;
+}
+
 // the opening of a named capture group, which is how the parameter names are read back out of a
 // finished pattern
 const NAMED_GROUP = /\(\?<([^>]+)>/g;
@@ -73,7 +161,7 @@ const NAMED_GROUP = /\(\?<([^>]+)>/g;
  * into an array. Here and not on the regex itself, because one own property takes a RegExp off V8's
  * fast path: replace() went from 37ns to 808ns and test() from 22ns to 78ns.
  *
- * @typedef {{wildcardNames: string[], paramNames: string[], isWildcard: boolean[]}} PatternMeta
+ * @typedef {{wildcardNames: string[], paramNames: string[], outputNames: string[], isWildcard: boolean[]}} PatternMeta
  */
 const patternMeta = new WeakMap();
 
@@ -103,7 +191,7 @@ function getPatternMeta(pattern) {
  * 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.
  */
-function patternToRegex(pattern, isPrefix = false, caseSensitive = true) {
+function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict = false) {
     if (pattern instanceof RegExp) {
         // the application's own RegExp matches as written, whatever the routing setting says,
         // which is what express does with one
@@ -117,15 +205,122 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true) {
     let i = 0;
     const len = pattern.length;
     const wildcardNames = [];
+    // 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 uniqueGroupName = (name) => {
+        if (!groupOutputName.has(name)) {
+            groupOutputName.set(name, name);
+            return name;
+        }
+        let n = 2;
+        while (groupOutputName.has(name + "$" + n)) n++;
+        const group = name + "$" + n;
+        groupOutputName.set(group, name);
+        return group;
+    };
     // whether the token just emitted was a :parameter, which decides how greedy the next
     // optional group is allowed to be. see the comment where it is read
     let lastTokenWasParam = false;
+    // 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
+    let backtrack = "";
+    let wildcardBacktrack = "";
+    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. */
+    const literal = (text) => {
+        backtrack += text;
+        if (lastCaptureWasWildcard) {
+            wildcardBacktrack += text;
+        }
+        if (text.includes("/")) {
+            wildcardInSegment = false;
+            paramInSegment = false;
+        }
+    };
+    /**
+     * Whether a wildcard is still to come in the segment being written, which makes the parameters
+     * before it give ground so that it has something left to match.
+     *
+     * @param {number} from where to look from
+     * @returns {boolean}
+     */
+    const wildcardLaterInSegment = (from) => {
+        for (let j = from; j < len; j++) {
+            const c = pattern[j];
+            if (c === "\\") {
+                j++;
+            } else if (c === "/") {
+                return false;
+            } else if (c === "*") {
+                return true;
+            }
+        }
+        return false;
+    };
+    /**
+     * The literal text written immediately after this point, which is what the capture before it
+     * must not swallow.
+     *
+     * @param {number} from
+     * @returns {string}
+     */
+    const textAfter = (from) => {
+        let out = "";
+        for (let j = from; j < len; j++) {
+            const c = pattern[j];
+            if (c === "\\") {
+                out += pattern[++j] ?? "";
+                continue;
+            }
+            if (":*{}".includes(c)) {
+                break;
+            }
+            out += c;
+        }
+        return out;
+    };
+    /** A :parameter ends the run of text and stops the wildcard one from growing. */
+    const noteParam = () => {
+        backtrack = "";
+        lastCaptureWasWildcard = false;
+        paramInSegment = true;
+        lastTokenWasParam = true;
+    };
+    /**
+     * What a wildcard is allowed to match here, and the bookkeeping that goes with emitting one.
+     * The first wildcard of a path takes everything; one sharing a segment with an earlier wildcard
+     * stops at the text between them; and one in a later segment is held to a single segment.
+     *
+     * @returns {string} the body of the capture group
+     */
+    const wildcardClass = () => {
+        const body = wildcardInSegment
+            ? `${negate(backtrack, "")}+`
+            : wildcardBacktrack
+              ? `${negate(wildcardBacktrack, "")}+|${negate("/", "")}+`
+              : "[^]+";
+        backtrack = "";
+        wildcardBacktrack = "";
+        lastCaptureWasWildcard = true;
+        wildcardInSegment = true;
+        return body;
+    };
 
     while (i < len) {
         const ch = pattern[i];
 
         if (ch === "\\" && i + 1 < len) {
             regexPattern += "\\" + pattern[i + 1];
+            literal(pattern[i + 1]);
             i += 2;
             continue;
         }
@@ -134,16 +329,17 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true) {
         // boundary, so /te*st is literal "/te" followed by a wildcard named "st"
         if (ch === "*") {
             const at = i;
-            i++;
-            let name = "";
-            while (i < len && /\w/.test(pattern[i])) {
-                name += pattern[i++];
-            }
+            const splat = readParamName(pattern, i + 1);
+            const name = splat.name;
+            i = splat.next;
             if (!name) {
-                throw new Error(`Missing parameter name at index ${at}: ${pattern}`);
+                throw new Error(
+                    `Missing parameter name at index ${at + 1}: ${pattern}; visit https://git.new/pathToRegexpError for info`
+                );
             }
-            wildcardNames.push(name);
-            regexPattern += `(?<${name}>[^]+)`;
+            const splatGroup = uniqueGroupName(name);
+            wildcardNames.push(splatGroup);
+            regexPattern += `(?<${splatGroup}>${wildcardClass()})`;
             lastTokenWasParam = false;
             continue;
         }
@@ -160,14 +356,23 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true) {
                 if (!name) {
                     throw new Error(`Wildcard must be named in Express 5: use {*splat} (in "${pattern}")`);
                 }
-                wildcardNames.push(name);
+                const optionalGroup = uniqueGroupName(name);
+                wildcardNames.push(optionalGroup);
                 if (regexPattern.endsWith("/") || regexPattern.endsWith("\\/")) {
-                    // the slash belongs to the optional part, otherwise /{*splat} would not match /
+                    // the slash is part of the alternative rather than optional on its own: a
+                    // mount at /a/{*w} answers /a/ and /a/x, and not /a, which is what express
+                    // compiles it to
                     regexPattern = regexPattern.slice(0, regexPattern.endsWith("\\/") ? -2 : -1);
-                    regexPattern += `(?:/(?<${name}>.+))?/?`;
+                    // under strict routing the slash is part of the alternative, so /a/{*w}
+                    // answers /a/ and /a/x and not /a. Without it express loosens the pattern and
+                    // allows a trailing slash instead, which is the shape the path arrives in here
+                    regexPattern += strict
+                        ? `(?:/(?<${optionalGroup}>${wildcardClass()})|/)`
+                        : `(?:/(?<${optionalGroup}>${wildcardClass()}))?/?`;
                 } else {
-                    regexPattern += `(?<${name}>.*)`;
+                    regexPattern += `(?<${optionalGroup}>${wildcardClass()}|)`;
                 }
+                lastTokenWasParam = false;
                 continue;
             }
 
@@ -197,12 +402,10 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true) {
             let gi = 0;
             while (gi < groupContent.length) {
                 if (groupContent[gi] === ":") {
-                    gi++;
-                    let paramName = "";
-                    while (gi < groupContent.length && /\w/.test(groupContent[gi])) {
-                        paramName += groupContent[gi++];
-                    }
-                    groupRegex += `(?<${paramName}>${groupParamClass})`;
+                    const inner = readParamName(groupContent, gi + 1);
+                    const paramName = inner.name;
+                    gi = inner.next;
+                    groupRegex += `(?<${uniqueGroupName(paramName)}>${groupParamClass})`;
                 } else if (groupContent[gi] === ".") {
                     groupRegex += "\\.";
                     gi++;
@@ -215,22 +418,43 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true) {
                 }
             }
             regexPattern += `(?:${groupRegex})?`;
+            literal(groupContent);
             lastTokenWasParam = false;
             continue;
         }
 
         if (ch === ":") {
-            i++;
-            let name = "";
-            while (i < len && /\w/.test(pattern[i])) {
-                name += pattern[i++];
-            }
+            const named = readParamName(pattern, i + 1);
+            const name = named.name;
+            i = named.next;
             if (!name) {
-                throw new Error(`Missing parameter name at index ${i - 1}: ${pattern}`);
+                throw new Error(
+                    `Missing parameter name at index ${i}: ${pattern}; visit https://git.new/pathToRegexpError for info`
+                );
             }
             // a following optional group needs room to match, so the parameter gives ground
-            regexPattern += i < len && pattern[i] === "{" ? `(?<${name}>[^/]+?)` : `(?<${name}>[^/]+)`;
-            lastTokenWasParam = true;
+            const paramGroup = uniqueGroupName(name);
+            // How much of its segment a parameter may take, which path-to-regexp decides by what
+            // else shares the segment with it. Alone it takes everything up to the next slash; with
+            // a wildcard beside it, before or after, it stops at the text that separates the two,
+            // so the wildcard has something left to match; and a second parameter in the segment
+            // may also be exactly that separating text, which is the alternative below.
+            let head;
+            let alternative = "";
+            if (wildcardInSegment) {
+                head = negate("/", backtrack);
+            } else if (wildcardLaterInSegment(i)) {
+                head = negate("/", textAfter(i));
+            } else if (paramInSegment) {
+                head = negate("/", backtrack);
+                alternative = "|" + escapeRe(backtrack);
+            } else {
+                head = "[^/]";
+            }
+            // a following optional group needs room to match, so the parameter gives ground
+            const lazy = i < len && pattern[i] === "{" ? "?" : "";
+            regexPattern += `(?<${paramGroup}>${head}+${lazy}${alternative})`;
+            noteParam();
             continue;
         }
 
@@ -246,19 +470,24 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true) {
         } else {
             regexPattern += ch;
         }
+        literal(ch);
         lastTokenWasParam = false;
         i++;
     }
 
-    const regex = /** @type {PathRegExp} */ (
-        new RegExp(`^${regexPattern}${isPrefix ? "(?=$|/)" : "$"}`, caseSensitive ? "" : "i")
-    );
+    // Without strict routing express allows one trailing slash at the end of the pattern
+    // rather than taking it off the path, which is the only way /things and /things/ can be the
+    // same route while // and /things/ stay different paths. A mount ends at a segment boundary
+    // instead, and the slash after it belongs to what follows.
+    const ending = isPrefix ? "(?=$|/)" : strict ? "$" : "/?$";
+    const regex = /** @type {PathRegExp} */ (new RegExp(`^${regexPattern}${ending}`, caseSensitive ? "" : "i"));
     // read back out of the finished pattern, so the list cannot disagree with the regex. Asking for
     // each name in turn beats walking match.groups with for-in: 176ns against 349
     const paramNames = [...regexPattern.matchAll(NAMED_GROUP)].map((m) => m[1]);
     patternMeta.set(regex, {
         wildcardNames,
         paramNames,
+        outputNames: paramNames.map((name) => groupOutputName.get(name) ?? name),
         isWildcard: paramNames.map((name) => wildcardNames.includes(name))
     });
     return regex;
@@ -307,7 +536,7 @@ function canBeOptimized(pattern) {
 
 // a parameter that is the whole segment, which is the only shape µWS matches the same way Express
 // does. "/flights/:from-:to" is one segment to µWS and two parameters to Express.
-const WHOLE_SEGMENT_PARAM = /^:\w+$/;
+const WHOLE_SEGMENT_PARAM = /^:[$_\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*$/u;
 
 /**
  * Whether µWS's own router matches this path exactly as Express would, parameters included.
@@ -704,7 +933,9 @@ function decodeParam(value) {
     try {
         return decodeURIComponent(value);
     } catch {
-        const err = /** @type {any} */ (new Error(`Failed to decode param '${value}'`));
+        // a URIError, not an Error: express throws what decodeURIComponent threw, so an error
+        // handler written as `err instanceof URIError` has to keep working here
+        const err = /** @type {any} */ (new URIError(`Failed to decode param '${value}'`));
         err.status = 400;
         err.statusCode = 400;
         err.expose = true;

package/src/view.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/websocket.js

@@ -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.
+*/
+
 "use strict";
 
 const { canBeOptimizedWithParams, decodeParam, NullObject } = require("./utils.js");

package/src/worker.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