fulmine.js 5.1.2 → 5.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.1.2",
+    "version": "5.1.4",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -70,7 +70,7 @@
         "cookie": "^1.1.1",
         "cookie-signature": "^1.2.2",
         "encodeurl": "^2.0.0",
-        "fast-querystring": "^1.1.2",
+        "fast-decode-uri-component": "^1.0.1",
         "fast-zlib": "^2.0.1",
         "fresh": "^2.0.0",
         "iconv-lite": "^0.7.3",
@@ -131,6 +131,7 @@
         "express-rate-limit": "^8.5.2",
         "express-session": "^1.19.0",
         "express-subdomain": "^1.0.6",
+        "fast-querystring": "^1.1.2",
         "globals": "^17.8.0",
         "graphql-http": "^1.22.4",
         "helmet": "^8.2.0",

package/src/application.js

@@ -28,7 +28,7 @@ const {
     fastQueryParse,
     NullObject
 } = require("./utils.js");
-const querystring = require("fast-querystring");
+const parseQuery = require("./parse-query.js");
 const Request = require("./request.js");
 const Response = require("./response.js");
 const ViewClass = require("./view.js");
@@ -77,6 +77,13 @@ class FSWorker {
     }
 }
 
+// the worker path's own bound: a file bigger than this streams instead, so the cache never
+// holds an entry the read path would not have produced whole
+const FILE_CACHE_MAX_ENTRY = 768 * 1024;
+// oldest-first once the budget is spent. A static directory that beats this is being served by
+// something other than an application server anyway
+const FILE_CACHE_BUDGET = 64 * 1024 * 1024;
+
 class Application extends Router {
     /**
      * @param {object} [settings] the options express() takes. uwsOptions goes to uWS and decides
@@ -187,10 +194,17 @@ class Application extends Router {
         // the uWS listen socket, and the responses being served right now: close() stops the
         // first and waits for the second, the way node's server.close() does
         this._listenSocket = undefined;
-        this._pendingResponses = new Set();
-        // on the per-app prototype layer, not per response: the set is the same for every
-        // response this app serves, and the per-request write was pure repetition
-        /** @type {any} */ (this.response)._pendingIn = this._pendingResponses;
+        // readSmallFile's cache and its in-flight reads, see the method
+        this._fileCache = new Map();
+        this._fileCacheBytes = 0;
+        this._fileReadsInFlight = new Map();
+        // the responses being served right now, an intrusive list: linking is three pointer
+        // stores where a Set paid identity hashing and table upkeep per request. A holder object
+        // rather than a bare field, because the callable app copies own scalars by value and two
+        // copies of a head would disagree; an object rides by reference, the way the Set did
+        this._pending = /** @type {{ head: any }} */ ({ head: null });
+        // on the per-app prototype layer, not per response, same as the Set was
+        /** @type {any} */ (this.response)._pendingIn = this._pending;
         this._draining = false;
         // read here, at construction, the way express does; an empty NODE_ENV means development,
         // which the ?? in the shared default would miss
@@ -250,6 +264,56 @@ class Application extends Router {
         });
     }
 
