fulmine.js 5.1.4 → 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.4",
+    "version": "5.1.6",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {

package/src/middlewares.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",

package/src/request.js

@@ -324,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.