fulmine.js 5.1.8 → 5.2.0

package/README.md

@@ -1,3 +1,5 @@
+<img src="./assets/logo-mark.svg" alt="" width="88" align="right">
+
 # Fulmine
 
 A drop-in replacement for Express 5, running on [µWebSockets.js](https://github.com/uNetworking/uWebSockets.js) instead of `node:http`. Your existing middleware keeps working.
@@ -25,8 +27,37 @@ See [Migrating](#migrating) for what it handles and what it deliberately does no
 
 [![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)
+[![CodeQL](https://github.com/nigrosimone/fulmine.js/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/nigrosimone/fulmine.js/actions/workflows/codeql.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
+## Table of contents
+
+- [Why this exists](#why-this-exists)
+- [Performance](#performance)
+- [Public benchmarks](#public-benchmarks)
+- [Attribution](#attribution)
+- [Difference from similar projects](#difference-from-similar-projects)
+- [Migrating](#migrating)
+- [Docker](#docker)
+- [Differences from Express](#differences-from-express)
+- [Performance tips](#performance-tips)
+- [WebSockets](#websockets)
+    - [socket.io](#socketio)
+- [HTTP/3](#http3)
+- [Versioning](#versioning)
+- [Compatibility](#compatibility)
+    - [express](#express)
+    - [Application](#application)
+    - [Application settings](#application-settings)
+    - [Request](#request)
+    - [Response](#response)
+    - [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)
+
 ## Why this exists
 
 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.
@@ -55,7 +86,7 @@ to run it yourself.
 
 Numbers produced by a project about itself deserve suspicion, so Fulmine also stands in public arenas, run by their own rigs under their own rules:
 
-- **[HttpArena](https://www.http-arena.com/#sort=rps:-1&q=Js)** (the link lands filtered on the JavaScript entries): first among the JavaScript entries and second overall across every language on the board. The saved run measures 7.64 million pipelined requests per second, 1.12 million on the json profile, 457 thousand on compressed json and 222 thousand on the Postgres profile.
+- **[HttpArena](https://www.http-arena.com/#sort=rps:-1&q=Js)** (the link lands filtered on the JavaScript entries): first among the JavaScript entries, across fifteen subscribed profiles. The saved runs measure 24.3 million WebSocket echoes per second pipelined and 3.77 million one-at-a-time (past Bun's own dedicated WebSocket entry), 7.3 million pipelined HTTP requests per second, 1.12 million on the json profile with 1.04 million of that surviving TLS, 457 thousand on compressed json, and 359 thousand on the Postgres CRUD profile, within ten percent of the leading Rust and C# entries there.
 - **[web-frameworks](https://github.com/the-benchmarker/web-frameworks)**: entry merged, numbers arrive with their next published round.
 
 More to come as their maintainers take the entries in.
@@ -194,10 +225,37 @@ On top of that, a handler simple enough to be read at registration time is compi
 
 ## WebSockets
 
-Since you don't create http server manually, you can't properly use http.on("upgrade") to handle WebSockets. To solve this, there's currently 2 options:
+`app.ws()` registers a WebSocket route, served by µWS itself. There is no `http.Server` underneath, so `http.on("upgrade")` and the libraries built on it do not apply; this is the replacement.
+
+```js
+app.ws("/room/:id", {
+    upgrade(req, res) {
+        // runs before the handshake, with a real request and response.
+        // Answering the response declines the socket:
+        if (!req.query.token) return res.sendStatus(401);
+        // and anything left on the request is there for the socket's whole life:
+        req.room = req.params.id;
+    },
+    open(ws) {
+        ws.subscribe(ws.req.room);
+    },
+    message(ws, message, isBinary) {
+        ws.publish(ws.req.room, message, isBinary);
+    },
+    close(ws, code, message) {}
+});
+```
+
+- **The behavior object is µWS's**, settings included: `maxPayloadLength`, `idleTimeout`, `compression`, `maxBackpressure`, `sendPingsAutomatically` and the rest are passed through untouched, as are the `open`, `message`, `drain`, `close`, `ping`, `pong`, `dropped` and `subscription` handlers. The socket is µWS's too, so `send`, `subscribe`, `publish`, `cork` and `getBufferedAmount` behave exactly as its documentation describes.
+- **`upgrade(req, res)` is this project's addition.** It runs before the handshake with the same `Request` and `Response` your routes get, so a session, a token or a header decides whether the socket opens. Answering the response, with `res.sendStatus(401)` or any other write, declines the upgrade. Returning a promise holds the handshake until it settles, which is what an authentication lookup needs.
+- **`ws.req` is that request**, and it outlives the response: the client's address, headers, query and params are readable from any handler for as long as the socket is open. Hanging your own values on it in `upgrade` is how per-connection state gets to `message`.
+- **Routers work.** `router.ws("/lobby", …)` mounted with `app.use("/chat", router)` serves `/chat/lobby`.
+- **Paths are the ones µWS matches**: literal, or with parameters that are a whole segment such as `/room/:id`. Anything else throws where it is written rather than failing to match later.
+- **Broadcasting from outside a socket**: `app.publish(topic, message)` and `app.numSubscribers(topic)`.
+
+A WebSocket route and an ordinary route can share a path: the upgrade goes to the WebSocket route, a plain GET goes through normal routing.
 
-- [Ultimate WS](https://github.com/dimdenGD/ultimate-ws) implements a `ws` compatible API on the same idea: a drop-in replacement for the `ws` module. It was written against Ultimate Express and hooks into the same upgrade mechanism, which Fulmine still exposes, but that combination is not covered by this project's tests. There's a guide for how to upgrade http requests in the documentation.
-- You can simply use `app.uwsApp` to access uWebSockets.js `App` instance and call its `ws()` method directly.
+If you would rather use the `ws` module's API, [Ultimate WS](https://github.com/dimdenGD/ultimate-ws) is a drop-in replacement for it written against Ultimate Express, and Fulmine still exposes the mechanism it hooks into, but that combination is not covered by this project's tests. `app.uwsApp` also remains available for anything µWS offers that this does not.
 
 ### socket.io
 
@@ -226,9 +284,10 @@ which runs the same file against Express and against Fulmine and compares the ou
 
 ## HTTP/3
 
-HTTP/3 is supported. To use:
+There is an `http3: true` option, inherited from Ultimate Express, that asks µWebSockets.js for its experimental HTTP/3 app. **It is guarded off with the currently pinned µWS build**: asking for it throws a clear error, because the underlying `H3App` segfaults during construction on Linux, verified with µWS alone before a single request is served. On Windows the listener does come up, but nothing answers over QUIC that we could verify, and shipping an option that works on no deployable platform helps nobody. A skipped canary test probes `H3App` on every CI run and will turn red the day µWS ships working QUIC in its prebuilt binaries, which is when the guard goes and this section changes.
 
 ```js
+// what it would look like, once µWS's H3 support actually works
 const app = express({
     http3: true,
     uwsOptions: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.1.8",
+    "version": "5.2.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {
@@ -13,7 +13,7 @@
         "test:types": "tsd --files tests/types/*.test-d.ts",
         "test:express": "node tools/express-suite.js",
         "benchmark:compare": "node benchmark/run.js",
-        "cover": "npm run cover:unit && npm run cover:report",
+        "cover": "npm run cover:full && npm run cover:report",
         "cover:unit": "nyc --silent npm run test",
         "cover:report": "nyc report --reporter=html",
         "lint": "eslint .",
@@ -25,7 +25,9 @@
         "typecheck": "tsc -p tsconfig.typecheck.json",
         "benchmark:ab": "node benchmark/ab.js",
         "benchmark:profile": "node benchmark/profile.js",
-        "release:local": "node tools/release-local.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"
     },
     "engines": {
         "node": ">=22"

package/src/application.js

@@ -15,10 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// H3App, DeclarativeResponse and _cfg all exist at runtime but are missing from the
-// declaration file the package ships, so the module is read through a loose alias
 const uWS = require("uWebSockets.js");
-const uWSAny = /** @type {any} */ (uWS);
 const Router = require("./router.js");
 const {
     removeDuplicateSlashes,
@@ -36,6 +33,7 @@ const path = require("path");
 const os = require("os");
 const { Worker } = require("worker_threads");
 const cluster = require("cluster");
+const { registerWebSocketRoutes } = require("./websocket.js");
 
 const cpuCount = os.cpus().length;
 
@@ -102,10 +100,14 @@ class Application extends Router {
         if (settings.uwsApp) {
             this.uwsApp = settings.uwsApp;
         } else if (settings.http3) {
-            if (!settings.uwsOptions.key_file_name || !settings.uwsOptions.cert_file_name) {
-                throw new Error("uwsOptions.key_file_name and uwsOptions.cert_file_name are required for HTTP/3");
-            }
-            this.uwsApp = uWSAny.H3App(settings.uwsOptions);
+            // uWS.H3App exists in the pinned build but its QUIC stack does not: the constructor
+            // segfaults on Linux and hangs forever on Windows before serving a single request,
+            // verified 2026-08-05 with uWS alone. A clear throw beats a native crash; this
+            // branch goes back to H3App once uNetworking ships working QUIC in the prebuilts.
+            throw new Error(
+                "http3 is not usable with the pinned uWebSockets.js build: its H3App crashes " +
+                    "during construction. Track uNetworking/uWebSockets.js for working QUIC support."
+            );
         } else if (settings.uwsOptions.key_file_name && settings.uwsOptions.cert_file_name) {
             this.uwsApp = uWS.SSLApp(settings.uwsOptions);
         } else {
@@ -514,6 +516,9 @@ class Application extends Router {
      */
     listen(port, host, backlog, callback) {
         this._compileOptimizedRoutes();
+        // before the catch-all: µWS sends an upgrade to the websocket route even when a
+        // catch-all covers the same path, so the two coexist and the order is only tidiness
+        registerWebSocketRoutes(this);
         this._createRequestHandler();
         // node's shapes: (cb), (port, cb), (port, host, cb) and (port, host, backlog, cb)
         if (typeof port === "function") {
@@ -594,6 +599,32 @@ class Application extends Router {
         return this;
     }
 
+    /**
+     * Publishes a message to every socket subscribed to a topic, from outside any of them.
+     *
+     * The socket's own `publish` reaches the same topics; this one is for the sender that is
+     * not a socket, a timer or a route handler broadcasting to a room.
+     *
+     * @param {string} topic
+     * @param {string|ArrayBuffer|Buffer} message
+     * @param {boolean} [isBinary]
+     * @param {boolean} [compress]
+     * @returns {boolean} whether the topic had anyone listening
+     */
+    publish(topic, message, isBinary, compress) {
+        return this.uwsApp.publish(topic, message, isBinary, compress);
+    }
+
+    /**
+     * How many sockets are subscribed to a topic.
+     *
+     * @param {string} topic
+     * @returns {number}
+     */
+    numSubscribers(topic) {
+        return this.uwsApp.numSubscribers(topic);
+    }
+
     /**
      * The bound address, or null when not listening.
      * @returns {{address: string, family: string, port: number}|null}

package/src/declarative.js

@@ -606,6 +606,13 @@ module.exports = function compileDeclarative(cb, app) {
             }
         }
 
+        // a handler that never sends is not a response: Express leaves the request waiting, so
+        // compiling the empty shape would answer a bare 200 where the ordinary path answers
+        // nothing at all. It has to fall back instead.
+        if (!sendUsed && !sendStatusUsed) {
+            return false;
+        }
+
         let decRes = new uWSAny.DeclarativeResponse();
 
         if (statusCode !== 200) {

package/src/middlewares.js

@@ -251,7 +251,7 @@ function bodyError(message, status, type, extra) {
  * that climbs out of the root, applies the dotfiles and index rules, and hands the rest over.
  *
  * @param {string} root directory to serve from
- * @param {object} [options] index, redirect, fallthrough, dotfiles, extensions, setHeaders, etag
+ * @param {import("./options").StaticOptions} [options]
  * @returns {(req: any, res: any, next: (err?: any) => void) => any}
  */
 function serveStatic(root, options) {
@@ -321,8 +321,8 @@ function serveStatic(root, options) {
             } else return next();
         }
         let _path = url;
-        const fullpath = path.resolve(path.join(options.root, url));
-        if (options.root && !fullpath.startsWith(path.resolve(options.root))) {
+        const fullpath = path.resolve(path.join(root, url));
+        if (root && !fullpath.startsWith(path.resolve(root))) {
             if (!options.fallthrough) {
                 res.status(403);
                 return next(httpError(403));
@@ -472,13 +472,16 @@ function createInflate(contentEncoding) {
  *   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
+ * @returns {(options?: import("./options").BodyParserOptions) => Function} the middleware factory
  */
 function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy, keepsBuffer) {
-    return function (options) {
+    return function (userOptions) {
         // 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
-        options = options && typeof options === "object" ? { ...options } : new NullObject();
+        // object, altering it after the parser was built would alter the parser. The type says
+        // settled because the block below fills in every default, which is what the middleware
+        // and its closures then rely on
+        /** @type {import("./options").BodyParserOptions} */
+        const options = userOptions && typeof userOptions === "object" ? { ...userOptions } : new NullObject();
         // refused where it is written, not where it is used: an option nobody can honour is a
         // mistake in the application, and body-parser throws for it at the same point
         if (options.verify !== undefined && options.verify !== false && typeof options.verify !== "function") {
@@ -491,11 +494,17 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
         // and every comparison against it is false. express.json({ limit: 5 * 1024 * 1024 }) had no
         // limit at all. parse, and only what needs parsing
         if (typeof options.limit === "undefined") {
-            options.limit = bytes.parse("100kb");
+            options.limit = /** @type {number} */ (bytes.parse("100kb"));
         } else if (typeof options.limit !== "number") {
-            options.limit = bytes.parse(options.limit);
+            // bytes.parse answers null for a size it cannot read, and body-parser passes that
+            // along untouched too: matching it matters more than improving on it here
+            options.limit = /** @type {number} */ (bytes.parse(options.limit));
         }
 
+        // settled above, and read once: every check below wants the value, not the bag
+        const limit = /** @type {number} */ (options.limit);
+        const defaultCharset = /** @type {string} */ (options.defaultCharset ?? "utf-8");
+
         if (typeof options.inflate === "undefined") options.inflate = true;
         if (typeof options.type === "undefined") options.type = defaultType;
         if (typeof options.type === "string") {
@@ -523,7 +532,9 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
         //
         // typeis.is and not typeis(req, ...): the request form first checks that there is a body,
         // and the caller below has established that already.
-        const claimsType = memoizeByString((contentType) => !!typeis.is(contentType, options.type));
+        const claimsType = memoizeByString(
+            (contentType) => !!typeis.is(contentType, /** @type {string[]} */ (options.type))
+        );
 
         let additionalMethods;
 
@@ -585,7 +596,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // answers 415 even for an empty body, and before the verify hook can run
             let encoding;
             if (charsetPolicy) {
-                encoding = charsetOf(type) ?? options.defaultCharset;
+                encoding = charsetOf(type) ?? defaultCharset;
                 if (
                     (charsetPolicy === "utf" && encoding.slice(0, 4) !== "utf-") ||
                     (charsetPolicy === "urlencoded" && encoding !== "utf-8" && encoding !== "iso-8859-1")
@@ -611,12 +622,12 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             }
 
             // skip reading too large body
-            if (length && +length > options.limit) {
+            if (length && +length > limit) {
                 return next(
                     bodyError("request entity too large", 413, "entity.too.large", {
                         expected: +length,
                         length: +length,
-                        limit: options.limit
+                        limit: limit
                     })
                 );
             }
@@ -674,13 +685,13 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             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) => {
+                req._res.collectBody(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
+                                limit: limit,
+                                received: limit
                             })
                         );
                     }
@@ -710,7 +721,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // known and we aren't inflating, the final size is known up front, so chunks can go
             // straight into one buffer and the body is copied once.
             // the cap means a client that declares a body and never sends it costs no more than one
-            // that actually sends a body that size, and content-length above options.limit was
+            // that actually sends a body that size, and content-length above limit was
             // already rejected above
             const declaredLength = inflate ? -1 : Number(length);
             let target =
@@ -757,13 +768,13 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
              */
             function keepChunk(buf) {
                 totalSize += buf.length;
-                if (totalSize > options.limit) {
+                if (totalSize > limit) {
                     finished = true;
                     abs.length = 0;
                     target = null;
                     next(
                         bodyError("request entity too large", 413, "entity.too.large", {
-                            limit: options.limit,
+                            limit: limit,
                             received: totalSize
                         })
                     );

package/src/options.d.ts

@@ -0,0 +1,94 @@
+// The option bags the file-serving and body-parsing paths take, written once and referenced from
+// the JSDoc of the functions that read them. They live in a declaration file rather than as
+// @typedef blocks in the sources because those sources export classes, and a typedef hanging off
+// a `module.exports = class` module makes TypeScript see two unrelated copies of the class.
+
+/** What res.sendFile, express.static and res.download all read. The names and defaults are send's. */
+export interface SendFileOptions {
+    /** The directory a relative path resolves against, and the boundary nothing may climb out of. */
+    root?: string;
+    /** Cache-Control's max-age, in milliseconds or as a duration such as "1d". */
+    maxAge?: number | string;
+    /** Adds Cache-Control: immutable, which is only meaningful next to a long maxAge. */
+    immutable?: boolean;
+    /** Whether Last-Modified is sent, from the file's mtime. */
+    lastModified?: boolean;
+    /** Whether an ETag is sent. */
+    etag?: boolean;
+    /** Whether a Range request is honoured. */
+    acceptRanges?: boolean;
+    /** Whether Cache-Control is sent at all. */
+    cacheControl?: boolean;
+    /**
+     * What to do with a path holding a dotfile. "ignore_files" is one more than send offers:
+     * it hides a dotfile that is the last segment while letting a dotted directory through.
+     */
+    dotfiles?: "allow" | "deny" | "ignore" | "ignore_files";
+    /** Extra headers for the response. */
+    headers?: Record<string, string>;
+    /** Called before the file goes out, to set headers from the path or its stat. */
+    setHeaders?: (res: any, path: string, stat: any) => void;
+    /** First byte of the window to send. */
+    start?: number;
+    /** Last byte of the window to send. */
+    end?: number;
+    /** The path is already encoded, so leave it alone. */
+    skipEncodePath?: boolean;
+    /** Internal: locals carried through to a view render. */
+    _locals?: Record<string, any>;
+    /** Internal: the stat the caller already took, so it is not taken twice. */
+    _stat?: any;
+    /** Internal: the caller computed the ETag itself. */
+    _ownEtag?: boolean;
+}
+
+/** What express.static reads on top of everything res.sendFile takes. */
+export interface StaticOptions extends SendFileOptions {
+    /** The file served for a directory, or false to serve none. */
+    index?: string | false;
+    /** Whether a directory without a trailing slash is redirected to one. */
+    redirect?: boolean;
+    /** Whether a request this middleware cannot serve moves on instead of being answered. */
+    fallthrough?: boolean;
+    /** Extensions tried when the path names no file, or false to try none. */
+    extensions?: string[] | false;
+}
+
+/** A body parser's options once its factory has filled in every default it needs. */
+export interface SettledBodyParserOptions extends BodyParserOptions {
+    limit: number;
+    inflate: boolean;
+    /** the string form is turned into a one-element list by the factory */
+    type: string[] | ((req: any) => boolean);
+    defaultCharset: string;
+}
+
+/** What the body parsers take. The four share these; each names below the ones it alone reads. */
+export interface BodyParserOptions {
+    /** The largest body to accept, as bytes or as "100kb". */
+    limit?: number | string;
+    /** Which content types this parser claims. */
+    type?: string | string[] | ((req: any) => boolean);
+    /** Runs on the raw bytes before parsing, which is where a signature check belongs. */
+    verify?: false | ((req: any, res: any, buf: Buffer, encoding: string) => void);
+    /** Whether a compressed body is decompressed rather than refused. */
+    inflate?: boolean;
+    /** The charset assumed when the request names none. */
+    defaultCharset?: string;
+    /** json only: refuse a body that is not an object or an array. */
+    strict?: boolean;
+    /** json only, passed to JSON.parse. */
+    reviver?: (key: string, value: any) => any;
+    /** urlencoded only: parse with qs rather than the plain parser. */
+    extended?: boolean;
+    /** urlencoded only: how many parameters to accept. */
+    parameterLimit?: number;
+    /** urlencoded only, extended only: how deep a nested object may go. */
+    depth?: number;
+    /** urlencoded only, passed to qs. */
+    charsetSentinel?: boolean;
+    /** urlencoded only, passed to qs. */
+    interpretNumericEntities?: boolean;
+    /** Internal: the single type this parser claims, which lets the prologue compare strings. */
+    simpleType?: string;
+}

package/src/request.js

@@ -139,26 +139,53 @@ module.exports = class Request extends Readable {
     /** @type {Record<string, string[]>|null} */
     #cachedDistinctHeaders = null;
 
-    // Flat, name then value: an array of pairs meant one array allocated per header on every
-    // request, and a request carries eight or ten of them. Everything that reads this walks it two
-    // at a time. The names are lowercase by contract: uWS lowers them on the wire and the node
-    // shim lowers them in its forEach, so readers compare without lowering again.
+    /**
+     * Every header, flat: name then value, name then value.
+     *
+     * An array of pairs meant one array allocated per header on every request, and a request
+     * carries eight or ten of them, so everything that reads this walks it two at a time. The
+     * names are lowercase by contract: uWS lowers them on the wire and the node shim lowers
+     * them in its forEach, so readers compare without lowering again.
+     *
+     * @type {string[]}
+     */
     #rawHeadersEntries = [];
 
     /** @type {string|undefined|null} */
     #cachedParsedIp = null;
 
+    /** Whether backpressure has asked uWS to stop delivering the body for now. */
     #paused = false;
 
-    // a bodyless request whose empty end has not been delivered yet, see the constructor
+    /** A bodyless request whose empty end has not been delivered yet, see the constructor. */
     #emptyBody = false;
 
+    /**
+     * What a body parser left behind, and undefined until one claims the request.
+     * @type {any}
+     */
     body;
 
+    /**
+     * The response this request arrived with, linked so either reaches the other.
+     *
+     * Typed loosely on purpose: it is linked right after construction rather than in the
+     * constructor, and the honest `Response|undefined` would put a check in front of every
+     * use of a field that is never observed unset.
+     *
+     * @type {any}
+     */
     res;
 
-    // one function for every request, fed through currentRequest: an arrow in the constructor
-    // captured `this`, which cost a context and a function allocation per request
+    /**
+     * Copies one header out of uWS and notices the two things the constructor decides by.
+     *
+     * One function for every request, fed through currentRequest: an arrow in the constructor
+     * captured `this`, which cost a context and a function allocation per request.
+     *
+     * @param {string} headerKey lowercase, as uWS hands it over
+     * @param {string} value
+     */
     static #collectHeader = (headerKey, value) => {
         const r = currentRequest;
         r.#rawHeadersEntries.push(headerKey, value);
@@ -183,10 +210,31 @@ module.exports = class Request extends Readable {
         }
     };
 
+    /**
+     * The parameters a native uWS route matched, by name, or undefined off that path.
+     * @type {Record<string, string>|undefined}
+     */
     optimizedParams;
 
+    /**
+     * The continuation of the chain currently running, which express also hands to a handler
+     * through the request. Declared rather than left to appear on assignment: runRoute sets it
+     * on every request, and an undeclared property is a shape change on each one.
+     *
+     * @type {any}
+     */
+    next;
+
+    /**
+     * What the chain threw or passed to next(err), waiting for an error handler.
+     * @type {any}
+     */
     _error;
 
+    /**
+     * Set by the paths that must not earn an ETag, res.sendFile's stream among them.
+     * @type {boolean|undefined}
+     */
     noEtag;
 
     /**
@@ -749,6 +797,33 @@ module.exports = class Request extends Readable {
         return this.connection;
     }
 
+    /**
+     * Cuts this request loose from the µWS response it arrived on, keeping the two things only
+     * that response could answer.
+     *
+     * A websocket upgrade hands the request to the socket, which outlives the response by the
+     * whole life of the connection. Reading the peer address through the freed response is not
+     * an error but a use after free, so the values are taken while it is still alive and an
+     * inert stand-in answers anything that asks later.
+     */
+    _detachFromResponse() {
+        const uwsRes = this._res;
+        if (!this.rawIp) {
+            this.rawIp = uwsRes.getRemoteAddress();
+        }
+        const remotePort = uwsRes.getRemotePort();
+        const rawIp = this.rawIp;
+        this._res = {
+            getRemoteAddress: () => rawIp,
+            getRemotePort: () => remotePort,
+            // a body cannot arrive on an upgraded socket, and a stray reader must not reach µWS
+            onData() {},
+            pause() {},
+            resume() {},
+            close() {}
+        };
+    }
+
     /**
      * Whether the client's cached copy is still good, from If-None-Match and If-Modified-Since
      * against the response headers set so far. Only GET and HEAD can be fresh.

package/src/response.js

@@ -123,6 +123,7 @@ module.exports = class Response extends Writable {
     /** @type {Socket|null} */
     #socket = null;
 
+    /** Whether end() has run, which is what makes a second one a no-op rather than a throw. */
     #ended = false;
 
     /** @type {((err?: Error|null) => void)|null} */
@@ -131,6 +132,10 @@ module.exports = class Response extends Writable {
     /** @type {any} */
     #outHeaders = null;
 
+    /**
+     * The request this response answers, linked so either reaches the other.
+     * @type {InstanceType<typeof import("./request.js")>}
+     */
     req;
 
     /**
@@ -145,6 +150,9 @@ module.exports = class Response extends Writable {
     constructor(res, req, app) {
         super();
         this._req = req;
+        // linked here rather than by the caller: the pair is built together, and a field the
+        // constructor leaves unset is a shape change on whoever assigns it first
+        this.req = req;
         this._res = res;
         this.headersSent = false;
         this.app = app;
@@ -673,7 +681,7 @@ module.exports = class Response extends Writable {
      * "ignore"), `acceptRanges`, `cacheControl`, `immutable`, `etag` and `setHeaders`.
      *
      * @param {string} path
-     * @param {Record<string, any>} [options]
+     * @param {import("./options").SendFileOptions} [options]
      * @param {(err?: Error) => void} [callback] called once sent, or with the error
      */
     sendFile(path, options = new NullObject(), callback) {
@@ -893,9 +901,11 @@ module.exports = class Response extends Writable {
         // range requests
         if (options.acceptRanges) {
             if (this.req.headers.range) {
-                let ranges = this.req.range(len, {
-                    combine: true
-                });
+                // the branch above established the header is there, so range() cannot answer
+                // the undefined it uses to mean "no Range header"
+                let ranges = /** @type {ReturnType<typeof import("range-parser")>} */ (
+                    this.req.range(len, { combine: true })
+                );
 
                 // if-range
                 if (!isRangeFresh(this.req, this)) {
@@ -1003,7 +1013,7 @@ module.exports = class Response extends Writable {
      *
      * @param {string} path
      * @param {string} [filename] name offered to the user, defaults to the basename of the path
-     * @param {Record<string, any>} [options] passed through to sendFile
+     * @param {import("./options").SendFileOptions} [options] passed through to sendFile
      * @param {(err?: Error) => void} [callback]
      */
     download(path, filename, options, callback) {
@@ -1236,7 +1246,10 @@ module.exports = class Response extends Writable {
      */
     cookie(name, value, options) {
         const opt = { ...(options ?? {}) }; // create a new ref because we change original object (https://github.com/dimdenGD/ultimate-express/issues/68)
-        if (opt.signed && !this.req.secret) {
+        // cookie-parser hangs the secret on the request, so it is read off it rather than
+        // declared here: without that middleware there is none, which is what this checks
+        const req = /** @type {any} */ (this.req);
+        if (opt.signed && !req.secret) {
             // the message has to read like this: it is the one Express throws, and it names the
             // thing that is actually missing rather than the library that noticed
             throw new Error('cookieParser("secret") required for signed cookies');
@@ -1254,7 +1267,7 @@ module.exports = class Response extends Writable {
             delete opt.maxAge;
         }
         if (opt.signed) {
-            val = "s:" + sign(val, this.req.secret);
+            val = "s:" + sign(val, req.secret);
         }
 
         if (opt.path == null) {
@@ -1304,7 +1317,9 @@ module.exports = class Response extends Writable {
      */
     format(object) {
         const keys = Object.keys(object).filter((v) => v !== "default");
-        const key = keys.length > 0 ? this.req.accepts(keys) : false;
+        // accepts answers the whole list only when asked with no arguments; given types it
+        // answers the best of them, or false
+        const key = keys.length > 0 ? /** @type {string|false} */ (this.req.accepts(keys)) : false;
 
         this.vary("Accept");
 
@@ -1501,6 +1516,10 @@ module.exports = class Response extends Writable {
         return this.set("content-type", ct);
     }
 
+    /**
+     * express carries both names for the same method, and middleware reaches for either.
+     * @type {(type: string) => any}
+     */
     contentType = this.type;
 
     /**

package/src/router.js

@@ -37,6 +37,7 @@ const statuses = require("statuses");
 const { METHODS } = require("http");
 const { isNodeRequest, serveNodeRequest } = require("./node-shim.js");
 const { chainUsage } = require("./usage.js");
+const { checkBehavior } = require("./websocket.js");
 
 // every method the declarative compiler can emit: a patched one must disable compilation, or the
 // patch would be honoured everywhere but on compiled routes
@@ -836,10 +837,27 @@ function generateErrorPageHtml(err) {
 }
 
 module.exports = class Router extends EventEmitter {
+    /**
+     * The router or application this one is mounted on, undefined until it is.
+     * @type {any}
+     */
     parent;
 
+    /**
+     * Whether listen() has run, after which a new route can no longer reach uWS.
+     * @type {boolean|undefined}
+     */
     listenCalled;
 
+    /**
+     * The uWS app routes are registered on.
+     *
+     * Typed loosely on purpose: only an Application owns one, and the callers that reach for
+     * it have already established that, so the honest `TemplatedApp|undefined` would only add
+     * casts where the guard already is.
+     *
+     * @type {any}
+     */
     uwsApp;
 
     /**
@@ -852,6 +870,10 @@ module.exports = class Router extends EventEmitter {
         this._paramCallbacks = new Map();
         this._mountpathCache = new Map();
         this._routes = [];
+        // websocket routes, kept apart from the HTTP ones: µWS serves them itself and listen()
+        // hands them over whole, mount paths and all
+        /** @type {any[]|null} */
+        this._wsRoutes = null;
         // the native presets allowed to skip the header copy, so a late middleware or an etag
         // arriving after listen can take the permission back; null until one is granted
         /** @type {Set<any>|null} */
@@ -1393,7 +1415,6 @@ module.exports = class Router extends EventEmitter {
         const request = new this._request(req, res, this, preset, skipHolder);
         const response = new this._response(res, request, this);
         request.res = response;
-        response.req = request;
 
         return request;
     }
@@ -1974,6 +1995,38 @@ module.exports = class Router extends EventEmitter {
         return this;
     }
 
+    /**
+     * Registers a websocket route, which µWS serves itself.
+     *
+     * The behavior is µWS's, settings and socket handlers alike, plus one addition: an
+     * `upgrade(req, res)` of this project's own shape, which runs before the handshake with a
+     * real request and response. Answering with the response declines the socket, which is how
+     * a check refuses one; returning a promise holds the handshake until it settles.
+     *
+     * The request lives as long as the socket and reaches every handler as `ws.req`, so what
+     * the upgrade learned about the client, and anything it hangs on the request, is there when
+     * a message arrives.
+     *
+     * @example
+     * app.ws("/room/:id", {
+     *     upgrade(req, res) {
+     *         if (!req.query.token) return res.sendStatus(401);
+     *         req.room = req.params.id;
+     *     },
+     *     open(ws) { ws.subscribe(ws.req.room); },
+     *     message(ws, message, isBinary) { ws.publish(ws.req.room, message, isBinary); }
+     * });
+     *
+     * @param {string} path a literal path, or one whose parameters are whole segments
+     * @param {object} behavior µWS's WebSocketBehavior, plus the optional `upgrade` above
+     * @returns {this}
+     */
+    ws(path, behavior) {
+        checkBehavior(path, behavior);
+        (this._wsRoutes ??= []).push({ path, behavior, owner: this });
+        return this;
+    }
+
     /**
      * A builder for one path, so the path is written once and the verbs chain off it.
      *

package/src/types.d.ts

@@ -24,6 +24,9 @@ declare module "fulmine.js" {
         export import urlencoded = e.urlencoded;
 
         export import RouterOptions = e.RouterOptions;
+        // Router is declared rather than re-exported, because this project's routers carry ws()
+        export function Router(options?: e.RouterOptions): FulmineRouter;
+        export type Router = FulmineRouter;
         export import Application = e.Application;
         export import CookieOptions = e.CookieOptions;
         export import Errback = e.Errback;
@@ -41,7 +44,6 @@ declare module "fulmine.js" {
         export import RequestHandler = e.RequestHandler;
         export import RequestParamHandler = e.RequestParamHandler;
         export import Response = e.Response;
-        export import Router = e.Router;
         export import Send = e.Send;
     }
 
@@ -49,12 +51,43 @@ declare module "fulmine.js" {
         uwsApp: uWS.TemplatedApp;
     };
 
-    type Fulmine = Omit<e.Express, "listen"> & {
+    // what app.ws() hands the socket, and what µWS merges onto it: the request is reachable as
+    // ws.req for as long as the socket is open
+    type SocketData = { req: e.Request };
+    type FulmineWebSocket = uWS.WebSocket<SocketData> & SocketData;
+
+    // µWS's behavior, with its socket handlers retyped around that request and its own upgrade
+    // replaced by this project's, which takes a request and a response
+    type WebSocketBehavior = Omit<
+        uWS.WebSocketBehavior<SocketData>,
+        "upgrade" | "open" | "message" | "dropped" | "drain" | "close" | "ping" | "pong" | "subscription"
+    > & {
+        upgrade?: (req: e.Request, res: e.Response) => void | Promise<void>;
+        open?: (ws: FulmineWebSocket) => void;
+        message?: (ws: FulmineWebSocket, message: ArrayBuffer, isBinary: boolean) => void;
+        dropped?: (ws: FulmineWebSocket, message: ArrayBuffer, isBinary: boolean) => void;
+        drain?: (ws: FulmineWebSocket) => void;
+        close?: (ws: FulmineWebSocket, code: number, message: ArrayBuffer) => void;
+        ping?: (ws: FulmineWebSocket, message: ArrayBuffer) => void;
+        pong?: (ws: FulmineWebSocket, message: ArrayBuffer) => void;
+        subscription?: (ws: FulmineWebSocket, topic: ArrayBuffer, newCount: number, oldCount: number) => void;
+    };
+
+    // interfaces rather than aliases: `this` is how ws() answers the router or the app it was
+    // called on, and an alias naming itself in an intersection is circular
+    interface FulmineRouter extends e.Router {
+        ws(path: string, behavior: WebSocketBehavior): this;
+    }
+
+    interface Fulmine extends Omit<e.Express, "listen"> {
         readonly uwsApp: uWS.TemplatedApp;
         listen(port: number, callback?: (token: any) => void): FulmineServer;
         listen(port: number, host: string, callback?: (token: any) => void): FulmineServer;
         listen(callback: (token: any) => void): FulmineServer;
-    };
+        ws(path: string, behavior: WebSocketBehavior): this;
+        publish(topic: string, message: string | ArrayBuffer | Buffer, isBinary?: boolean, compress?: boolean): boolean;
+        numSubscribers(topic: string): number;
+    }
 
     function express(settings?: Settings): Fulmine;
 

package/src/usage.js

@@ -76,7 +76,13 @@ function callbackUsage(fn) {
 
 /** @param {Function} fn @returns {number} */
 function analyze(fn) {
-    let code = fn.toString();
+    // toString is application-controlled and may throw or answer anything: unreadable is unknown
+    let code;
+    try {
+        code = String(fn.toString());
+    } catch {
+        return UNKNOWN;
+    }
     if (code.startsWith("function") || code.startsWith("async function")) {
         code = code.replace(/function *\(/, "function __cb(");
     }

package/src/websocket.js

@@ -0,0 +1,223 @@
+"use strict";
+
+const { canBeOptimizedWithParams, decodeParam, NullObject } = require("./utils.js");
+
+// the parameter names in a path, in the order µWS numbers them
+const PARAM = /:(\w+)/g;
+
+// Handlers µWS calls with the socket. Everything else in a behavior object is a µWS setting
+// (maxPayloadLength, idleTimeout, compression, ...) and rides through untouched.
+const SOCKET_HANDLERS = ["open", "message", "dropped", "drain", "close", "ping", "pong", "subscription"];
+
+/**
+ * Joins a mount path and a route path the way the router does, without the empty-string edges
+ * that would leave a double slash.
+ *
+ * @param {string} prefix
+ * @param {string} path
+ * @returns {string}
+ */
+function joinPaths(prefix, path) {
+    if (!prefix || prefix === "/") {
+        return path;
+    }
+    if (!path || path === "/") {
+        return prefix;
+    }
+    return prefix + path;
+}
+
+/**
+ * Every websocket route reachable from this router, with the mount paths already applied.
+ *
+ * Walked separately from the HTTP routes: those fall back to ordinary routing when µWS cannot
+ * match them, and a websocket has no fallback to fall back to, so an unmountable one has to be
+ * refused out loud instead.
+ *
+ * @param {any} router
+ * @param {string|null} prefix the mount path accumulated so far, or null once a mount was a
+ *   shape µWS cannot match, which makes everything below it unreachable
+ * @param {any[]} out
+ * @param {Set<any>} seen routers already walked, since a router may be mounted twice
+ */
+function collectRoutes(router, prefix, out, seen) {
+    if (seen.has(router)) {
+        return;
+    }
+    seen.add(router);
+
+    for (const entry of router._wsRoutes ?? []) {
+        if (prefix === null) {
+            throw new Error(
+                `websocket route "${entry.path}" sits under a mount µWS cannot match. ` +
+                    "Mount the router on a literal path, or on one whose parameters are whole segments."
+            );
+        }
+        const path = joinPaths(prefix, entry.path);
+        if (!canBeOptimizedWithParams(path)) {
+            throw new Error(
+                `websocket path "${path}" is not one µWS can match. Use a literal path, or ` +
+                    "parameters that are a whole segment, as in /room/:id."
+            );
+        }
+        out.push({ path, behavior: entry.behavior, owner: entry.owner });
+    }
+
+    for (const route of router._routes) {
+        if (!route.use) {
+            continue;
+        }
+        for (const callback of route.callbacks) {
+            // a mounted Router, or a callable sub-app, which is a function carrying routes
+            if (callback && callback._routes) {
+                const mount =
+                    prefix === null || typeof route.path !== "string" || !canBeOptimizedWithParams(route.path)
+                        ? null
+                        : joinPaths(prefix, route.path);
+                collectRoutes(callback, mount, out, seen);
+            }
+        }
+    }
+}
+
+/**
+ * The µWS upgrade handler for one route: it builds this project's request and response, offers
+ * them to the application's own `upgrade` hook, and completes the handshake unless that hook
+ * answered the request itself.
+ *
+ * @param {any} app the application whose request and response classes serve this route
+ * @param {string} path the composed path, whose parameters are read back by index
+ * @param {any} behavior what the caller registered
+ * @returns {(res: any, req: any, context: any) => void}
+ */
+function makeUpgradeHandler(app, path, behavior) {
+    const paramNames = [...path.matchAll(PARAM)].map((match) => match[1]);
+    const userUpgrade = behavior.upgrade;
+
+    return (res, req, context) => {
+        // read off the µWS request before anything can await: it is neutered on return, and the
+        // handshake needs these three even when the upgrade is decided asynchronously
+        const key = req.getHeader("sec-websocket-key");
+        const protocol = req.getHeader("sec-websocket-protocol");
+        const extensions = req.getHeader("sec-websocket-extensions");
+
+        const request = new app._request(req, res, app);
+        if (paramNames.length) {
+            const params = new NullObject();
+            for (let i = 0; i < paramNames.length; i++) {
+                params[paramNames[i]] = decodeParam(req.getParameter(i));
+            }
+            request.params = params;
+        }
+
+        let aborted = false;
+
+        /** Completes the handshake, unless the hook answered or the client already left. */
+        const accept = () => {
+            if (aborted || request.res?.finished) {
+                return;
+            }
+            // the socket outlives the response, so what only the response can answer is read
+            // while it is still alive: reading it later would be a use after free
+            request._detachFromResponse();
+            res.cork(() => {
+                res.upgrade({ req: request }, key, protocol, extensions, context);
+            });
+        };
+
+        if (!userUpgrade) {
+            accept();
+            return;
+        }
+
+        const response = new app._response(res, request, app);
+        request.res = response;
+
+        let decision;
+        try {
+            decision = userUpgrade(request, response);
+        } catch (err) {
+            // an upgrade that throws refuses the socket, and says so the way an unhandled route
+            // would rather than leaving the client hanging on a half-open handshake
+            if (!response.finished) {
+                res.cork(() => {
+                    response.status(500).end();
+                });
+            }
+            app.emit("error", err);
+            return;
+        }
+
+        if (!decision || typeof decision.then !== "function") {
+            accept();
+            return;
+        }
+
+        // an async hook (a session lookup, a token check) outlives this callback, so µWS has to
+        // be told who to call if the client leaves first. Registered now, still inside the
+        // handler, which is the only place µWS accepts it
+        res.onAborted(() => {
+            aborted = true;
+        });
+        // and whatever the hook writes now lands outside the cork µWS holds for this callback,
+        // so the response opens its own, exactly as a route handler answering late does
+        response._corkNeeded = true;
+        decision.then(accept, (err) => {
+            if (!aborted && !response.finished) {
+                res.cork(() => {
+                    response.status(500).end();
+                });
+            }
+            app.emit("error", err);
+        });
+    };
+}
+
+/**
+ * Hands every websocket route this application can reach to µWS. Called from listen(), before
+ * the catch-all goes on: µWS routes an upgrade to the websocket route even when a catch-all
+ * covers the same path, so the two live side by side.
+ *
+ * @param {any} app
+ */
+function registerWebSocketRoutes(app) {
+    const routes = [];
+    collectRoutes(app, "", routes, new Set());
+    for (const route of routes) {
+        const uwsBehavior = { ...route.behavior };
+        delete uwsBehavior.upgrade;
+        // bound to the owner's classes, so a mounted sub-app's request layer is the one its own
+        // handlers expect
+        uwsBehavior.upgrade = makeUpgradeHandler(route.owner ?? app, route.path, route.behavior);
+        app.uwsApp.ws(route.path, uwsBehavior);
+    }
+}
+
+/**
+ * Whatever a caller passed as a behavior, checked where it is written rather than where it is
+ * used: a handler under a misspelled name would otherwise never run and never say why.
+ *
+ * @param {string} path
+ * @param {any} behavior
+ */
+function checkBehavior(path, behavior) {
+    if (typeof path !== "string") {
+        throw new TypeError("app.ws() requires a path string");
+    }
+    if (!behavior || typeof behavior !== "object") {
+        throw new TypeError("app.ws() requires a behavior object, as µWS takes");
+    }
+    if (!canBeOptimizedWithParams(path)) {
+        throw new Error(
+            `websocket path "${path}" is not one µWS can match. Use a literal path, or ` +
+                "parameters that are a whole segment, as in /room/:id."
+        );
+    }
+    for (const name of [...SOCKET_HANDLERS, "upgrade"]) {
+        if (behavior[name] !== undefined && typeof behavior[name] !== "function") {
+            throw new TypeError(`app.ws() behavior.${name} must be a function`);
+        }
+    }
+}
+
+module.exports = { registerWebSocketRoutes, checkBehavior };