+    /**
+     * A small file through the worker pool, with two things on top: concurrent asks for the same
+     * path share one read, and the bytes of an unchanged file come from a bounded cache,
+     * validated against the stat the caller already paid for, so a touched file is re-read.
+     * A hit completes on a macrotask, which is when a worker's answer would have arrived; code
+     * that passed the suites against worker timing keeps passing against this.
+     * `app.set("file cache", false)` turns the cache off; the shared read stays.
+     *
+     * @param {string} fullpath
+     * @param {import("fs").Stats} stat
+     * @returns {Promise<Buffer>}
+     */
+    readSmallFile(fullpath, stat) {
+        const caching = this.get("file cache");
+        if (caching) {
+            const cached = this._fileCache.get(fullpath);
+            if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+                return new Promise((resolve) => setImmediate(resolve, cached.data));
+            }
+        }
+        let pending = this._fileReadsInFlight.get(fullpath);
+        if (pending) {
+            return pending;
+        }
+        pending = this.readFileWithWorker(fullpath).then((data) => {
+            if (caching && stat.size <= FILE_CACHE_MAX_ENTRY) {
+                const existing = this._fileCache.get(fullpath);
+                if (existing) {
+                    this._fileCacheBytes -= existing.size;
+                    this._fileCache.delete(fullpath);
+                }
+                this._fileCache.set(fullpath, { mtimeMs: stat.mtimeMs, size: stat.size, data });
+                this._fileCacheBytes += stat.size;
+                for (const [key, entry] of this._fileCache) {
+                    if (this._fileCacheBytes <= FILE_CACHE_BUDGET) {
+                        break;
+                    }
+                    this._fileCache.delete(key);
+                    this._fileCacheBytes -= entry.size;
+                }
+            }
+            return data;
+        });
+        this._fileReadsInFlight.set(fullpath, pending);
+        // never cached past settlement: a rejection clears the slot the same way
+        const clear = () => this._fileReadsInFlight.delete(fullpath);
+        pending.then(clear, clear);
+        return pending;
+    }
+
     /**
      * Reads or writes an application setting. One argument is the getter, and the check is on
      * `arguments.length`, so `set(key, undefined)` still writes. Some keys have a side effect:
@@ -281,7 +345,7 @@ class Application extends Router {
             if (value === "extended") {
                 this.settings["query parser fn"] = fastQueryParse;
             } else if (value === "simple" || value === true) {
-                this.settings["query parser fn"] = querystring.parse;
+                this.settings["query parser fn"] = parseQuery;
             } else if (typeof value === "function") {
                 this.settings["query parser fn"] = value;
             } else if (value === false) {
@@ -374,8 +438,16 @@ class Application extends Router {
         // removal rides the close listener the Response constructor already has, since a second
         // once() per request measured a tenth of a microsecond on the hot path.
         // An aborted response only flips its flags without emitting 'close', which is why
-        // close()'s drain also sweeps the set by those flags instead of trusting this alone
-        this._pendingResponses.add(request.res);
+        // close()'s drain also sweeps the list by those flags instead of trusting this alone
+        const response = request.res;
+        const pending = this._pending;
+        response._pendingLinked = true;
+        response._pendingPrev = null;
+        response._pendingNext = pending.head;
+        if (pending.head !== null) {
+            pending.head._pendingPrev = response;
+        }
+        pending.head = response;
         return request;
     }
 
@@ -388,6 +460,9 @@ class Application extends Router {
         this.uwsApp.any("/*", async (res, req) => {
             const request = this.handleRequest(res, req);
             const response = request.res;
+            // armed up front here: this handler awaits, so the response outlives the callback
+            // on every path through it
+            this._armAbort(res, response);
 
             try {
                 const routed = this._routeRequest(request, response);
@@ -695,19 +770,23 @@ class Application extends Router {
             this.uwsApp.close();
             this.emit("close");
         };
-        if (this._pendingResponses.size === 0) {
+        if (this._pending.head === null) {
             process.nextTick(finish);
             return this;
         }
-        // a finished response emits 'close' and removes itself; an aborted one only flips its
+        // a finished response emits 'close' and unlinks itself; an aborted one only flips its
         // flags, so the drain sweeps by them. The timer also keeps the loop alive until done.
         const sweep = setInterval(() => {
-            for (const response of this._pendingResponses) {
+            let response = this._pending.head;
+            while (response !== null) {
+                // taken before the unlink, which nulls the pointers
+                const next = response._pendingNext;
                 if (response.finished || response.aborted) {
-                    this._pendingResponses.delete(response);
+                    response._unlinkPending();
                 }
+                response = next;
             }
-            if (this._pendingResponses.size === 0) {
+            if (this._pending.head === null) {
                 clearInterval(sweep);
                 finish();
             }

package/src/middlewares.js

@@ -21,7 +21,7 @@ const bytes = require("bytes");
 const zlib = require("fast-zlib");
 const typeis = require("type-is");
 const qs = require("qs");
-const querystring = require("fast-querystring");
+const parseQuery = require("./parse-query.js");
 const { AsyncResource } = require("async_hooks");
 const { fastQueryParse, NullObject, asStatError, httpError, memoizeByString } = require("./utils.js");
 
@@ -954,7 +954,8 @@ const urlencoded = createBodyParser(
                     })
                 );
             } else {
-                req.body = querystring.parse(body);
+                // the vendored parser, so an urlencoded body inspects like req.query does
+                req.body = parseQuery(body);
             }
         } catch (e) {
             // qs reports a depth overflow as a RangeError with its own wording; body-parser

package/src/node-shim.js

@@ -395,6 +395,8 @@ function serveNodeRequest(router, nodeReq, nodeRes, next) {
     const shimReq = new NodeHttpRequest(nodeReq);
     const request = router.handleRequest(shimRes, shimReq);
     const response = request.res;
+    // the shim's onAborted rides node's own close event, needed on every request here
+    router._armAbort(shimRes, response);
 
     return router._routeRequest(request, response).then((matched) => {
         if (matched || response.headersSent || response.aborted) {

package/src/parse-query.js

@@ -0,0 +1,120 @@
+"use strict";
+
+/*
+The parser from fast-querystring 1.1.x (MIT, Copyright (c) Yagiz Nizipli,
+https://github.com/anonrig/fast-querystring), vendored for one change: the result is a bare
+Object.create(null) instead of the library's Empty-constructor trick. The trick is faster to
+construct but node inspects it as "Empty <[Object: null prototype] {}>", where Express shows
+"[Object: null prototype]", and matching that used to cost an Object.assign copy of every parse
+on every query-carrying request. The copy was worth more than the trick.
+*/
+
+const fastDecode = require("fast-decode-uri-component");
+
+const plusRegex = /\+/g;
+
+/**
+ * node's querystring.parse semantics on a null-prototype result: repeated keys accumulate into
+ * arrays, '+' is a space, percent sequences decode when present and stay literal when broken.
+ *
+ * @param {string} input
+ * @returns {Record<string, string | string[]>}
+ */
+function parseQuery(input) {
+    const result = Object.create(null);
+
+    if (typeof input !== "string") {
+        return result;
+    }
+
+    const inputLength = input.length;
+    let key;
+    let value = "";
+    let startingIndex = -1;
+    let equalityIndex = -1;
+    let shouldDecodeKey = false;
+    let shouldDecodeValue = false;
+    let keyHasPlus = false;
+    let valueHasPlus = false;
+    let hasBothKeyValuePair;
+    let c;
+
+    // a boundary of input.length + 1, so the last pair is handled inside the loop
+    for (let i = 0; i < inputLength + 1; i++) {
+        c = i !== inputLength ? input.charCodeAt(i) : 38;
+
+        // '&' or the end of the input closes the current pair
+        if (c === 38) {
+            hasBothKeyValuePair = equalityIndex > startingIndex;
+
+            // the equality index doubles as the end of the key when there was no '='
+            if (!hasBothKeyValuePair) {
+                equalityIndex = i;
+            }
+
+            key = input.slice(startingIndex + 1, equalityIndex);
+
+            // only a pair with at least an '=' or a non-empty key lands in the result
+            if (hasBothKeyValuePair || key.length > 0) {
+                if (keyHasPlus) {
+                    key = key.replace(plusRegex, " ");
+                }
+                if (shouldDecodeKey) {
+                    key = fastDecode(key) || key;
+                }
+                if (hasBothKeyValuePair) {
+                    value = input.slice(equalityIndex + 1, i);
+                    if (valueHasPlus) {
+                        value = value.replace(plusRegex, " ");
+                    }
+                    if (shouldDecodeValue) {
+                        value = fastDecode(value) || value;
+                    }
+                }
+
+                const currentValue = result[key];
+                if (currentValue === undefined) {
+                    result[key] = value;
+                } else {
+                    // value.pop is cheaper than Array.isArray here, as upstream measured
+                    if (currentValue.pop) {
+                        currentValue.push(value);
+                    } else {
+                        result[key] = [currentValue, value];
+                    }
+                }
+            }
+
+            value = "";
+            startingIndex = i;
+            equalityIndex = i;
+            shouldDecodeKey = false;
+            shouldDecodeValue = false;
+            keyHasPlus = false;
+            valueHasPlus = false;
+        } else if (c === 61) {
+            if (equalityIndex <= startingIndex) {
+                equalityIndex = i;
+            } else {
+                // a second '=' belongs to the value and needs decoding
+                shouldDecodeValue = true;
+            }
+        } else if (c === 43) {
+            if (equalityIndex > startingIndex) {
+                valueHasPlus = true;
+            } else {
+                keyHasPlus = true;
+            }
+        } else if (c === 37) {
+            if (equalityIndex > startingIndex) {
+                shouldDecodeValue = true;
+            } else {
+                shouldDecodeKey = true;
+            }
+        }
+    }
+
+    return result;
+}
+
+module.exports = parseQuery;

