fulmine.js 5.19.2 → 5.19.3

package/src/server-shape.js

@@ -16,40 +16,31 @@ limitations under the License.
 
 // What makes an application answer the questions a library asks about an http.Server.
 //
-// `app.listen()` returns the app, and there is no node server under it: the socket belongs to µWS.
-// That is the one place where a drop-in stops being a drop-in, because the graceful shutdown
-// libraries, the connection trackers and the health check wrappers do not use a server, they
-// *recognise* one: `server instanceof http.Server`, then close(), address(), getConnections() and
-// the events around them. Everything they need can be answered honestly here.
+// `app.listen()` returns the app and there is no node server under it, the socket belongs to uWS.
+// Graceful shutdown libraries, connection trackers and health check wrappers recognise a server
+// with `server instanceof http.Server`, then call close(), address(), getConnections().
 //
-// Two halves, and the second is the delicate one:
+// Two halves:
 //
-//   - the members. close(), address(), listening and the events already exist on the application,
-//     because Express hands back an http.Server and code written for Express uses them. What was
-//     missing is the rest of the net.Server surface, added below.
-//   - the recognition. An application cannot inherit from http.Server: its prototype chain already
-//     runs through Router and this project's own EventEmitter, and http.Server.prototype has a
-//     chain of its own that cannot be spliced into it without re-parenting node's classes for the
-//     whole process. So instanceof is taught about applications instead, through the hook the
-//     language provides for exactly this: Symbol.hasInstance. The patch is additive. Everything
-//     that was an http.Server before still is, and the only new answer is for an application.
+//   - the members. close(), address(), listening and the events are already on the application,
+//     because Express hands back an http.Server. The rest of net.Server is added below.
+//   - the recognition. An application cannot inherit from http.Server, its prototype chain runs
+//     through Router and this project's own EventEmitter. So instanceof is taught instead, with
+//     Symbol.hasInstance. The patch is additive, nothing loses the answer it had.
 //
-// What this deliberately does not do is pretend the plumbing is there. Nothing emits 'request',
-// 'connection' or 'upgrade', because those carry node sockets and there are none: a library that
-// counts connections through them counts zero, and socket.io still wants app.uwsApp. The shape is
-// honest about what is behind it, which is why getConnections answers with the requests in flight
-// rather than with a number nobody could stand behind.
+// Nothing emits 'request', 'connection' or 'upgrade': those carry node sockets and there are none.
+// A library counting connections through them counts zero, and socket.io wants app.uwsApp.
 
 const http = require("http");
 const net = require("net");
 
-// what marks an application, read by the instanceof hook below. A symbol rather than a property
-// name, so nothing can be mistaken for an application by carrying the wrong field
+// what marks an application, read by the instanceof hook below. A symbol, so no plain field name
+// can be mistaken for it
 const kIsApplication = Symbol.for("fulmine.application");
 
 /**
  * Teaches `instanceof` that an application is a server, once per class. The original answer is
- * asked first and is never overruled: this only adds an answer for objects carrying the mark.
+ * asked first and never overruled.
  *
  * @param {Function} klass http.Server or net.Server
  */
@@ -65,8 +56,8 @@ function acceptApplications(klass) {
             if (previous.call(this, value)) {
                 return true;
             }
-            // an application is a function, and a property read works on one; the guard is for the
-            // primitives and the nulls that reach any instanceof
+            // an application is a function and a property read works on one. The guard is for the
+            // primitives and nulls that reach any instanceof
             return value != null && /** @type {any} */ (value)[kIsApplication] === true;
         },
         configurable: true,
@@ -79,8 +70,8 @@ acceptApplications(http.Server);
 acceptApplications(net.Server);
 
 /**
- * The net.Server members an application does not get from Express's side of the API, defined on
- * the application prototype. Each one answers for µWS rather than for a socket node does not have.
+ * The net.Server members Express's API does not give, on the application prototype. Each one
+ * answers for uWS, not for a node socket.
  *
  * @param {any} prototype Application.prototype
  */
