fulmine.js 5.6.0 → 5.7.0

package/README.md

@@ -374,7 +374,7 @@ Worth changing, if these are routes that carry traffic
 
 It loads the application with `listen()` replaced by the half that compiles the routes, so nothing binds a port and the listen callback does not run: profiling a running service does not start a second copy of it. There is no score, on purpose. A percentage of routes is not a percentage of traffic, and an application with a thousand cold routes and one hot one that fell back would score well and serve badly.
 
-2. Do not use external `serve-static` module. Instead use built-in `express.static()` middleware, which is optimized for Fulmine. If your build already writes `.br` and `.gz` files next to the originals, `express.static(dir, { preCompressed: true })` serves those to the clients that accept them, so nothing is compressed at request time. It costs one more `stat` per request and sends a fraction of the bytes: on a 4KB script with a brotli twin, 12 times fewer. `Vary: Accept-Encoding` is sent whether or not a variant is found, the content type stays the one the requested name implies, and each variant carries its own ETag.
+2. Do not use external `serve-static` module. Instead use built-in `express.static()` middleware, which is optimized for Fulmine. If your build already writes `.br` and `.gz` files next to the originals, `express.static(dir, { preCompressed: true })` serves those to the clients that accept them, so nothing is compressed at request time and a fraction of the bytes goes out: on a 4KB script with a brotli twin, 12 times fewer. It costs no more than serving the file itself, one `stat` per request, because the twin is looked for before the file and its own `stat` is the only one the request needs. A type that is already compressed, a woff2 or a webp, is not looked up at all, and which twins a path has is remembered for a second: `{ cache: false }` asks the disk every time, `{ cache: "5s" }` sets the window. Only their presence is remembered, never their size or mtime, so nothing is ever described by a stale number. `Vary: Accept-Encoding` is sent whether or not a twin is found, the content type stays the one the requested name implies, and each variant carries its own ETag.
 
 3. Do not use `body-parser` module. Instead use built-in `express.text()`, `express.json()` etc.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.6.0",
