fulmine.js 5.4.1 → 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)
@@ -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.1",
+    "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/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;