fulmine.js 5.2.0 → 5.4.0

package/src/request.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
@@ -84,6 +86,31 @@ function formatIPv6(groups) {
     return out;
 }
 
+/**
+ * Whether these sixteen bytes are an IPv4-mapped address, ::ffff:0:0/96: ten zero bytes and then
+ * 0xffff. Ten comparisons rather than a loop, because this runs on every address that is read and
+ * the first mismatch answers immediately for a real IPv6 peer.
+ *
+ * @param {Uint8Array} bytes exactly sixteen of them
+ * @returns {boolean}
+ */
+function isMappedIPv4(bytes) {
+    return (
+        bytes[10] === 0xff &&
+        bytes[11] === 0xff &&
+        bytes[0] === 0 &&
+        bytes[1] === 0 &&
+        bytes[2] === 0 &&
+        bytes[3] === 0 &&
+        bytes[4] === 0 &&
+        bytes[5] === 0 &&
+        bytes[6] === 0 &&
+        bytes[7] === 0 &&
+        bytes[8] === 0 &&
+        bytes[9] === 0
+    );
+}
+
 /**
  * Whether node would report an IPv4 peer of this app in mapped form, "::ffff:a.b.c.d". Node maps
  * it whenever the listener is dual stack, which is every listen() not given an IPv4 address to
@@ -98,6 +125,9 @@ function mapsIPv4Peer(app) {
     return !(host && isIP(host) === 4);
 }
 
+/** What µWS returns for a proxied address when no PROXY protocol preamble arrived. */
+const emptyAddress = new ArrayBuffer(0);
+
 const discardedDuplicates = new Set([
     "age",
     "authorization",
@@ -119,8 +149,6 @@ const discardedDuplicates = new Set([
     "user-agent"
 ]);
 
-let key = 0;
-
 // 128 KB of body buffered before uWS is asked to pause
 const READABLE_OPTIONS = { highWaterMark: 128 * 1024 };
 
@@ -129,7 +157,115 @@ const READABLE_OPTIONS = { highWaterMark: 128 * 1024 };
 // of once per request.
 let currentRequest = null;
 
-module.exports = class Request extends Readable {
+/**
+ * A Readable that has not been built yet.
+ *
+ * Every request pays for the stream and almost none of them use it: a GET carries no body, and the
+ * bodies that do arrive are collected by µWS and handed to the parsers without the stream being
+ * touched. Measured on this machine, running Readable's constructor costs about 90ns of the 900ns
+ * a hello-world request costs in total, which is a tenth of it for a facility nobody asked for.
+ *
+ * So the chain says Readable and the constructor does not run. `Request extends LazyReadable`, and
+ * LazyReadable's prototype is Readable's, which keeps `req instanceof Readable` true and every
+ * Readable method reachable; what is missing is `_readableState`, and that is built on the first
+ * touch. A derived class cannot skip its super() call, but a base class with nothing in it costs
+ * nothing to call.
+ *
+ * The wrapping below is generated rather than written out, and deliberately: every own member of
+ * Readable's prototype gets a version that materialises first, so there is no list to keep in step
+ * and no door left unguarded. Missing one would not be a slow path, it would be a TypeError on
+ * `undefined._readableState` in whatever corner of a stream nobody tested.
+ */
+class LazyReadableBase {}
+Object.setPrototypeOf(LazyReadableBase.prototype, Readable.prototype);
+Object.setPrototypeOf(LazyReadableBase, Readable);
+
+// what the chain says at runtime, said again for the type checker, which cannot see a prototype
+// being reassigned: everything a Readable offers is reachable from a Request, and is a Readable's
+const LazyReadable = /** @type {typeof Readable} */ (/** @type {unknown} */ (LazyReadableBase));
+
+/**
+ * Builds the stream this object has been pretending to be. Idempotent: everything that can be
+ * reached from outside goes through it, so it is called far more often than it does anything.
+ *
+ * EventEmitter's init keeps an _events that is already there, so listeners added before this
+ * survive it.
+ *
+ * @param {any} stream
+ */
+function materialise(stream) {
+    if (stream._readableState === undefined) {
+        Readable.call(stream, READABLE_OPTIONS);
+    }
+}
+
+for (const member of [
+    ...Object.getOwnPropertyNames(Readable.prototype),
+    ...Object.getOwnPropertySymbols(Readable.prototype)
+]) {
+    // the constructor is not a door, and `readable` is handled below because a request writes it
+    // and writing it must not build the very thing this is avoiding
+    if (member === "constructor" || member === "readable") {
+        continue;
+    }
+    const descriptor = /** @type {PropertyDescriptor} */ (Object.getOwnPropertyDescriptor(Readable.prototype, member));
+    if (typeof descriptor.value === "function") {
+        const inner = descriptor.value;
+        Object.defineProperty(LazyReadableBase.prototype, member, {
+            ...descriptor,
+            /** @this {any} @param {...any} args */
+            value: function (...args) {
+                materialise(this);
+                return inner.apply(this, args);
+            }
+        });
+    } else if (descriptor.get || descriptor.set) {
+        const innerGet = descriptor.get;
+        const innerSet = descriptor.set;
+        Object.defineProperty(LazyReadableBase.prototype, member, {
+            ...descriptor,
+            get: innerGet
+                ? /** @this {any} */ function () {
+                      materialise(this);
+                      return innerGet.call(this);
+                  }
+                : undefined,
+            set: innerSet
+                ? /** @this {any} @param {any} value */ function (value) {
+                      materialise(this);
+                      innerSet.call(this, value);
+                  }
+                : undefined
+        });
+    }
+}
+
+const nodeReadable = /** @type {PropertyDescriptor} */ (
+    Object.getOwnPropertyDescriptor(Readable.prototype, "readable")
+);
+
+// `readable` on its own: a request sets it while it is being built, and node's setter is a no-op
+// without the state anyway, so the flag is kept as a plain field until there is a stream to ask
+Object.defineProperty(LazyReadableBase.prototype, "readable", {
+    configurable: true,
+    enumerable: false,
+    /** @this {any} */
+    get: function () {
+        return this._readableState === undefined
+            ? this._readableFlag === true
+            : /** @type {any} */ (nodeReadable.get).call(this);
+    },
+    /** @this {any} @param {any} value */
+    set: function (value) {
+        if (this._readableState === undefined) {
+            this._readableFlag = !!value;
+            return;
+        }
+        /** @type {any} */ (nodeReadable.set).call(this, value);
+    }
+});
+
+module.exports = class Request extends LazyReadable {
     /** @type {Record<string, any>|null} */
     #cachedQuery = null;
 
@@ -200,13 +336,20 @@ module.exports = class Request extends Readable {
         ) {
             r._connectionClose = true;
         } else if (
-            // content-length: 0 declares that there is nothing, which is the same as declaring
-            // nothing: the stream ends empty either way, without the onData subscription
-            (headerKey.length === 14 && headerKey === "content-length" && value !== "0") ||
+            (headerKey.length === 14 && headerKey === "content-length") ||
             (headerKey.length === 17 && headerKey === "transfer-encoding")
         ) {
-            // noticed here so the body decision in the constructor does not build the headers object
-            r._declaresBody = true;
+            // saying anything about framing at all, "0" included. A parser that can see a
+            // content-length answers about the body it describes, even an empty one: a zero length
+            // with a charset nobody can decode is a 415 in express and here, so a chain may only
+            // step over a parser when the request said nothing about a body whatsoever
+            r._hasBodyHeaders = true;
+            // content-length: 0 declares that there is nothing, which is the same as declaring
+            // nothing: the stream ends empty either way, without the onData subscription
+            if (value !== "0" || headerKey.length === 17) {
+                // noticed here so the body decision in the constructor does not build the headers object
+                r._declaresBody = true;
+            }
         }
     };
 
@@ -216,6 +359,95 @@ module.exports = class Request extends Readable {
      */
     optimizedParams;
 
+    /**
+     * Whether a body parser has already read this request, so a second one leaves it alone.
+     * @type {boolean|undefined}
+     */
+    bodyRead;
+
+    /**
+     * The route currently running, which express hands to a handler through the request.
+     * @type {any}
+     */
+    route;
+
+    /**
+     * Which hop the error being carried came from, so an error handler declared before it does
+     * not catch what happened after it.
+     * @type {number|undefined}
+     */
+    _errorKey;
+
+    /**
+     * Which app.route() the failing route belonged to, when it belonged to one. Express builds one
+     * route out of everything hung off an app.route(), so an error handler written on it catches
+     * what its siblings raised, and nothing else does.
+     * @type {number|undefined}
+     */
+    _errorGroup;
+
+    /**
+     * How much of _originalPath the mounts entered so far have taken. Kept as a count rather than
+     * worked out from the mount patterns, because what a mount took is what it matched, and a
+     * pattern rebuilt from the whole stack does not always match the same thing.
+     * @type {number}
+     */
+    _consumed = 0;
+
+    /**
+     * next() as the router means it: the rest of the route is skipped. res.sendFile reports its
+     * failures here, because express reports them to the router and not to the route.
+     * @type {((err?: any) => void)|undefined}
+     */
+    _leaveRoute;
+
+    /**
+     * What `readable` answers while there is no stream to ask, see LazyReadable. Declared so the
+     * class has one shape whether or not anything ever streams.
+     * @type {boolean}
+     */
+    _readableFlag = true;
+
+    /**
+     * The peer address as uWS hands it over, sixteen bytes or four.
+     *
+     * Declared although the constructor only sometimes fills it in: a property that appears on
+     * some requests and not others gives the class more than one shape, and every read of every
+     * other field pays for that.
+     *
+     * @type {ArrayBuffer|undefined}
+     */
+    rawIp;
+
+    /**
+     * Whether rawIp came from a PROXY protocol preamble rather than from the socket. Only the
+     * IPv4 mapping reads it, see parsedIp. Declared for the same reason as rawIp.
+     * @type {boolean}
+     */
+    _ipFromProxy = false;
+
+    /**
+     * Whether the request declared a body, content-length or transfer-encoding, spotted during
+     * the header copy. Declared for the same reason as rawIp.
+     * @type {boolean|undefined}
+     */
+    _declaresBody;
+
+    /**
+     * Whether the request said anything at all about framing, a content-length of "0" included.
+     * Wider than _declaresBody on purpose: a parser that can see a content-length answers about
+     * the body it describes even when that body is empty, so this is what decides whether a chain
+     * may step over one. Declared for the same reason as rawIp.
+     * @type {boolean|undefined}
+     */
+    _hasBodyHeaders;
+
+    /**
+     * Whether the client asked for the connection to be closed. Declared for the same reason.
+     * @type {boolean|undefined}
+     */
+    _connectionClose;
+
     /**
      * The continuation of the chain currently running, which express also hands to a handler
      * through the request. Declared rather than left to appear on assignment: runRoute sets it
@@ -252,19 +484,32 @@ module.exports = class Request extends Readable {
      *   literal registration, a holder of its own for a parameterised one
      */
     constructor(req, res, app, preset, skipHolder) {
-        // the same object every time: Readable reads these options and never writes to them
-        super(READABLE_OPTIONS);
+        // nothing: the stream is built on the first touch, see LazyReadable
+        super();
         this._res = res;
         this._req = req;
-        this.readable = true;
+        // the plain field behind the `readable` accessor, written rather than set so a request that
+        // never streams never builds a stream
+        this._readableFlag = true;
         if (skipHolder !== undefined && skipHolder.skipHeaders) {
             // The chain behind this registration provably never reads a header, so instead of
             // copying them all out of uWS the constructor asks for the four that steer the
             // framework itself: body framing, keep-alive, and accept for the error page a
             // throw could still need. A GET that does declare a body is the rare case, and
             // the parsers and the stream want the whole picture, so it takes the full copy.
+            //
+            // Seven named reads against one forEach looks like it should lose, and does not: the
+            // seven are flat at 0.75us however many headers are on the wire, since each one is a
+            // napi crossing and the scan behind it is nothing, while the copy pays a hop back into
+            // JS per header and grows, 1.16us at four headers, 1.61 at eight, 2.90 at sixteen. They
+            // do not cross, and the gap widens exactly where real traffic lives, since a browser
+            // sends a dozen or more. The body case pays two of the seven and then copies anyway,
+            // which is 0.2us on a request that is about to read a body.
             const length = req.getHeader("content-length");
             const transferEncoding = req.getHeader("transfer-encoding");
+            if (length !== "" || transferEncoding !== "") {
+                this._hasBodyHeaders = true;
+            }
             if ((length !== "" && length !== "0") || transferEncoding !== "") {
                 currentRequest = this;
                 this._req.forEach(Request.#collectHeader);
@@ -304,10 +549,6 @@ module.exports = class Request extends Readable {
             currentRequest = null;
         }
         this.routeCount = 1;
-        this.key = key++;
-        if (key > 100000) {
-            key = 0;
-        }
         this.app = app;
         // both forms are kept, because both are asked for: the query with its "?" goes into
         // req.url, and req.query parses the raw one. Keeping only the first meant slicing the "?"
@@ -318,8 +559,11 @@ module.exports = class Request extends Readable {
             this._rawQuery = "";
             this.urlQuery = "";
         } else {
-            this._rawQuery = req.getQuery() ?? "";
-            this.urlQuery = this._rawQuery === "" ? "" : "?" + this._rawQuery;
+            // getQuery tells "/a" from "/a?": no query string at all reads undefined, an empty
+            // one reads "". Express keeps that lone "?" in req.url, so the two are kept apart
+            const rawQuery = req.getQuery();
+            this._rawQuery = rawQuery ?? "";
+            this.urlQuery = rawQuery === undefined ? "" : "?" + rawQuery;
         }
         if (preset) {
             // the registration's constants: two native crossings and their strings not asked for
@@ -347,9 +591,6 @@ module.exports = class Request extends Readable {
             this.endsWithSlash = this.path.charCodeAt(this.path.length - 1) === 0x2f;
             this._opPath = this.path;
             this._originalPath = this.path;
-            if (this.endsWithSlash && this.path !== "/" && !this.app.get("strict routing")) {
-                this._opPath = this._opPath.slice(0, -1);
-            }
             this.method = req.getCaseSensitiveMethod().toUpperCase();
             this._isOptions = this.method === "OPTIONS";
             this._isHead = this.method === "HEAD";
@@ -370,16 +611,24 @@ module.exports = class Request extends Readable {
         // null for the same reason as the two above: a request that never enters a mount never
         // needs either array, and the push sites materialize them
         this._stack = null;
-        // number of entries in _stack that aren't the empty path. while this is 0 the whole
-        // stack joins to "", so getFullMountpath can skip the join entirely
-        this._stackMounted = 0;
+        // how many characters of _originalPath the mounts entered so far have taken, which is
+        // where baseUrl ends and the path below them begins
+        this._consumed = 0;
         this._paramStack = null;
+        // route and application in pairs, one pair per mounted application entered from another
+        // application, so handing back puts the one that was current back, see rememberApp
+        this._appStack = undefined;
         this.receivedData = false;
         // reading ip is very slow in UWS, so its better to not do it unless truly needed
-        if (this.app.needsIpAfterResponse || this.key < 100) {
-            // if app needs ip after response, read it now because after response its not accessible
-            // also read it for first 100 requests to not error
-            this.rawIp = this._res.getRemoteAddress();
+        if (app.needsIpAfterResponse) {
+            // an app that has been seen asking after the response reads it now, because by then
+            // µWS has freed it
+            this.rawIp = this._readRawIp();
+        } else if (app._ipProbes < 100) {
+            // and until this app has been seen either way, the first hundred requests read it, so
+            // one of them can be the one that finds out
+            app._ipProbes++;
+            this.rawIp = this._readRawIp();
         }
 
         // A body exists on the wire only when the request declares one, content-length or
@@ -483,8 +732,8 @@ module.exports = class Request extends Readable {
         if (this._baseUrlOverride !== undefined) {
             return this._baseUrlOverride;
         }
-        const match = this._originalPath.match(this.app.getFullMountpath(this));
-        return match ? match[0] : "";
+        // what the mounts took, which is where the path they left off begins
+        return this._consumed === 0 ? "" : this._originalPath.slice(0, this._consumed);
     }
 
     /**
@@ -641,38 +890,50 @@ module.exports = class Request extends Readable {
                 ? this._originalPath
                 : this._originalPath.slice(0, this._originalPath.length - oldPath.length);
         this._rawQuery = queryIndex === -1 ? "" : newUrl.slice(queryIndex + 1);
-        this.urlQuery = this._rawQuery === "" ? "" : "?" + this._rawQuery;
+        // a rewrite to "/a?" keeps its "?", as one arriving that way does
+        this.urlQuery = queryIndex === -1 ? "" : "?" + this._rawQuery;
         this.#cachedQuery = null;
         this._originalPath = prefix + newPath;
         this.path = newPath;
         this.endsWithSlash = newPath.charCodeAt(newPath.length - 1) === 0x2f;
-        this._opPath =
-            this.endsWithSlash && newPath !== "/" && !this.app.get("strict routing") ? newPath.slice(0, -1) : newPath;
+        this._opPath = newPath;
         this._lastUrl = newUrl;
     }
 
     /**
-     * The query string parsed by whichever parser the "query parser" setting names, cached for the
-     * life of the request. A null-prototype object, so a key like "__proto__" cannot reach
-     * Object.prototype. No setter, so assigning to req.query throws as it does on Express.
+     * The query string parsed by whichever parser the "query parser" setting names. A null-prototype
+     * object, so a key like "__proto__" cannot reach Object.prototype. No setter, so assigning to
+     * req.query throws as it does on Express.
+     *
+     * Every read answers a new object, because express's getter re-parses on every read and so hands
+     * one back too. Two consequences an application can see, and both of them bite: `req.query` is
+     * never the object another reader holds, and a write to a key of it is gone by the next read.
+     * That second one is how express-validator's sanitisers behave: `.trim()` on a query parameter
+     * changes nothing an ordinary handler will see, which is why it also offers matchedData(). With
+     * the parse cached and handed out as itself, the sanitised value leaked into req.query here and
+     * a handler written against express read a trimmed value where express gives it the raw one.
+     *
+     * The parse itself is still done once. What is copied per read is the shallow result, which is
+     * cheaper than express's re-parse and answers the same for everything but a write to a nested
+     * key, which only the extended parser can produce.
      *
      * @returns {Record<string, any>}
      */
     get query() {
-        if (this.#cachedQuery) {
-            return this.#cachedQuery;
+        let parsed = this.#cachedQuery;
+        if (parsed === null) {
+            const qp = this.app.get("query parser fn");
+            // the vendored default already answers on a bare null prototype, so it goes out as is;
+            // any other parser is copied onto one, which is what kept fast-querystring's result from
+            // inspecting as "Empty <[Object: null prototype] {}>" where Express shows the bare form
+            parsed = qp
+                ? qp === parseQuery
+                    ? parseQuery(this._rawQuery)
+                    : Object.assign(Object.create(null), qp(this._rawQuery))
+                : Object.create(null);
+            this.#cachedQuery = parsed;
         }
-        const qp = this.app.get("query parser fn");
-        // the vendored default already answers on a bare null prototype, so it goes out as is;
-        // any other parser is copied onto one, which is what kept fast-querystring's result from
-        // inspecting as "Empty <[Object: null prototype] {}>" where Express shows the bare form
-        const parsed = qp
-            ? qp === parseQuery
-                ? parseQuery(this._rawQuery)
-                : Object.assign(Object.create(null), qp(this._rawQuery))
-            : Object.create(null);
-        this.#cachedQuery = parsed;
-        return parsed;
+        return Object.assign(Object.create(null), parsed);
     }
 
     /**
@@ -717,6 +978,32 @@ module.exports = class Request extends Readable {
         return typeof val === "string" && val.toLowerCase() === "xmlhttprequest";
     }
 
+    /**
+     * The peer address bytes, from the socket or, when the application asked for it, from a PROXY
+     * protocol preamble the load balancer in front of this server sent ahead of the request.
+     *
+     * The setting is off by default and has to stay that way. µWS parses the preamble from whoever
+     * sends it, with nothing to ask for it at listen time and no way to restrict who may, so an
+     * application that took the address unconditionally would let any client claim any address:
+     * the first sixteen bytes of a connection are enough to become 10.0.0.1 for a rate limiter, an
+     * allow list or an audit log. Turn it on only when nothing can reach this server except the
+     * proxy in front of it.
+     *
+     * @returns {ArrayBuffer} the socket's own address when no preamble arrived
+     */
+    _readRawIp() {
+        const uwsRes = this._res;
+        if (this.app.get("trust proxy protocol")) {
+            const proxied = uwsRes.getProxiedRemoteAddress();
+            // empty unless a preamble arrived, which is the only thing that tells the two apart
+            if (proxied.byteLength !== 0) {
+                this._ipFromProxy = true;
+                return proxied;
+            }
+        }
+        return uwsRes.getRemoteAddress();
+    }
+
     /**
      * The peer address as text, read from uWS and cached. Reading it is expensive and it is gone
      * once the response has finished, so it is read up front for the first hundred requests, and
@@ -739,24 +1026,39 @@ module.exports = class Request extends Readable {
                 // fallback once
                 return mapsIPv4Peer(this.app) ? "::ffff:127.0.0.1" : "127.0.0.1";
             }
-            this.rawIp = this._res.getRemoteAddress();
+            this.rawIp = this._readRawIp();
         }
+        // read once: the branch above settled it, and every use below wants the bytes
+        const rawIp = /** @type {ArrayBuffer} */ (this.rawIp);
         /** @type {string|undefined} */
         let ip;
-        if (this.rawIp.byteLength === 4) {
+        if (rawIp.byteLength === 4) {
             // ipv4
-            ip = new Uint8Array(this.rawIp).join(".");
-            if (mapsIPv4Peer(this.app)) {
+            ip = new Uint8Array(rawIp).join(".");
+            // the mapped form belongs to a dual stack listener, which is what makes an IPv4 peer
+            // arrive as ::ffff:a.b.c.d. An address a proxy declared never came through that socket,
+            // so it is left as the four numbers the proxy sent
+            if (!this._ipFromProxy && mapsIPv4Peer(this.app)) {
                 ip = "::ffff:" + ip;
             }
-        } else if (this.rawIp.byteLength === 16) {
-            // ipv6
-            const dv = new DataView(this.rawIp);
-            const groups = new Array(8);
-            for (let i = 0; i < 8; i++) {
-                groups[i] = dv.getUint16(i * 2);
+        } else if (rawIp.byteLength === 16) {
+            const bytes = new Uint8Array(rawIp);
+            if (isMappedIPv4(bytes)) {
+                // ::ffff:a.b.c.d, which is what a dual stack listener hands over for every IPv4
+                // peer, so it is what nearly every request here is. The general path below reaches
+                // the same string through a DataView, an array of eight groups and a scan for the
+                // longest run of zeros, and measured 157ns more per request for it. Anything that
+                // reads req.ip pays that once, and morgan reads it on every line it writes.
+                ip = "::ffff:" + bytes[12] + "." + bytes[13] + "." + bytes[14] + "." + bytes[15];
+            } else {
+                // ipv6
+                const dv = new DataView(rawIp);
+                const groups = new Array(8);
+                for (let i = 0; i < 8; i++) {
+                    groups[i] = dv.getUint16(i * 2);
+                }
+                ip = formatIPv6(groups);
             }
-            ip = formatIPv6(groups);
         } else {
             ip = undefined; // unix sockets dont have ip
         }
@@ -809,12 +1111,15 @@ module.exports = class Request extends Readable {
     _detachFromResponse() {
         const uwsRes = this._res;
         if (!this.rawIp) {
-            this.rawIp = uwsRes.getRemoteAddress();
+            this.rawIp = this._readRawIp();
         }
         const remotePort = uwsRes.getRemotePort();
         const rawIp = this.rawIp;
         this._res = {
             getRemoteAddress: () => rawIp,
+            // whatever a preamble said is already in rawIp, and asking again is the use after free
+            // this method exists to avoid
+            getProxiedRemoteAddress: () => emptyAddress,
             getRemotePort: () => remotePort,
             // a body cannot arrive on an upgraded socket, and a stray reader must not reach µWS
             onData() {},