fulmine.js 5.2.0 → 5.3.0

package/NOTICE

@@ -13,8 +13,35 @@ 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.
+(https://github.com/anonrig/fast-querystring), vendored in src/parse-query.js
+and licensed under the MIT License, which requires the following to travel with
+every copy:
+
+  Copyright (c) 2022 Yagiz Nizipli
+
+  Permission is hereby granted, free of charge, to any
+  person obtaining a copy of this software and associated
+  documentation files (the "Software"), to deal in the
+  Software without restriction, including without
+  limitation the rights to use, copy, modify, merge,
+  publish, distribute, sublicense, and/or sell copies of
+  the Software, and to permit persons to whom the Software
+  is furnished to do so, subject to the following
+  conditions:
+
+  The above copyright notice and this permission notice
+  shall be included in all copies or substantial portions
+  of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+  ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+  TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+  PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+  SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+  DEALINGS IN THE SOFTWARE.
 
 As required by section 4(b) of the Apache License, the following are the
 significant changes made to the original work:

package/README.md

@@ -21,10 +21,17 @@ There is a command that does that replacing for you, across a whole project, and
 npx fulmine migrate --dry-run   # say what it would change, change nothing
 npx fulmine migrate             # do it
 npx fulmine differences         # just the list of what to check by hand
+npx fulmine profile             # what listen() decided about each route
 ```
 
 See [Migrating](#migrating) for what it handles and what it deliberately does not.
 
+There is a **[live demo](https://fulmine-demo.fly.dev)**, which is an ordinary Express application:
+real routes, `helmet`, `cors`, `compression`, `express-session` and `morgan` unmodified, and a
+WebSocket chat served by `app.ws()`. It links to [its own source](https://fulmine-demo.fly.dev/source),
+which is [in this repository](./demo). It shows no throughput figure on purpose: it runs on a small
+shared machine, so the number would describe the machine rather than the framework.
+
 [![npm version](https://img.shields.io/npm/v/fulmine.js)](https://www.npmjs.com/package/fulmine.js)
 [![Node.js >= 22.0.0](https://img.shields.io/badge/Node.js-%3E=22.0.0-green)](https://nodejs.org)
 [![Coverage Status](https://coveralls.io/repos/github/nigrosimone/fulmine.js/badge.svg?branch=main)](https://coveralls.io/github/nigrosimone/fulmine.js?branch=main)
@@ -39,6 +46,7 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
 - [Attribution](#attribution)
 - [Difference from similar projects](#difference-from-similar-projects)
 - [Migrating](#migrating)
+    - [When Express is somebody else's dependency](#when-express-is-somebody-elses-dependency)
 - [Docker](#docker)
 - [Differences from Express](#differences-from-express)
 - [Performance tips](#performance-tips)
@@ -55,8 +63,8 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
     - [Router](#router)
 - [Tested middlewares](#tested-middlewares)
 - [Tested view engines](#tested-view-engines)
-- [Working on Fulmine](#working-on-fulmine)
-    - [Writing a comparison test](#writing-a-comparison-test)
+- [The demo](https://fulmine-demo.fly.dev)
+- [Working on Fulmine](./CONTRIBUTING.md)
 
 ## Why this exists
 
@@ -121,22 +129,64 @@ 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.
 
+### When Express is somebody else's dependency
+
+A framework built on Express does not `require("express")` in your code, it requires it in its own,
+so there is nothing for `migrate` to rewrite. Every package manager can answer `express` with this
+package instead, for your project and everything under it:
+
+```jsonc
+// npm and its lockfile, in package.json
+{
+    "overrides": {
+        "express": "npm:fulmine.js@^5"
+    }
+}
+
+// pnpm, in package.json
+{
+    "pnpm": {
+        "overrides": {
+            "express": "npm:fulmine.js@^5"
+        }
+    }
+}
+
+// yarn 1 and berry, in package.json
+{
+    "resolutions": {
+        "express": "npm:fulmine.js@^5"
+    }
+}
+```
+
+Then reinstall, so the lockfile is rewritten: `rm -rf node_modules` and `npm install`, or the
+equivalent for your manager. `npm ls express` should answer `express@npm:fulmine.js`.
+
+Two things to know before you do it. The substitution reaches **every** dependency that asks for
+Express, including ones you have never looked at, so run your own tests afterwards and read
+[the differences](#differences-from-express): what a framework does with Express is usually more
+than what an application does. And a package that reaches into `express/lib/...` rather than its
+public surface will not find what it expects, since the files there are ours.
+
+Bun is not an option: µWebSockets.js is a native Node addon, and Bun does not load it.
+
 ## Docker
 
 Two things about µWebSockets.js make a Dockerfile that works for Express fail here, and both have easy answers:
 
-- **No Alpine, and no Debian bookworm either.** µWebSockets.js ships prebuilt binaries linked against glibc 2.38 or newer. Alpine images use musl, so the binary does not load at all; `node:22` and `node:22-slim` are Debian bookworm, whose glibc 2.36 fails at startup with `GLIBC_2.38' not found`. Use the trixie variants: `node:22-trixie-slim` and up.
-- **`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-trixie` have git; `-slim` ones do not.
+- **No Alpine, and no Debian bookworm either.** µWebSockets.js ships prebuilt binaries linked against glibc 2.38 or newer. Alpine images use musl, so the binary does not load at all; `node:26` and `node:26-slim` are Debian bookworm, whose glibc 2.36 fails at startup with `GLIBC_2.38' not found`. Use the trixie variants: `node:26-trixie-slim` and up.
+- **`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:26-trixie` 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-trixie AS build
+FROM node:26-trixie AS build
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --omit=dev
 
-FROM node:22-trixie-slim
+FROM node:26-trixie-slim
 WORKDIR /app
 COPY --from=build /app/node_modules ./node_modules
 COPY . .
@@ -144,7 +194,7 @@ EXPOSE 3000
 CMD ["node", "server.js"]
 ```
 
-A single-stage `node:22-trixie-slim` image works too if you `apt-get install -y git ca-certificates` before `npm ci`. Prebuilt binaries exist for x64 and arm64 on Linux, macOS and Windows, so nothing is compiled at install time either way.
+A single-stage `node:26-trixie-slim` image works too if you `apt-get install -y git ca-certificates` 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
 
@@ -211,6 +261,37 @@ On top of that, a handler simple enough to be read at registration time is compi
 
 `app.set("declarative responses", false)` turns the whole thing off if you would rather have Express's exact framing than the speed.
 
+None of that is guesswork you have to do from the outside. `listen()` decides it all, and `npx fulmine profile` prints what it decided:
+
+```sh
+npx fulmine profile              # the file package.json's "main" points at
+npx fulmine profile server.js    # or name it
+```
+
+```text
+7 route(s), 4 answered by µWS itself
+
+  GET    /api/health          µWS  /api/health  (2 in front of it in its chain)
+  GET    /hello               µWS  /hello  (compiled to a response, reads no query)
+  GET    /:anything           router: something before it in the same router overlaps its paths
+  GET    /after-the-param     router: the parameter route /:anything is written before it
+  SEARCH /odd                 router: µWS does not serve SEARCH
+
+What this adds up to
+
+  4 of 7 route(s) matched by µWS in C++
+  1 answered from a response written at startup, running no javascript
+  layers in front of a compiled handler: 1 at least, 2 at most, 1.8 on average
+
+Worth changing, if these are routes that carry traffic
+
+  GET /after-the-param
+    write it above /:anything. Express answers whichever matches first, so the order is
+    already what decides, and with the literal first µWS can match it in C++ as well.
+```
+
+It loads the application with `listen()` replaced by the half that compiles the routes, so nothing binds a port and the listen callback does not run: profiling a running service does not start a second copy of it. There is no score, on purpose. A percentage of routes is not a percentage of traffic, and an application with a thousand cold routes and one hot one that fell back would score well and serve badly.
+
 2. Do not use external `serve-static` module. Instead use built-in `express.static()` middleware, which is optimized for Fulmine.
 
 3. Do not use `body-parser` module. Instead use built-in `express.text()`, `express.json()` etc.
@@ -524,57 +605,5 @@ Any Express view engine should work. Here's list of engines we include in our te
 
 ## Working on Fulmine
 
-```sh
-npm test                  # the comparison suite: every test runs against Express, then against
-                          # Fulmine, and the two outputs have to match byte for byte
-npm test middlewares      # one category
-npm test tests/tests/res/res-send.js   # one file
-
-npm run test:unit         # the pure functions, which the comparison cannot reach
-npm run test:types        # the TypeScript declarations, through tsd
-npm run typecheck         # checkJs over src, which is where the JSDoc types are checked
-
-npm run lint              # eslint, including the rule that every function in src carries a JSDoc block
-npm run format            # prettier
-npm run cover             # the comparison suite under nyc, then an HTML report
-
-npm run benchmark:compare -- --duration 20      # against Express, scenario by scenario
-npm run benchmark:ab -- --against main          # this working tree against another revision
-
-npm run test:express                            # Express's own test suite, run against this
-npm run test:express -- res.sendFile --verbose  # one area of it, with mocha's output
-```
-
-The comparison suite is the load-bearing one. A test is a file that prints; the runner executes it
-twice, once with `express` and once with this, and fails on any difference. That is why adding a
-test means writing something that prints what you want compared, and why a test that prints from
-both the server and the client at once is a bug: the two orderings are a race.
-
-### Writing a comparison test
-
-A test file is an ordinary script. The first line is its description, the second may carry a marker,
-and the rest sets up an app, makes requests and prints. `tests/helpers.js` has what to print with:
-
-|                         |                                                                                                                                                                                                                                                             |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fetchTest(url, init)`  | `fetch`, plus a line with the status and the headers worth comparing. Returns the response untouched, so the test goes on to read the body as it would have. Lines come out in call order, never in arrival order.                                          |
-| `sequential([() => …])` | Runs requests one at a time. `Promise.all` starts them together and the two servers then answer in whatever order they scheduled, which is a difference the runner would report as a failure.                                                               |
-| `// INSPECT`            | On the second line. The runner then mounts `inspectRequest` in front of every app the file makes, and each request prints its `method`, `url`, `originalUrl`, `baseUrl`, `path`, `protocol`, `secure`, `hostname`, `host`, `xhr`, `subdomains` and `query`. |
-| `// OFF: reason`        | Skips the file.                                                                                                                                                                                                                                             |
-
-`// INSPECT` is not free everywhere, which is why it is asked for rather than always on. It is a
-middleware, so a route behind it stops being compiled into a declarative response and is served by
-the ordinary path instead: a file whose routes do compile would quietly stop covering the compiled
-one. And Express builds its router at the first `use()`, freezing `strict routing` and
-`case sensitive routing` as they are at that moment, so a file that sets either one afterwards must
-not ask for it. Everywhere else it is worth having: it is what caught a pathless mount dropping the
-middleware in front of it.
-
-`npm run test:express` is the other kind of test: it clones Express at the version in
-`devDependencies`, points its entry at this source and runs its suite against it. It is a bug mine
-rather than a gate, and its exit status says nothing. Read the header of `tools/express-suite.js`
-before reading its numbers: some of what it reports is Express testing its own internals, which the
-clone still has, and some is internals used as public API.
-
-`benchmark/README.md` covers measuring, including why the A/B runs pipelined by default and why a
-null control matters.
+How to run the suites, what each of them is for, and how to write a comparison test:
+[`CONTRIBUTING.md`](./CONTRIBUTING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.2.0",
+    "version": "5.3.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -12,6 +12,7 @@
         "test:unit": "node --test \"tests/unit/*.test.js\"",
         "test:types": "tsd --files tests/types/*.test-d.ts",
         "test:express": "node tools/express-suite.js",
+        "fuzz": "node tools/fuzz.js",
         "benchmark:compare": "node benchmark/run.js",
         "cover": "npm run cover:full && npm run cover:report",
         "cover:unit": "nyc --silent npm run test",
@@ -27,7 +28,10 @@
         "benchmark:profile": "node benchmark/profile.js",
         "release:local": "node tools/release-local.js",
         "cover:full": "nyc --silent npm run test && nyc --silent --no-clean npm run test:unit && nyc --silent --no-clean npm run test:express && nyc report",
-        "cover:check": "nyc check-coverage --statements 93 --branches 88 --functions 92 --lines 93"
+        "cover:check": "nyc check-coverage --statements 93 --branches 88 --functions 92 --lines 93",
+        "demo:start": "npm --prefix demo install && npm --prefix demo start",
+        "demo:deploy": "fly deploy ./demo --config ./demo/fly.toml",
+        "demo:logs": "fly logs --app fulmine-demo"
     },
     "engines": {
         "node": ">=22"

package/src/application.js

@@ -2,6 +2,8 @@
 Copyright 2024 dimden.dev
 Copyright 2026 Nigro Simone
 
+This file is derived from Ultimate Express and has been modified.
+
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
@@ -83,6 +85,20 @@ const FILE_CACHE_MAX_ENTRY = 768 * 1024;
 const FILE_CACHE_BUDGET = 64 * 1024 * 1024;
 
 class Application extends Router {
+    /**
+     * An application reads an unset routing flag from the app it is mounted on, which a plain
+     * Router does not: express chains a mounted app's settings onto its parent's.
+     *
+     * @type {boolean}
+     */
+    _inheritsSettings = true;
+
+    /**
+     * An application, which a plain Router is not. See Router#_isApplication.
+     * @type {boolean}
+     */
+    _isApplication = true;
+
     /**
      * @param {object} [settings] the options express() takes. uwsOptions goes to uWS and decides
      *   between an HTTP, an HTTPS and an HTTP/3 server; threads sizes the file-reading pool, and 0
@@ -171,6 +187,12 @@ class Application extends Router {
             if (parent.response) {
                 Object.setPrototypeOf(this.response, parent.response);
             }
+            // and the engines with them, which is the same chaining express does: a sub-app renders
+            // with whatever the parent registered unless it registered its own. Without this a
+            // render inside a mounted app looked for a module named after the extension.
+            if (parent.engines) {
+                Object.setPrototypeOf(this.engines, parent.engines);
+            }
             // a "trust proxy" this app never set is inherited from the parent, as express does:
             // the defaults are deleted so get() falls through to the parent's value
             if (
@@ -357,10 +379,6 @@ class Application extends Router {
                 // express's wording, which applications match on
                 throw new TypeError("unknown value for query parser function: " + value);
             }
-        } else if (key === "views") {
-            // a list of directories is searched in order by View.lookup, each resolved here once
-            this.settings[key] = Array.isArray(value) ? value.map((dir) => path.resolve(dir)) : path.resolve(value);
-            return this;
         } else if (key === "etag") {
             // an etag arriving after listen would make send consult freshness headers the
             // header-skip routes never copied, so those skips are taken back
@@ -417,13 +435,13 @@ class Application extends Router {
     }
 
     /**
-     * Whether a setting is truthy. Reads this app's own settings, without falling back to a
-     * parent app the way get() does.
+     * Whether a setting is truthy. Reads through to the app this one is mounted on, as get() does
+     * and as express does: mounting chains a sub-app's settings onto its parent's.
      * @param {string} key setting name
      * @returns {boolean}
      */
     enabled(key) {
-        return !!this.settings[key];
+        return !!this.get(key);
     }
 
     /**
@@ -432,7 +450,7 @@ class Application extends Router {
      * @returns {boolean}
      */
     disabled(key) {
-        return !this.settings[key];
+        return !this.get(key);
     }
 
     /**
@@ -471,32 +489,42 @@ class Application extends Router {
      * between an error, the automatic OPTIONS reply and a 404.
      */
     _createRequestHandler() {
-        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);
-                // dispatch has run its synchronous stretch inside _routeRequest by now, still
-                // under the cork uWS holds for this callback; the await below leaves it
-                response._corkNeeded = true;
-                const matchedRoute = await routed;
-                if (!matchedRoute && !response.headersSent && !response.aborted) {
-                    this._endUnmatched(request, response);
-                }
-            } catch (err) {
-                // an internal throw answers 500 as express's final handler would, instead of
-                // dying as an unhandled rejection
-                if (response.aborted || response.finished) {
-                    console.error(err);
-                } else {
-                    this._handleError(err, null, request, response);
-                }
+        this.uwsApp.any("/*", (res, req) => this._serveGeneric(res, req));
+    }
+
+    /**
+     * Serves one request by walking this app's chain, with no registration-time shortcut. It is
+     * what the catch-all runs, and also what a native registration falls back to when it sees a
+     * request it must not answer itself, see the case guard in Router#_registerUwsRoute.
+     *
+     * @param {any} res the uWS response
+     * @param {any} req the uWS request
+     */
+    async _serveGeneric(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);
+            // dispatch has run its synchronous stretch inside _routeRequest by now, still
+            // under the cork uWS holds for this callback; the await below leaves it
+            response._corkNeeded = true;
+            const matchedRoute = await routed;
+            if (!matchedRoute && !response.headersSent && !response.aborted) {
+                this._endUnmatched(request, response);
             }
-        });
+        } catch (err) {
+            // an internal throw answers 500 as express's final handler would, instead of
+            // dying as an unhandled rejection
+            if (response.aborted || response.finished) {
+                console.error(err);
+            } else {
+                this._handleError(err, null, request, response);
+            }
+        }
     }
 
     /**
@@ -733,7 +761,12 @@ class Application extends Router {
             view = new View(name, {
                 defaultEngine: this.get("view engine"),
                 root: this.get("views"),
-                engines: { ...this.engines }
+                // the object itself, not a copy of it: a mounted app reaches its parent's engines
+                // through the prototype chain, and a spread only carries what the app owns, so a
+                // sub-app rendering with the parent's engine went off to require() a module named
+                // after the extension. Express hands its own object over too, and means to: a view
+                // that loads an engine by require caches it back here
+                engines: this.engines
             });
             if (!view.path) {
                 const dirs =