fulmine.js 5.4.1 → 5.5.1

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)
@@ -130,6 +131,33 @@ 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 a cache 1.50x**.
+The render itself is the same JavaScript on both sides and measures the same, so on a cache miss the
+framework is not what your page is waiting for. Which is the useful way round: an SSR application
+spends most of its traffic outside the render, and that is where the difference is.
+
+Caching those pages is [`ng-ssr-caching`](https://www.npmjs.com/package/ng-ssr-caching), a middleware
+that runs on Express and here alike, and the same measurement says a page costs 17.2ms to render and
+1.9ms to serve from it. It is worth knowing why it keeps the ETag beside the bytes: a cache that
+stores only the body makes the server hash the whole document again on every hit, and measures level
+with no cache at all on the serving side.
+
 ### 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 +655,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.1",
+    "version": "5.5.1",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {

package/src/request.js

@@ -700,6 +700,73 @@ module.exports = class Request extends LazyReadable {
         return this.res?.finished || this.res?.aborted;
     }
 
+    /** @type {AbortController|undefined} */
+    #abortController;
+
+    /**
+     * node's `req.signal`, an AbortSignal that fires when the request is over, so work started for
+     * a visitor who has gone away can be stopped. `@angular/ssr` reads it when it builds a web
+     * Request out of this one, which is how an SSR render learns to give up.
+     *
+     * Made on the first ask rather than for every request: most requests never look at it, and an
+     * AbortController each would be an allocation nobody reads.
+     *
+     * @returns {AbortSignal}
+     */
+    get signal() {
+        if (!this.#abortController) {
+            const controller = new AbortController();
+            this.#abortController = controller;
+            const stop = () => controller.abort();
+            if (this.res?.aborted || this.res?.finished) {
+                stop();
+            } else {
+                // the request, not the response: a client abort is reported by destroying this
+                // stream and emitting "aborted" on it, and the response is never told to close
+                this.once("aborted", stop);
+                this.once("close", stop);
+            }
+        }
+
+        return this.#abortController.signal;
+    }
+
+    /**
+     * The trailing headers of a chunked request. µWebSockets.js does not surface them, so these
+     * stay empty, which is also what node hands back until the request has ended.
+     *
+     * @returns {Record<string, string>}
+     */
+    get trailers() {
+        return {};
+    }
+
+    /**
+     * @returns {Record<string, string[]>}
+     */
+    get trailersDistinct() {
+        return {};
+    }
+
+    /**
+     * node's per-request socket timeout. µWS runs its own idle timeout, set through
+     * `uwsOptions.idleTimeout`, and this cannot change it. The listener is registered as node's is.
+     *
+     * @param {number} msecs
+     * @param {() => void} [callback]
+     * @returns {this}
+     */
+
+    /**
+     *
+     */
+    setTimeout(msecs, callback) {
+        if (typeof callback === "function") {
+            this.once("timeout", callback);
+        }
+        return this;
+    }
+
     /**
      * Readable's pull. uWS pushes the body rather than being pulled from, so all this does is
      * lift the backpressure that a full queue put on it.

package/src/response.js

@@ -51,6 +51,18 @@ const { EventEmitter } = require("events");
 const http = require("http");
 const ms = require("ms");
 
+// How much a chunked response may gather before it is handed to uWS. Measured on uWS alone with
+// 33 KB written in 500 pieces: 16.2ms handed over one piece at a time, 0.79ms in 4 KB blocks,
+// 0.43ms in 8 KB, 0.45ms in 16 KB. Past 8 KB the curve is flat, so this is the smallest size that
+// buys the whole saving, and it bounds what one response can hold back.
+const COALESCE_LIMIT = 16 * 1024;
+
+// Below which a chunk is worth gathering. Merging costs a copy, and a chunk that is already
+// substantial does not earn it back: measured at 33 KB in eight pieces, gathering them made the
+// response 28% dearer, while the same bytes in sixty-six pieces got 3.4x cheaper. Anything from
+// here up goes straight through.
+const COALESCE_BELOW = 4 * 1024;
+
 const outgoingMessage = new http.OutgoingMessage();
 const symbols = Object.getOwnPropertySymbols(outgoingMessage);
 // if a future node renames it, fall back to a private symbol rather than writing a property
@@ -208,6 +220,24 @@ module.exports = class Response extends LazyWritable {
     /** @type {((err?: Error|null) => void)|null} */
     #pendingCallback = null;
 
+    /**
+     * Chunks written but not yet handed to uWS, and their total size.
+     *
+     * uWS charges for a write against everything already buffered behind it, so a chunked response
+     * written in many small pieces costs quadratically once it passes the socket's own buffer:
+     * measured on uWS alone, 500 writes of 66 bytes take 13ms against 0.06ms for 100 of them.
+     * Handing it the same bytes in blocks costs 0.4ms. Nothing here changes what goes on the wire,
+     * only how many calls it takes to put it there.
+     * @type {Buffer[]}
+     */
+    #queued = [];
+
+    /** How many bytes {@link #queued} holds, kept alongside so the flush does not add them up. */
+    #queuedBytes = 0;
+
+    /** Whether a flush is already booked for the end of this turn. */
+    #flushBooked = false;
+
     /** @type {any} */
     #outHeaders = null;
 
@@ -400,10 +430,55 @@ module.exports = class Response extends LazyWritable {
         return this.#socket;
     }
 
+    /**
+     * Hands everything queued to uWS as one write, which is where the saving is, and keeps the
+     * backpressure the single write used to do.
+     *
+     * @param {((err?: Error|null) => void)|null} callback the stream's, when there is one waiting
+     */
+    #flushQueued(callback) {
+        if (this.#queuedBytes === 0) {
+            if (callback) callback(null);
+            return;
+        }
+        const body = this.#queued.length === 1 ? this.#queued[0] : Buffer.concat(this.#queued, this.#queuedBytes);
+        this.#queued = [];
+        this.#queuedBytes = 0;
+
+        const ok = this._res.write(body);
+        if (ok) {
+            this.writingChunk = false;
+            if (callback) callback(null);
+            else this.emit("drain");
+        } else if (callback) {
+            this.#pendingCallback = callback;
+            this._res.onWritable(() => {
+                if (this.aborted || this.finished) return true;
+                const cb = this.#pendingCallback;
+                this.#pendingCallback = null;
+                this.writingChunk = false;
+                if (cb) cb(null);
+                return true;
+            });
+        } else {
+            // nothing is waiting on this one: uWS drains it and the next write finds out
+            this.writingChunk = false;
+        }
+    }
+
+    /**
+     * The booked flush. An arrow so it can be handed to nextTick without binding it every write.
+     */
+    #flushOnTick = () => {
+        this.#flushBooked = false;
+        if (this.aborted || this.finished || this.#queuedBytes === 0) return;
+        this._res.cork(() => this.#flushQueued(null));
+    };
+
     /**
      * Writable's sink. Sends the headers if they have not gone yet, then hands the chunk to uWS,
-     * either as a chunk of a chunked response or through tryEnd when a Content-Length said how
-     * much there would be. Backpressure comes back as onWritable, which is what defers the
+     * either through the queue above for a chunked response or through tryEnd when a Content-Length
+     * said how much there would be. Backpressure comes back as onWritable, which is what defers the
      * callback rather than dropping the chunk.
      *
      * @param {any} chunk
@@ -441,20 +516,23 @@ module.exports = class Response extends LazyWritable {
             }
 
             if (this.chunkedTransfer) {
-                const ok = this._res.write(chunk);
-                if (ok) {
+                // Held back rather than written, and handed over in one piece at the end of this
+                // turn or once it is big enough to be worth a call. A stream that writes once per
+                // turn, an SSE feed for instance, still leaves on its own turn: the queue only ever
+                // gathers what was written without yielding in between.
+                this.#queued.push(/** @type {Buffer} */ (chunk));
+                this.#queuedBytes += /** @type {Buffer} */ (chunk).byteLength;
+                // a chunk that is already big enough to be worth its own call leaves with whatever
+                // was waiting in front of it, rather than paying for a copy it does not need
+                if (this.#queuedBytes >= COALESCE_LIMIT || /** @type {Buffer} */ (chunk).byteLength >= COALESCE_BELOW) {
+                    this.#flushQueued(callback);
+                } else {
+                    if (!this.#flushBooked) {
+                        this.#flushBooked = true;
+                        process.nextTick(this.#flushOnTick);
+                    }
                     this.writingChunk = false;
                     callback(null);
-                } else {
-                    this.#pendingCallback = callback;
-                    this._res.onWritable(() => {
-                        if (this.aborted || this.finished) return true;
-                        const cb = this.#pendingCallback;
-                        this.#pendingCallback = null;
-                        this.writingChunk = false;
-                        if (cb) cb(null);
-                        return true;
-                    });
                 }
             } else {
                 const lastOffset = this._res.getWriteOffset();
@@ -658,6 +736,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 +761,20 @@ module.exports = class Response extends LazyWritable {
             this._res.endWithoutBody();
         } else if (!data && contentLength) {
             this._res.endWithoutBody(contentLength.toString());
+        } else if (headWasAlreadyOut && this.chunkedTransfer) {
+            // whatever is still queued goes first: end() must not overtake the body written before it
+            this.#flushQueued(null);
+            // 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 +1328,239 @@ 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's `writeEarlyHints`, which sends a `103` carrying the resources the page will want, so a
+     * browser can start fetching them while the server is still rendering.
+     *
+     * **Nothing is sent here.** µWebSockets.js has no API for an informational response, so the
+     * hints cannot reach the wire, and this exists so that code written for Express keeps running
+     * rather than dying on "res.writeEarlyHints is not a function". The callback is still called,
+     * because node calls it once the hints are out and a caller may be waiting on it.
+     *
+     * `writeContinue` and `writeProcessing` below are the same story with `100` and `102`.
+     *
+     * @param {Record<string, string|string[]>} [hints]
+     * @param {() => void} [callback]
+     * @returns {void}
+     */
+
+    /**
+     *
+     */
+    writeEarlyHints(hints, callback) {
+        this.#refuseInformationAfterHead();
+        // node writes the hints first and calls back after, so a caller that sequences work on it
+        // gets the same order here
+        if (typeof callback === "function") {
+            process.nextTick(callback);
+        }
+    }
+
+    /**
+     * node's `writeContinue`, the `100` that answers an `Expect: 100-continue`. Nothing is sent:
+     * see {@link Response#writeEarlyHints}.
+     *
+     * @returns {void}
+     */
+    writeContinue() {
+        this.#refuseInformationAfterHead();
+    }
+
+    /**
+     * node's `writeProcessing`, the `102`. Nothing is sent: see {@link Response#writeEarlyHints}.
+     *
+     * @returns {void}
+     */
+    writeProcessing() {
+        this.#refuseInformationAfterHead();
+    }
+
+    /**
+     * node throws from all three of the above once the head has gone out, since an informational
+     * response can only come before it, and an application may well be relying on that throw.
+     *
+     * @returns {void}
+     */
+    #refuseInformationAfterHead() {
+        if (this.headersSent) {
+            /** @type {NodeJS.ErrnoException} */
+            const err = new Error("Cannot write headers after they are sent to the client");
+            err.code = "ERR_HTTP_HEADERS_SENT";
+            throw err;
+        }
+    }
+
+    /**
+     * node's `addTrailers`, the headers that follow a chunked body. µWebSockets.js cannot send
+     * them, so nothing is written and the response is otherwise unaffected.
+     *
+     * @param {Record<string, string>|[string, string][]} [headers]
+     * @returns {void}
+     */
+
+    /**
+     *
+     */
+    addTrailers(headers) {}
+
+    /**
+     * node's per-response socket timeout. µWS runs its own idle timeout, set through
+     * `uwsOptions.idleTimeout`, and this cannot change it. The callback is registered on "timeout"
+     * as node's does, so nothing is lost by calling it, and nothing happens either.
+     *
+     * @param {number} msecs
+     * @param {() => void} [callback]
+     * @returns {this}
+     */
+
+    /**
+     *
+     */
+    setTimeout(msecs, callback) {
+        if (typeof callback === "function") {
+            this.once("timeout", callback);
+        }
+        return this;
+    }
+
+    /**
+     * node's `assignSocket` and `detachSocket`, which the http server uses when a response is
+     * handed a raw socket. There is no such socket here.
+     *
+     * @param {any} [socket]
+     * @returns {void}
+     */
+
+    /**
+     *
+     */
+    assignSocket(socket) {}
+
+    /**
+     * @param {any} [socket]
+     * @returns {void}
+     */
+
+    /**
+     *
+     */
+    detachSocket(socket) {}
+
+    /**
+     * node's `statusMessage`, the reason phrase. It is held as `statusText` here, and the two are
+     * the same thing: this is the name node and Express use, so code that sets it keeps working.
+     *
+     * @returns {string|undefined}
+     */
+    get statusMessage() {
+        return this.statusText;
+    }
+
+    set statusMessage(value) {
+        this.statusText = value;
+    }
+
+    /**
+     * Whether a header has been set on this response, which is node's `hasHeader`. Names are
+     * compared lowercased, as node compares them.
+     *
+     * @param {string} name
+     * @returns {boolean}
+     */
+    hasHeader(name) {
+        return this.headers[name.toLowerCase()] !== undefined;
+    }
+
+    /**
+     * The names of the headers set so far, lowercased, which is node's `getHeaderNames`.
+     *
+     * @returns {string[]}
+     */
+    getHeaderNames() {
+        return Object.keys(this.headers);
+    }
+
+    /**
+     * node's `getRawHeaderNames`, which returns the names in the case they were set in. Header
+     * names are held lowercased here, so this returns what {@link Response#getHeaderNames} does.
+     *
+     * @returns {string[]}
+     */
+    getRawHeaderNames() {
+        return Object.keys(this.headers);
+    }
+
+    /**
+     * Adds a value to a header without replacing what is there, which is node's `appendHeader`.
+     * A header that already has one value becomes a list, as node makes it.
+     *
+     * @param {string} name
+     * @param {string|readonly string[]} value
+     * @returns {this}
+     */
+    appendHeader(name, value) {
+        const key = name.toLowerCase();
+        const current = this.headers[key];
+        if (current === undefined) {
+            return this.setHeader(name, /** @type {any} */ (value));
+        }
+        const merged = [].concat(/** @type {any} */ (current), /** @type {any} */ (value));
+        return this.setHeader(name, /** @type {any} */ (merged));
+    }
+
+    /**
+     * Sets several headers at once from a Headers or a Map, which is node's `setHeaders`. A
+     * `Headers` gives `set-cookie` back through getSetCookie, so those stay separate values rather
+     * than one folded string.
+     *
+     * @param {Headers|Map<string, string|readonly string[]>} headers
+     * @returns {this}
+     */
+    setHeaders(headers) {
+        if (typeof Headers === "function" && headers instanceof Headers) {
+            for (const name of new Set([...headers.keys()])) {
+                if (name === "set-cookie") {
+                    this.setHeader(name, /** @type {any} */ (headers.getSetCookie()));
+                } else {
+                    this.setHeader(name, /** @type {any} */ (headers.get(name)));
+                }
+            }
+            return this;
+        }
+        for (const [name, value] of headers) {
+            this.setHeader(name, /** @type {any} */ (value));
+        }
+        return this;
+    }
+
     /**
      * 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;