fulmine.js 5.19.2 → 5.19.4

package/src/hot-settings.js

@@ -0,0 +1,80 @@
+/*
+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.
+*/
+
+const { settingsEpoch } = require("./utils.js");
+
+// The settings the hot paths read, resolved to plain fields: each read was a variadic get() whose
+// rest array escapes into createRoute, plus a dictionary miss per mount level for the json keys.
+// One shape for every router, stale when the epoch moves.
+class HotSettings {
+    /** Every field declared up front, one hidden class for every router's copy. */
+    constructor() {
+        this.epoch = 0;
+        this.xPoweredBy = false;
+        this.etagFn = undefined;
+        // null means every method, which is express's behaviour and the default
+        this.etagMethods = null;
+        this.queryParserFn = undefined;
+        this.trustProxyFn = undefined;
+        this.trustProxyProtocol = false;
+        this.jsonEscape = undefined;
+        this.jsonReplacer = undefined;
+        this.jsonSpaces = undefined;
+    }
+}
+
+/**
+ * What app.settings is wrapped in, so a write that never went through set() still bumps the epoch.
+ * Only writes are trapped, a read is the plain operation on the object.
+ *
+ * defineProperty is here for the trust proxy default marker, which set() writes that way.
+ */
+const settingsWriteTraps = {
+    /**
+     * @param {Record<string|symbol, unknown>} target the settings object itself, whose keys are the application's
+     * @param {string|symbol} key
+     * @param {unknown} value whatever the application is setting
+     */
+    set(target, key, value) {
+        target[key] = value;
+        settingsEpoch.n++;
+        return true;
+    },
+    /**
+     * @param {Record<string|symbol, unknown>} target the settings object itself
+     * @param {string|symbol} key
+     */
+    deleteProperty(target, key) {
+        delete target[key];
+        settingsEpoch.n++;
+        return true;
+    },
+    /**
+     * @param {Record<string|symbol, unknown>} target the settings object itself
+     * @param {string|symbol} key
+     * @param {PropertyDescriptor} descriptor
+     */
+    defineProperty(target, key, descriptor) {
+        Object.defineProperty(target, key, descriptor);
+        settingsEpoch.n++;
+        return true;
+    }
+};
+
+module.exports = { HotSettings, settingsWriteTraps };

package/src/index.js