package/src/request.js

@@ -22,6 +22,7 @@ const parseRange = require("range-parser");
 const proxyaddr = require("proxy-addr");
 const { isIP } = require("node:net");
 const fresh = require("fresh");
+const parseQuery = require("./parse-query.js");
 const { Readable } = require("stream");
 
 // accepts, type-is, proxy-addr and fresh all declare a node IncomingMessage and read nothing off
@@ -540,10 +541,14 @@ module.exports = class Request extends Readable {
             return this.#cachedQuery;
         }
         const qp = this.app.get("query parser fn");
-        // copied onto a plain null-prototype object, or node inspects fast-querystring's result as
-        // "Empty <[Object: null prototype] {}>" where Express shows "[Object: null prototype]".
-        // Object.create(null) and not { __proto__: null }: 318ns against 640
-        const parsed = qp ? Object.assign(Object.create(null), qp(this._rawQuery)) : Object.create(null);
+        // the vendored default already answers on a bare null prototype, so it goes out as is;
+        // any other parser is copied onto one, which is what kept fast-querystring's result from
+        // inspecting as "Empty <[Object: null prototype] {}>" where Express shows the bare form
+        const parsed = qp
+            ? qp === parseQuery
+                ? parseQuery(this._rawQuery)
+                : Object.assign(Object.create(null), qp(this._rawQuery))
+            : Object.create(null);
         this.#cachedQuery = parsed;
         return parsed;
     }

