fulmine.js 5.1.3 → 5.1.6

package/NOTICE

@@ -12,6 +12,10 @@ itself and can be inspected with `git log` and `git shortlog -sn`.
 Fulmine is not affiliated with, endorsed by, or maintained by the authors of
 Ultimate Express.
 
+This product includes code derived from fast-querystring
+(https://github.com/anonrig/fast-querystring), Copyright (c) Yagiz Nizipli,
+licensed under the MIT License, vendored in src/parse-query.js.
+
 As required by section 4(b) of the Apache License, the following are the
 significant changes made to the original work:
 
@@ -19,10 +23,27 @@ significant changes made to the original work:
   - Public API documented, and type checked from those annotations.
   - Router dispatch reworked so a chain of N middlewares allocates one promise
     instead of N, and the mount stack is no longer walked on every hop.
-  - Request bodies are collected into a single buffer instead of being copied
-    once per chunk and again on concatenation.
+  - Request bodies are collected in native code by uWebSockets.js when the
+    length is known, with the size limit enforced before any byte reaches
+    JavaScript, instead of being copied once per chunk and again on
+    concatenation; the body parsers read the few headers they need from the
+    raw header entries and bind the caller's async context only when a read
+    actually goes asynchronous.
   - Empty request bodies now produce the same value each Express body parser
     produces, rather than being skipped.
+  - Routes whose path is a literal are registered as native uWebSockets.js
+    routes, with their path and method handed to the request as
+    registration-time constants.
+  - sendFile answers small unchanged files from a stat-validated cache, and
+    concurrent reads of the same file are coalesced.
+  - The query string parser is vendored from fast-querystring and answers on a
+    bare null prototype, matching how Express displays parsed queries.
+  - Express 5's own test suite runs against Fulmine as a CI gate, from a
+    pinned checkout of Express.
+  - The app is callable as a request listener, so http.createServer(app),
+    supertest and anything else that invokes an app directly keeps working
+    through a node:http shim.
+  - Releases are built and published to npm from CI.
   - Benchmark harness reworked: wrk replaced by autocannon so the suite runs
     anywhere Node does, NODE_ENV is set, load errors and response validation are
     no longer discarded, rows bounded by shared work are labelled, and scenarios

package/README.md

@@ -90,6 +90,31 @@ npx fulmine differences         # print the list below and change nothing
 The command is installed under both `fulmine` and `fulmine.js`. Use `fulmine`: `npx` cannot run a
 command whose name ends in `.js` on Windows, where it exits without a word.
 
+## Docker
+
+Two things about µWebSockets.js make a Dockerfile that works for Express fail here, and both have easy answers:
+
+- **No Alpine.** µWebSockets.js ships prebuilt binaries linked against glibc. Alpine images use musl, so the binary does not load. Use a Debian-based image such as `node:22-slim` instead of `node:22-alpine`.
+- **`git` must be there when `npm install` runs.** µWebSockets.js is not on npm; it is installed straight from GitHub (`github:uNetworking/uWebSockets.js`), and npm uses git to fetch it. Full images like `node:22` have git; `-slim` ones do not.
+
+The clean way to satisfy both is a multi-stage build: install with the full image, run with the slim one.
+
+```dockerfile
+FROM node:22 AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+FROM node:22-slim
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+A single-stage `node:22-slim` image works too if you `apt-get install -y git` before `npm ci`. Prebuilt binaries exist for x64 and arm64 on Linux, macOS and Windows, so nothing is compiled at install time either way.
+
 ## Differences from Express
 
 - `app.listen()` returns the app, not an `http.Server`. There is no node server underneath, so `server.close()`, `server.address()` and anything that attaches itself to a real `http.Server` need a look. `app.close()`, `app.address()` and `app.listening` are there and do what you would expect.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.1.3",
+    "version": "5.1.6",
     "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");
@@ -345,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) {
@@ -460,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);

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");
 
@@ -289,7 +289,10 @@ function serveStatic(root, options) {
     options._ownEtag = true;
 
     return (req, res, next) => {
-        next = AsyncResource.bind(next);
+        // Not bound here: every path down to sendFile is synchronous, statSync included, so the
+        // caller's async context is intact at each of these next() calls. Only sendFile's
+        // completion can arrive on a uWS callback that carries no context, and that one
+        // continuation is bound where it is handed over.
 
         // a file is read, not written: anything but GET and HEAD belongs to whoever comes next, or
         // is refused outright when this middleware is the last word
@@ -410,11 +413,15 @@ function serveStatic(root, options) {
 
         options._stat = stat;
 
-        return res.sendFile(_path, options, (e) => {
-            if (e) {
-                next(options.fallthrough && FALLTHROUGH_STATUSES.has(e.status) ? undefined : e);
-            }
-        });
+        return res.sendFile(
+            _path,
+            options,
+            AsyncResource.bind((e) => {
+                if (e) {
+                    next(options.fallthrough && FALLTHROUGH_STATUSES.has(e.status) ? undefined : e);
+                }
+            })
+        );
     };
 }
 
@@ -462,9 +469,11 @@ function createInflate(contentEncoding) {
  * @param {string} [charsetPolicy] which charsets this parser accepts, as body-parser draws the
  *   lines: "utf" (json, utf-* only), "urlencoded" (utf-8 and iso-8859-1), "any" (anything iconv
  *   knows), or undefined for a parser that never decodes (raw)
+ * @param {boolean} [keepsBuffer] whether the collected buffer itself escapes to the application,
+ *   which rules out handing it a view over uWS memory
  * @returns {(options?: object) => Function} the middleware factory
  */
-function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy) {
+function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy, keepsBuffer) {
     return function (options) {
         // a copy, because everything below writes the parsed values back: with the caller's own
         // object, altering it after the parser was built would alter the parser
@@ -500,6 +509,10 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
         }
         if (typeof options.defaultCharset === "undefined") options.defaultCharset = "utf-8";
 
+        // whether the collected bytes escape the collection callback: the raw parser hands the
+        // buffer itself to the application, and a verify hook may keep what it is shown
+        const copyBody = keepsBuffer || typeof options.verify === "function";
+
         // Whether a content-type is one this parser claims, remembered per parser.
         //
         // Only reached when the caller asked for a wildcard or a list, since a plain type takes the
@@ -514,14 +527,17 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
         let additionalMethods;
 
         return (req, res, next) => {
-            next = AsyncResource.bind(next);
+            // Not bound yet: every return in this prologue is synchronous, so the caller's async
+            // context is still intact and an AsyncResource here would be 1.4 microseconds of
+            // nothing. The bind happens below, only once a real read is about to go async.
 
             // skip reading body twice
             if (req.bodyRead) {
                 return next();
             }
 
-            const type = req.headers["content-type"];
+            // straight from the raw entries: three headers do not justify building the object
+            const type = req._rawHeader("content-type");
 
             // req.body is deliberately left undefined until a parser claims the request. That is
             // what lets a handler tell "nothing parsed this" apart from "the body was empty",
@@ -534,13 +550,13 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 return next();
             }
 
-            const length = req.headers["content-length"];
+            const length = req._rawHeader("content-length");
 
             // No content-length and no transfer-encoding means the request carries no body at all,
             // and a body parser must leave it alone rather than parse nothing into an empty value.
             // type-is applies this before matching the type, but the simpleType shortcut below
             // compares strings directly and would otherwise skip the check.
-            if (req.headers["transfer-encoding"] === undefined && isNaN(length)) {
+            if (req._rawHeader("transfer-encoding") === undefined && isNaN(length)) {
                 return next();
             }
 
@@ -620,7 +636,8 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             const abs = [];
             let inflate;
             let totalSize = 0;
-            const contentEncoding = (req.headers["content-encoding"] || "identity").toLowerCase();
+            const rawContentEncoding = req._rawHeader("content-encoding");
+            const contentEncoding = (rawContentEncoding || "identity").toLowerCase();
             if (!options.inflate && contentEncoding !== "identity") {
                 return next(
                     bodyError("content encoding unsupported", 415, "encoding.unsupported", {
@@ -629,19 +646,64 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 );
             }
             if (options.inflate) {
-                inflate = createInflate(req.headers["content-encoding"]);
+                inflate = createInflate(rawContentEncoding);
                 if (inflate === false) {
                     return next(
                         bodyError(
-                            'unsupported content encoding "' + req.headers["content-encoding"] + '"',
+                            'unsupported content encoding "' + rawContentEncoding + '"',
                             415,
                             "encoding.unsupported",
-                            { encoding: req.headers["content-encoding"] }
+                            {
+                                encoding: rawContentEncoding
+                            }
                         )
                     );
                 }
             }
 
+            // From here the body really gets read, and uWS delivers it on native callbacks that
+            // carry no async context, so this is the one continuation that has to be bound: an
+            // upstream middleware's AsyncLocalStorage must still be there when next runs
+            next = AsyncResource.bind(next);
+
+            // with a known content-length and nothing to decompress, uWS can collect the whole
+            // body in native code: one callback instead of one per chunk, the limit enforced
+            // before any byte reaches JS, and no copy at all - the parsers turn the bytes into
+            // req.body before the callback returns, so a view over uWS's own memory is enough
+            if (!req.receivedData && !inflate && !isNaN(length) && Number(length) > 0 && req._res.collectBody) {
+                req.bodyRead = true;
+                const declared = Number(length);
+                req._res.collectBody(options.limit, (body) => {
+                    if (body === null) {
+                        // over maxSize: uWS refused it natively
+                        return next(
+                            bodyError("request entity too large", 413, "entity.too.large", {
+                                limit: options.limit,
+                                received: options.limit
+                            })
+                        );
+                    }
+                    if (body.byteLength !== declared) {
+                        return next(
+                            bodyError("request size did not match content length", 400, "request.size.invalid", {
+                                expected: declared,
+                                length: declared,
+                                received: body.byteLength
+                            })
+                        );
+                    }
+                    let buf = Buffer.from(body);
+                    if (copyBody) {
+                        buf = Buffer.from(buf);
+                    }
+                    if (!runVerify(req, res, next, options, buf)) {
+                        return;
+                    }
+                    beforeReturn(req, res, next, options, buf, encoding);
+                });
+                return;
+            }
+
             // uWS neuters its ArrayBuffer after the callback, so every chunk has to be copied out of
             // it - and then Buffer.concat copied the whole body a second time. when content-length is
             // known and we aren't inflating, the final size is known up front, so chunks can go
@@ -860,10 +922,17 @@ const json = createBodyParser(
     "utf"
 );
 
-const raw = createBodyParser("application/octet-stream", function (req, res, next, options, buf) {
-    req.body = buf;
-    next();
-});
+const raw = createBodyParser(
+    "application/octet-stream",
+    function (req, res, next, options, buf) {
+        req.body = buf;
+        next();
+    },
+    undefined,
+    undefined,
+    // req.body is the collected buffer itself, so it must not be a view over uWS memory
+    true
+);
 
 const text = createBodyParser(
     "text/plain",
@@ -954,7 +1023,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
@@ -323,6 +324,28 @@ module.exports = class Request extends Readable {
         });
     }
 
+    /**
+     * One header by its lowercase wire name, straight from the raw entries. The body parsers ask
+     * for three of these per request, and materializing the whole headers object for that costs
+     * more than all three scans together. Reads the built object instead when it already exists,
+     * so joined duplicates come out the same either way.
+     *
+     * @param {string} name lowercase
+     * @returns {string|undefined}
+     */
+    _rawHeader(name) {
+        if (this.#cachedHeaders !== null) {
+            return this.#cachedHeaders[name];
+        }
+        const entries = this.#rawHeadersEntries;
+        for (let i = 0, len = entries.length; i < len; i += 2) {
+            if (entries[i] === name) {
+                return entries[i + 1];
+            }
+        }
+        return undefined;
+    }
+
     /**
      * 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.
@@ -540,10 +563,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/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"),