+    "version": "5.7.0",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "bin": {

package/src/compression.js

@@ -36,11 +36,31 @@ limitations under the License.
 const zlib = require("zlib");
 const bytes = require("bytes");
 const compressible = require("compressible");
-const { negotiateEncoding, ENCODING_ANY } = require("./utils.js");
+const { negotiateEncoding, ENCODING_ANY, memoizeByString } = require("./utils.js");
 
 // Cache-Control: no-transform forbids recoding the body, which is what this does
 const NO_TRANSFORM = /(?:^|,)\s*?no-transform\s*?(?:,|$)/;
 
+/**
+ * Says the answer depends on Accept-Encoding. res.vary() parses what is there and merges, which on
+ * the usual response is parsing an absent header: only a response that already varies pays for it.
+ *
+ * @param {any} res
+ */
+function addVary(res) {
+    if (res.getHeader("Vary") === undefined) {
+        res.setHeader("Vary", "Accept-Encoding");
+        return;
+    }
+    res.vary("Accept-Encoding");
+}
+
+/**
+ * res.flush for a response that is not being compressed. The compression module puts a function
+ * there on every response it sees, and code written against it calls one without asking first.
+ */
+function noFlush() {}
+
 // what enforceEncoding is allowed to name, the compression module's list
 const ENFORCEABLE = new Set(["gzip", "deflate", "identity", "br"]);
 
@@ -61,12 +81,16 @@ const SYNC_LIMIT = 24 * 1024;
  */
 function shouldCompress(req, res) {
     const type = res.getHeader("Content-Type");
-    if (type === undefined || !compressible(String(type))) {
+    if (type === undefined) {
         return false;
     }
-    return true;
+    // memoized, because an application answers with two or three content-types and compressible
+    // splits the parameters off and searches the mime database to reach the same answer each time
+    return isCompressible(typeof type === "string" ? type : String(type));
 }
 
+const isCompressible = memoizeByString((type) => compressible(type) === true);
+
 /**
  * How many bytes a chunk is, which is what the threshold is compared against.
  *
@@ -184,6 +208,37 @@ function compression(options) {
     }
 
     return function compression(req, res, next) {
+        // Negotiated here rather than when the body arrives, because the answer to "could this
+        // request take a compressed body at all" decides how much of this middleware the response
+        // has to carry. Most requests to most routes cannot: a client that sent no Accept-Encoding,
+        // one that refused everything, a HEAD. Those get the Vary and nothing else, since the
+        // answer still depends on the header even when this particular client did not ask.
+        const accept = req.headers["accept-encoding"];
+        let chosen = negotiateEncoding(accept === undefined ? "" : accept, ENCODING_ANY);
+        if (accept === undefined && ENFORCEABLE.has(enforceEncoding)) {
+            chosen = enforceEncoding;
+        }
+        if (!chosen || chosen === "identity" || req.method === "HEAD") {
+            res.flush = noFlush;
+            const _plainEnd = res.end;
+            let varied = false;
+            res.end = function end(chunk, encoding, callback) {
+                if (!varied) {
+                    varied = true;
+                    const cacheControl = res.headersSent ? undefined : res.getHeader("Cache-Control");
+                    if (
+                        !res.headersSent &&
+                        filter(req, res) &&
+                        !(cacheControl && NO_TRANSFORM.test(String(cacheControl)))
+                    ) {
+                        addVary(res);
+                    }
+                }
+                return _plainEnd.call(this, chunk, encoding, callback);
+            };
+            return next();
+        }
+
         const _write = res.write;
         const _end = res.end;
         const _on = res.on;
@@ -243,7 +298,7 @@ function compression(options) {
             if (cacheControl && NO_TRANSFORM.test(String(cacheControl))) {
                 return noCompress();
             }
-            res.vary("Accept-Encoding");
+            addVary(res);
             // NaN when there is no Content-Length, and a comparison against NaN is false: a body
             // whose size is not known yet is compressed whatever the threshold says
             if (Number(res.getHeader("Content-Length")) < threshold || Number(length) < threshold) {
@@ -253,27 +308,17 @@ function compression(options) {
             if (already && already !== "identity") {
                 return noCompress();
             }
-            if (req.method === "HEAD") {
-                return noCompress();
-            }
             // a range is a window into the bytes on disk, and a client that asked for one cannot
             // decode a compressed answer to it
             if (res.statusCode === 206 || res.getHeader("Content-Range") !== undefined) {
                 return noCompress();
             }
-            const accept = req.headers["accept-encoding"];
-            let method = negotiateEncoding(accept === undefined ? "" : accept, ENCODING_ANY);
-            if (accept === undefined && ENFORCEABLE.has(enforceEncoding)) {
-                method = enforceEncoding;
-            }
-            if (!method || method === "identity") {
-                return noCompress();
-            }
-            res.setHeader("Content-Encoding", method);
+            // HEAD never reaches here: it took the Vary-only path above
+            res.setHeader("Content-Encoding", chosen);
             // what it says is the size of the body before this middleware saw it. The whole-body
             // path below puts the right one back; the streaming one cannot know it in advance
             res.removeHeader("Content-Length");
-            return method;
+            return chosen;
         }
 
         /**

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/utils.js

@@ -220,9 +220,13 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
         groupOutputName.set(group, name);
         return group;
     };
-    // whether the token just emitted was a :parameter, which decides how greedy the next
-    // optional group is allowed to be. see the comment where it is read
+    // whether the token just emitted was a :parameter or a wildcard, which decides how greedy the
+    // next optional group is allowed to be. see the comment where it is read
     let lastTokenWasParam = false;
+    // the wildcard just emitted, and where it ends, so an optional group written right after it
+    // can rewrite the two into one alternation. See the { branch
+    let lastWildcard = /** @type {{start: number, body: string, name: string}|null} */ (null);
+    let lastWildcardEnd = -1;
     // What path-to-regexp calls the wildcard backtrack: the literal text written since the last
     // wildcard. Once a wildcard has eaten slashes, a later one in the same path is held to a single
     // segment, or the two would divide the path between them in more than one way and the regex
@@ -339,8 +343,16 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
             }
             const splatGroup = uniqueGroupName(name);
             wildcardNames.push(splatGroup);
-            regexPattern += `(?<${splatGroup}>${wildcardClass()})`;
-            lastTokenWasParam = false;
+            const body = wildcardClass();
+            // where this capture starts and what it is made of, so an optional group written right
+            // after it can rewrite the pair into the alternation path-to-regexp compiles. See the
+            // { branch below
+            lastWildcard = { start: regexPattern.length, body, name };
+            regexPattern += `(?<${splatGroup}>${body})`;
+            lastWildcardEnd = regexPattern.length;
+            // the group that follows is held to one segment of its own, the way it is after a
+            // parameter: without it ext could take the separator back and swallow the dots
+            lastTokenWasParam = true;
             continue;
         }
 
@@ -417,7 +429,23 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
                     gi++;
                 }
             }
-            regexPattern += `(?:${groupRegex})?`;
+            if (lastWildcard && lastWildcardEnd === regexPattern.length) {
+                // A wildcard immediately before the group. `(?<w>[^]+)(?:group)?` can never let
+                // the group match, because the wildcard is greedy and the group may be empty, and
+                // making the wildcard lazy is not the same thing either: it gives the trailing
+                // slash away, and /*path{.:ext} against /a/b/ then loses the empty last segment.
+                // path-to-regexp writes the two branches out instead, group first and the
+                // wildcard greedy in both, so that is what goes here. The second branch captures
+                // the same parameter under a name of its own, which is what uniqueGroupName is for.
+                const second = uniqueGroupName(lastWildcard.name);
+                wildcardNames.push(second);
+                const withWildcard = regexPattern.slice(lastWildcard.start);
+                regexPattern =
+                    regexPattern.slice(0, lastWildcard.start) +
+                    `(?:${withWildcard}${groupRegex}|(?<${second}>${lastWildcard.body}))`;
+            } else {
+                regexPattern += `(?:${groupRegex})?`;
+            }
             literal(groupContent);
             lastTokenWasParam = false;
             continue;