fulmine.js 5.2.0 → 5.4.0

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
@@ -119,7 +121,84 @@ function statusLine(code, text) {
     return `${code} ${text ?? statuses.message[code] ?? "unknown"}`.trim();
 }
 
-module.exports = class Response extends Writable {
+/**
+ * A Writable that has not built its state yet, the mirror of LazyReadable in request.js and there
+ * for the same reason: a response is a Writable because middleware expects one, and the ordinary
+ * one never uses it. `send()` reaches `end()`, which is overridden here and goes straight to
+ * _finish, so the WritableState is allocated for every response and read by nobody. It is needed
+ * only by res.write(), by a stream piped into the response, by cork and by the writableX getters.
+ *
+ * `Response extends LazyWritable`, whose prototype is Writable's, so `res instanceof Writable`
+ * stays true and every Writable method is reachable; what is missing is `_writableState`, built on
+ * the first touch. Measured at 45 nanoseconds a response on the machine this was written on.
+ *
+ * As on the Readable side the wrapping is generated rather than written out: every own member of
+ * Writable's prototype gets a version that materialises first, so there is no list to keep in step.
+ * Missing one would not be a slow path, it would be a TypeError on `undefined._writableState`.
+ */
+class LazyWritableBase {}
+Object.setPrototypeOf(LazyWritableBase.prototype, Writable.prototype);
+Object.setPrototypeOf(LazyWritableBase, Writable);
+
+// what the chain says at runtime, said again for the type checker, which cannot see a prototype
+// being reassigned
+const LazyWritable = /** @type {typeof Writable} */ (/** @type {unknown} */ (LazyWritableBase));
+
+/**
+ * Builds the stream this object has been pretending to be. Idempotent: everything reachable 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 both the shape the constructor
+ * wrote and any listener added before this survive it.
+ *
+ * @param {any} stream
+ */
+function materialiseWritable(stream) {
+    if (stream._writableState === undefined) {
+        Writable.call(stream);
+    }
+}
+
+for (const member of [
+    ...Object.getOwnPropertyNames(Writable.prototype),
+    ...Object.getOwnPropertySymbols(Writable.prototype)
+]) {
+    if (member === "constructor") {
+        continue;
+    }
+    const descriptor = /** @type {PropertyDescriptor} */ (Object.getOwnPropertyDescriptor(Writable.prototype, member));
+    if (typeof descriptor.value === "function") {
+        const inner = descriptor.value;
+        Object.defineProperty(LazyWritableBase.prototype, member, {
+            ...descriptor,
+            /** @this {any} @param {...any} args */
+            value: function (...args) {
+                materialiseWritable(this);
+                return inner.apply(this, args);
+            }
+        });
+    } else if (descriptor.get || descriptor.set) {
+        const innerGet = descriptor.get;
+        const innerSet = descriptor.set;
+        Object.defineProperty(LazyWritableBase.prototype, member, {
+            ...descriptor,
+            get: innerGet
+                ? /** @this {any} */ function () {
+                      materialiseWritable(this);
+                      return innerGet.call(this);
+                  }
+                : undefined,
+            set: innerSet
+                ? /** @this {any} @param {any} value */ function (value) {
+                      materialiseWritable(this);
+                      innerSet.call(this, value);
+                  }
+                : undefined
+        });
+    }
+}
+
+module.exports = class Response extends LazyWritable {
     /** @type {Socket|null} */
     #socket = null;
 
@@ -149,6 +228,19 @@ module.exports = class Response extends Writable {
      */
     constructor(res, req, app) {
         super();
+        // the EventEmitter half stays eager, since the stream half is what LazyWritable defers and
+        // the two listeners below are written straight into this map. These are the five keys and
+        // the order node's own Writable constructor lays down, so the hidden class is the one every
+        // other stream in the process has, and node's init keeps this object when the state is
+        // finally built
+        this._events = {
+            close: undefined,
+            error: undefined,
+            prefinish: undefined,
+            finish: undefined,
+            drain: undefined
+        };
+        this._eventsCount = 0;
         this._req = req;
         // linked here rather than by the caller: the pair is built together, and a field the
         // constructor leaves unset is a shape change on whoever assigns it first
@@ -183,13 +275,42 @@ module.exports = class Response extends Writable {
         }
 
         this.body = undefined;
+        // what was handed to uWS, kept so a caller asking for content-length after the fact can be
+        // answered, see get(). Undefined until the response ends, and for one that sends no body
+        /** @type {string|Buffer|undefined} */
+        this._sentBody = undefined;
         // false while the uWS route handler is still in its synchronous window, where uWS holds
         // the socket corked itself; the two uWS entry points flip it once that window closes
         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 */
@@ -421,6 +542,12 @@ module.exports = class Response extends Writable {
         // the value here is nearly always the 10-char "keep-alive", which paid a scan per response
         const closing =
             typeof connection === "string" && connection.length === 5 && connection.toLowerCase() === "close";
+        // for..in over an object some responses delete from, which is the shape the request side
+        // was taken off for #rawHeadersEntries. It stays here, and the difference is where the
+        // deletes are: a 200 with a body performs none. Only 204, 304, 205, the freshness branch of
+        // sendFile and removeHeader do, this object is built fresh per response, so a dictionary one
+        // of them made costs that response and nothing after it. The request side deleted on every
+        // request, which is what made it worth a different structure
         for (const header in headers) {
             if (closing && header === "keep-alive") {
                 continue;
@@ -557,8 +684,12 @@ module.exports = class Response extends Writable {
             // an allocation per body, and uWS reads the view's own offset and length
             if (this.req.method === "HEAD") {
                 const length = Buffer.byteLength(data ?? "");
+                this.headers["content-length"] = String(length);
                 this._res.endWithoutBody(length.toString());
             } else {
+                // remembered rather than measured: only a caller that asks for content-length pays
+                // for it, and uWS is measuring the same bytes for the wire anyway
+                this._sentBody = data ?? "";
                 this._res.end(data);
             }
         }
@@ -703,7 +834,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 +991,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 +1059,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;
@@ -1150,7 +1289,19 @@ module.exports = class Response extends Writable {
      * @returns {string|string[]|undefined}
      */
     get(field) {
-        return this.headers[field.toLowerCase()];
+        const name = field.toLowerCase();
+        const value = this.headers[name];
+        // Content-Length is on the wire but not in here: uWS measures the body it is handed and
+        // writes the header itself, which saves measuring it twice. Express sets it in send(), so
+        // anything reading it back finds it there, and morgan's common and combined formats do
+        // exactly that on every line they write. Worked out here rather than in send() so a
+        // response nobody asks pays nothing, and kept once worked out.
+        if (value === undefined && name === "content-length" && this._sentBody !== undefined) {
+            const length = Buffer.byteLength(this._sentBody);
+            this.headers["content-length"] = String(length);
+            return String(length);
+        }
+        return value;
     }
 
     /**
@@ -1226,7 +1377,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,17 +1478,22 @@ module.exports = class Response extends Writable {
 
         this.vary("Accept");
 
+        // the router next, as express hands over: inside a route with a four argument handler of
+        // its own, a 406 leaves the route rather than being caught by that handler. Where the two
+        // are the same step, _leaveRoute is the very object the surrounding layer received, which
+        // is what express's own test asserts, see Walk#runRoute
+        const next = this.req._leaveRoute ?? this.req.next;
         if (key) {
             this.set("Content-Type", normalizeType(key).value);
-            object[key](this.req, this, this.req.next);
+            object[key](this.req, this, next);
         } else if (object.default) {
-            object.default(this.req, this, this.req.next);
+            object.default(this.req, this, next);
         } else {
             // an error and not an answer: express hands the error handler the types it could have
             // sent, which is how an application says what it supports
             const err = httpError(406);
             err.types = keys.map((type) => normalizeType(type).value);
-            this.req.next(err);
+            next(err);
         }
 
         return this;