package/src/response.js

@@ -202,9 +202,32 @@ module.exports = class Response extends Writable {
      */
     _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);
+        this._unlinkPending();
+    }
+
+    /**
+     * Takes this response out of its app's pending list, which the graceful close() drains. The
+     * list head lives in a holder on the per-app response prototype layer, see the Application
+     * constructor; the linked flag makes a second call, from the drain or a late 'close', a no-op.
+     */
+    _unlinkPending() {
+        if (this._pendingLinked !== true) {
+            return;
+        }
+        this._pendingLinked = false;
+        const pending = /** @type {any} */ (this)._pendingIn;
+        const prev = this._pendingPrev;
+        const next = this._pendingNext;
+        if (prev) {
+            prev._pendingNext = next;
+        } else if (pending && pending.head === this) {
+            pending.head = next;
+        }
+        if (next) {
+            next._pendingPrev = prev;
+        }
+        this._pendingPrev = null;
+        this._pendingNext = null;
     }
 
     /**
@@ -911,7 +934,7 @@ module.exports = class Response extends Writable {
         // serve smaller files using workers
         if (this.app.workers.length && stat.size < 768 * 1024 && !partial) {
             this.app
-                .readFileWithWorker(fullpath)
+                .readSmallFile(fullpath, stat)
                 .then((data) => {
                     if (this.finished || this.aborted) {
                         // the client went away while the worker was reading. Express reports

package/src/router.js

@@ -1345,11 +1345,22 @@ module.exports = class Router extends EventEmitter {
         const response = new this._response(res, request, this);
         request.res = response;
         response.req = request;
-        res.onAborted(onNativeAborted.bind(response));
 
         return request;
     }
 
+    /**
+     * Tells uWS whom to call on a client abort. Out of handleRequest, because uWS only needs it
+     * for a response that outlives its handler callback: the native handler arms it in its
+     * finally when the answer is still pending, which on a synchronous route it never is.
+     *
+     * @param {any} res uWS response
+     * @param {any} response
+     */
+    _armAbort(res, response) {
+        res.onAborted(onNativeAborted.bind(response));
+    }
+
     /**
      * Whether a route registered later in the same router could match a path this one matches.
      *
@@ -1437,6 +1448,11 @@ module.exports = class Router extends EventEmitter {
                     // whatever runs after this line is outside the cork uWS held for this
                     // callback, so later writes have to open their own
                     response._corkNeeded = true;
+                    // an abort can only arrive after this callback returns, so a response that
+                    // already finished inside it never needs uWS told at all
+                    if (!response.finished) {
+                        this._armAbort(res, response);
+                    }
                 }
             };
         };

package/src/utils.js

@@ -19,7 +19,7 @@ const mime = require("mime-types");
 const path = require("path");
 const proxyaddr = require("proxy-addr");
 const qs = require("qs");
-const querystring = require("fast-querystring");
+const parseQuery = require("./parse-query.js");
 const crypto = require("crypto");
 const statuses = require("statuses");
 const { Stats } = require("fs");
@@ -46,7 +46,8 @@ function fastQueryParse(query, options) {
     }
     if (len <= 128) {
         if (!query.includes("[") && !query.includes("%5B") && !query.includes(".") && !query.includes("%2E")) {
-            return Object.assign(Object.create(null), querystring.parse(query));
+            // already on a bare null prototype, no copy needed, see parse-query.js
+            return parseQuery(query);
         }
     }
     return Object.assign(Object.create(null), qs.parse(query, options));
@@ -564,7 +565,7 @@ const defaultSettings = {
     etag: "weak",
     "etag fn": () => createETagGenerator({ weak: true }),
     "query parser": "simple",
-    "query parser fn": () => querystring.parse,
+    "query parser fn": () => parseQuery,
     "subdomain offset": 2,
     "trust proxy": false,
     views: () => path.join(process.cwd(), "views"),
@@ -573,6 +574,9 @@ const defaultSettings = {
     // asking which framework is running, and every hardening guide says to remove it. Set it back
     // to true if something depends on it.
     "x-powered-by": false,
+    // fulmine's own: unchanged small files served by sendFile come from a bounded cache
+    // validated per request against the file's stat, see Application#readSmallFile
+    "file cache": true,
     // "case sensitive routing" is deliberately absent: unset means insensitive, as in Express 5.
     // The native µWS router matches bytes, so the compiler in _compileOptimizedRoutes only hands
     // it routes whose earlier siblings it can prove agree under either case rule.