fulmine.js 5.2.0 → 5.3.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
@@ -129,7 +156,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 +335,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 +358,88 @@ 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 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,11 +476,13 @@ 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
@@ -265,6 +491,9 @@ module.exports = class Request extends Readable {
             // the parsers and the stream want the whole picture, so it takes the full copy.
             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);
@@ -318,8 +547,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 +579,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,10 +599,13 @@ 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) {
@@ -483,8 +715,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,13 +873,13 @@ 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;
     }
 
@@ -741,22 +973,34 @@ module.exports = class Request extends Readable {
             }
             this.rawIp = this._res.getRemoteAddress();
         }
+        // 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(".");
+            ip = new Uint8Array(rawIp).join(".");
             if (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
         }

package/src/response.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
@@ -188,8 +190,33 @@ module.exports = class Response extends Writable {
         this._corkNeeded = false;
         // shared methods, not arrows: two closures and a once() wrapper here were four
         // allocations per request. EventEmitter calls listeners with this = the emitter.
-        this.on("error", this._onAbortError);
-        this.on("close", this._onCloseCleanup);
+        //
+        // Written into the map rather than through on(). A stream arrives with its _events already
+        // shaped, "close" and "error" among the keys and every value undefined, so filling two of
+        // them is the same hidden class on() would have produced and none of its work: the argument
+        // check, the newListener emission, the is-there-one-already branch and the max listener
+        // count. Two calls per response, and the profile put them at 6% of a hello-world.
+        //
+        // The condition is the whole safety of it: a fresh response has no listeners, so both slots
+        // are free, and anything else falls back to on(). Adding one later goes through on() as
+        // usual and finds what this wrote, because this wrote what on() writes.
+        // cast because _events and _eventsCount are EventEmitter's own bookkeeping and carry no
+        // type: they are what on() writes, and this writes the same two entries
+        const self = /** @type {any} */ (this);
+        const events = self._events;
+        if (
+            self._eventsCount === 0 &&
+            events !== undefined &&
+            events.error === undefined &&
+            events.close === undefined
+        ) {
+            events.error = this._onAbortError;
+            events.close = this._onCloseCleanup;
+            self._eventsCount = 2;
+        } else {
+            this.on("error", this._onAbortError);
+            this.on("close", this._onCloseCleanup);
+        }
     }
 
     /** @param {Error} err */
@@ -703,7 +730,10 @@ module.exports = class Response extends Writable {
         // Express's completion handler, exactly: a callback hears everything and the response is
         // left alone, so it can still answer 200 after a 404 error. Without one, a directory
         // falls through as a plain next(), and aborts and write errors go nowhere.
-        const next = this.req.next;
+        // the router's next and not the route's: express reports a file it could not serve past
+        // the rest of the route, so a four argument handler written inside the route never sees
+        // it. _leaveRoute is that; req.next is kept for everything else, see Walk#stepOutOfRoute
+        const next = this.req._leaveRoute ?? this.req.next;
         const done = /** @type {(err?: any) => void} */ (
             (err) => {
                 if (callback) return callback(err);
@@ -857,9 +887,6 @@ module.exports = class Response extends Writable {
         if (options.etag && !this.headers["etag"]) {
             this.headers["etag"] = statTag(stat, true);
         }
-        if (!options.etag) {
-            this.req.noEtag = true;
-        }
 
         // announced before the conditional checks, because those can return early and the header
         // still belongs on the response. send does it in the same order, so a 412 or a 416 still
@@ -928,6 +955,14 @@ module.exports = class Response extends Writable {
             }
         }
 
+        // Turning the etag off means this file goes out without one, and only this file: the
+        // exits above hand an error to the application, and the body its handler sends computes
+        // its own etag, as it does on express. Suppressing it before those exits made a 416 or a
+        // 412 answer without one.
+        if (!options.etag) {
+            this.req.noEtag = true;
+        }
+
         // anything but the whole file, whether from a Range header or the start/end options,
         // has to go through the read stream with explicit bounds
         const partial = offset > 0 || len < stat.size;
@@ -1226,7 +1261,11 @@ module.exports = class Response extends Writable {
         const done =
             callback ||
             ((err, str) => {
-                if (err) return this.req.next(err);
+                // the router's next and not the route's, the same as sendFile: express reports a
+                // view it could not render to req.next, which the router owns, so the rest of the
+                // route is skipped and a four argument handler written inside it never sees the
+                // error. A callback, when there is one, hears everything instead
+                if (err) return (this.req._leaveRoute ?? this.req.next)(err);
                 this.send(str);
             });
 
@@ -1323,6 +1362,12 @@ module.exports = class Response extends Writable {
 
         this.vary("Accept");
 
+        // req.next, not the router next sendFile and render use. Express's is the router's here
+        // too, so inside a route with a four argument handler of its own this hands the error to
+        // that handler where express would have left the route. Passing the router next instead
+        // fails express's own res.format test, which asserts the handler is given the very same
+        // function the surrounding middleware received: outside a route the two are equivalent but
+        // not identical. The whole thing is the open req.next question at Walk's constructor
         if (key) {
             this.set("Content-Type", normalizeType(key).value);
             object[key](this.req, this, this.req.next);