fulmine.js 5.21.4 → 5.21.6

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.21.4",
+    "version": "5.21.6",
     "description": "Drop-in Express 5 replacement on uWebSockets.js, up to 20x faster. Same API, your middleware and framework keep working.",
     "main": "src/index.js",
     "exports": {

package/src/index.js

@@ -17,27 +17,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// A project on pnpm owns the uWebSockets.js dependency itself, see `npx fulmine.js pnpm`, so the
-// one installed can drift from the one this package pins and was tested against. Said once, at
-// require time, where it reaches every deployment rather than only the ones that run verify.
-{
-    const pinned = /#v?([\d.]+)$/.exec(require("../package.json").dependencies["uWebSockets.js"])?.[1];
-    /** @type {string|undefined} */
-    let installed;
-    try {
-        // its exports map does not expose package.json, so it is read beside the entry point
-        const beside = require("path").join(require.resolve("uWebSockets.js"), "..", "package.json");
-        installed = JSON.parse(require("fs").readFileSync(beside, "utf8")).version;
-    } catch {
-        // nothing to compare against, which is not worth a warning of its own
-    }
-    if (pinned && installed && installed !== pinned) {
-        console.warn(
-            `fulmine.js: uWebSockets.js ${installed} is installed, this version was tested with ${pinned}.\n` +
-                "  On pnpm the pin is the project's own: `npx fulmine.js pnpm` writes the tested one."
-        );
-    }
-}
 const Application = require("./application.js");
 const Router = require("./router.js");
 const Route = require("./route.js");

package/src/middlewares.js

@@ -31,13 +31,43 @@ const parseQuery = require("./parse-query.js");
 const { kGetSafe } = require("./usage.js");
 const { AsyncResource } = require("async_hooks");
 
+// node's unexported Symbol("context_frame"), where an AsyncResource keeps the store it captured,
+// read off the first resource. null when node has none, then every binding keeps its scope
+/** @type {symbol|null|undefined} */
+let kContextFrame;
+// set once an init hook was seen, never cleared: from then on every binding has its scope as before
+let initHooksSeen = false;
+
 /**
- * AsyncResource.bind without node's generic wrapper: ~1.9us per call there, ~0.08 here.
+ * raw-body's wrap: AsyncResource.bind without node's generic wrapper (~1.9us per call there), and no
+ * scope without an AsyncLocalStorage store or an init hook: 2.3 to 3.5us per request in a uWS
+ * callback, +9 to 16% on the arena's POST. new AsyncResource("") throws only while a hook listens.
  *
  * @param {(...args: any[]) => any} fn called with at most one argument by every caller here
  * @returns {(err?: any) => any}
  */
 function bindContext(fn) {
+    if (!initHooksSeen) {
+        /** @type {AsyncResource|undefined} */
+        let probe;
+        try {
+            probe = new AsyncResource("");
+        } catch {
+            initHooksSeen = true;
+        }
+        if (probe !== undefined) {
+            if (kContextFrame === undefined) {
+                kContextFrame =
+                    Object.getOwnPropertySymbols(probe).find((s) => s.description === "context_frame") ?? null;
+            }
+            if (kContextFrame !== null && /** @type {any} */ (probe)[kContextFrame] === undefined) {
+                return fn;
+            }
+            // a store to carry, and no init hook to have seen the empty type: the probe is the resource
+            const resource = probe;
+            return (err) => resource.runInAsyncScope(fn, undefined, err);
+        }
+    }
     const resource = new AsyncResource(fn.name || "bound-anonymous-fn");
     return (err) => resource.runInAsyncScope(fn, undefined, err);
 }
@@ -586,8 +616,14 @@ function serveStatic(root, options) {
             }
             const ext = path.extname(fullpath);
             let i = 0;
-            // no extension on a directory; on the decoded url, as send tries it
-            if (ext === "" && !url.endsWith("/") && options.extensions) {
+            // no extension on a directory; on the decoded url and only after ENOENT, as send does:
+            // ENOTDIR or ENAMETOOLONG report the path asked, not the last extension (fuzz seed 3561875562)
+            if (
+                /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT" &&
+                ext === "" &&
+                !url.endsWith("/") &&
+                options.extensions
+            ) {
                 while (i < options.extensions.length) {
                     try {
                         stat = fs.statSync(fullpath + "." + options.extensions[i]);
@@ -1174,9 +1210,14 @@ const json = createBodyParser(
 
         // strict: only an object or an array is a body
         if (options.strict !== false) {
-            // exactly the four characters body-parser skips
-            // eslint-disable-next-line no-control-regex
-            const first = text.match(/^[\x20\x09\x0a\x0d]*([^\x20\x09\x0a\x0d])/)?.[1];
+            // the four characters body-parser skips, space, tab, LF and CR, with a loop: the regex
+            // allocated a match array per body, 56ns to 14
+            let at = 0;
+            let code = text.charCodeAt(0);
+            while (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) {
+                code = text.charCodeAt(++at);
+            }
+            const first = at < text.length ? text[at] : undefined;
             if (first !== "{" && first !== "[") {
                 // a SyntaxError, as body-parser builds it
                 return next(

package/src/node-shim.js

@@ -15,14 +15,36 @@ limitations under the License.
 */
 
 // A uWS-shaped request and response over node's own, for supertest and http.createServer(app).
-// Not fast and not meant to be. Where the models disagree node's gives way: cork only runs its
-// callback, a status is kept until the first byte of body
+// Not the fast path, app.listen() is, but about 1.5x Express on a hello world on Linux. Where the
+// models disagree node's gives way: cork only runs its callback, a status is kept until the first
+// byte of body
 
 const { IncomingMessage } = require("http");
+const { HEADER_NAME_BUF, HEADER_VALUE_BUF } = require("./response-utils.js");
 
 /** What µWS returns for an address nobody declared. */
 const emptyAddress = new ArrayBuffer(0);
 
+// The strings behind the Buffers writeHeaders hands over for the recurring names and values.
+// Decoded on every response they gave node a new string to check, lowercase and hash each time
+/** @type {Map<unknown, string>} */
+const HEADER_TEXT = new Map();
+for (const cache of [HEADER_NAME_BUF, HEADER_VALUE_BUF]) {
+    for (const text in cache) {
+        HEADER_TEXT.set(cache[text], text);
+    }
+}
+
+/**
+ * A header name or value as node's appendHeader takes it.
+ *
+ * @param {unknown} part
+ * @returns {string}
+ */
+function headerText(part) {
+    return typeof part === "string" ? part : (HEADER_TEXT.get(part) ?? String(part));
+}
+
 /**
  * An IP address as the four or sixteen bytes uWS hands over; unreadable comes back empty.
  *
@@ -93,6 +115,22 @@ function toArrayBuffer(chunk) {
     return /** @type {ArrayBuffer} */ (buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
 }
 
+/**
+ * A body chunk as node's write takes it: a string goes as it is and node encodes it once, with
+ * the head, anything else is copied as toArrayBuffer does.
+ *
+ * @param {ArrayBuffer|Buffer|string} chunk
+ * @returns {Buffer|string}
+ */
+function toNodeChunk(chunk) {
+    return typeof chunk === "string" ? chunk : Buffer.from(toArrayBuffer(chunk));
+}
+
+/** @param {Buffer|string} chunk */
+function byteLength(chunk) {
+    return typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length;
+}
+
 /** uWS's HttpRequest over node's IncomingMessage. */
 class NodeHttpRequest {
     /** @type {import("http").IncomingMessage} */
@@ -241,16 +279,16 @@ class NodeHttpResponse {
     writeHeader(key, value) {
         if (!this._nodeRes.headersSent) {
             // writeHeaders hands the recurring names and values over as Buffers
-            this._nodeRes.appendHeader(String(key), String(value));
+            this._nodeRes.appendHeader(headerText(key), headerText(value));
         }
         return this;
     }
 
     /** @param {ArrayBuffer|Buffer|string} chunk @returns {boolean} false when the socket is full */
     write(chunk) {
-        const buffer = Buffer.from(toArrayBuffer(chunk));
-        this._offset += buffer.length;
-        return this._nodeRes.write(buffer);
+        const data = toNodeChunk(chunk);
+        this._offset += byteLength(data);
+        return this._nodeRes.write(data);
     }
 
     /** @param {ArrayBuffer|Buffer|string} [body] */
@@ -262,9 +300,9 @@ class NodeHttpResponse {
             this._nodeRes.end();
             return this;
         }
-        const buffer = Buffer.from(toArrayBuffer(body));
-        this._offset += buffer.length;
-        this._nodeRes.end(buffer);
+        const data = toNodeChunk(body);
+        this._offset += byteLength(data);
+        this._nodeRes.end(data);
         return this;
     }
 
@@ -298,9 +336,9 @@ class NodeHttpResponse {
         if (!this._nodeRes.headersSent && !this._nodeRes.hasHeader("Content-Length")) {
             this._nodeRes.setHeader("Content-Length", String(totalSize));
         }
-        const buffer = Buffer.from(toArrayBuffer(chunk));
-        const ok = this._nodeRes.write(buffer);
-        this._offset += buffer.length;
+        const data = toNodeChunk(chunk);
+        const ok = this._nodeRes.write(data);
+        this._offset += byteLength(data);
         const done = this._offset >= totalSize;
         if (done) {
             this._nodeRes.end();

package/src/request.js

@@ -999,8 +999,9 @@ module.exports = class Request extends LazyReadable {
         /** @type {string|undefined} */
         let ip;
         if (rawIp.byteLength === 4) {
-            // plain, as node writes an IPv4 peer on an IPv4 socket
-            ip = new Uint8Array(rawIp).join(".");
+            // plain, as node writes an IPv4 peer; by hand, Uint8Array join() was 420us per 1000 requests
+            const bytes = new Uint8Array(rawIp);
+            ip = bytes[0] + "." + bytes[1] + "." + bytes[2] + "." + bytes[3];
         } else if (rawIp.byteLength === 16) {
             const bytes = new Uint8Array(rawIp);
             if (isMappedIPv4(bytes)) {

package/src/response-utils.js

@@ -34,8 +34,30 @@ const kShapeMode =
     Symbol("shapeMode");
 // names setHeader has validated and lowercased, so the constant names middleware writes per
 // request are one Map hit. Insert-only after validation, bounded; only setHeader may insert,
-// the never-throwing readers keep their plain toLowerCase
+// the never-throwing readers have HEADER_KEYS below
 const VALIDATED_HEADER_NAMES = new Map();
+// lowercase names for the header readers, apart from the map above as nothing here is validated.
+// A fresh lowercase key goes through the V8 runtime on res.headers: 76ns against 6 cached, and
+// helmet's removeHeader("X-Powered-By") alone was 190us per thousand requests. Bounded too
+/** @type {Map<string, string>} */
+const HEADER_KEYS = new Map();
+
+/**
+ * The key a header lives under in res.headers, for the readers.
+ *
+ * @param {string} field the name as the caller wrote it
+ * @returns {string}
+ */
+function headerKey(field) {
+    let key = HEADER_KEYS.get(field);
+    if (key === undefined) {
+        key = field.toLowerCase();
+        if (HEADER_KEYS.size < 512 && typeof field === "string") {
+            HEADER_KEYS.set(field, key);
+        }
+    }
+    return key;
+}
 // The names and values that recur on every response, kept as Buffers for the uWS crossing: a Buffer
 // is memcpy'd as it is, a string pays a UTF-8 scan and copy per call. A header that is not here
 // crosses as the string it was. Names must stay lowercase, as writeHeaders receives them. The
@@ -121,6 +143,7 @@ module.exports = {
     kOutHeaders,
     kShapeMode,
     VALIDATED_HEADER_NAMES,
+    headerKey,
     HEADER_NAME_BUF,
     HEADER_VALUE_BUF,
     statusLine,

package/src/response.js

@@ -57,6 +57,7 @@ const {
     kOutHeaders,
     kShapeMode,
     VALIDATED_HEADER_NAMES,
+    headerKey,
     HEADER_NAME_BUF,
     HEADER_VALUE_BUF,
     statusLine,
@@ -77,6 +78,10 @@ const JSON_UTF8 = "application/json; charset=utf-8";
 
 // the seeded Keep-Alive, a constant so setHeader can tell it from one the application set
 const SEEDED_KEEP_ALIVE = "timeout=10";
+// the seeded connection and keep-alive as one value, every response writes them in one call:
+// 572ns to 438 per head with a content-type, on node 26
+const SEEDED_PAIR = "keep-alive\r\nkeep-alive: " + SEEDED_KEEP_ALIVE;
+const SEEDED_PAIR_BUF = Buffer.from(SEEDED_PAIR);
 // send's ceiling for maxAge, one year
 const MAX_MAXAGE = 60 * 60 * 24 * 365 * 1000;
 
@@ -600,8 +605,11 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Writes every header set so far to uWS, the point of no return. Content-Length is kept on
-     * totalSize instead: uWS takes the length through tryEnd or endWithoutBody. One writeHeader
-     * per header: packing the head into one writeStatus measured slower, see issue #11.
+     * totalSize instead: uWS takes the length through tryEnd or endWithoutBody.
+     *
+     * From the third line on the head goes in one writeHeader, joined in the first value, as uWS
+     * writes `name: value\r\n` without reading it. Per head on node 26: helmet's set 3953ns to 1327,
+     * five lines 1013 to 531. One or two lines keep a call each, the join costs what it saves (issue #11).
      *
      * @param {boolean} utf8 unused, kept because node's equivalent takes it and the two callers
      *   differ on what they know about the body
@@ -614,6 +622,16 @@ module.exports = class Response extends LazyWritable {
         // length first: the value is nearly always "keep-alive", which paid a lowercase per response
         const closing =
             typeof connection === "string" && connection.length === 5 && connection.toLowerCase() === "close";
+        // the node shim writes a line with node's appendHeader, that refuses the CRLF of a join
+        const joins = res._nodeRes === undefined;
+        // lines not written yet: the first two apart, from the third on in joined
+        let lines = 0;
+        let pair = false;
+        let firstName = "";
+        let firstValue = "";
+        let secondName = "";
+        let secondValue = "";
+        let joined = "";
         // for..in over an object a few responses delete from (204, 304, 205, a 304 file,
         // removeHeader), rare enough to keep the shape, unlike the request side
         for (const header in headers) {
@@ -637,20 +655,107 @@ module.exports = class Response extends LazyWritable {
                 this.#userChunked = true;
                 continue;
             }
-            // the recurring names and values cross as cached Buffers, see HEADER_NAME_BUF
-            const name = HEADER_NAME_BUF[header] || header;
-            if (Array.isArray(value)) {
-                for (const val of value) {
-                    res.writeHeader(name, HEADER_VALUE_BUF[val] || val);
+            // a string first, nearly every value is one
+            const isText = typeof value === "string";
+            const list = isText || !Array.isArray(value) ? null : value;
+            // only text is joined, the rest crosses alone as before. false is joined as "false", the
+            // content-type res.set stores for an unknown type
+            let joinable = joins && (isText || list !== null || value === false);
+            if (joinable && list !== null) {
+                for (let i = 0; i < list.length; i++) {
+                    if (typeof list[i] !== "string") {
+                        joinable = false;
+                        break;
+                    }
                 }
-            } else {
-                res.writeHeader(name, HEADER_VALUE_BUF[value] || value);
             }
+            if (!joinable) {
+                // the lines before this one go first, so the order on the wire holds
+                if (lines !== 0) {
+                    Response.#writeLines(res, lines, pair, firstName, firstValue, secondName, secondValue, joined);
+                    lines = 0;
+                    pair = false;
+                }
+                // the recurring names and values cross as cached Buffers, see HEADER_NAME_BUF
+                const name = HEADER_NAME_BUF[header] || header;
+                if (list !== null) {
+                    for (const val of list) {
+                        res.writeHeader(name, HEADER_VALUE_BUF[val] || val);
+                    }
+                } else {
+                    res.writeHeader(name, HEADER_VALUE_BUF[value] || value);
+                }
+                continue;
+            }
+            const count = list === null ? 1 : list.length;
+            for (let i = 0; i < count; i++) {
+                const text = list === null ? (value === false ? "false" : value) : list[i];
+                if (
+                    lines === 1 &&
+                    !pair &&
+                    header === "keep-alive" &&
+                    text === SEEDED_KEEP_ALIVE &&
+                    firstName === "connection" &&
+                    firstValue === "keep-alive"
+                ) {
+                    // the seeded pair, one line from here on
+                    pair = true;
+                    continue;
+                }
+                if (lines === 0) {
+                    firstName = header;
+                    firstValue = text;
+                } else if (lines === 1) {
+                    secondName = header;
+                    secondValue = text;
+                } else if (lines === 2) {
+                    joined =
+                        (pair ? SEEDED_PAIR : firstValue) +
+                        "\r\n" +
+                        secondName +
+                        ": " +
+                        secondValue +
+                        "\r\n" +
+                        header +
+                        ": " +
+                        text;
+                } else {
+                    joined += "\r\n" + header + ": " + text;
+                }
+                lines++;
+            }
+        }
+        if (lines !== 0) {
+            Response.#writeLines(res, lines, pair, firstName, firstValue, secondName, secondValue, joined);
         }
         this.headersSent = true;
         this.#headOut = true;
     }
 
+    /**
+     * Writes the lines of writeHeaders: one or two a call each, three or more in one call.
+     *
+     * @param {import("uWebSockets.js").HttpResponse} res
+     * @param {number} lines how many, the seeded pair counted as one
+     * @param {boolean} pair whether the first line is the seeded pair
+     * @param {string} firstName
+     * @param {string} firstValue
+     * @param {string} secondName
+     * @param {string} secondValue
+     * @param {string} joined the first value with the other lines after it
+     */
+    static #writeLines(res, lines, pair, firstName, firstValue, secondName, secondValue, joined) {
+        const name = HEADER_NAME_BUF[firstName] || firstName;
+        if (lines > 2) {
+            res.writeHeader(name, joined);
+            return;
+        }
+        res.writeHeader(name, pair ? SEEDED_PAIR_BUF : HEADER_VALUE_BUF[firstValue] || firstValue);
+        if (lines === 2) {
+            res.writeHeader(HEADER_NAME_BUF[secondName] || secondName, HEADER_VALUE_BUF[secondValue] || secondValue);
+        }
+    }
+
     /**
      * node's, called before a body when writeHead never was. Guarded here: the compression module
      * calls it on the strength of node's _header, which this response does not keep.
@@ -1473,7 +1578,7 @@ module.exports = class Response extends LazyWritable {
      * @returns {boolean}
      */
     hasHeader(name) {
-        return this.headers[name.toLowerCase()] !== undefined;
+        return this.headers[headerKey(name)] !== undefined;
     }
 
     /**
@@ -1502,7 +1607,7 @@ module.exports = class Response extends LazyWritable {
      * @returns {this}
      */
     appendHeader(name, value) {
-        const key = name.toLowerCase();
+        const key = headerKey(name);
         const current = this.headers[key];
         if (current === undefined) {
             return this.setHeader(name, value);
@@ -1563,7 +1668,7 @@ module.exports = class Response extends LazyWritable {
                 this.set(header, fields[header]);
             }
         } else {
-            const name = field.toLowerCase();
+            const name = headerKey(field);
             // coerced here as Express does, so res.get answers what was sent
             let out = Array.isArray(value) ? value.map(String) : String(value);
             if (name === "content-type") {
@@ -1592,7 +1697,7 @@ module.exports = class Response extends LazyWritable {
      * @returns {string|string[]|undefined}
      */
     get(field) {
-        const name = field.toLowerCase();
+        const name = headerKey(field);
         const value = this.headers[name];
         // Content-Length is uWS's, measured from the body it was handed: worked out here only for
         // whoever asks, morgan's common and combined formats do, and kept
@@ -1631,7 +1736,7 @@ module.exports = class Response extends LazyWritable {
         if (this.headersSent) {
             throw headersSentError("remove");
         }
-        const key = field.toLowerCase();
+        const key = headerKey(field);
         // helmet removes a header most responses never carry, and a delete is a runtime call
         if (key in this.headers) {
             delete this.headers[key];

package/src/uws.js

@@ -21,6 +21,30 @@ limitations under the License.
 /** @type {any} */
 let uWS;
 
+/**
+ * A project on pnpm owns the uWebSockets.js dependency itself, see `npx fulmine.js pnpm`, so the
+ * one installed can drift from the one this package pins and was tested against. Said once, when
+ * it is loaded: an app served through node's http never loads it and has nothing to hear.
+ */
+function warnOnDrift() {
+    const pinned = /#v?([\d.]+)$/.exec(require("../package.json").dependencies["uWebSockets.js"])?.[1];
+    /** @type {string|undefined} */
+    let installed;
+    try {
+        // its exports map does not expose package.json, so it is read beside the entry point
+        const beside = require("path").join(require.resolve("uWebSockets.js"), "..", "package.json");
+        installed = JSON.parse(require("fs").readFileSync(beside, "utf8")).version;
+    } catch {
+        // nothing to compare against, which is not worth a warning of its own
+    }
+    if (pinned && installed && installed !== pinned) {
+        console.warn(
+            `fulmine.js: uWebSockets.js ${installed} is installed, this version was tested with ${pinned}.\n` +
+                "  On pnpm the pin is the project's own: `npx fulmine.js pnpm` writes the tested one."
+        );
+    }
+}
+
 /**
  * The µWS module. H3App, DeclarativeResponse and _cfg exist at runtime but are missing from the
  * .d.ts the package ships, so it is handed back loosely typed.
@@ -29,6 +53,7 @@ let uWS;
  */
 function loadUWS() {
     if (uWS === undefined) {
+        warnOnDrift();
         uWS = /** @type {any} */ (require("uWebSockets.js"));
         try {
             // disable Uwebsockets header