fulmine.js 5.0.0 → 5.1.1

package/src/response.js

@@ -103,6 +103,22 @@ class Socket extends EventEmitter {
     }
 }
 
+// One status line per code, built on first use: the default path, with no custom reason phrase,
+// paid a template string and a trim per request for a line that never changes. Bounded to real
+// HTTP codes so a wild writeHead value cannot grow the array or flip it into dictionary mode.
+const STATUS_LINES = [];
+/**
+ * @param {number} code
+ * @param {string|undefined} text an explicit reason phrase, which bypasses the cache
+ * @returns {string} the uWS status line, e.g. "200 OK"
+ */
+function statusLine(code, text) {
+    if (text === undefined && Number.isInteger(code) && code >= 100 && code <= 999) {
+        return STATUS_LINES[code] ?? (STATUS_LINES[code] = code + " " + (statuses.message[code] ?? "unknown"));
+    }
+    return `${code} ${text ?? statuses.message[code] ?? "unknown"}`.trim();
+}
+
 module.exports = class Response extends Writable {
     /** @type {Socket|null} */
     #socket = null;
@@ -117,9 +133,6 @@ module.exports = class Response extends Writable {
 
     req;
 
-    /** @type {Set<any>|undefined} the app's live-response set, see Application#handleRequest */
-    _pendingIn;
-
     /**
      * Built for every request, right after the Request it belongs to. The headers start with the
      * two that describe the connection, since every response carries them, and x-powered-by only
@@ -162,23 +175,38 @@ module.exports = class Response extends Writable {
         }
 
         this.body = undefined;
-        this.on("error", (err) => {
-            if (this.finished) {
-                return;
-            }
-            this._res.cork(() => {
-                this._res.close();
-                this.finished = true;
-                this.#socket?.emit("close");
-            });
-        });
-        this.once("close", () => {
-            this.#ended = true;
-            // the application's graceful close() waits on this set, see its handleRequest
-            this._pendingIn?.delete(this);
+        // 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);
+    }
+
+    /** @param {Error} err */
+    _onAbortError(err) {
+        if (this.finished) {
+            return;
+        }
+        this._res.cork(() => {
+            this._res.close();
+            this.finished = true;
+            this.#socket?.emit("close");
         });
     }
 
+    /**
+     * on(), not once(), so this must stay idempotent: end() emits 'close' by hand and a later
+     * destroy() makes Writable emit it again.
+     */
+    _onCloseCleanup() {
+        this.#ended = true;
+        // the application's graceful close() waits on this set, which lives on the per-app
+        // response prototype layer, see the Application constructor
+        /** @type {any} */ (this)._pendingIn?.delete(this);
+    }
+
     /**
      * Where node keeps the outgoing headers of an OutgoingMessage. Only code going through node's
      * own header path ever looks, cookie-session being the one in this project's tests, so the
@@ -247,9 +275,11 @@ module.exports = class Response extends Writable {
             if (!this.headersSent) {
                 this.writeHead(this.statusCode);
                 // "unknown" and not the bare number: node writes that reason phrase for a code it
-                // has no message for, so the raw status lines match
-                const statusMessage = this.statusText ?? statuses.message[this.statusCode] ?? "unknown";
-                this._res.writeStatus(`${this.statusCode} ${statusMessage}`.trim());
+                // has no message for, so the raw status lines match. The default 200 with no
+                // phrase is uWS's own head, byte for byte, so it is not written at all
+                if (this.statusCode !== 200 || this.statusText !== undefined) {
+                    this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+                }
                 this.writeHeaders(typeof chunk === "string");
             }
 
@@ -353,13 +383,18 @@ module.exports = class Response extends Writable {
         // the connection is closing. That happens both when the client asked and when something
         // else set the header on the way out, which is what a proxy passing an upstream response
         // through does.
-        const connection = this.headers["connection"];
-        const closing = typeof connection === "string" && connection.toLowerCase() === "close";
-        for (const header in this.headers) {
+        const headers = this.headers;
+        const res = this._res;
+        const connection = headers["connection"];
+        // length before lowercasing: no string of another length can lowercase to "close", and
+        // 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 (const header in headers) {
             if (closing && header === "keep-alive") {
                 continue;
             }
-            const value = this.headers[header];
+            const value = headers[header];
             if (header === "content-length") {
                 // if content-length is set, disable chunked transfer encoding, since size is known
                 this.chunkedTransfer = false;
@@ -368,10 +403,10 @@ module.exports = class Response extends Writable {
             }
             if (Array.isArray(value)) {
                 for (const val of value) {
-                    this._res.writeHeader(header, val);
+                    res.writeHeader(header, val);
                 }
             } else {
-                this._res.writeHeader(header, value);
+                res.writeHeader(header, value);
             }
         }
         this.headersSent = true;
@@ -446,48 +481,67 @@ module.exports = class Response extends Writable {
             return this;
         }
         this.writeHead(this.statusCode);
-        this._res.cork(() => {
-            if (!this.headersSent) {
-                // freshness is not decided here. node's end() knows nothing about conditional
-                // requests, and Express answers 304 from send() and from sendFile(), each of
-                // which strips the entity headers first. Deciding it here meant res.end("body")
-                // answered 304 and dropped the body that the caller had just written.
-                // "unknown" for a code without a message, as node's status line has it
-                const statusMessage = this.statusText ?? statuses.message[this.statusCode] ?? "unknown";
-                this._res.writeStatus(`${this.statusCode} ${statusMessage}`.trim());
-                this.writeHeaders(true);
+        // uWS holds the socket corked for the synchronous window of its route handler, and
+        // cork inside cork is a passthrough: the wrapper and its closure are only paid once the
+        // answer has outlived that window, which is what _corkNeeded records
+        if (this._corkNeeded) {
+            this._res.cork(() => this._finish(data, cb));
+        } else {
+            this._finish(data, cb);
+        }
+        return this;
+    }
+
+    /**
+     * The corked tail of end(): status, headers, body and the finish events. Split out so a
+     * synchronous answer calls it straight, already inside uWS's own cork.
+     *
+     * @param {any} data
+     * @param {any} cb
+     */
+    _finish(data, cb) {
+        if (!this.headersSent) {
+            // freshness is not decided here. node's end() knows nothing about conditional
+            // requests, and Express answers 304 from send() and from sendFile(), each of
+            // which strips the entity headers first. Deciding it here meant res.end("body")
+            // answered 304 and dropped the body that the caller had just written.
+            // "unknown" for a code without a message, as node's status line has it.
+            // The default 200 with no phrase is not written at all: uWS emits the identical
+            // "HTTP/1.1 200 OK" head on its own, and the crossing costs more than it says
+            if (this.statusCode !== 200 || this.statusText !== undefined) {
+                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
             }
-            const contentLength = this.headers["content-length"];
-            if (STATUSES_WITHOUT_BODY.has(this.statusCode) || this.statusCode < 200) {
-                // no body and no length describing one, whatever the caller passed. node decides
-                // this the same way, from the status alone, so res.status(304).end("x") sends the
-                // status and nothing else on either.
-                this._res.endWithoutBody();
-            } else if (!data && contentLength) {
-                this._res.endWithoutBody(contentLength.toString());
+            this.writeHeaders(true);
+        }
+        const contentLength = this.headers["content-length"];
+        if (STATUSES_WITHOUT_BODY.has(this.statusCode) || this.statusCode < 200) {
+            // no body and no length describing one, whatever the caller passed. node decides
+            // this the same way, from the status alone, so res.status(304).end("x") sends the
+            // status and nothing else on either.
+            this._res.endWithoutBody();
+        } else if (!data && contentLength) {
+            this._res.endWithoutBody(contentLength.toString());
+        } else {
+            if (data instanceof Buffer) {
+                data = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+            }
+            if (this.req.method === "HEAD") {
+                const length = Buffer.byteLength(data ?? "");
+                this._res.endWithoutBody(length.toString());
             } else {
-                if (data instanceof Buffer) {
-                    data = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
-                }
-                if (this.req.method === "HEAD") {
-                    const length = Buffer.byteLength(data ?? "");
-                    this._res.endWithoutBody(length.toString());
-                } else {
-                    this._res.end(data);
-                }
+                this._res.end(data);
             }
+        }
 
-            this.finished = true;
-            this.#socket?.emit("close");
-            this.emit("finish");
-            this.emit("close");
-            cb &&
-                queueMicrotask(() => {
-                    this.#ended = true;
-                    cb();
-                });
-        });
-        return this;
+        this.finished = true;
+        this.#socket?.emit("close");
+        this.emit("finish");
+        this.emit("close");
+        cb &&
+            queueMicrotask(() => {
+                this.#ended = true;
+                cb();
+            });
     }
 
     /**
@@ -616,7 +670,17 @@ module.exports = class Response extends Writable {
         if (!options) options = new NullObject();
         // the callback is optional: without one, errors go to next(). The router assigns req.next
         // before any handler can run, so by the time sendFile is reachable it is always there.
-        const done = /** @type {(err?: Error) => void} */ (callback ?? this.req.next);
+        // 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;
+        const done = /** @type {(err?: any) => void} */ (
+            (err) => {
+                if (callback) return callback(err);
+                if (err && err.code === "EISDIR") return next();
+                if (err && err.code !== "ECONNABORTED" && err.syscall !== "write") next(err);
+            }
+        );
         // default options
         // Normalised the way send does, and it is not fussiness: max-age takes a non-negative
         // integer count of seconds, so 0.5, -1 and Infinity are all invalid, and a client that
@@ -661,12 +725,10 @@ module.exports = class Response extends Writable {
         // it can go back into path
         const decoded = decode(path);
         if (decoded === -1) {
-            this.status(400);
             return done(httpError(400));
         }
         path = decoded;
         if (~path.indexOf("\0")) {
-            this.status(400);
             return done(httpError(400));
         }
         // send's two branches: with a root the path is normalized first, so an in-root ".." like
@@ -676,18 +738,15 @@ module.exports = class Response extends Writable {
         if (options.root) {
             path = Path.normalize("." + Path.sep + path);
             if (UP_PATH_REGEXP.test(path)) {
-                this.status(403);
                 return done(httpError(403));
             }
             parts = path.split(Path.sep);
             fullpath = Path.resolve(Path.join(options.root, path));
             if (!fullpath.startsWith(Path.resolve(options.root))) {
-                this.status(403);
                 return done(httpError(403));
             }
         } else {
             if (UP_PATH_REGEXP.test(path)) {
-                this.status(403);
                 return done(httpError(403));
             }
             parts = Path.normalize(path).split(Path.sep);
@@ -700,21 +759,18 @@ module.exports = class Response extends Writable {
                 case "allow":
                     break;
                 case "deny":
-                    this.status(403);
                     return done(httpError(403));
                 case "ignore_files": {
                     // the file segment alone: with a root the normalized parts no longer carry a
                     // leading empty segment, so a bare dotfile can be the only part
                     const len = parts.length;
                     if (parts[len - 1].startsWith(".")) {
-                        this.status(404);
                         return done(httpError(404));
                     }
                     break;
                 }
                 case "ignore":
                 default:
-                    this.status(404);
                     return done(httpError(404));
             }
         }
@@ -732,8 +788,7 @@ module.exports = class Response extends Writable {
                 // Express reports a directory as an EISDIR with no status, because send tells it
                 // apart from an error: it emits "directory", and res.sendFile has no listener for
                 // one. So this is not a 404, and an error handler reading err.code sees the code
-                // it expects.
-                this.status(404);
+                // it expects. Without a callback, done() turns it into a plain next().
                 const err = /** @type {any} */ (new Error("EISDIR, read"));
                 err.code = "EISDIR";
                 return done(err);
@@ -785,17 +840,38 @@ module.exports = class Response extends Writable {
 
         // conditional requests
         if (isPreconditionFailure(this.req, this)) {
-            this.status(412);
             return done(httpError(412));
         }
 
+        // if-modified-since, if-none-match. Before range handling, as send orders it: a fresh
+        // request with an unsatisfiable Range gets the 304, never the 416.
+        if (this.req.fresh) {
+            // the same fields send removes: everything describing a body that is not being sent.
+            delete this.headers["content-type"];
+            delete this.headers["content-encoding"];
+            delete this.headers["content-language"];
+            delete this.headers["content-length"];
+            this.status(304);
+            this.end();
+            // the response is complete, so a callback hears about it. Never done(): on success
+            // that would be next(), and the request would fall through to the next handler.
+            if (callback) callback();
+            return;
+        }
+
+        // the start and end options, before the Range header: send serves ranges relative to the
+        // window they select, so both the parse and the Content-Range total use the windowed len
+        let offset = options.start || 0;
+        let len = Math.max(0, stat.size - offset);
+        if (options.end !== undefined) {
+            const bytes = options.end - offset + 1;
+            if (len > bytes) len = bytes;
+        }
+
         // range requests
-        let offset = 0,
-            len = stat.size,
-            ranged = false;
         if (options.acceptRanges) {
             if (this.req.headers.range) {
-                let ranges = this.req.range(stat.size, {
+                let ranges = this.req.range(len, {
                     combine: true
                 });
 
@@ -805,44 +881,36 @@ module.exports = class Response extends Writable {
                 }
 
                 if (ranges === -1) {
-                    this.status(416);
-                    this.headers["content-range"] = `bytes */${stat.size}`;
+                    // the header goes on the response itself, as send writes it before raising
+                    // the error, and the status stays on the error for the handler to apply
+                    this.headers["content-range"] = `bytes */${len}`;
                     return done(httpError(416));
                 }
                 if (ranges !== -2 && ranges.length === 1) {
                     this.status(206);
                     const range = ranges[0];
-                    this.headers["content-range"] = `bytes ${range.start}-${range.end}/${stat.size}`;
-                    offset = range.start;
+                    this.headers["content-range"] = `bytes ${range.start}-${range.end}/${len}`;
+                    offset += range.start;
                     len = range.end - range.start + 1;
-                    ranged = true;
                 }
             }
         }
 
-        // if-modified-since, if-none-match
-        if (this.req.fresh) {
-            // the same fields send removes: everything describing a body that is not being sent.
-            // Content-Range goes too, since a 304 answers the whole conditional request and not
-            // the range that was asked for.
-            delete this.headers["content-type"];
-            delete this.headers["content-encoding"];
-            delete this.headers["content-language"];
-            delete this.headers["content-length"];
-            delete this.headers["content-range"];
-            this.status(304);
-            return this.end();
-        }
+        // 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;
 
         if (this.req.method === "HEAD") {
             // len, not stat.size: a ranged HEAD answers with the length of the selected part,
             // as send sets it before ending
-            this.set("Content-Length", len);
-            return this.end();
+            this.set("Content-Length", String(len));
+            this.end();
+            if (callback) callback();
+            return;
         }
 
         // serve smaller files using workers
-        if (this.app.workers.length && stat.size < 768 * 1024 && !ranged) {
+        if (this.app.workers.length && stat.size < 768 * 1024 && !partial) {
             this.app
                 .readFileWithWorker(fullpath)
                 .then((data) => {
@@ -872,12 +940,12 @@ module.exports = class Response extends Writable {
             const opts = {
                 highWaterMark: HIGH_WATERMARK
             };
-            if (ranged) {
+            if (partial) {
                 opts.start = offset;
                 opts.end = Math.max(offset, offset + len - 1);
             }
             const file = fs.createReadStream(fullpath, opts);
-            this.set("Content-Length", len);
+            this.set("Content-Length", String(len));
             // pipe() forwards nothing from the source, so a read error after the stat, the file
             // gone or unreadable, must reach next()/the callback instead of crashing the process
             file.on("error", (err) => {
@@ -896,6 +964,11 @@ module.exports = class Response extends Writable {
                 this.removeListener("close", cleanup);
                 socket?.removeListener("close", cleanup);
             });
+            // "end" only fires on a full read, and never together with "error", so the callback
+            // hears about completion exactly once, as it does on the worker path
+            if (callback) {
+                file.once("end", () => callback());
+            }
             file.pipe(this);
         }
     }
@@ -915,16 +988,16 @@ module.exports = class Response extends Writable {
         let done = callback;
         /** @type {string|null|undefined} */
         let name = filename;
-        let opts = options || new NullObject();
+        let opts = options || null;
 
         // support function as second or third arg
         if (typeof filename === "function") {
             done = /** @type {any} */ (filename);
             name = null;
-            opts = {};
+            opts = null;
         } else if (typeof options === "function") {
             done = /** @type {any} */ (options);
-            opts = {};
+            opts = null;
         }
 
         // support optional filename, where options may be in it's place
@@ -932,15 +1005,31 @@ module.exports = class Response extends Writable {
             name = null;
             opts = filename;
         }
-        if (!name) {
-            name = Path.basename(path);
-        }
-        if (!opts.root && !isAbsolute(path)) {
-            opts.root = process.cwd();
+
+        // Handed to sendFile as a header option rather than set here, as Express does: headers
+        // from the options only go out once the stat has succeeded, so a 404 or a 403 carries no
+        // Content-Disposition. The Content-Type still comes from the file's own extension.
+        const headers = {
+            "Content-Disposition": contentDisposition(name || path)
+        };
+
+        // merge user-provided headers, which never get to override the disposition
+        if (opts && opts.headers) {
+            for (const key of Object.keys(opts.headers)) {
+                if (key.toLowerCase() !== "content-disposition") {
+                    headers[key] = opts.headers[key];
+                }
+            }
         }
 
-        this.attachment(name);
-        this.sendFile(path, opts, done);
+        // merge user-provided options
+        const merged = Object.create(opts ?? null);
+        merged.headers = headers;
+
+        // resolved here so a relative path works against cwd, exactly as Express resolves it
+        const fullPath = !merged.root ? Path.resolve(path) : path;
+
+        return this.sendFile(fullPath, merged, done);
     }
 
     /**
@@ -1362,7 +1451,8 @@ module.exports = class Response extends Writable {
                     body = `<p>${statuses.message[status]}. Redirecting to ${escapeHtml(address)}</p>`;
                 },
                 default: () => {
-                    this.set("Content-Type", "text/plain; charset=utf-8");
+                    // no Content-Type on purpose: Express leaves the header off entirely when
+                    // the client accepts neither text nor html
                     body = "";
                 }
             });