fulmine.js 5.0.0-rc.1 → 5.1.0

package/README.md

@@ -23,6 +23,7 @@ npx fulmine differences         # just the list of what to check by hand
 
 See [Migrating](#migrating) for what it handles and what it deliberately does not.
 
+[![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)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
@@ -30,13 +31,13 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
 
 There are several fast HTTP servers for Node built on [µWebSockets.js](https://github.com/uNetworking/uWebSockets.js). What is scarce is one you can actually drop into an existing Express application without rewriting it.
 
-Compatibility here is not a claim, it is a test suite. Every test runs against real Express first and then against Fulmine, and the outputs have to match byte for byte. That is what makes `helmet`, `cors`, `passport`, `morgan`, `multer`, `express-session` and the rest of the ecosystem work rather than "mostly work".
+Compatibility here is not a claim, it is a test suite. Every test runs against real Express first and then against Fulmine, and the outputs have to match byte for byte. That is what makes `helmet`, `cors`, `passport`, `morgan`, `multer`, `express-session` and the rest of the ecosystem work rather than "mostly work". Express 5's own test suite runs against Fulmine too, and passes whole: 1130 passing, 0 failing at the pinned Express version.
 
 ## Performance
 
 Fulmine is faster than Express where the framework itself is doing the work, and the same speed where it is not. Both halves of that sentence matter, so here is the honest version.
 
-**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. These land between 1.7x and 3x: plain routing 1.7x to 2.3x, an API endpoint with params and a query 1.8x to 2.7x, nested routers 2.2x to 2.5x, a urlencoded body 2.7x to 3x.
+**Where it is clearly faster.** Routing and dispatch, request shapes with params and query strings, connection handling. Plain routing lands between 1.9x and 3.9x: hello-world 1.9x to 2.7x, an API endpoint with params and a query 3x to 3.8x, five route shapes served by one process 2.7x to 3.9x, nested routers 2.2x to 2.8x, a urlencoded body 3.2x to 3.8x, a thousand concurrent connections 2.7x to 3x. Route tables are where the native router shows: a thousand routes 9.8x to 12.7x, with a parameter in every one of them 9.9x to 14.3x, a parameterised route in a mounted router 7.4x to 8.8x. Those routes go to µWS's own router instead of being scanned, so the gap grows with the table instead of shrinking. Even the chain of 100 middlewares, for a long time the one routing row that stayed even because its cost is calling application code a hundred times, sits at 1.35x to 1.55x after the per-request allocation work of August 2026.
 
 **Where it is a wash.** Any request whose cost is dominated by work both servers hand to the same library. A 512 KiB JSON body is `JSON.parse`, a gzipped response is zlib, a hashed upload is OpenSSL, a 5 MiB stream is memory bandwidth. On those the ratio is capped by arithmetic somewhere around 1.0x to 1.2x, and no amount of work on either server moves it. The benchmark labels those rows rather than quietly publishing them as if the two were equivalent.
 
@@ -47,8 +48,7 @@ Two things worth knowing before comparing numbers with anyone:
 
 There is no table here on purpose. CI runs the whole benchmark on every push and every pull request
 and posts the result where it belongs: as a comment on the commit or the pull request, and as a
-`benchmark-summary` artifact on the run. A table pasted in here would be a snapshot of one machine
-on one day, and would start rotting immediately. See [`benchmark/README.md`](./benchmark/README.md)
+`benchmark-summary` artifact on the run, see [`benchmark/README.md`](./benchmark/README.md)
 to run it yourself.
 
 ## Attribution
@@ -84,7 +84,6 @@ command whose name ends in `.js` on Windows, where it exits without a word.
 ## 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.
-- `case sensitive routing` is enabled by default.
 - `x-powered-by` is disabled by default. Express sends `X-Powered-By: Express` unless you turn it off; Fulmine does not send it unless you turn it on with `app.set("x-powered-by", true)`. The header only tells anyone asking which framework is running.
 - request body is only read for POST, PUT, PATCH and QUERY requests by default. You can add additional methods by setting `body methods` to array with uppercased methods.
 - For HTTPS, instead of doing this:
@@ -134,8 +133,7 @@ app.listen(3000, () => {
 
 1. Fulmine tries to optimize routing as much as possible, but it's only possible if:
 
-- `case sensitive routing` is enabled (it is by default, unlike in normal Express).
-- the path is a plain string, or its parameters are whole segments: `/users/:id` and `/a/:b/c/:d` qualify, `/flights/:from-:to` does not, and neither does a `*splat` or a `{}` group.
+- the path is a plain string, or its parameters are whole segments: `/users/:id` and `/a/:b/c/:d` qualify, `/flights/:from-:to` does not, and neither does a `*splat` or a `{}` group. Routing is case-insensitive by default, as in Express; a request in the registered case is still served natively, any other case takes the ordinary path, and a route whose overlap with an earlier one leans on a cased literal goes the ordinary way for every request.
 - inside a mounted router, nothing registered after the route in that router could match the same path. `/orders/:id`, `/orders/:id/items` and `/invoices/:id` are all optimized together, since no request reaches two of them. `/users/:id` followed by `/users/me` is not: Express answers `/users/me` with the first of the two and the native router would answer it with the second, so both go the ordinary way.
 
 Optimized routes can be up to 10 times faster than normal routes, as they're using native uWS router and have pre-calculated path.
@@ -237,7 +235,7 @@ In general, basically all features and options are supported. Use the [Express 5
 - 🚧 express.request (this is not a constructor but a prototype for replacing methods)
 - 🚧 express.response (this is not a constructor but a prototype for replacing methods)
 - 🚧 express.application (likewise: a method added here is on every app)
-- ❌ express.Route. `app.route("/path").get(...).post(...)` works and is what almost everyone means by this; what is missing is the class itself, for constructing a route and wiring it up by hand.
+- ✅ express.Route. Both `app.route("/path").get(...).post(...)` and the class itself, for building a route by hand and dispatching to it.
 
 ### Application
 
@@ -459,6 +457,26 @@ twice, once with `express` and once with this, and fails on any difference. That
 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`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.0.0-rc.1",
+    "version": "5.1.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -73,6 +73,7 @@
         "fast-querystring": "^1.1.2",
         "fast-zlib": "^2.0.1",
         "fresh": "^2.0.0",
+        "iconv-lite": "^0.7.3",
         "mime-types": "^3.0.2",
         "ms": "^2.1.3",
         "proxy-addr": "^2.0.7",

package/src/application.js

@@ -29,6 +29,8 @@ const {
     NullObject
 } = require("./utils.js");
 const querystring = require("fast-querystring");
+const Request = require("./request.js");
+const Response = require("./response.js");
 const ViewClass = require("./view.js");
 const path = require("path");
 const os = require("os");
@@ -37,6 +39,10 @@ const cluster = require("cluster");
 
 const cpuCount = os.cpus().length;
 
+// marks a "trust proxy" that was never set by the application, under the key express uses, so a
+// mounted sub-app knows it may inherit the parent's
+const trustProxyDefaultSymbol = "@@symbol:trust_proxy_default";
+
 const workers = [];
 let taskKey = 0;
 const workerTasks = new NullObject();
@@ -101,9 +107,69 @@ class Application extends Router {
         this.ssl = settings.uwsOptions.key_file_name && settings.uwsOptions.cert_file_name;
         this.cache = new NullObject();
         this.engines = { __proto__: null };
-        this.locals = {
-            settings: this.settings
+        // a null prototype, as express gives app.locals, so a local named like an Object method
+        // is just a local
+        this.locals = Object.create(null);
+        this.locals.settings = this.settings;
+        // each app gets its own request/response prototype layer, so extending app.request cannot
+        // leak into another app; a mounted sub-app re-parents its layer onto the parent's below.
+        // The constructors are written out: the implicit derived one spreads its arguments, which
+        // was an allocation on every request
+        this._request = class extends Request {
+            /**
+             * @param {any} req
+             * @param {any} res
+             * @param {any} app
+             */
+            constructor(req, res, app) {
+                super(req, res, app);
+            }
+        };
+        this._response = class extends Response {
+            /**
+             * @param {any} res
+             * @param {any} req
+             * @param {any} app
+             */
+            constructor(res, req, app) {
+                super(res, req, app);
+            }
+
+            /**
+             * Node counts an explicit writeHead as the head gone out; remembered here so the
+             * automatic OPTIONS reply can refuse to add headers after it, as express's does.
+             *
+             * @param {number} statusCode
+             * @param {string|Record<string, any>} [statusMessage]
+             * @param {Record<string, any>} [headers]
+             * @returns {this}
+             */
+            writeHead(statusCode, statusMessage, headers) {
+                this._headWritten = true;
+                return super.writeHead(statusCode, statusMessage, headers);
+            }
         };
+        this.request = this._request.prototype;
+        this.response = this._response.prototype;
+        this.on("mount", (parent) => {
+            // the parent's extensions show through, and an override here stays here. Only an
+            // application has a layer to hang onto: a plain router mount leaves things alone
+            if (parent.request) {
+                Object.setPrototypeOf(this.request, parent.request);
+            }
+            if (parent.response) {
+                Object.setPrototypeOf(this.response, parent.response);
+            }
+            // 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 (
+                this.settings[trustProxyDefaultSymbol] === true &&
+                typeof parent.settings["trust proxy fn"] === "function"
+            ) {
+                delete this.settings["trust proxy"];
+                delete this.settings["trust proxy fn"];
+            }
+        });
         this.listenCalled = false;
         this.workers = [];
         for (let i = 0; i < settings.threads; i++) {
@@ -117,6 +183,19 @@ class Application extends Router {
         this.listening = false;
         // the host handed to listen(), which is all address() has to go on
         this._listenHost = undefined;
+        // 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;
+        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
+        if (typeof this.settings.env === "undefined") {
+            this.settings.env = process.env.NODE_ENV || "development";
+        }
         for (const key in defaultSettings) {
             if (typeof this.settings[key] === "undefined") {
                 if (typeof defaultSettings[key] === "function") {
@@ -126,6 +205,11 @@ class Application extends Router {
                 }
             }
         }
+        // non-enumerable, so the marker never shows up walking the settings
+        Object.defineProperty(this.settings, trustProxyDefaultSymbol, {
+            configurable: true,
+            value: true
+        });
         this.set("view", ViewClass);
         this.set("views", path.resolve("views"));
     }
@@ -169,7 +253,7 @@ class Application extends Router {
      * 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:
      * `trust proxy`, `query parser` and `etag` compile the value into a function kept beside it,
-     * `views` becomes an absolute path, and `env` set to "production" turns the view cache on.
+     * and `views` becomes an absolute path.
      *
      * @param {string} key setting name
      * @param {*} [value] value to store; omit to read instead
@@ -181,28 +265,33 @@ class Application extends Router {
         }
         if (key === "trust proxy") {
             if (!value) {
-                delete this.settings["trust proxy fn"];
+                // compiled, not deleted: an explicit false must shadow a parent's setting when
+                // this app is mounted, and a deleted key would read straight through to it
+                this.settings["trust proxy fn"] = compileTrust(false);
             } else {
                 this.settings["trust proxy fn"] = compileTrust(value);
             }
+            // set explicitly, so a mount no longer inherits the parent's
+            Object.defineProperty(this.settings, trustProxyDefaultSymbol, {
+                configurable: true,
+                value: false
+            });
         } else if (key === "query parser") {
             if (value === "extended") {
                 this.settings["query parser fn"] = fastQueryParse;
-            } else if (value === "simple") {
+            } else if (value === "simple" || value === true) {
                 this.settings["query parser fn"] = querystring.parse;
             } else if (typeof value === "function") {
                 this.settings["query parser fn"] = value;
-            } else {
+            } else if (value === false) {
                 this.settings["query parser fn"] = undefined;
-            }
-        } else if (key === "env") {
-            if (value === "production") {
-                this.settings["view cache"] = true;
             } else {
-                this.settings["view cache"] = undefined;
+                // express's wording, which applications match on
+                throw new TypeError("unknown value for query parser function: " + value);
             }
         } else if (key === "views") {
-            this.settings[key] = path.resolve(value);
+            // 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") {
             if (typeof value === "function") {
@@ -220,7 +309,8 @@ class Application extends Router {
                         delete this.settings["etag fn"];
                         break;
                     default:
-                        throw new Error(`Invalid etag mode: ${value}`);
+                        // express's wording, which applications match on
+                        throw new TypeError("unknown value for etag function: " + value);
                 }
             }
         }
@@ -268,6 +358,25 @@ class Application extends Router {
         return !this.settings[key];
     }
 
+    /**
+     * Router's handleRequest plus the bookkeeping a graceful close() needs: every live response
+     * is held in a set until it finishes, so close() knows when the last one is done. Native
+     * routes and the catch-all both come through here, since both call it on the app.
+     *
+     * @param {any} res uWS response
+     * @param {any} req uWS request, readable only during this call
+     * @returns {any} the request, with the response reachable as request.res
+     */
+    handleRequest(res, req) {
+        const request = super.handleRequest(res, req);
+        // 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);
+        return request;
+    }
+
     /**
      * Registers the catch-all uWS handler, which is what serves every request that no optimized
      * route took natively. It walks this app's own chain and, when nothing in it answered, decides
@@ -275,11 +384,22 @@ class Application extends Router {
      */
     _createRequestHandler() {
         this.uwsApp.any("/*", async (res, req) => {
-            const { request, response } = this.handleRequest(res, req);
+            const request = this.handleRequest(res, req);
+            const response = request.res;
 
-            const matchedRoute = await this._routeRequest(request, response);
-            if (!matchedRoute && !response.headersSent && !response.aborted) {
-                this._endUnmatched(request, response);
+            try {
+                const matchedRoute = await this._routeRequest(request, response);
+                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);
+                }
             }
         });
     }
@@ -295,21 +415,27 @@ class Application extends Router {
      *
      * @param {number|string} [port] port, or a unix socket path; 0 picks a free port
      * @param {string} [host] interface to bind; every interface when omitted
+     * @param {number} [backlog] accepted for node's signature; uWS sizes its own queue
      * @param {(err?: Error) => void} [callback] called once bound, or with the bind error
      * @returns {this} the app, which doubles as the server handle
      */
-    listen(port, host, callback) {
+    listen(port, host, backlog, callback) {
         this._compileOptimizedRoutes();
         this._createRequestHandler();
-        // support listen(callback)
-        if (!callback && typeof port === "function") {
+        // node's shapes: (cb), (port, cb), (port, host, cb) and (port, host, backlog, cb)
+        if (typeof port === "function") {
             callback = port;
             port = 0;
-        }
-        // support listen(port, callback)
-        if (typeof host === "function") {
+        } else if (typeof host === "function") {
             callback = host;
             host = undefined;
+        } else if (typeof backlog === "function") {
+            callback = backlog;
+        }
+        // bare listen() and listen(undefined, cb) bind an OS-assigned port, as node does; left
+        // undefined the port fell through to the unix-socket branch below
+        if (port == null) {
+            port = 0;
         }
         // uWS runs this handler from inside its own listen(), so everything it hands back to the
         // caller is deferred a tick. Express binds synchronously too but reports through events,
@@ -337,6 +463,8 @@ class Application extends Router {
             this.port = uWS.us_socket_local_port(socket);
             this.listening = true;
             this._listenHost = host;
+            // kept so close() can stop accepting without dropping what is in flight
+            this._listenSocket = socket;
             process.nextTick(() => {
                 // `this` is the app, which is what listen() returns here. Express binds it to the
                 // http.Server, which is what listen() returns there, so
@@ -451,20 +579,21 @@ class Application extends Router {
         // render exists to hand the result somewhere, so there is always a callback by this point:
         // either the third argument or the second one, shuffled above
         const done = /** @type {(err: Error|null, html?: string) => void} */ (callback);
-        if (!options) {
-            options = new NullObject();
-        } else {
-            options = Object.assign({}, options);
-        }
+        // express's order, least specific first: app.locals, then res.locals riding in as _locals,
+        // and what was passed to this call wins over both
+        const opts = options || new NullObject();
+        options = new NullObject();
         for (const key in this.locals) {
             options[key] = this.locals[key];
         }
-
-        if (options._locals) {
-            for (const key in options._locals) {
-                options[key] = options._locals[key];
+        if (opts._locals) {
+            for (const key in opts._locals) {
+                options[key] = opts._locals[key];
             }
         }
+        for (const key in opts) {
+            options[key] = opts[key];
+        }
 
         if (options.cache == null) {
             options.cache = this.enabled("view cache");
@@ -511,7 +640,13 @@ class Application extends Router {
     }
 
     /**
-     * Stops listening and emits 'close'.
+     * Stops accepting connections, lets in-flight requests finish, then emits 'close'.
+     *
+     * Node's server.close(), which Express hands back from listen(), only closes the listen
+     * socket and waits for what is being served; uWS's close() forcefully terminates every
+     * connection, so calling it first aborted whatever a graceful shutdown was waiting for.
+     * It still runs, but only once the last pending response is done, to drop the idle
+     * keep-alive connections nothing else would close.
      *
      * The callback is the first 'close' listener, so it runs before any added afterwards. Closing
      * a server that was not listening still calls back, with an ERR_SERVER_NOT_RUNNING error, the
@@ -522,9 +657,6 @@ class Application extends Router {
      */
     close(callback) {
         const wasListening = this.listening;
-        if (this.listenCalled && wasListening) {
-            this.uwsApp.close();
-        }
         this.listening = false;
         // in Express the close callback is nothing more than the first 'close' listener, and a
         // server that was not running still gets called back, with an error
@@ -539,7 +671,41 @@ class Application extends Router {
                 callback(err);
             });
         }
-        process.nextTick(() => this.emit("close"));
+        if (!this.listenCalled || !wasListening) {
+            // a close while a drain is underway does not emit again: the pending drain's single
+            // 'close' serves both calls, which is what node does too
+            if (!this._draining) {
+                process.nextTick(() => this.emit("close"));
+            }
+            return this;
+        }
+        if (this._listenSocket) {
+            uWS.us_listen_socket_close(this._listenSocket);
+            this._listenSocket = undefined;
+        }
+        this._draining = true;
+        const finish = () => {
+            this._draining = false;
+            this.uwsApp.close();
+            this.emit("close");
+        };
+        if (this._pendingResponses.size === 0) {
+            process.nextTick(finish);
+            return this;
+        }
+        // a finished response emits 'close' and removes 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) {
+                if (response.finished || response.aborted) {
+                    this._pendingResponses.delete(response);
+                }
+            }
+            if (this._pendingResponses.size === 0) {
+                clearInterval(sweep);
+                finish();
+            }
+        }, 10);
         return this;
     }
 }

package/src/cli.js

@@ -51,9 +51,9 @@ const DIFFERENCES = [
         'A body sent with GET or DELETE is not read unless you add the method: app.set("body methods", [...]).'
     ],
     [
-        "case sensitive routing is on by default",
-        '/Users and /users are two different routes unless you set app.set("case sensitive routing", false).\n' +
-            "It is on because it is what makes a route eligible for the native router."
+        "case sensitive routing matches Express: insensitive by default",
+        "/Users and /users are the same route, as in Express 5. A request in the registered case is still\n" +
+            'answered by the native router; set app.set("case sensitive routing", true) to make case matter.'
     ],
     [
         "x-powered-by is off by default",

package/src/declarative.js

@@ -220,9 +220,8 @@ module.exports = function compileDeclarative(cb, app) {
         }
 
         const [req, res] = args;
-        let queryName,
-            paramsName,
-            queries = [],
+        let queryName, paramsName;
+        const queries = [],
             params = [];
 
         if (fn.params[0].type === "ObjectPattern") {
@@ -384,12 +383,14 @@ module.exports = function compileDeclarative(cb, app) {
                 if (call.arguments[0].type !== "Literal" || call.arguments[1].type !== "Literal") {
                     return false;
                 }
-                let [header, value] = [call.arguments[0].value, call.arguments[1].value];
+                // String() at capture: a numeric literal would reach uWS's writeHeader as itself,
+                // and uWS refuses anything that is not a string
+                let [header, value] = [call.arguments[0].value, String(call.arguments[1].value)];
                 const name = String(header).toLowerCase();
                 // res.set charsets a content-type and res.setHeader does not, since the second is
                 // node's and node does not know what a media type is
                 if (call.obj.propertyName !== "setHeader" && name === "content-type") {
-                    value = withDefaultCharset(String(value));
+                    value = withDefaultCharset(value);
                 }
                 const index = headers.findIndex((entry) => String(entry[0]).toLowerCase() === name);
                 if (index === -1) {
@@ -409,7 +410,7 @@ module.exports = function compileDeclarative(cb, app) {
                 if (call.arguments[0].type !== "Literal" || call.arguments[1].type !== "Literal") {
                     return false;
                 }
-                headers.push([call.arguments[0].value, call.arguments[1].value]);
+                headers.push([call.arguments[0].value, String(call.arguments[1].value)]);
             } else if (call.obj.propertyName === "sendStatus") {
                 if (call.arguments[0].type !== "Literal") {
                     return false;
@@ -552,6 +553,11 @@ module.exports = function compileDeclarative(cb, app) {
                          * @returns {boolean}
                          */
                         function check(node) {
+                            // only "+" concatenates; any other operator computes a value the
+                            // parts cannot represent, so the handler falls back
+                            if (node.operator !== "+") {
+                                return false;
+                            }
                             if (node.right.type === "Literal") {
                                 stuff.push({ type: "text", value: node.right.value });
                             } else if (node.right.type === "MemberExpression") {
@@ -602,12 +608,14 @@ module.exports = function compileDeclarative(cb, app) {
 
         let decRes = new uWSAny.DeclarativeResponse();
 
-        if (statusCode != 200) {
-            const statusMessage = statuses.message[statusCode] ?? "";
-            decRes = decRes.writeStatus(`${statusCode} ${statusMessage}`.trim());
-            if (!headers.some((header) => header[0].toLowerCase() === "content-type")) {
-                decRes = decRes.writeHeader("content-type", "text/plain; charset=utf-8");
-            }
+        if (statusCode !== 200) {
+            const statusMessage = statuses.message[statusCode] ?? "unknown";
+            decRes = decRes.writeStatus(`${statusCode} ${statusMessage}`);
+        }
+        // only sendStatus types its body: it goes through res.type("txt") on the ordinary path,
+        // while status(n).end() sends no Content-Type at all, in Express and here alike
+        if (sendStatusUsed && !headers.some((header) => header[0].toLowerCase() === "content-type")) {
+            decRes = decRes.writeHeader("content-type", "text/plain; charset=utf-8");
         }
 
         // the same two the ordinary path seeds every response with. Without them a route answered

package/src/index.js

@@ -21,6 +21,7 @@ const uWS = require("uWebSockets.js");
 const uWSAny = /** @type {any} */ (uWS);
 const Application = require("./application.js");
 const Router = require("./router.js");
+const Route = require("./route.js");
 const middlewares = require("./middlewares.js");
 const Request = require("./request.js");
 const Response = require("./response.js");
@@ -41,6 +42,7 @@ try {
 /**
  * @type {typeof Application & {
  *   Router: Function,
+ *   Route: typeof Route,
  *   request: object,
  *   response: object,
  *   application: object,
@@ -59,6 +61,9 @@ module.exports.Router = function (options) {
     return new Router(options)._asCallable();
 };
 
+// express exports it, and code that builds a route by hand rather than through a router uses it
+module.exports.Route = Route;
+
 module.exports.request = Request.prototype;
 module.exports.response = Response.prototype;
 // the third of the trio: adding a method here adds it to every app, the same as express.application