@@ -17,8 +17,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// H3App, DeclarativeResponse and _cfg all exist at runtime but are missing from the
-// declaration file the package ships, so the module is read through a loose alias
+// 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 Application = require("./application.js");
@@ -36,9 +36,8 @@ try {
 }
 
 try {
-    // the compile cache, in node since 22.8: the next boot of the same code skips compiling it.
-    // Asked for here because in practice the framework is the entry point of the application
-    // using it. Respects NODE_DISABLE_COMPILE_CACHE, and booting without a cache is not an error
+    // 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
     require("node:module").enableCompileCache?.();
 } catch (error) {
     // node below 22.8, or a disk the cache cannot be written to
@@ -47,9 +46,8 @@ try {
 // The factory doubles as a namespace, as in Express: Router, static and the body parsers hang off
 // the function that creates an app.
 //
-// Written as `module.exports.name = ...` and never through an alias: cjs-module-lexer reads this
-// file as text to decide which named exports an ESM importer gets, and it cannot see through one.
-// Nothing here is executed to find that out.
+// Always `module.exports.name = ...`, never through an alias: cjs-module-lexer reads this file as
+// text to decide the named exports an ESM importer gets, and it cannot see through an alias.
 /**
  * @type {typeof Application & {
  *   Router: Function,
@@ -69,8 +67,7 @@ try {
  */
 module.exports = /** @type {any} */ (Application);
 
-// a router is a function too, for the same reason an app is: it has to be callable to be usable as
-// middleware
+// a router is a function too: it has to be callable to be used as middleware
 module.exports.Router = function (options) {
     return new Router(options)._asCallable();
 };
@@ -80,18 +77,15 @@ module.exports.Route = Route;
 
 module.exports.request = Request.prototype;
 module.exports.response = Response.prototype;
-// the third of the trio: adding a method here adds it to every app, the same as express.application
+// adding a method here adds it to every app, the same as express.application
 module.exports.application = Application.Application.prototype;
 
 module.exports.static = middlewares.static;
-// what listen() decided about each route, as something a test can assert on rather than something
-// to read in a terminal. See src/testing.js
+// what listen() decided about each route, as something a test can assert on. See src/testing.js
 module.exports.testing = require("./testing.js");
-// not one of express's, since express has none: the compression module is what everyone installs
-// instead, and this is that middleware's options and behaviour without the install
+// express has none: this is the compression module's options and behaviour, without the install
 module.exports.compression = require("./compression.js");
-// Server-Timing with the routing verdict in it, which no other framework can report because no
-// other framework has two routes to tell apart. See src/server-timing.js
+// Server-Timing with the routing verdict in it. See src/server-timing.js
 module.exports.serverTiming = require("./server-timing.js");
 module.exports.json = middlewares.json;
 module.exports.urlencoded = middlewares.urlencoded;

package/src/lazy-readable.js

@@ -0,0 +1,131 @@
+/*
+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.
+*/
+
+const { Readable } = require("stream");
+
+// 128 KB of body buffered before uWS is asked to pause
+const READABLE_OPTIONS = { highWaterMark: 128 * 1024 };
+
+/**
+ * A Readable that has not been built yet.
+ *
+ * Every request pays for the stream and almost none use it: a GET carries no body, and the bodies
+ * that arrive are collected by uWS and handed to the parsers without touching the stream. Measured
+ * on this machine, Readable's constructor is about 90ns of the 900ns a hello-world request costs.
+ *
+ * So the chain says Readable and the constructor does not run. `Request extends LazyReadable`, and
+ * LazyReadable's prototype is Readable's, so `req instanceof Readable` stays true and every
+ * Readable method is reachable. What is missing is `_readableState`, built on the first touch.
+ *
+ * The wrapping below is generated, not written out: every own member of Readable's prototype gets a
+ * version that materialises first, so there is no list to keep in step. Missing one would be a
+ * TypeError on `undefined._readableState`, not a slow path.
+ */
+class LazyReadableBase {}
+Object.setPrototypeOf(LazyReadableBase.prototype, Readable.prototype);
+Object.setPrototypeOf(LazyReadableBase, Readable);
+
+// what the chain says at runtime, said again for the type checker, which cannot see a prototype
+// being reassigned: everything a Readable offers is reachable from a Request, and is a Readable's
+const LazyReadable = /** @type {typeof Readable} */ (/** @type {unknown} */ (LazyReadableBase));
+
+/**
+ * Builds the stream this object has been pretending to be. Idempotent: everything that can be
+ * reached from outside goes through it, so it is called far more often than it does anything.
+ *
+ * EventEmitter's init keeps an _events that is already there, so listeners added before this
+ * survive it.
+ *
+ * @param {any} stream the Request pretending to be one, before its state exists
+ */
+function materialise(stream) {
+    if (stream._readableState === undefined) {
+        Readable.call(stream, READABLE_OPTIONS);
+    }
+}
+
+for (const member of [
+    ...Object.getOwnPropertyNames(Readable.prototype),
+    ...Object.getOwnPropertySymbols(Readable.prototype)
+]) {
+    // the constructor is not a door, and `readable` is handled below because a request writes it
+    // and writing it must not build the very thing this is avoiding
+    if (member === "constructor" || member === "readable") {
+        continue;
+    }
+    const descriptor = /** @type {PropertyDescriptor} */ (Object.getOwnPropertyDescriptor(Readable.prototype, member));
+    if (typeof descriptor.value === "function") {
+        const inner = descriptor.value;
+        Object.defineProperty(LazyReadableBase.prototype, member, {
+            ...descriptor,
+            /** @this {import("stream").Readable} @param {...unknown} args */
+            value: function (...args) {
+                materialise(this);
+                return inner.apply(this, args);
+            }
+        });
+    } else if (descriptor.get || descriptor.set) {
+        const innerGet = descriptor.get;
+        const innerSet = descriptor.set;
+        Object.defineProperty(LazyReadableBase.prototype, member, {
+            ...descriptor,
+            get: innerGet
+                ? /** @this {import("stream").Readable} */ function () {
+                      materialise(this);
+                      return innerGet.call(this);
+                  }
+                : undefined,
+            set: innerSet
+                ? /** @this {import("stream").Readable} @param {unknown} value */ function (value) {
+                      materialise(this);
+                      innerSet.call(this, value);
+                  }
+                : undefined
+        });
+    }
+}
+
+const nodeReadable = /** @type {PropertyDescriptor} */ (
+    Object.getOwnPropertyDescriptor(Readable.prototype, "readable")
+);
+
+// `readable` on its own: a request sets it while it is being built, and node's setter is a no-op
+// without the state anyway, so the flag is kept as a plain field until there is a stream to ask
+Object.defineProperty(LazyReadableBase.prototype, "readable", {
+    configurable: true,
+    enumerable: false,
+    // `this` is loose in both: node's state field, which its typings do not declare, and this
+    // project's own flag
+    /** @this {any} */
+    get: function () {
+        return this._readableState === undefined
+            ? this._readableFlag === true
+            : /** @type {() => boolean} */ (nodeReadable.get).call(this);
+    },
+    /** @this {any} @param {unknown} value */
+    set: function (value) {
+        if (this._readableState === undefined) {
+            this._readableFlag = !!value;
+            return;
+        }
+        /** @type {(value: unknown) => void} */ (nodeReadable.set).call(this, value);
+    }
+});
+
+module.exports = { LazyReadable, READABLE_OPTIONS };

package/src/lazy-writable.js

@@ -0,0 +1,97 @@
+/*
+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.
+*/
+
+const { Writable } = require("stream");
+
+/**
+ * A Writable that has not built its state yet, the mirror of LazyReadable and for the same reason:
+ * a response is a Writable because middleware expects one, and the ordinary one never uses it.
+ * `send()` reaches `end()`, which is overridden here and goes straight to _finish, so the
+ * WritableState was allocated for every response and read by nobody. Only res.write(), a pipe,
+ * cork and the writableX getters need it.
+ *
+ * `Response extends LazyWritable`, whose prototype is Writable's, so `res instanceof Writable`
+ * stays true. `_writableState` is built on the first touch. Measured at 45ns a response.
+ *
+ * As on the Readable side the wrapping is generated: every own member of Writable's prototype gets
+ * a version that materialises first, so there is no list to keep in step.
+ */
+class LazyWritableBase {}
+Object.setPrototypeOf(LazyWritableBase.prototype, Writable.prototype);
+Object.setPrototypeOf(LazyWritableBase, Writable);
+
+// what the chain says at runtime, said again for the type checker, which cannot see a prototype
+// being reassigned
+const LazyWritable = /** @type {typeof Writable} */ (/** @type {unknown} */ (LazyWritableBase));
+
+/**
+ * Builds the stream this object has been pretending to be. Idempotent: everything reachable from
+ * outside goes through it, so it is called far more often than it does anything.
+ *
+ * EventEmitter's init keeps an _events that is already there, so both the shape the constructor
+ * wrote and any listener added before this survive it.
+ *
+ * @param {any} stream the Response pretending to be one, before its state exists
+ */
+function materialiseWritable(stream) {
+    if (stream._writableState === undefined) {
+        Writable.call(stream);
+    }
+}
+
+for (const member of [
+    ...Object.getOwnPropertyNames(Writable.prototype),
+    ...Object.getOwnPropertySymbols(Writable.prototype)
+]) {
+    if (member === "constructor") {
+        continue;
+    }
+    const descriptor = /** @type {PropertyDescriptor} */ (Object.getOwnPropertyDescriptor(Writable.prototype, member));
+    if (typeof descriptor.value === "function") {
+        const inner = descriptor.value;
+        Object.defineProperty(LazyWritableBase.prototype, member, {
+            ...descriptor,
+            /** @this {import("stream").Writable} @param {...unknown} args */
+            value: function (...args) {
+                materialiseWritable(this);
+                return inner.apply(this, args);
+            }
+        });
+    } else if (descriptor.get || descriptor.set) {
+        const innerGet = descriptor.get;
+        const innerSet = descriptor.set;
+        Object.defineProperty(LazyWritableBase.prototype, member, {
+            ...descriptor,
+            get: innerGet
+                ? /** @this {import("stream").Writable} */ function () {
+                      materialiseWritable(this);
+                      return innerGet.call(this);
+                  }
+                : undefined,
+            set: innerSet
+                ? /** @this {import("stream").Writable} @param {unknown} value */ function (value) {
+                      materialiseWritable(this);
+                      innerSet.call(this, value);
+                  }
+                : undefined
+        });
+    }
+}
+
+module.exports = { LazyWritable };