fulmine.js 5.4.0 → 5.5.0

package/README.md

@@ -46,6 +46,7 @@ shared machine, so the number would describe the machine rather than the framewo
 - [Attribution](#attribution)
 - [Difference from similar projects](#difference-from-similar-projects)
 - [Migrating](#migrating)
+    - [Angular SSR](#angular-ssr)
     - [When Express is somebody else's dependency](#when-express-is-somebody-elses-dependency)
 - [Docker](#docker)
 - [Differences from Express](#differences-from-express)
@@ -96,7 +97,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, 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.
+- **[web-frameworks](https://web-frameworks-benchmark.netlify.app/result?l=javascript)**: entry merged, numbers arrive with their next published round.
 
 More to come as their maintainers take the entries in.
 
@@ -130,6 +131,28 @@ 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.
 
+### Angular SSR
+
+The `server.ts` that `ng add @angular/ssr` generates is an ordinary Express application, so the same
+one-line change applies, and `@angular/ssr`'s own `AngularNodeAppEngine` and
+`writeResponseToNodeResponse` work against Fulmine's request and response unchanged. One extra step
+is needed, and it is Angular's build rather than this library: the server bundle is built with
+esbuild, which tries to inline every dependency and cannot load µWS's native binary. Declare the two
+as external in `angular.json`:
+
+```json
+"architect": { "build": { "options": {
+    "externalDependencies": ["fulmine.js", "uWebSockets.js"]
+} } }
+```
+
+What it is worth, measured on an Angular 22 application with each server reporting its own CPU per
+request, nine alternating rounds: **static assets 3.29x**, and **a page served from an in-process
+cache 1.90x**, but only when the cache keeps the body's ETag and length beside the bytes. A cache
+that stores the bytes alone measures level with Express, because both then hash the document again
+on every hit. The render itself is the same JavaScript on both sides and measures the same: on a
+cache miss the framework is not what your page is waiting for.
+
 ### 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,
@@ -627,6 +650,7 @@ Fulmine adds three of its own:
 - ✅ res.removeHeader()
 - ✅ res.write()
 - ✅ res.writeHead()
+- ✅ res.flushHeaders()
 
 ### Router
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.4.0",
+    "version": "5.5.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {

package/src/request.js

@@ -266,9 +266,6 @@ Object.defineProperty(LazyReadableBase.prototype, "readable", {
 });
 
 module.exports = class Request extends LazyReadable {
-    /** @type {Record<string, any>|null} */
-    #cachedQuery = null;
-
     /** @type {Record<string, any>|null} */
     #cachedHeaders = null;
 
@@ -892,7 +889,6 @@ module.exports = class Request extends LazyReadable {
         this._rawQuery = queryIndex === -1 ? "" : newUrl.slice(queryIndex + 1);
         // a rewrite to "/a?" keeps its "?", as one arriving that way does
         this.urlQuery = queryIndex === -1 ? "" : "?" + this._rawQuery;
-        this.#cachedQuery = null;
         this._originalPath = prefix + newPath;
         this.path = newPath;
         this.endsWithSlash = newPath.charCodeAt(newPath.length - 1) === 0x2f;
@@ -913,27 +909,28 @@ module.exports = class Request extends LazyReadable {
      * the parse cached and handed out as itself, the sanitised value leaked into req.query here and
      * a handler written against express read a trimmed value where express gives it the raw one.
      *
-     * The parse itself is still done once. What is copied per read is the shallow result, which is
-     * cheaper than express's re-parse and answers the same for everything but a write to a nested
-     * key, which only the extended parser can produce.
+     * And that is why there is no cache: the fresh object comes from parsing the raw string again,
+     * not from copying a kept parse. As first shipped this was parse-once-copy-per-read, and the
+     * copy was the expensive half: Object.assign between null-prototype objects, which live in
+     * V8's dictionary mode, measured 638ns for a two-parameter query where parsing the same string
+     * measures 119ns, and on a benchmark whose every request carries such a query it cost +1.5us
+     * of CPU per request, which a public arena saw as -8% on its query-carrying rows. A handler
+     * that reads req.query once per request now pays exactly what it paid when the parse was
+     * cached, one parse, and a handler that reads it N times pays N parses, which is express's
+     * own cost shape.
      *
      * @returns {Record<string, any>}
      */
     get query() {
-        let parsed = this.#cachedQuery;
-        if (parsed === null) {
-            const qp = this.app.get("query parser fn");
-            // the vendored default already answers on a bare null prototype, so it goes out as is;
-            // any other parser is copied onto one, which is what kept fast-querystring's result from
-            // inspecting as "Empty <[Object: null prototype] {}>" where Express shows the bare form
-            parsed = qp
-                ? qp === parseQuery
-                    ? parseQuery(this._rawQuery)
-                    : Object.assign(Object.create(null), qp(this._rawQuery))
-                : Object.create(null);
-            this.#cachedQuery = parsed;
-        }
-        return Object.assign(Object.create(null), parsed);
+        const qp = this.app.get("query parser fn");
+        // the vendored default already answers on a bare null prototype, so it goes out as is;
+        // any other parser is copied onto one, which is what kept fast-querystring's result from
+        // inspecting as "Empty <[Object: null prototype] {}>" where Express shows the bare form
+        return qp
+            ? qp === parseQuery
+                ? parseQuery(this._rawQuery)
+                : Object.assign(Object.create(null), qp(this._rawQuery))
+            : Object.create(null);
     }
 
     /**

package/src/response.js

@@ -658,6 +658,10 @@ module.exports = class Response extends LazyWritable {
      * @param {any} cb
      */
     _finish(data, cb) {
+        // read before the head is written below, which is what sets the flag: what matters further
+        // down is whether something had already committed the framing, a flushHeaders() or a first
+        // res.write(), not whether this call is about to write the head itself
+        const headWasAlreadyOut = this.headersSent;
         if (!this.headersSent) {
             // freshness is not decided here. node's end() knows nothing about conditional
             // requests, and Express answers 304 from send() and from sendFile(), each of
@@ -679,6 +683,18 @@ module.exports = class Response extends LazyWritable {
             this._res.endWithoutBody();
         } else if (!data && contentLength) {
             this._res.endWithoutBody(contentLength.toString());
+        } else if (headWasAlreadyOut && this.chunkedTransfer) {
+            // The head has already gone out without a length, which is what flushHeaders() and the
+            // first res.write() both do, so this response is committed to chunked framing and a
+            // length can no longer describe it. node is committed the same way: after a flush,
+            // res.end("body") sends a chunk, not a Content-Length. Handing the body to uWS's end()
+            // here would have it append a length to a head that already said otherwise, which is
+            // what the comparison test caught.
+            if (data) {
+                this._res.write(data);
+                this._sentBody = data;
+            }
+            this._res.endWithoutBody();
         } else {
             // a Buffer goes to uWS as the view it is: copying it into a fresh ArrayBuffer was
             // an allocation per body, and uWS reads the view's own offset and length
@@ -1232,6 +1248,34 @@ module.exports = class Response extends LazyWritable {
         return this;
     }
 
+    /**
+     * Sends the status line and the headers now, without waiting for a body, which is node's
+     * flushHeaders(). Callers use it to let the client start on the head while the body is still
+     * being produced, and one of them is `@angular/ssr`'s writeResponseToNodeResponse, which calls
+     * it before streaming a rendered page.
+     *
+     * A second call does nothing, as node's does. Nothing is written for a response already
+     * finished or aborted: uWS has let go of it by then.
+     *
+     * @returns {void}
+     */
+    flushHeaders() {
+        if (this.headersSent || this.finished || this.aborted) {
+            return;
+        }
+        this._res.cork(() => {
+            this.writeHead(this.statusCode);
+            // the same rule the chunked write path follows: uWS emits the 200 head itself, byte for
+            // byte, so writing it again would only cost a crossing
+            if (this.statusCode !== 200 || this.statusText !== undefined) {
+                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+            }
+            // true, as the chunked path passes for a string chunk: what follows a flush is a body
+            // written in pieces, and the framing has to be the one that allows them
+            this.writeHeaders(true);
+        });
+    }
+
     /**
      * Node asks this before validating a header value, and answering true keeps it permissive.
      * Only reached through code that goes down node's own header path.

package/src/types.d.ts

@@ -96,10 +96,39 @@ declare module "fulmine.js" {
     }
 
     interface Fulmine extends Omit<e.Express, "listen"> {
+        /**
+         * The app is a node request handler, so it can be handed to anything that takes one. That
+         * is what `http.createServer(app)` does, what supertest does, and what `@angular/ssr`'s
+         * createNodeRequestHandler(app) does in the server.ts Angular generates.
+         *
+         * Express declares this through its own RequestHandler on the Express interface; here it
+         * has to be written out, because the request and response an application sees are this
+         * project's own and node's shapes only arrive through the shim. It has always worked at
+         * runtime and the type did not say so, which compiled fine in JavaScript and stopped a
+         * TypeScript consumer at the first line that passed the app anywhere.
+         */
+        (
+            req: import("http").IncomingMessage,
+            res: import("http").ServerResponse,
+            next?: (err?: unknown) => void
+        ): void | Promise<void>;
+
         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;
+
+        /**
+         * Binds, and calls back the way Express 5 does: with nothing when the socket is listening,
+         * and with the error when the bind failed, since Express registers the listen callback on
+         * 'error' as well as on 'listening'. `this` inside it is the app, which is what listen
+         * returns here and what Express's http.Server is there.
+         *
+         * A string port is accepted and is what `process.env.PORT` gives you: numeric strings are
+         * bound as ports, anything else is taken as a unix socket path and bound through µWS's
+         * listen_unix. The four shapes below are node's own.
+         */
+        listen(callback?: (error?: Error) => void): FulmineServer;
+        listen(port: number | string, callback?: (error?: Error) => void): FulmineServer;
+        listen(port: number | string, host: string, callback?: (error?: Error) => void): FulmineServer;
+        listen(port: number | string, host: string, backlog: number, callback?: (error?: Error) => void): FulmineServer;
         ws(path: string, behavior: WebSocketBehavior): this;
         publish(topic: string, message: string | ArrayBuffer | Buffer, isBinary?: boolean, compress?: boolean): boolean;
         numSubscribers(topic: string): number;