fulmine.js 5.0.0-rc.1

package/src/utils.js

@@ -0,0 +1,993 @@
+/*
+Copyright 2024 dimden.dev
+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.
+*/
+
+const mime = require("mime-types");
+const path = require("path");
+const proxyaddr = require("proxy-addr");
+const qs = require("qs");
+const querystring = require("fast-querystring");
+const crypto = require("crypto");
+const statuses = require("statuses");
+const { Stats } = require("fs");
+
+const EMPTY_REGEX = new RegExp(``);
+
+/**
+ * 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
+ * query with no bracket and no dot goes through fast-querystring instead, which is several times
+ * quicker and produces the same answer for that shape.
+ *
+ * @param {string} query the query string, without the leading "?"
+ * @param {object} [options] passed through to qs when it is used
+ * @returns {Record<string, any>} null-prototype, so a key from the query cannot reach Object.prototype
+ */
+function fastQueryParse(query, options) {
+    // the result keeps a null prototype, which is why req.query prints as "[Object: null
+    // prototype] {}". Spreading it into a plain object would put Object.prototype keys back
+    // within reach of a query string.
+    const len = query.length;
+    if (len === 0) {
+        return Object.create(null);
+    }
+    if (len <= 128) {
+        if (!query.includes("[") && !query.includes("%5B") && !query.includes(".") && !query.includes("%2E")) {
+            return Object.assign(Object.create(null), querystring.parse(query));
+        }
+    }
+    return Object.assign(Object.create(null), qs.parse(query, options));
+}
+
+/**
+ * Collapses runs of slashes, so //a///b reads as /a/b. Express does the same before matching, and
+ * without it a path could dodge a route by being written with an extra slash.
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+function removeDuplicateSlashes(path) {
+    return path.replace(/\/{2,}/g, "/");
+}
+
+// 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;
+
+/**
+ * What a compiled pattern captures: the names in order, and which of them are wildcards to split
+ * 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
+ */
+const patternMeta = new WeakMap();
+
+/**
+ * What patternToRegex worked out about a pattern, or undefined for a RegExp the application wrote
+ * itself.
+ * @param {RegExp} pattern
+ * @returns {PatternMeta|undefined}
+ */
+function getPatternMeta(pattern) {
+    return patternMeta.get(pattern);
+}
+
+/**
+ * A compiled path pattern. A plain RegExp, deliberately.
+ * @typedef {RegExp} PathRegExp
+ */
+
+/**
+ * Compiles a path into a regex, following path-to-regexp v8:
+ *   - :param          a named parameter, one segment
+ *   - /*splat         a named wildcard, one or more segments, captured as an array
+ *   - {...}           an optional group
+ *   - \x              an escaped literal
+ *
+ * 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.
+ */
+function patternToRegex(pattern, isPrefix = false) {
+    if (pattern instanceof RegExp) {
+        return pattern;
+    }
+    if (isPrefix && pattern === "") {
+        return EMPTY_REGEX;
+    }
+
+    let regexPattern = "";
+    let i = 0;
+    const len = pattern.length;
+    const wildcardNames = [];
+    // 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;
+
+    while (i < len) {
+        const ch = pattern[i];
+
+        if (ch === "\\" && i + 1 < len) {
+            regexPattern += "\\" + pattern[i + 1];
+            i += 2;
+            continue;
+        }
+
+        // *splat: one or more characters, slashes included. It is not anchored to a segment
+        // 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++];
+            }
+            if (!name) {
+                throw new Error(`Missing parameter name at index ${at}: ${pattern}`);
+            }
+            wildcardNames.push(name);
+            regexPattern += `(?<${name}>[^]+)`;
+            lastTokenWasParam = false;
+            continue;
+        }
+
+        if (ch === "{") {
+            // {*splat}: zero or more segments, so it also matches the mount point
+            if (pattern[i + 1] === "*") {
+                i += 2;
+                let name = "";
+                while (i < len && pattern[i] !== "}") {
+                    name += pattern[i++];
+                }
+                i++;
+                if (!name) {
+                    throw new Error(`Wildcard must be named in Express 5: use {*splat} (in "${pattern}")`);
+                }
+                wildcardNames.push(name);
+                if (regexPattern.endsWith("/") || regexPattern.endsWith("\\/")) {
+                    // the slash belongs to the optional part, otherwise /{*splat} would not match /
+                    regexPattern = regexPattern.slice(0, regexPattern.endsWith("\\/") ? -2 : -1);
+                    regexPattern += `(?:/(?<${name}>.+))?/?`;
+                } else {
+                    regexPattern += `(?<${name}>.*)`;
+                }
+                continue;
+            }
+
+            // optional group, which may itself contain a parameter: {.:ext}, {/:page}
+            i++;
+            let groupContent = "";
+            let braceDepth = 1;
+            while (i < len && braceDepth > 0) {
+                if (pattern[i] === "{") braceDepth++;
+                else if (pattern[i] === "}") {
+                    braceDepth--;
+                    if (braceDepth === 0) break;
+                }
+                groupContent += pattern[i++];
+            }
+            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.
+            const separator = lastTokenWasParam && groupContent[0] && groupContent[0] !== ":" ? groupContent[0] : "";
+            const groupParamClass = `[^/${separator.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}]+`;
+
+            let groupRegex = "";
+            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})`;
+                } else if (groupContent[gi] === ".") {
+                    groupRegex += "\\.";
+                    gi++;
+                } else if (groupContent[gi] === "/") {
+                    groupRegex += "/";
+                    gi++;
+                } else {
+                    groupRegex += groupContent[gi].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                    gi++;
+                }
+            }
+            regexPattern += `(?:${groupRegex})?`;
+            lastTokenWasParam = false;
+            continue;
+        }
+
+        if (ch === ":") {
+            i++;
+            let name = "";
+            while (i < len && /\w/.test(pattern[i])) {
+                name += pattern[i++];
+            }
+            if (!name) {
+                throw new Error(`Missing parameter name at index ${i - 1}: ${pattern}`);
+            }
+            // a following optional group needs room to match, so the parameter gives ground
+            regexPattern += i < len && pattern[i] === "{" ? `(?<${name}>[^/]+?)` : `(?<${name}>[^/]+)`;
+            lastTokenWasParam = true;
+            continue;
+        }
+
+        // these have no meaning in a path, and the route is refused rather than matching them
+        // literally: a path that quietly stops matching is worse than one that fails at startup.
+        // Escape them to use them as literals.
+        if ("?+()[]!".includes(ch)) {
+            throw new Error(`Unexpected ${ch} at index ${i}: ${pattern}`);
+        }
+
+        if (".^$|}".includes(ch)) {
+            regexPattern += "\\" + ch;
+        } else {
+            regexPattern += ch;
+        }
+        lastTokenWasParam = false;
+        i++;
+    }
+
+    const regex = /** @type {PathRegExp} */ (new RegExp(`^${regexPattern}${isPrefix ? "(?=$|/)" : "$"}`));
+    // 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,
+        isWildcard: paramNames.map((name) => wildcardNames.includes(name))
+    });
+    return regex;
+}
+
+/**
+ * Whether a path has anything in it that a string comparison cannot answer, which is a parameter,
+ * a wildcard or an optional group. A regular expression is already compiled, so it needs nothing.
+ *
+ * @param {string|RegExp} pattern
+ * @returns {boolean}
+ */
+function needsConversionToRegex(pattern) {
+    if (pattern instanceof RegExp) {
+        return false;
+    }
+
+    return pattern.includes("*") || pattern.includes(":") || pattern.includes("{");
+}
+
+/**
+ * Whether a path is a plain literal, which is what makes a route eligible for the native uWS
+ * router. Not simply the opposite of needsConversionToRegex: a RegExp answers false to both, since
+ * it needs no conversion and cannot be optimized either.
+ *
+ * @param {string|RegExp} pattern
+ * @returns {boolean}
+ */
+function canBeOptimized(pattern) {
+    if (pattern instanceof RegExp) {
+        return false;
+    }
+    return !pattern.includes("*") && !pattern.includes("{") && !pattern.includes(":");
+}
+
+// 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+$/;
+
+/**
+ * Whether µWS's own router matches this path exactly as Express would, parameters included.
+ *
+ * µWS matches `:name` against one non-empty segment, as Express does, and has nothing for a v5
+ * wildcard or an optional group. A parameter counts only when it is the whole segment: Express
+ * matches `/flights/:from-:to` inside a segment and µWS does not.
+ *
+ * @param {string|RegExp} pattern
+ * @returns {boolean}
+ */
+function canBeOptimizedWithParams(pattern) {
+    if (pattern instanceof RegExp) {
+        return false;
+    }
+    if (/[*{}()[\]?+\\]/.test(pattern)) {
+        return false;
+    }
+    if (!pattern.includes(":")) {
+        return true;
+    }
+    for (const segment of pattern.split("/")) {
+        if (segment.includes(":") && !WHOLE_SEGMENT_PARAM.test(segment)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Whether two paths could both match the same request.
+ *
+ * Only asked about paths µWS could match itself, so the answer is structural: the same number of
+ * segments, and no position where two different literals meet. `/orders/:id` and `/invoices/:id`
+ * cannot both match, `/users/:id` and `/users/me` can. Anything else is not asked, and the caller
+ * reads "do not know" as yes.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function pathsCanOverlap(a, b) {
+    const left = a.split("/");
+    const right = b.split("/");
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let i = 0; i < left.length; i++) {
+        if (left[i] === right[i]) {
+            continue;
+        }
+        // a parameter matches whatever is in that segment, so only two different literals settle it
+        if (left[i].charCodeAt(0) === 0x3a || right[i].charCodeAt(0) === 0x3a) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+
+/**
+ * Splits one entry of an Accept-style header into its value and its parameters, with q pulled out
+ * as the quality since that is the one every caller wants.
+ *
+ * @param {string} str a single entry, such as "text/html;q=0.8;level=1"
+ * @returns {{value: string, quality: number, params: Record<string, string>}}
+ */
+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: {} };
+
+    while (index < length) {
+        const splitIndex = str.indexOf("=", index);
+        if (splitIndex === -1) break;
+
+        const colonIndex = str.indexOf(";", index);
+        const endIndex = colonIndex === -1 ? length : colonIndex;
+
+        if (splitIndex > endIndex) {
+            index = str.lastIndexOf(";", splitIndex - 1) + 1;
+            continue;
+        }
+
+        const key = str.slice(index, splitIndex).trim();
+        const value = str.slice(splitIndex + 1, endIndex).trim();
+
+        if (key === "q") {
+            ret.quality = parseFloat(value);
+        } else {
+            ret.params[key] = value;
+        }
+
+        index = endIndex + 1;
+    }
+
+    return ret;
+}
+
+// How many answers a memo keeps before it starts over.
+//
+// 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.
+const MEMO_LIMIT = 512;
+
+/**
+ * A pure function of one string, with its answers kept.
+ *
+ * The wrapped function must never answer undefined, since that is what the cache reads as a miss.
+ * The mime lookups here answer false for something they do not know, which caches correctly.
+ *
+ * @param {(key: string) => any} fn
+ * @returns {(key: string) => any}
+ */
+function memoizeByString(fn) {
+    const cache = new Map();
+    return function memoized(key) {
+        let hit = cache.get(key);
+        if (hit === undefined) {
+            hit = fn(key);
+            if (cache.size >= MEMO_LIMIT) {
+                cache.clear();
+            }
+            cache.set(key, hit);
+        }
+        return hit;
+    };
+}
+
+// mime.lookup walks the extension and searches the database for it, which for the same "json" on
+// every response is 273 ns to reach the same answer. Kept, it is 6.
+const lookupType = memoizeByString((type) => mime.lookup(type) || "application/octet-stream");
+
+/**
+ * The full content-type an extension stands for, charset included, as res.type() writes it.
+ * @param {string} type an extension, or a media type, which is returned as given
+ * @returns {string}
+ */
+const contentTypeFor = memoizeByString((type) => mime.contentType(type) || "application/octet-stream");
+
+/**
+ * A media type from either spelling: "html" is looked up in the mime database, while anything
+ * containing a slash is already one and is parsed for its parameters.
+ *
+ * @param {string} type an extension or a full media type
+ * @returns {{value: string, params: Record<string, string>}}
+ */
+function normalizeType(type) {
+    // a fresh object every time on purpose: the caller owns params and may write to it
+    return ~type.indexOf("/") ? acceptParams(type) : { value: lookupType(type), params: {} };
+}
+
+/**
+ * JSON.stringify, plus the escaping the "json escape" setting asks for: <, > and & become their
+ * 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} [replacer] the "json replacer" setting
+ * @param {string|number} [spaces] the "json spaces" setting
+ * @param {boolean} [escape] the "json escape" setting
+ * @returns {string}
+ */
+function stringify(value, replacer, spaces, escape) {
+    let json = replacer || spaces ? JSON.stringify(value, replacer, spaces) : JSON.stringify(value);
+
+    if (escape && typeof json === "string") {
+        json = json.replace(/[<>&]/g, function (c) {
+            switch (c.charCodeAt(0)) {
+                case 0x3c:
+                    return "\\u003c";
+                case 0x3e:
+                    return "\\u003e";
+                case 0x26:
+                    return "\\u0026";
+                default:
+                    return c;
+            }
+        });
+    }
+
+    return json;
+}
+
+const defaultSettings = {
+    "jsonp callback name": "callback",
+    env: () => process.env.NODE_ENV ?? "development",
+    etag: "weak",
+    "etag fn": () => createETagGenerator({ weak: true }),
+    "query parser": "simple",
+    "query parser fn": () => querystring.parse,
+    "subdomain offset": 2,
+    "trust proxy": false,
+    views: () => path.join(process.cwd(), "views"),
+    "view cache": () => process.env.NODE_ENV === "production",
+    // off by default, unlike Express, which keeps it for historical reasons. It only tells anyone
+    // asking which framework is running, and every hardening guide says to remove it. Set it back
+    // to true if something depends on it.
+    "x-powered-by": false,
+    "case sensitive routing": true,
+    "declarative responses": true
+};
+
+/**
+ * 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}
+ */
+function compileTrust(val) {
+    if (typeof val === "function") return val;
+
+    if (val === true) {
+        // Support plain true/false
+        return function () {
+            return true;
+        };
+    }
+
+    if (typeof val === "number") {
+        // Support trusting hop count
+        return function (a, i) {
+            return i < val;
+        };
+    }
+
+    if (typeof val === "string") {
+        // Support comma-separated values
+        val = val.split(",").map(function (v) {
+            return v.trim();
+        });
+    }
+
+    return proxyaddr.compile(val || []);
+}
+
+const shownWarnings = new Set();
+/**
+ * Warns once per call site that a method has a newer name, in the format the deprecate package
+ * uses, so the output sits alongside the warnings Express's own dependencies produce. Once per
+ * site rather than once per call: the same line warning on every request would be a flood.
+ *
+ * @param {string} oldMethod
+ * @param {string} newMethod
+ * @param {boolean} [full] print the whole stack rather than the one frame that called it
+ */
+function deprecated(oldMethod, newMethod, full = false) {
+    const err = new Error();
+    // V8 always fills this in for an Error made right here
+    const stack = err.stack ?? "";
+    const pos = full
+        ? stack.split("\n").slice(1).join("\n")
+        : stack.split("\n")[3].trim().split("(").slice(1).join("(").split(")").slice(0, -1).join(")");
+    if (shownWarnings.has(pos)) return;
+    shownWarnings.add(pos);
+    console.warn(
+        `${new Date().toLocaleString("en-UK", {
+            weekday: "short",
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+            hour: "numeric",
+            minute: "numeric",
+            second: "numeric",
+            timeZone: "GMT",
+            timeZoneName: "short"
+        })} fulmine.js deprecated ${oldMethod}: Use ${newMethod} instead at ${pos}`
+    );
+}
+
+/**
+ * findIndex, but resuming from a position. The router walks the same route list many times per
+ * request, each time picking up after the route it just ran, and Array.findIndex has no way to
+ * start anywhere but the beginning.
+ *
+ * @param {any[]} arr
+ * @param {(item: any, index: number, arr: any[]) => boolean} fn
+ * @param {number} [index] where to start
+ * @returns {number} the index, or -1
+ */
+function findIndexStartingFrom(arr, fn, index = 0) {
+    for (let i = index, end = arr.length; i < end; i++) {
+        if (fn(arr[i], i, arr)) {
+            return i;
+        }
+    }
+    return -1;
+}
+
+/**
+ * decodeURIComponent that answers rather than throwing. A malformed escape in a URL is a bad
+ * request and not an exception, so callers check for the sentinel and answer 400.
+ *
+ * @param {string} path
+ * @returns {string|-1} -1 when the path cannot be decoded
+ */
+function decode(path) {
+    try {
+        return decodeURIComponent(path);
+    } catch (err) {
+        return -1;
+    }
+}
+
+/**
+ * A route parameter as the application should see it, which means decoded: `/users/caff%C3%A8`
+ * arrives as "caffè". A percent sequence that will not decode is the client's mistake and becomes a
+ * 400, with the message Express uses.
+ *
+ * @param {string} value
+ * @returns {string}
+ * @throws {any} carrying status 400 when the value cannot be decoded
+ */
+function decodeParam(value) {
+    // the common case, and worth the check: a parameter is usually a number or a word, and
+    // decodeURIComponent is not free
+    if (value.indexOf("%") === -1) {
+        return value;
+    }
+    try {
+        return decodeURIComponent(value);
+    } catch {
+        const err = /** @type {any} */ (new Error(`Failed to decode param '${value}'`));
+        err.status = 400;
+        err.statusCode = 400;
+        err.expose = true;
+        throw err;
+    }
+}
+
+const UP_PATH_REGEXP = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
+
+/**
+ * Whether any segment is a dotfile. A single "." is not one, being the current directory, which is
+ * why the length is checked before the first character.
+ *
+ * @param {string[]} parts the path split on slashes
+ * @returns {boolean}
+ */
+function containsDotFile(parts) {
+    for (let i = 0, len = parts.length; i < len; i++) {
+        const part = parts[i];
+        if (part.length > 1 && part[0] === ".") {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Splits a comma-separated header value into its tokens, trimming the spaces around each. Written
+ * out by hand rather than with split and trim because it runs for every conditional request.
+ *
+ * @param {string} str
+ * @returns {string[]}
+ */
+function parseTokenList(str) {
+    let end = 0;
+    const list = [];
+    let start = 0;
+
+    // gather tokens
+    for (let i = 0, len = str.length; i < len; i++) {
+        switch (str.charCodeAt(i)) {
+            case 0x20 /*   */:
+                if (start === end) {
+                    start = end = i + 1;
+                }
+                break;
+            case 0x2c /* , */:
+                if (start !== end) {
+                    list.push(str.substring(start, end));
+                }
+                start = end = i + 1;
+                break;
+            default:
+                end = i + 1;
+                break;
+        }
+    }
+
+    // final token
+    if (start !== end) {
+        list.push(str.substring(start, end));
+    }
+
+    return list;
+}
+
+/**
+ * An HTTP date as a timestamp, or NaN when it is missing or unreadable. NaN rather than a throw
+ * because every comparison against it is false, which is the answer a bad date should give.
+ *
+ * @param {string|undefined} date
+ * @returns {number}
+ */
+function parseHttpDate(date) {
+    const timestamp = date && Date.parse(date);
+    return typeof timestamp === "number" ? timestamp : NaN;
+}
+
+/**
+ * Whether the request's If-Match or If-Unmodified-Since says the copy the client is acting on is
+ * 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
+ * @returns {boolean}
+ */
+function isPreconditionFailure(req, res) {
+    const match = req.headers["if-match"];
+
+    // if-match
+    if (match) {
+        const etag = res.get("etag");
+        return (
+            !etag ||
+            (match !== "*" &&
+                parseTokenList(match).every((match) => {
+                    return match !== etag && match !== "W/" + etag && "W/" + match !== etag;
+                }))
+        );
+    }
+
+    // if-unmodified-since
+    const unmodifiedSince = parseHttpDate(req.headers["if-unmodified-since"]);
+    if (!isNaN(unmodifiedSince)) {
+        const lastModified = parseHttpDate(res.get("Last-Modified"));
+        return isNaN(lastModified) || lastModified > unmodifiedSince;
+    }
+
+    return false;
+}
+
+// the sha1 of nothing, which the etag package answers with without hashing
+const EMPTY_ENTITY_TAG = '"0-2jmj7l5rSw0yVb/vlWAYkK/YBwk"';
+
+/**
+ * The ETag of a body: its length in hex, a dash, and the first 27 characters of the base64 sha1.
+ * The same string the etag package produces, and tests/unit/utils.test.js holds it to that.
+ *
+ * crypto.hash and not crypto.createHash: the one-shot form allocates no hash object, and on a 500
+ * byte body it is twice as fast for the same answer, 924ns against 1963.
+ *
+ * @param {Buffer|string} entity
+ * @param {boolean} weak
+ * @returns {string}
+ */
+function entityTag(entity, weak) {
+    if (entity.length === 0) {
+        return weak ? "W/" + EMPTY_ENTITY_TAG : EMPTY_ENTITY_TAG;
+    }
+    // the byte length, which for a string is not its character count
+    const len = typeof entity === "string" ? Buffer.byteLength(entity, "utf8") : entity.length;
+    const tag = `"${len.toString(16)}-${crypto.hash("sha1", entity, "base64").substring(0, 27)}"`;
+    return weak ? "W/" + tag : tag;
+}
+
+/**
+ * The ETag of a file, which is its size and mtime rather than its contents: send computes it this
+ * way so that serving a large file does not mean reading it twice.
+ *
+ * @param {import("fs").Stats} stat
+ * @param {boolean} weak
+ * @returns {string}
+ */
+function statTag(stat, weak) {
+    const tag = `"${stat.size.toString(16)}-${stat.mtime.getTime().toString(16)}"`;
+    return weak ? "W/" + tag : tag;
+}
+
+/**
+ * The function the "etag" setting installs. It takes either a body or an fs.Stats, since a file's
+ * ETag comes from its size and mtime while a body's comes from its contents.
+ *
+ * @param {{weak: boolean}} options
+ * @returns {(body: any, encoding?: BufferEncoding) => string}
+ */
+function createETagGenerator(options) {
+    return function generateETag(body, encoding) {
+        if (body instanceof Stats) {
+            return statTag(body, options.weak);
+        }
+        const buf = !Buffer.isBuffer(body) ? Buffer.from(body, encoding) : body;
+        return entityTag(buf, options.weak);
+    };
+}
+
+/**
+ * Whether an If-Range still holds, which decides between answering the range that was asked for
+ * 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
+ * @returns {boolean}
+ */
+function isRangeFresh(req, res) {
+    const ifRange = req.headers["if-range"];
+    if (!ifRange) {
+        return true;
+    }
+
+    // if-range as etag
+    if (ifRange.indexOf('"') !== -1) {
+        const etag = res.get("etag");
+        return Boolean(etag && ifRange.indexOf(etag) !== -1);
+    }
+
+    // if-range as modified date
+    const lastModified = res.get("Last-Modified");
+    return parseHttpDate(lastModified) <= parseHttpDate(ifRange);
+}
+
+/**
+ * Escapes the five characters that would otherwise be markup. Written as a scan rather than a
+ * chain of replaces because it runs on every error page and every redirect body.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+    const s = String(str);
+    const len = s.length;
+    let i = 0;
+
+    // Fast scan: find first char that needs escaping
+    for (; i < len; i++) {
+        const ch = s.charCodeAt(i);
+        if (ch === 0x26 || ch === 0x3c || ch === 0x3e || ch === 0x22 || ch === 0x27) {
+            break;
+        }
+    }
+
+    // No escaping needed
+    if (i === len) return s;
+
+    // Build escaped string from the first match onward
+    let escaped = s.substring(0, i);
+
+    for (; i < len; i++) {
+        const ch = s.charCodeAt(i);
+        switch (ch) {
+            case 0x26: // &
+                escaped += "&amp;";
+                break;
+            case 0x3c: // <
+                escaped += "&lt;";
+                break;
+            case 0x3e: // >
+                escaped += "&gt;";
+                break;
+            case 0x22: // "
+                escaped += "&quot;";
+                break;
+            case 0x27: // '
+                escaped += "&#39;";
+                break;
+            default:
+                escaped += s.charAt(i);
+                break;
+        }
+    }
+
+    return escaped;
+}
+
+// a charset parameter that is already there, and the whole parameter so it can be replaced
+const CHARSET_PRESENT = /;\s*charset\s*=/i;
+const CHARSET_PARAM = /;\s*charset\s*=\s*[^;]*/i;
+const UTF8_CHARSET = "; charset=utf-8";
+
+/**
+ * The value plus the charset its media type implies: text/* gets one, and so does any type whose
+ * mime database entry names one. Memoized, since an application sends two or three content-types
+ * and working it out again costs 159ns against 7.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+const withDefaultCharset = memoizeByString((value) => {
+    if (CHARSET_PRESENT.test(value)) {
+        return value;
+    }
+    const charset = mime.charset(value.split(";")[0]);
+    return charset ? `${value}; charset=${charset.toLowerCase()}` : value;
+});
+
+/**
+ * The same content-type, saying utf-8. A string body is written as utf-8 whatever the header
+ * claimed, so a header claiming otherwise is wrong on the wire, and Express replaces it too.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function withUtf8Charset(value) {
+    // almost every string body already carries the header in this exact form, and the pair of
+    // regular expressions below was 2% of the time spent serving a request
+    if (value.endsWith(UTF8_CHARSET)) {
+        return value;
+    }
+    return CHARSET_PARAM.test(value) ? value.replace(CHARSET_PARAM, UTF8_CHARSET) : `${value}${UTF8_CHARSET}`;
+}
+
+// The status send picks for a failed stat. Anything else is the file being there but unreadable,
+// which is the server's problem and not the request's.
+const STAT_ERROR_STATUS = { ENAMETOOLONG: 404, ENOTDIR: 404, ENOENT: 404 };
+
+/**
+ * The error send and serve-static refuse with, so that the file serving here refuses the same way.
+ *
+ * They build these with http-errors, so they carry `status`, `statusCode` and `expose`, which is
+ * what `res.status(err.status || 500)` reads. Without a status a 403, a 404 and a 416 all came out
+ * of that handler as 500. The message is the status's own name, as http-errors writes it.
+ *
+ * @param {number} status
+ * @returns {any}
+ */
+function httpError(status) {
+    const err = /** @type {any} */ (new Error(statuses.message[status]));
+    err.expose = status < 500;
+    err.statusCode = status;
+    err.status = status;
+    return err;
+}
+
+/**
+ * Marks an fs error the way send does before it is handed on, so an error handler reading
+ * err.status or err.statusCode finds what it would find behind Express. The three properties are
+ * assigned in this order because they are serialised in insertion order, and an error handler that
+ * answers with res.send(err) sends them.
+ *
+ * The error itself is returned rather than a new one, so its errno, code, syscall and path survive.
+ *
+ * @param {any} err
+ * @returns {any} the same error
+ */
+function asStatError(err) {
+    err.expose = false;
+    err.statusCode = STAT_ERROR_STATUS[err.code] ?? 500;
+    err.status = err.statusCode;
+    return err;
+}
+
+// fast null object
+// A constructor whose instances have no prototype, so a key from a request body or a query string
+// cannot reach Object.prototype. Typed as returning a plain record: without that, assigning one
+// reads as assigning `any`, which resets narrowing instead of removing undefined from it.
+/** @type {new () => Record<string, any>} */
+const NullObject = /** @type {any} */ (function () {});
+NullObject.prototype = Object.create(null);
+
+module.exports = {
+    removeDuplicateSlashes,
+    patternToRegex,
+    getPatternMeta,
+    needsConversionToRegex,
+    acceptParams,
+    normalizeType,
+    stringify,
+    defaultSettings,
+    compileTrust,
+    deprecated,
+    UP_PATH_REGEXP,
+    NullObject,
+    decode,
+    decodeParam,
+    containsDotFile,
+    parseTokenList,
+    parseHttpDate,
+    isPreconditionFailure,
+    createETagGenerator,
+    entityTag,
+    statTag,
+    contentTypeFor,
+    memoizeByString,
+    isRangeFresh,
+    findIndexStartingFrom,
+    fastQueryParse,
+    canBeOptimized,
+    canBeOptimizedWithParams,
+    pathsCanOverlap,
+    escapeHtml,
+    withDefaultCharset,
+    withUtf8Charset,
+    asStatError,
+    httpError,
+    EMPTY_REGEX
+};