fulmine.js 5.6.0 → 5.8.0

package/src/middlewares.js

@@ -23,6 +23,8 @@ const bytes = require("bytes");
 const zlib = require("fast-zlib");
 const typeis = require("type-is");
 const mime = require("mime-types");
+const compressible = require("compressible");
+const ms = require("ms");
 const qs = require("qs");
 const parseQuery = require("./parse-query.js");
 const { kGetSafe } = require("./usage.js");
@@ -267,6 +269,52 @@ function bodyError(message, status, type, extra) {
     return Object.assign(err, extra);
 }
 
+/**
+ * Whether a file of this extension is one anybody writes a `.br` or a `.gz` next to. A webp or a
+ * woff2 is already compressed and never has a twin, and looking for one costs two stats on a
+ * request that could not have used it: on a mixed directory that is most of the stat time. An
+ * extension nothing knows is looked up anyway, since it might well be text.
+ *
+ * @param {string} extension including the dot, or "" for a name without one
+ * @returns {boolean}
+ */
+const hasTwins = memoizeByString((extension) => {
+    const type = mime.lookup(extension);
+    return type ? compressible(type) === true : true;
+});
+
+// Which twins a path has, remembered for a moment. What is cached is only whether they are there,
+// never their size or their mtime: those decide the ETag, the Last-Modified and the length, so they
+// are read fresh on every request and a file that changed is never described by a stale number.
+// The worst a stale entry can do is serve the file where it could have served the twin, or look for
+// a twin that has just been deleted and fall back. nginx's open_file_cache is the same trade.
+const twinCache = new Map();
+const TWIN_CACHE_LIMIT = 4096;
+
+/**
+ * What is known about a path's twins right now, as a record to fill in.
+ *
+ * @param {string} filePath
+ * @param {number} ttl how long an answer stays good, in milliseconds
+ * @returns {{br: boolean|undefined, gz: boolean|undefined, until: number}}
+ */
+function twinsOf(filePath, ttl) {
+    const now = Date.now();
+    const known = twinCache.get(filePath);
+    if (known !== undefined && known.until > now) {
+        return known;
+    }
+    const entry = { br: undefined, gz: undefined, until: now + ttl };
+    // cleared rather than evicted one by one, as memoizeByString does: this holds one small object
+    // per path served, and a directory big enough to reach the limit is being served by something
+    // other than an application server anyway
+    if (twinCache.size >= TWIN_CACHE_LIMIT) {
+        twinCache.clear();
+    }
+    twinCache.set(filePath, entry);
+    return entry;
+}
+
 /**
  * The compressed twin of a file to serve in its place, or undefined when the client would rather
  * have the file itself or the twin is not there.
@@ -275,17 +323,19 @@ function bodyError(message, status, type, extra) {
  * Last-Modified of a variant are its own, which is the whole point. Two bodies sharing one ETag is
  * how a shared cache ends up handing brotli to a client that cannot read it.
  *
- * At most two stats, and usually one: negotiation picks the best of the two encodings first, and
- * only looks at the other when the client takes it too and the first file is missing.
+ * One stat when the answer is a twin, and none at all when the last request already found there is
+ * no twin to have. See twinCache above for what is remembered and what is not.
  *
  * @param {string} filePath absolute path of the file that was asked for
  * @param {string|undefined} accept the request's Accept-Encoding
+ * @param {number} ttl how long the twin cache holds an answer, 0 to ask the disk every time
  * @returns {{suffix: string, encoding: string, stat: import("fs").Stats}|undefined}
  */
