fulmine.js 5.0.0 → 5.1.0

package/src/request.js

@@ -83,6 +83,20 @@ function formatIPv6(groups) {
     return out;
 }
 
+/**
+ * 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
+ * bind. uWS already hands mapped peers over as sixteen bytes; four bytes only reach req.ip from a
+ * v4-bound native listener or through the node shim, whose server supertest binds dual stack.
+ *
+ * @param {any} app the application the request arrived at
+ * @returns {boolean}
+ */
+function mapsIPv4Peer(app) {
+    const host = app._listenHost;
+    return !(host && isIP(host) === 4);
+}
+
 const discardedDuplicates = new Set([
     "age",
     "authorization",
@@ -109,6 +123,11 @@ let key = 0;
 // 128 KB of body buffered before uWS is asked to pause
 const READABLE_OPTIONS = { highWaterMark: 128 * 1024 };
 
+// Whose headers the shared collector below is filling. uWS's forEach is synchronous and runs no
+// user code, so the handoff cannot interleave; module-level so the callback exists once instead
+// of once per request.
+let currentRequest = null;
+
 module.exports = class Request extends Readable {
     /** @type {Record<string, any>|null} */
     #cachedQuery = null;
@@ -133,6 +152,30 @@ module.exports = class Request extends Readable {
 
     res;
 
+    // one function for every request, fed through currentRequest: an arrow in the constructor
+    // captured `this`, which cost a context and a function allocation per request
+    static #collectHeader = (headerKey, value) => {
+        const r = currentRequest;
+        r.#rawHeadersEntries.push(headerKey, value);
+        // spotted in the loop that is running anyway: a client asking for the connection to be
+        // closed must not be answered that it is being kept alive. The response is built right
+        // after this and reads the flag.
+        if (
+            headerKey.length === 10 &&
+            headerKey === "connection" &&
+            value.length === 5 &&
+            value.toLowerCase() === "close"
+        ) {
+            r._connectionClose = true;
+        } else if (
+            (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;
+        }
+    };
+
     optimizedParams;
 
     _error;
@@ -154,15 +197,9 @@ module.exports = class Request extends Readable {
         this._res = res;
         this._req = req;
         this.readable = true;
-        this._req.forEach((key, value) => {
-            this.#rawHeadersEntries.push(key, value);
-            // spotted in the loop that is running anyway: a client asking for the connection to be
-            // closed must not be answered that it is being kept alive. The response is built right
-            // after this and reads the flag.
-            if (key.length === 10 && key === "connection" && value.length === 5 && value.toLowerCase() === "close") {
-                this._connectionClose = true;
-            }
-        });
+        currentRequest = this;
+        this._req.forEach(Request.#collectHeader);
+        currentRequest = null;
         this.routeCount = 1;
         this.key = key++;
         if (key > 100000) {
@@ -206,11 +243,13 @@ module.exports = class Request extends Readable {
         // The router builds it the first time it has something to put in it.
         this._matchedMethods = this._isOptions ? new Set() : null;
         this._paramCalled = null;
-        this._stack = [];
+        // 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;
-        this._paramStack = [];
+        this._paramStack = null;
         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) {
@@ -227,32 +266,46 @@ module.exports = class Request extends Readable {
             this.method === "PUT" ||
             this.method === "PATCH" ||
             this.method === "QUERY" ||
-            (additionalMethods && additionalMethods.includes(this.method))
+            (additionalMethods && additionalMethods.includes(this.method)) ||
+            // any request that declares a body carries one, whatever the verb: a GET with
+            // content-length left unread would end this stream empty and poison the keep-alive
+            // connection with its unconsumed bytes. uWS itself discards GET bodies, so this is
+            // the node shim's path
+            /** @type {any} */ (this)._declaresBody
         ) {
-            this._res.onData((ab, isLast) => {
-                this.receivedData = true;
-                if (this.#responseEnded) {
-                    return;
-                }
-                // ab.slice(0) copies the ArrayBuffer; uWS neuters `ab` after this callback,
-                // so a Buffer.from(ab) view would corrupt data left in the Readable queue.
-                const chunk = Buffer.from(ab.slice(0));
-                const accepted = this.push(chunk);
-                // push() may synchronously end the response via a flowing-mode listener.
-                if (!accepted && !isLast && !this.#responseEnded) {
-                    this._res.pause();
-                    this.#paused = true;
-                }
-                if (isLast) {
-                    this.push(null);
-                }
-            });
+            this._subscribeBody();
         } else {
             this.receivedData = true;
             this.push(null);
         }
     }
 
+    /**
+     * Subscribes to the uWS body stream. Out of the constructor so a bodyless request allocates
+     * no closure at all there; must still run during the constructor call, since uWS only feeds a
+     * handler registered before the route handler returns.
+     */
+    _subscribeBody() {
+        this._res.onData((ab, isLast) => {
+            this.receivedData = true;
+            if (this.#responseEnded) {
+                return;
+            }
+            // ab.slice(0) copies the ArrayBuffer; uWS neuters `ab` after this callback,
+            // so a Buffer.from(ab) view would corrupt data left in the Readable queue.
+            const chunk = Buffer.from(ab.slice(0));
+            const accepted = this.push(chunk);
+            // push() may synchronously end the response via a flowing-mode listener.
+            if (!accepted && !isLast && !this.#responseEnded) {
+                this._res.pause();
+                this.#paused = true;
+            }
+            if (isLast) {
+                this.push(null);
+            }
+        });
+    }
+
     /**
      * Whether there is any point still reading the body: once the response is finished or the
      * connection is gone, uWS has nothing left to hand over.
@@ -405,7 +458,10 @@ module.exports = class Request extends Readable {
      * @returns {string}
      */
     get protocol() {
-        const proto = this.app.ssl ? "https" : "http";
+        // express reads socket.encrypted, and middleware does assign to the stand-in; the app's
+        // own ssl flag answers when nothing has built the stand-in yet
+        const conn = this.#cachedConnection;
+        const proto = (conn ? conn.encrypted : this.app.ssl) ? "https" : "http";
         const trust = this.app.get("trust proxy fn");
         if (!trust) {
             return proto;
@@ -481,7 +537,7 @@ module.exports = class Request extends Readable {
 
     /**
      * The hostname's subdomains, furthest from the root first, dropping the last
-     * "subdomain offset" labels. Empty for an IP address.
+     * "subdomain offset" labels. An IP host is one label, never split on its dots.
      * @returns {string[]}
      */
     get subdomains() {
@@ -490,15 +546,14 @@ module.exports = class Request extends Readable {
         }
 
         const hostname = this.hostname;
-        if (!hostname || isIP(hostname)) {
+        if (!hostname) {
             return (this.#cachedSubdomains = []);
         }
 
         const offset = this.app.get("subdomain offset");
-        const parts = hostname.split(".");
-        const subdomains = parts.reverse().slice(offset);
+        const parts = isIP(hostname) ? [hostname] : hostname.split(".").reverse();
 
-        return (this.#cachedSubdomains = subdomains);
+        return (this.#cachedSubdomains = parts.slice(offset));
     }
 
     /**
@@ -531,7 +586,7 @@ module.exports = class Request extends Readable {
         if (!this.rawIp) {
             if (finished) {
                 // fallback once
-                return "127.0.0.1";
+                return mapsIPv4Peer(this.app) ? "::ffff:127.0.0.1" : "127.0.0.1";
             }
             this.rawIp = this._res.getRemoteAddress();
         }
@@ -540,6 +595,9 @@ module.exports = class Request extends Readable {
         if (this.rawIp.byteLength === 4) {
             // ipv4
             ip = new Uint8Array(this.rawIp).join(".");
+            if (mapsIPv4Peer(this.app)) {
+                ip = "::ffff:" + ip;
+            }
         } else if (this.rawIp.byteLength === 16) {
             // ipv6
             const dv = new DataView(this.rawIp);

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,35 @@ 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);
+        // 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
@@ -248,8 +273,7 @@ module.exports = class Response extends Writable {
                 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());
+                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
                 this.writeHeaders(typeof chunk === "string");
             }
 
@@ -353,13 +377,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 +397,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;
@@ -453,8 +482,7 @@ module.exports = class Response extends Writable {
                 // 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._res.writeStatus(statusLine(this.statusCode, this.statusText));
                 this.writeHeaders(true);
             }
             const contentLength = this.headers["content-length"];
@@ -616,7 +644,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 +699,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 +712,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 +733,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 +762,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 +814,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 +855,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 +914,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 +938,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 +962,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 +979,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 +1425,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 = "";
                 }
             });