fulmine.js 5.20.0 → 5.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.20.0",
+    "version": "5.21.1",
     "description": "Drop-in Express 5 replacement on uWebSockets.js, up to 20x faster. Same API, your middleware and framework keep working.",
     "main": "src/index.js",
     "exports": {
@@ -116,7 +116,7 @@
         "statuses": "^2.0.2",
         "tseep": "^1.3.1",
         "type-is": "^2.1.0",
-        "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.69.0",
+        "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.71.0",
         "vary": "^1.1.2"
     },
     "peerDependencies": {

package/src/application.js

@@ -17,7 +17,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-const uWS = require("uWebSockets.js");
+const { loadUWS } = require("./uws.js");
 const Router = require("./router.js");
 const {
     removeDuplicateSlashes,
@@ -59,7 +59,10 @@ class FSWorker {
      */
     constructor() {
         this.busy = false;
-        this.worker = new Worker(path.join(__dirname, "worker.js"));
+        // its own execArgv, not the parent thread's: a worker inherits them, and a --require or
+        // --import written for the parent (Angular's route extraction registers a loader that reads
+        // workerData) throws inside a thread that only reads files
+        this.worker = new Worker(path.join(__dirname, "worker.js"), { execArgv: [] });
 
         this.worker.on("message", (message) => {
             // node speaks on this channel too: under --watch a worker reports the files it loaded
@@ -113,6 +116,15 @@ class Application extends Router {
      */
     _testingCompiled;
 
+    /**
+     * The uWS app once made, or the one settings.uwsApp handed in. See the uwsApp getter.
+     * @type {any}
+     */
+    _uwsApp;
+
+    /** What uWS.App or uWS.SSLApp is given, kept until the app is made. */
+    _uwsOptions;
+
     /**
      * @param {object} [settings] the options express() takes. uwsOptions goes to uWS and decides
      *   between an HTTP, an HTTPS and an HTTP/3 server; threads sizes the file-reading pool, and 0
@@ -135,9 +147,7 @@ class Application extends Router {
         if (this._clusterWorkers > 0 && cluster.isPrimary) {
             becomeSupervisor();
         }
-        if (settings.uwsApp) {
-            this.uwsApp = /** @type {import("uWebSockets.js").TemplatedApp} */ (settings.uwsApp);
-        } else if (settings.http3) {
+        if (settings.http3) {
             // 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
@@ -146,12 +156,12 @@ class Application extends Router {
                 "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 {
-            this.uwsApp = uWS.App(settings.uwsOptions);
         }
         this.ssl = settings.uwsOptions.key_file_name && settings.uwsOptions.cert_file_name;
+        // the uWS app is made on first use, see the uwsApp getter: what listen(), ws() and the
+        // optimizer need, and what an app served through node's http never asks for
+        this._uwsApp = settings.uwsApp;
+        this._uwsOptions = settings.uwsOptions;
         this.cache = new NullObject();
         this.engines = { __proto__: null };
         // a null prototype, as express gives app.locals, so a local named like an Object method
@@ -509,6 +519,22 @@ class Application extends Router {
         return request;
     }
 
+    /**
+     * The µWS app underneath, for anything µWS offers that this does not: socket.io attaches to
+     * it. Made the first time it is asked for, so an application that only ever answers through
+     * node's http, a test through supertest or Angular's build extracting routes in a worker
+     * thread, never loads the binary. See src/uws.js for why that matters.
+     *
+     * @returns {any}
+     */
+    get uwsApp() {
+        if (this._uwsApp === undefined) {
+            const uWS = loadUWS();
+            this._uwsApp = this.ssl ? uWS.SSLApp(this._uwsOptions) : uWS.App(this._uwsOptions);
+        }
+        return this._uwsApp;
+    }
+
     /**
      * Registers the catch-all uWS handler, which is what serves every request that no optimized
      * route took natively. It walks this app's own chain and, when nothing in it answered, decides
@@ -617,7 +643,7 @@ class Application extends Router {
             // listen() returns. The callback is not: running it here would run it before listen()
             // had returned, and `const server = app.listen(p, () => server.address())` - the form
             // the Express docs use - would die on the temporal dead zone.
-            this.port = uWS.us_socket_local_port(socket);
+            this.port = loadUWS().us_socket_local_port(socket);
             this.listening = true;
             this._listenHost = host;
             // kept so close() can stop accepting without dropping what is in flight
@@ -888,7 +914,7 @@ class Application extends Router {
             return this;
         }
         if (this._listenSocket) {
-            uWS.us_listen_socket_close(this._listenSocket);
+            loadUWS().us_listen_socket_close(this._listenSocket);
             this._listenSocket = undefined;
         }
         this._draining = true;

package/src/cli.js

@@ -107,10 +107,11 @@ const DIFFERENCES = [
     [
         "a compiled route keeps its connection header",
         "A handler simple enough to be read at registration time is answered natively, and a client\n" +
-            "that sent Connection: close is still told keep-alive, though the socket does close. A body\n" +
-            "with a piece of the query in it is framed chunked, since its length is not known until the\n" +
-            "request arrives. A response that would carry a validator is never compiled, so conditional\n" +
-            'requests behave as on Express. app.set("declarative responses", false) turns it off.'
+            "that sent Connection: close is still told keep-alive, though the socket does close. A\n" +
+            "response that would carry a validator is never compiled, so conditional requests behave as\n" +
+            'on Express. app.set("declarative responses", false) turns it off. A body with a piece of\n' +
+            'the query or a route parameter in it is compiled only under app.set("declarative request\n' +
+            'values", true), which takes the value as uWS reads it: undecoded, the first one, or none.'
     ],
     [
         "headers are capped at 4096 bytes by default",

package/src/declarative.js

@@ -21,8 +21,7 @@ const acorn = require("acorn");
 const { stringify, contentTypeSet, withUtf8Charset, contentTypeFor, headerIsWritable } = require("./utils.js");
 // H3App, DeclarativeResponse and _cfg exist at runtime but are missing from the .d.ts the
 // package ships, so the module is read through a loose alias
-const uWS = require("uWebSockets.js");
-const uWSAny = /** @type {any} */ (uWS);
+const { loadUWS } = require("./uws.js");
 const statuses = require("statuses");
 
 /** @typedef {import("./application.js").Application} Application */
@@ -818,6 +817,12 @@ module.exports = function compileDeclarative(cb, app) {
         }
         const { sendUsed, bodyFromSend } = read;
 
+        // a part copied out of the request is written by uWS with its own reading of it, so the
+        // route is compiled only where the application asked for that
+        if (!app.get("declarative request values") && body.some((part) => part.type !== "text")) {
+            return false;
+        }
+
         // a handler that never sends is not a response: Express leaves the request waiting, so this
         // has to fall back instead of answering a bare 200
         if (!sendUsed && !sendStatusUsed) {
@@ -830,7 +835,7 @@ module.exports = function compileDeclarative(cb, app) {
             return false;
         }
 
-        let decRes = new uWSAny.DeclarativeResponse();
+        let decRes = new (loadUWS().DeclarativeResponse)();
 
         if (statusCode !== 200) {
             const statusMessage = statuses.message[statusCode] ?? "unknown";

package/src/index.js

@@ -17,11 +17,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// H3App, DeclarativeResponse and _cfg exist at runtime but are missing from the .d.ts the
-// package ships, so the module is read through a loose alias
-const uWS = require("uWebSockets.js");
-const uWSAny = /** @type {any} */ (uWS);
-
 // A project on pnpm owns the uWebSockets.js dependency itself, see `npx fulmine.js pnpm`, so the
 // one installed can drift from the one this package pins and was tested against. Said once, at
 // require time, where it reaches every deployment rather than only the ones that run verify.
@@ -50,13 +45,6 @@ const middlewares = require("./middlewares.js");
 const Request = require("./request.js");
 const Response = require("./response.js");
 
-try {
-    // disable Uwebsockets header
-    uWSAny._cfg("999999990007");
-} catch (error) {
-    // older uWS builds do not expose _cfg; there is nothing to fall back to
-}
-
 try {
     // the compile cache, node 22.8 and up: the next boot skips compiling the same code. Respects
     // NODE_DISABLE_COMPILE_CACHE, and booting without a cache is not an error

package/src/optimizer.js

@@ -558,8 +558,9 @@ function registerUwsRoute(router, route, optimizedPath) {
         route.paramCallbacks.size === 0 && // a param callback has to run, and this answers without running anything
         // a captured value is decoded when the route runs, and one that cannot be decoded is a
         // 400 in express and on the ordinary path here. Nothing runs to raise it on a
-        // declarative response, so GET /a-b%5Ec@d%e came back 200 from app.get("/:p12")
-        route.optimizedParams === undefined &&
+        // declarative response, so GET /a-b%5Ec@d%e came back 200 from app.get("/:p12").
+        // "declarative request values" is the application accepting that
+        (route.optimizedParams === undefined || router.get("declarative request values")) &&
         // a declarative response is answered by µWS itself, so no javascript runs and the case
         // guard could not: a route that needs one has to stay an ordinary handler
         caseGuards === null &&

package/src/router.js

@@ -100,9 +100,11 @@ module.exports = class Router extends EventEmitter {
      * it have already established that, so the honest `TemplatedApp|undefined` would only add
      * casts where the guard already is.
      *
-     * @type {any}
+     * @returns {any}
      */
-    uwsApp;
+    get uwsApp() {
+        return undefined;
+    }
 
     /**
      * Whether an unset routing flag reads on through the mount parent. Only an application does,

package/src/testing.js

@@ -187,8 +187,11 @@ function whyNotCompiled(app, entry) {
     if (!app.get("declarative responses")) {
         return "answered by µWS, but declarative responses are turned off";
     }
-    if (entry.path.includes(":")) {
-        return "answered by µWS, but the route captures, and nothing runs to decode the value";
+    if (entry.path.includes(":") && !app.get("declarative request values")) {
+        return (
+            "answered by µWS, but the route captures, and nothing runs to decode the value: " +
+            'app.set("declarative request values", true) is what puts a route here'
+        );
     }
     if (app.get("etag")) {
         return (

package/src/types.d.ts

@@ -18,6 +18,7 @@ declare module "fulmine.js" {
     import e from "express";
     import uWS from "uWebSockets.js";
     import { ZlibOptions, BrotliOptions } from "zlib";
+    import serveStatic = require("serve-static");
 
     type Settings = {
         uwsOptions?: uWS.AppOptions;
@@ -36,7 +37,16 @@ declare module "fulmine.js" {
         export import request = e.request;
         export import response = e.response;
 
-        export import static = e.static;
+        /** serve-static's options plus preCompressed, which is this project's. */
+        interface StaticOptions extends serveStatic.ServeStaticOptions<e.Response> {
+            /**
+             * Serve `file.br` or `file.gz` in place of `file` when one is on disk and the client
+             * takes it. Off by default. Which twins a path has is remembered for a second;
+             * `{ cache: false }` asks the disk every time, a duration sets how long.
+             */
+            preCompressed?: boolean | { cache?: number | string | false };
+        }
+        function static(root: string, options?: StaticOptions): e.RequestHandler;
         // export import query = e.query;
 
         // express has no compression middleware, so there is nothing to re-export: these are the

package/src/utils.js

@@ -1028,6 +1028,11 @@ const defaultSettings = {
     // The native µWS router matches bytes, so the compiler in _compileOptimizedRoutes only hands
     // it routes whose earlier siblings it can prove agree under either case rule.
     "declarative responses": true,
+    // off: a compiled body copies nothing out of the request. On, res.send(req.query.q) and
+    // res.send(req.params.id) compile too, written by uWS as it reads them and not as Express
+    // does: a query key repeated or missing gives the first value or nothing, a route parameter
+    // goes out undecoded, and one that Express refuses with a 400 is answered
+    "declarative request values": false,
     // on. Off hands every request to the ordinary chain instead of letting uWS match what it can,
     // which is slower and answers the same. Not a tuning knob: it exists so one application can be
     // served both ways and the answers compared, see `npm run fuzz -- --self`. A compiled response

package/src/uws.js

@@ -0,0 +1,45 @@
+/*
+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.
+
+// µWebSockets.js, loaded the first time something needs it rather than when this package is
+// required. An application that is built and never listens never loads the binary. Angular's
+// build imports server.ts in a worker thread to extract the routes and serves it through node's
+// http, and on Windows the binary crashes the process when a thread that loaded it exits
+// (uNetworking/uWebSockets.js#668), so the build only works if nothing in that thread loads it.
+
+/** @type {any} */
+let uWS;
+
+/**
+ * The µWS module. H3App, DeclarativeResponse and _cfg exist at runtime but are missing from the
+ * .d.ts the package ships, so it is handed back loosely typed.
+ *
+ * @returns {any}
+ */
+function loadUWS() {
+    if (uWS === undefined) {
+        uWS = /** @type {any} */ (require("uWebSockets.js"));
+        try {
+            // disable Uwebsockets header
+            uWS._cfg("999999990007");
+        } catch (error) {
+            // older uWS builds do not expose _cfg; there is nothing to fall back to
+        }
+    }
+    return uWS;
+}
+
+module.exports = { loadUWS };