-function pickPrecompressed(filePath, accept) {
-    if (!accept) {
+function pickPrecompressed(filePath, accept, ttl) {
+    if (!accept || !hasTwins(filePath.slice(filePath.lastIndexOf(".")))) {
         return undefined;
     }
+    const known = ttl > 0 ? twinsOf(filePath, ttl) : undefined;
     let allowed = ENCODING_BR | ENCODING_GZIP;
     // twice at most: the second pass is the case where brotli won and there is no .br on disk
     for (let attempt = 0; attempt < 2; attempt++) {
@@ -294,13 +344,17 @@ function pickPrecompressed(filePath, accept) {
         if (!variant) {
             return undefined;
         }
-        try {
-            const stat = fs.statSync(filePath + variant.suffix);
-            if (!stat.isDirectory()) {
-                return { suffix: variant.suffix, encoding: variant.encoding, stat };
+        if (known === undefined || known[variant.encoding === "br" ? "br" : "gz"] !== false) {
+            try {
+                const stat = fs.statSync(filePath + variant.suffix);
+                if (!stat.isDirectory()) {
+                    if (known !== undefined) known[variant.encoding === "br" ? "br" : "gz"] = true;
+                    return { suffix: variant.suffix, encoding: variant.encoding, stat };
+                }
+            } catch {
+                // not on disk, which is the ordinary case for a file nobody precompressed
             }
-        } catch {
-            // not on disk, which is the ordinary case for a file nobody precompressed
+            if (known !== undefined) known[variant.encoding === "br" ? "br" : "gz"] = false;
         }
         allowed &= ~variant.flag;
     }
@@ -343,6 +397,26 @@ function serveStatic(root, options) {
     if (options.setHeaders !== undefined && typeof options.setHeaders !== "function") {
         throw new TypeError("option setHeaders must be function");
     }
+    // How long express.static remembers which twins a path has. A second is short enough that a
+    // deploy is picked up while it is still going out, and long enough that the lookup costs
+    // nothing under any traffic at all. { cache: false } asks the disk on every request.
+    let twinTtl = 0;
+    if (options.preCompressed) {
+        const cache = /** @type {any} */ (
+            typeof options.preCompressed === "object" ? options.preCompressed.cache : undefined
+        );
+        twinTtl =
+            cache === undefined
+                ? 1000
+                : cache === false
+                  ? 0
+                  : typeof cache === "string"
+                    ? ms(/** @type {any} */ (cache))
+                    : cache;
+        if (typeof twinTtl !== "number" || !(twinTtl >= 0)) {
+            throw new TypeError("option preCompressed.cache must be a duration");
+        }
+    }
     options.root = root;
     // serve-static decides this for itself and never asks the app, so a static file keeps its
     // ETag under app.set("etag", false) and only { etag: false } here turns it off. res.sendFile
@@ -434,8 +508,22 @@ function serveStatic(root, options) {
         }
 
         let stat;
+        // The twin, looked for before the file itself rather than after it. When there is one, it
+        // is the file being served and its stat is the only one this request needs: the request
+        // that asks for /app.js and gets /app.js.br has no use for /app.js's size or mtime. A
+        // directory, or a path written with a trailing slash, keeps the ordinary order, since what
+        // decides those is the stat of the thing that was asked for.
+        let twin;
+        if (options.preCompressed && !rawPath.endsWith("/") && !req.endsWithSlash) {
+            twin = pickPrecompressed(filePath, req.headers["accept-encoding"], twinTtl);
+            if (twin) {
+                stat = twin.stat;
+            }
+        }
         try {
-            stat = fs.statSync(statTarget);
+            if (stat === undefined) {
+                stat = fs.statSync(statTarget);
+            }
         } catch (err) {
             // the one to report when nothing is found: send hands each failed attempt to the next
             // one and reports whichever came last, so an extensions option that also missed names
@@ -541,7 +629,8 @@ function serveStatic(root, options) {
             // whatever is served, the answer depended on the header, so a shared cache has to be
             // told. Said before the lookup, because it is true even when there is no variant
             res.vary("Accept-Encoding");
-            const variant = pickPrecompressed(filePath, req.headers["accept-encoding"]);
+            // already found before the stat below, on the ordinary path
+            const variant = twin ?? pickPrecompressed(filePath, req.headers["accept-encoding"], twinTtl);
             if (variant) {
                 _path += variant.suffix;
                 stat = variant.stat;

package/src/options.d.ts

@@ -72,8 +72,12 @@ export interface StaticOptions extends SendFileOptions {
      * Serve `file.br` or `file.gz` in place of `file` when one is on disk and the client takes it.
      * Off by default. Vary: Accept-Encoding is sent whether or not a variant is found, and the
      * content type stays the one the requested name implies.
+     *
+     * Which twins a path has is remembered for a second, since asking the disk costs a stat per
+     * request; `{ cache: false }` asks every time, and a duration sets how long. Only their
+     * presence is cached, never their size or mtime.
      */
-    preCompressed?: boolean;
+    preCompressed?: boolean | { cache?: number | string | false };
 }
 
 /** A body parser's options once its factory has filled in every default it needs. */

package/src/server-shape.js

@@ -0,0 +1,157 @@
+/*
+Copyright 2026 Nigro Simone
+
+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.
+*/
+
+// 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.
+//
+// Two halves, and the second is the delicate one:
+//
+//   - 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.
+//
+// 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.
+
+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
+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.
+ *
+ * @param {Function} klass http.Server or net.Server
+ */
+function acceptApplications(klass) {
+    const previous = /** @type {any} */ (klass)[Symbol.hasInstance];
+    // already taught, which happens when two copies of this package share one process
+    if (/** @type {any} */ (klass)[kIsApplication] === true) {
+        return;
+    }
+    Object.defineProperty(klass, Symbol.hasInstance, {
+        /** @param {any} value @returns {boolean} */
+        value: function (value) {
+            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
+            return value != null && /** @type {any} */ (value)[kIsApplication] === true;
+        },
+        configurable: true,
+        writable: true
+    });
+    Object.defineProperty(klass, kIsApplication, { value: true, configurable: true });
+}
+
+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.
+ *
+ * @param {any} prototype Application.prototype
+ */
+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.
+     *
+     * @param {(err: Error|null, count: number) => void} callback
+     */
+    prototype.getConnections = function getConnections(callback) {
+        let count = 0;
+        for (let response = this._pending.head; response !== null; response = response._pendingNext) {
+            count++;
+        }
+        // node answers this one asynchronously, and a caller written against it may rely on that
+        process.nextTick(callback, null, count);
+    };
+
+    /**
+     * 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.
+     *
+     * @returns {any}
+     */
+    prototype.ref = function ref() {
+        return this;
+    };
+
+    /** @returns {any} */
+    prototype.unref = function unref() {
+        return this;
+    };
+
+    /**
+     * 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.
+     *
+     * @this {any}
+     * @param {number} [msecs]
+     * @param {() => void} [callback]
+     * @returns {any}
+     */
+    prototype.setTimeout = function setTimeout(msecs, callback) {
+        this.timeout = msecs;
+        if (callback) {
+            this.on("timeout", callback);
+        }
+        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.
+    for (const [name, value] of /** @type {[string, any][]} */ ([
+        ["timeout", 0],
+        ["keepAliveTimeout", 5000],
+        ["headersTimeout", 60000],
+        ["requestTimeout", 300000],
+        ["maxHeadersCount", null],
+        ["maxRequestsPerSocket", 0]
+    ])) {
+        Object.defineProperty(prototype, name, { value, writable: true, configurable: true, enumerable: false });
+    }
+}
+
+module.exports = { addServerMembers, kIsApplication };

package/src/server-timing.js

@@ -0,0 +1,180 @@
+/*
+Copyright 2026 Nigro Simone
+
+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.
+*/
+
+// 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:
+//
+//     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
+// 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.
+//
+// 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 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. Every stopwatch
+// middleware has that boundary; this one says so.
+
+"use strict";
+
+/**
+ * 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.
+ *
+ * @param {bigint} nanoseconds
+ * @returns {string}
+ */
+function millis(nanoseconds) {
+    return (Number(nanoseconds) / 1e6).toFixed(2);
+}
+
+/**
+ * Escapes a description for the quoted-string it goes in.
+ * @param {string} text
+ * @returns {string}
+ */
+function describe(text) {
+    return `"${String(text).replace(/["\\]/g, "")}"`;
+}
+
+/**
+ * Measures the request and answers with Server-Timing.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.routing] whether to report how the request was routed. Default true.
+ * @param {boolean} [options.total] whether to report the time up to the head. Default true.
+ * @param {string} [options.name] what the total is called. Default "total".
+ * @returns {(req: any, res: any, next: (err?: any) => void) => void}
+ */
+function serverTiming(options) {
+    const opts = options || {};
+    const routing = opts.routing !== false;
+    const wantsTotal = opts.total !== false;
+    const totalName = opts.name || "total";
+
+    return function serverTiming(req, res, next) {
+        const started = process.hrtime.bigint();
+        /** @type {string[]} */
+        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.
+         *
+         * @param {string} name a token: letters, digits, dash and underscore
+         * @param {number} [duration] milliseconds
+         * @param {string} [description]
+         * @returns {any} the response, so calls chain
+         */
+        res.timing = function timing(name, duration, description) {
+            let mark = String(name).replace(/[^\w-]/g, "");
+            if (typeof duration === "number") {
+                mark += `;dur=${duration.toFixed(2)}`;
+            }
+            if (description) {
+                mark += `;desc=${describe(description)}`;
+            }
+            marks.push(mark);
+            return this;
+        };
+
+        /**
+         * Times a piece of work under a name, whatever it is: the value comes back, and a promise
+         * is timed to where it settles.
+         *
+         * @param {string} name
+         * @param {() => any} work
+         * @returns {any} whatever the work returned
+         */
+        res.time = function time(name, work) {
+            const from = process.hrtime.bigint();
+            const done = () => res.timing(name, Number(process.hrtime.bigint() - from) / 1e6);
+            let value;
+            try {
+                value = work();
+            } catch (err) {
+                done();
+                throw err;
+            }
+            if (value && typeof value.then === "function") {
+                return value.then(
+                    /** @param {any} resolved */ (resolved) => {
+                        done();
+                        return resolved;
+                    },
+                    /** @param {any} err */ (err) => {
+                        done();
+                        throw err;
+                    }
+                );
+            }
+            done();
+            return value;
+        };
+
+        const _write = res.write;
+        const _end = res.end;
+        let written = false;
+
+        /** Writes the header, once, just before the head goes out with the first byte of body. */
+        const stamp = () => {
+            if (written || res.headersSent) {
+                return;
+            }
+            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
+                const native = req.route?._native;
+                entries.push(`route;desc=${describe(native ? "native" : "router")}`);
+                if (native) {
+                    entries.push(`hdr;desc=${describe(native.skipHeaders ? "not copied" : "copied")}`);
+                    if (native.skipQuery) {
+                        entries.push(`query;desc=${describe("not parsed")}`);
+                    }
+                }
+            }
+            entries.push(...marks);
+            if (wantsTotal) {
+                entries.push(`${totalName};dur=${millis(process.hrtime.bigint() - started)}`);
+            }
+            if (entries.length !== 0) {
+                res.append("Server-Timing", entries.join(", "));
+            }
+        };
+
+        res.write = function write(chunk, encoding, callback) {
+            stamp();
+            return _write.call(this, chunk, encoding, callback);
+        };
+        res.end = function end(chunk, encoding, callback) {
+            stamp();
+            return _end.call(this, chunk, encoding, callback);
+        };
+
+        next();
+    };
+}
+
+module.exports = serverTiming;