fulmine.js 5.1.9 → 5.3.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
@@ -123,6 +125,7 @@ module.exports = class Response extends Writable {
     /** @type {Socket|null} */
     #socket = null;
 
+    /** Whether end() has run, which is what makes a second one a no-op rather than a throw. */
     #ended = false;
 
     /** @type {((err?: Error|null) => void)|null} */
@@ -131,6 +134,10 @@ module.exports = class Response extends Writable {
     /** @type {any} */
     #outHeaders = null;
 
+    /**
+     * The request this response answers, linked so either reaches the other.
+     * @type {InstanceType<typeof import("./request.js")>}
+     */
     req;
 
     /**
@@ -145,6 +152,9 @@ module.exports = class Response extends Writable {
     constructor(res, req, app) {
         super();
         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
+        this.req = req;
         this._res = res;
         this.headersSent = false;
         this.app = app;
@@ -180,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 */
@@ -673,7 +708,7 @@ module.exports = class Response extends Writable {
      * "ignore"), `acceptRanges`, `cacheControl`, `immutable`, `etag` and `setHeaders`.
      *
      * @param {string} path
-     * @param {Record<string, any>} [options]
+     * @param {import("./options").SendFileOptions} [options]
      * @param {(err?: Error) => void} [callback] called once sent, or with the error
      */
     sendFile(path, options = new NullObject(), callback) {
@@ -695,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);
@@ -849,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
@@ -893,9 +928,11 @@ module.exports = class Response extends Writable {
         // range requests
         if (options.acceptRanges) {
             if (this.req.headers.range) {
-                let ranges = this.req.range(len, {
-                    combine: true
-                });
+                // the branch above established the header is there, so range() cannot answer
+                // the undefined it uses to mean "no Range header"
+                let ranges = /** @type {ReturnType<typeof import("range-parser")>} */ (
+                    this.req.range(len, { combine: true })
+                );
 
                 // if-range
                 if (!isRangeFresh(this.req, this)) {
@@ -918,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;
@@ -1003,7 +1048,7 @@ module.exports = class Response extends Writable {
      *
      * @param {string} path
      * @param {string} [filename] name offered to the user, defaults to the basename of the path
-     * @param {Record<string, any>} [options] passed through to sendFile
+     * @param {import("./options").SendFileOptions} [options] passed through to sendFile
      * @param {(err?: Error) => void} [callback]
      */
     download(path, filename, options, callback) {
@@ -1216,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);
             });
 
@@ -1236,7 +1285,10 @@ module.exports = class Response extends Writable {
      */
     cookie(name, value, options) {
         const opt = { ...(options ?? {}) }; // create a new ref because we change original object (https://github.com/dimdenGD/ultimate-express/issues/68)
-        if (opt.signed && !this.req.secret) {
+        // cookie-parser hangs the secret on the request, so it is read off it rather than
+        // declared here: without that middleware there is none, which is what this checks
+        const req = /** @type {any} */ (this.req);
+        if (opt.signed && !req.secret) {
             // the message has to read like this: it is the one Express throws, and it names the
             // thing that is actually missing rather than the library that noticed
             throw new Error('cookieParser("secret") required for signed cookies');
@@ -1254,7 +1306,7 @@ module.exports = class Response extends Writable {
             delete opt.maxAge;
         }
         if (opt.signed) {
-            val = "s:" + sign(val, this.req.secret);
+            val = "s:" + sign(val, req.secret);
         }
 
         if (opt.path == null) {
@@ -1304,10 +1356,18 @@ module.exports = class Response extends Writable {
      */
     format(object) {
         const keys = Object.keys(object).filter((v) => v !== "default");
-        const key = keys.length > 0 ? this.req.accepts(keys) : false;
+        // accepts answers the whole list only when asked with no arguments; given types it
+        // answers the best of them, or false
+        const key = keys.length > 0 ? /** @type {string|false} */ (this.req.accepts(keys)) : false;
 
         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);
@@ -1501,6 +1561,10 @@ module.exports = class Response extends Writable {
         return this.set("content-type", ct);
     }
 
+    /**
+     * express carries both names for the same method, and middleware reaches for either.
+     * @type {(type: string) => any}
+     */
     contentType = this.type;
 
     /**