@@ -88,11 +79,8 @@ function addServerMembers(prototype) {
     Object.defineProperty(prototype, kIsApplication, { value: true, configurable: true });
 
     /**
-     * How many requests this application is serving right now.
-     *
-     * node counts sockets; there are none to count here, and the number a graceful shutdown is
-     * waiting for is this one anyway: it reaches zero when the last answer has gone out. An idle
-     * keep-alive connection is not counted, and closing does not wait for one either.
+     * How many requests this application is serving right now. node counts sockets, there are none
+     * here, and this is the number a graceful shutdown waits for. An idle keep-alive is not counted.
      *
      * @param {(err: Error|null, count: number) => void} callback
      */
@@ -106,9 +94,8 @@ function addServerMembers(prototype) {
     };
 
     /**
-     * node's, for a handle this does not own: µWS's loop is what keeps the process alive, and it
-     * is not something a caller may unref. Both are no-ops that hand the server back, so a chain
-     * written against node's API keeps working.
+     * A handle this does not own: uWS's loop keeps the process alive and a caller cannot unref it.
+     * Both are no-ops returning the server, so a chain written against node's API keeps working.
      *
      * @returns {any}
      */
@@ -122,8 +109,8 @@ function addServerMembers(prototype) {
     };
 
     /**
-     * Registers the callback the way node's does and remembers the value, which is all a caller
-     * can observe. The timeout itself belongs to µWS and is set through uwsOptions.idleTimeout.
+     * Registers the callback like node's does and remembers the value, which is all a caller can
+     * observe. The timeout belongs to uWS and is set through uwsOptions.idleTimeout.
      *
      * @this {any}
      * @param {number} [msecs]
@@ -138,10 +125,8 @@ function addServerMembers(prototype) {
         return this;
     };
 
-    // The numbers node's http.Server carries and a caller may read or write. They are inert here,
-    // and they are declared rather than left undefined because reading one is how a library works
-    // out what it is talking to: `server.keepAliveTimeout` undefined has been read as "not a
-    // server" before now.
+    // The numbers node's http.Server carries. Inert here, but declared rather than left undefined:
+    // a library reads `server.keepAliveTimeout` to work out what it is talking to.
     for (const [name, value] of /** @type {[string, any][]} */ ([
         ["timeout", 0],
         ["keepAliveTimeout", 5000],

package/src/server-timing.js

@@ -16,37 +16,27 @@ limitations under the License.
 
 // express.serverTiming(): Server-Timing, with the two things only this framework can put in it.
 //
-// A stopwatch middleware is nothing new, and there are several on npm. What none of them can add
-// is how the request was routed, because in every other framework there is only one way:
+// What no other stopwatch middleware can add is how the request was routed:
 //
 //     Server-Timing: route;desc="native", hdr;desc="not copied", total;dur=0.42
 //
-// `route;desc="native"` means µWS matched the path in C++ and handed over a chain worked out at
+// `route;desc="native"` means uWS matched the path in C++ and handed over a chain worked out at
 // startup. `route;desc="router"` means this request was matched here, in javascript, layer by
-// layer. That is the difference between the two halves of this project, per request, in the
-// browser's network panel, for someone who would never run a CLI.
+// layer. A handler compiled into a response never enters javascript, so there is nothing to time
+// on it: `npx fulmine profile` counts those.
 //
-// What it cannot show is the route that is faster still: a handler compiled into a response never
-// enters javascript, so no middleware runs on it and there is nothing to time. `npx fulmine
-// profile` is where those are counted.
-//
-// The other field only this framework can write is `work`, which names what the request was made to
-// build: the folded headers object, the parsed query, the body, the Readable, the Writable, the
-// socket stand-in. A fast request builds none of them and the field is absent, so it appears
-// exactly when something is worth looking at. See src/work.js.
+// `work` names what the request was made to build: folded headers, parsed query, body, Readable,
+// Writable, socket stand-in. A fast request builds none and the field is absent. See src/work.js.
 //
 // The duration ends where the header does. Server-Timing goes out with the head, so `total` covers
-// everything up to the moment the answer starts leaving, and not the body after it, and `work` has
-// the same boundary: a stream built by the write that carries the head is built after this is
-// written. Every stopwatch middleware has that boundary; this one says so.
+// everything up to the moment the answer starts leaving, and `work` has the same boundary.
 
 "use strict";
 
 const { work, names } = require("./work.js");
 
 /**
- * A duration in milliseconds, as Server-Timing writes them: two decimals, which is a hundredth of
- * a millisecond and finer than anything above it is worth.
+ * A duration in milliseconds, as Server-Timing writes them: two decimals.
  *
  * @param {bigint} nanoseconds
  * @returns {string}
@@ -88,9 +78,8 @@ function serverTiming(options) {
         const marks = [];
 
         /**
-         * Adds a mark of the caller's own, which is what the rest of Server-Timing is for: the
-         * query, the upstream call, the render. A duration is optional, since a mark with only a
-         * description is a legal entry and is how a cache hit is usually reported.
+         * Adds a mark of the caller's own: the query, the upstream call, the render. The duration
+         * is optional, a mark with only a description is a legal entry.
          *
          * @param {string} name a token: letters, digits, dash and underscore
          * @param {number} [duration] milliseconds
@@ -110,8 +99,8 @@ function serverTiming(options) {
         };
 
         /**
-         * Times a piece of work under a name, whatever it is: the value comes back, and a promise
-         * is timed to where it settles.
+         * Times a piece of work under a name. The value comes back, and a promise is timed to
+         * where it settles.
          *
          * @param {string} name
          * @param {() => any} work
@@ -155,8 +144,7 @@ function serverTiming(options) {
             written = true;
             const entries = [];
             if (routing) {
-                // what the router decided about the route this request ran, which is the same
-                // verdict npx fulmine profile prints for it
+                // the same verdict npx fulmine profile prints for this route
                 const native = req.route?._native;
                 entries.push(`route;desc=${describe(native ? "native" : "router")}`);
                 if (native) {
@@ -167,10 +155,9 @@ function serverTiming(options) {
                 }
             }
             if (wantsWork) {
-                // what this one request made the framework build, which the route verdict above
-                // cannot say: a native route still folds the headers if a middleware reads them,
-                // and that is per request, not per route. Read at the head, so it covers the
-                // chain and not the body written after it, the same boundary as the total.
+                // what this request made the framework build, which the route verdict cannot say:
+                // a native route still folds the headers if a middleware reads them. Read at the
+                // head, so it covers the chain and not the body, the same boundary as the total.
                 const listed = names(work(req, res));
                 if (listed.length !== 0) {
                     entries.push(`work;desc=${describe(listed.join(", "))}`);

package/src/socket.js

@@ -0,0 +1,208 @@
+/*
+Copyright 2024 dimden.dev
+Copyright 2026 Nigro Simone
+
+This file is derived from Ultimate Express and has been modified.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/** @typedef {import("./response.js")} Response */
+
+// events is faster at init, tseep is faster at sending events
+// since we create a ton of objects and dont send a ton of events, its better to use events here
+const { EventEmitter } = require("events");
+const { kShapeMode } = require("./response-utils.js");
+
+class Socket extends EventEmitter {
+    /**
+     * The Socket's error listener, shared across sockets: an error closes the stand-in, which is
+     * the close connection trackers wait for. EventEmitter calls it with this = the emitter.
+     *
+     * @this {any}
+     * @param {any} err whatever the response reported, which need not be an Error
+     */
+    static _onError(err) {
+        this.emit("close");
+    }
+
+    /**
+     * Enough of a node socket for the middleware that reaches for one. uWS has no socket object to
+     * hand over, so this stands in and forwards what it can to the response.
+     *
+     * @param {Response} response
+     */
+    constructor(response) {
+        super();
+        this.response = response;
+        this[kShapeMode] = true;
+        // middleware assigns to this one, which is why it is a field rather than a getter: express
+        // reads socket.encrypted for req.protocol and a proxy shim writes it
+        this.encrypted = response.req.app.ssl;
+        this.localPort = response.req.app.port;
+        // on-finished reads socket.readable before anything else, and a socket without one reads
+        // as a request that is already over
+        this.readable = true;
+
+        // shared, not an arrow: one per process instead of one per materialized socket
+        this.on("error", Socket._onError);
+    }
+
+    /** Whether anything more can be written, which stops being true once the response is done. */
+    get writable() {
+        return !this.response.finished;
+    }
+
+    /** The peer, as node reports it. Reading it out of uWS is slow, so the request caches it. */
+    get remoteAddress() {
+        return this.response.req.parsedIp;
+    }
+
+    /** A native µWS call almost no caller makes, so it stays behind its getter. */
+    get remotePort() {
+        return this.response.req._res.getRemotePort();
+    }
+
+    /**
+     * node's socket carries these three, usually called to take the timeout off. uWS has no per
+     * socket timeout reachable from javascript, so they do nothing and return the socket. n8n's
+     * chat trigger calls setTimeout on every webhook, and without it the workflow answered 500.
+     * @returns {this}
+     */
+    setTimeout() {
+        return this;
+    }
+
+    /** @returns {this} */
+    setKeepAlive() {
+        return this;
+    }
+
+    /** @returns {this} */
+    setNoDelay() {
+        return this;
+    }
+
+    /**
+     * Finishes the response through the socket, which is how the middleware that only knows
+     * about sockets ends one.
+     * @param {any} [body] whatever node's socket.end() would take
+     */
+    end(body) {
+        this.response.end(body);
+    }
+
+    /**
+     * What a server side socket answers about itself. uWS owns the connection, so these follow the
+     * response.
+     */
+    get destroyed() {
+        return this.response.finished === true;
+    }
+
+    /** @returns {string} "open" until the response is over, as a served socket reads. */
+    get readyState() {
+        return this.response.finished === true ? "closed" : "open";
+    }
+
+    /** @returns {boolean} never: this end was accepted, not dialled. */
+    get connecting() {
+        return false;
+    }
+
+    /** @returns {boolean} never, for the same reason. */
+    get pending() {
+        return false;
+    }
+
+    /**
+     * The end of the connection node reports here. There is no address to read back from uWS, so
+     * this is the port the application bound and the family the peer arrived on.
+     * @returns {{address: string|undefined, family: string, port: number|undefined}}
+     */
+    address() {
+        const remote = this.response.req.parsedIp;
+        return {
+            address: this.response.req.app._listenHost,
+            family: remote?.includes(":") ? "IPv6" : "IPv4",
+            port: this.localPort
+        };
+    }
+
+    /**
+     * Drops the connection. node takes an error and re-emits it, this closes and says so through
+     * 'close', since there is no socket underneath to carry an error of its own.
+     * @returns {this}
+     */
+    destroy() {
+        this.close();
+        return this;
+    }
+
+    /** @returns {this} */
+    destroySoon() {
+        this.close();
+        return this;
+    }
+
+    /**
+     * Holds and resumes the body arriving on this connection. The other half of node's pause()
+     * means nothing here, the response is written when the application writes it.
+     * @returns {this}
+     */
+    pause() {
+        this.response.req.pause();
+        return this;
+    }
+
+    /** @returns {this} */
+    resume() {
+        this.response.req.resume();
+        return this;
+    }
+
+    /**
+     * node writes these bytes straight onto the connection. There is no way past uWS's framing
+     * here, so they go through the response instead.
+     *
+     * @param {any} chunk
+     * @param {any} [encoding]
+     * @param {any} [callback] node's write signature, which takes all three loosely
+     * @returns {boolean}
+     */
+    write(chunk, encoding, callback) {
+        return this.response.write(chunk, encoding, callback);
+    }
+
+    /** The event loop is µWS's, so there is nothing to hold open or let go. @returns {this} */
+    ref() {
+        return this;
+    }
+
+    /** @returns {this} */
+    unref() {
+        return this;
+    }
+
+    /** Closes the connection outright, without finishing a response first. */
+    close() {
+        if (this.response.finished) {
+            return;
+        }
+        this.response.finished = true;
+        this.emit("close");
+        this.response._res.close();
+    }
+}
+
+module.exports = Socket;

package/src/testing.js

@@ -16,25 +16,27 @@ limitations under the License.
 
 // express.testing: what listen() decided about each route, as something a test can assert on.
 //
-// A route is answered by µWS itself only while it stays eligible, and eligibility is not a property
-// of the route alone: a `const` in the wrong place, a middleware that reads a header, a new route
-// written above an old one, and it quietly falls back to the ordinary router. The answer is still
-// correct, which is why nothing complains. What changes is the throughput, and by the time anyone
-// notices, the commit that did it is three weeks back.
+// A route is answered by uWS itself only while it stays eligible: a `const` in the wrong place, a
+// middleware that reads a header, a new route above an old one, and it falls back to the ordinary
+// router. The answer stays correct, so nothing complains, only the throughput changes.
 //
-// `npx fulmine profile` prints the same verdicts for a human to read. This is the half a test can
-// hold on to, so a pull request that loses the fast path fails in CI with the reason written out
-// instead of being found in production.
+// `npx fulmine profile` prints the same verdicts for a human. This is the half a test can hold on
+// to, so a pull request that loses the fast path fails in CI.
 
 "use strict";
 
 const { work, names: workNames } = require("./work.js");
 
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+/** @typedef {import("./router.js")} Router */
+/** @typedef {import("./application.js").Application} Application */
+
 /**
  * Every route of an application and of the routers mounted under it, each with the path it answers
  * from the outside.
  *
- * @param {any} router
+ * @param {Router} router
  * @param {string} prefix
  * @param {any[]} [into]
  * @returns {{route: any, full: string}[]}
@@ -55,7 +57,7 @@ function collectRoutes(router, prefix, into = []) {
  * Compiles the routes, which is what listen() does before it binds, without binding anything. Once
  * per application: a second compilation would register everything with µWS twice.
  *
- * @param {any} app
+ * @param {Application} app
  */
 function compileOnce(app) {
     if (app.listenCalled || app._testingCompiled) {
@@ -68,11 +70,10 @@ function compileOnce(app) {
 /**
  * What compiling the routes decided, one entry per route, in the order they were registered.
  *
- * This is the primitive the two assertions below are written on, and it is exported because an
- * application with rules of its own is better served asserting them itself: how many routes may
- * fall back, which ones may read headers, that the one route carrying the traffic is declarative.
+ * The primitive the two assertions below are written on. Exported so an application with rules of
+ * its own can assert them directly.
  *
- * @param {any} app an application, listening or not
+ * @param {Application} app an application, listening or not
  * @returns {{method: string, path: string, native: boolean, declarative: boolean, skipHeaders: boolean,
  *   skipQuery: boolean, reason: string|undefined}[]}
  */
@@ -94,8 +95,8 @@ function routeReport(app) {
 /**
  * Whether one of the patterns given names this route.
  *
- * A pattern is a path as it was registered, not a URL: "/api/items/:id" and not "/api/items/7". It
- * may carry the method, "GET /health", and it may end in "*" to name everything under a prefix.
+ * A pattern is a path as registered, not a URL: "/api/items/:id", not "/api/items/7". It may carry
+ * the method, "GET /health", and may end in "*" for everything under a prefix.
  *
  * @param {{method: string, path: string}} entry
  * @param {string} pattern
@@ -118,10 +119,10 @@ function names(entry, pattern) {
 }
 
 /**
- * The routes the patterns name, refusing a pattern that names none: a test that asserts about a
- * route it misspelled has to fail rather than pass on an empty list.
+ * The routes the patterns name. A pattern that names none throws, so a misspelled route fails
+ * instead of passing on an empty list.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {string|string[]} patterns
  * @param {string} caller the name in the message
  * @returns {ReturnType<typeof routeReport>}
@@ -152,12 +153,10 @@ function select(app, patterns, caller) {
 }
 
 /**
- * Throws unless every route named is answered by µWS itself.
- *
- * The message is the point: it names each route that fell back and why, in the same words
- * `npx fulmine profile` uses, so the failure says what to change.
+ * Throws unless every route named is answered by uWS itself. The message names each route that
+ * fell back and why, in the same words `npx fulmine profile` uses.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {string|string[]} patterns paths as they were registered, "GET /path" to pin the method,
  *   a trailing "*" for everything under a prefix
  */
@@ -174,12 +173,12 @@ function expectNative(app, patterns) {
 }
 
 /**
- * Why a route µWS already matches is still not compiled into a response.
+ * Why a route uWS already matches is still not compiled into a response.
  *
  * The handler is the last answer, not the first: three refusals come before it, and blaming the
- * handler for one of those sends the reader to rewrite something that was already simple enough.
+ * handler sends the reader to rewrite something that was already simple enough.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {{path: string}} entry
  * @returns {string}
  */
@@ -200,10 +199,10 @@ function whyNotCompiled(app, entry) {
 }
 
 /**
- * Throws unless every route named is answered from a response written at startup, which is the
- * step past native: µWS answers it without entering javascript at all.
+ * Throws unless every route named is answered from a response written at startup. One step past
+ * native: uWS answers it without entering javascript.
  *
- * @param {any} app
+ * @param {Application} app
  * @param {string|string[]} patterns as in expectNative
  */
 function expectDeclarative(app, patterns) {
@@ -228,31 +227,29 @@ function expectDeclarative(app, patterns) {
  * What this one request made the framework do, asked from inside a handler or from a `finish`
  * listener. See src/work.js for what each field means and why asking is free.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @returns {import("./work.js").Work}
  */
 function workReport(req, res) {
     return work(req, res);
 }
 
-// The work a fast request does none of, which is what expectLazy is about. The route verdict is
-// not in here: expectNative and expectDeclarative are what assert on that.
+// The work a fast request does none of. The route verdict is not here, expectNative and
+// expectDeclarative assert on that.
 const LAZY = ["headers", "query", "body", "requestStream", "responseStream", "socket"];
 
 /**
  * Throws if this request built anything it did not have to.
  *
- * The route verdict is a property of the application and holds for every request; this is the
- * other half, which holds for one. A route can stay native and still slow down request by request,
- * because a middleware read `req.headers.host` or piped instead of sending: the answer stays
- * correct, the route report stays green, and the throughput does not.
+ * The route verdict holds for every request, this holds for one. A native route still slows down
+ * request by request if a middleware reads `req.headers.host` or pipes instead of sending.
  *
- * `allow` names what is fine here, which is most of the point: a route that parses a body is
- * asserted as one that parses a body and nothing else.
+ * `allow` names what is fine here: a route that parses a body is asserted as one that parses a
+ * body and nothing else.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @param {object} [options]
  * @param {string[]} [options.allow] fields of the report this route is expected to do anyway
  */