fulmine.js 5.15.1 → 5.16.0

package/README.md

@@ -502,6 +502,13 @@ Server-Timing: route;desc="native", hdr;desc="not copied", db;dur=3.62, total;du
 app.use(express.compression({ threshold: 1024 }));
 ```
 
+One option is Fulmine's own, `encodings`: the list of what the middleware may answer with, out of `"br"`, `"gzip"` and `"deflate"`. What is not named is never used, however the client ranks it, and an uncompressed answer is always on offer. It exists because the preferred encoding is a cost decision, not only a size one: brotli compresses smaller but what it costs per response depends on the machine, and on a CPU where it runs expensive `encodings: ["gzip"]` buys the cheaper call for every client that accepts both.
+
+```js
+// answer gzip even to a client that also accepts br
+app.use(express.compression({ level: 1, encodings: ["gzip"] }));
+```
+
 Runnable: [`examples/compression.js`](./examples/compression.js).
 
 5. If a route answers with a JSON shape you know in advance, [express-fast-json-stringify](https://www.npmjs.com/package/express-fast-json-stringify) compiles that shape into a serializer and `res.fastJson()` replaces `res.json()`. `JSON.stringify()` has to walk an object it knows nothing about; a compiled serializer does not. It is worth reaching for, and a CPU profile says why: on a route answering 3.6KB of JSON, serialising it is about 25% of the time that is not spent waiting, ahead of the ETag at 19% and of everything the framework does to route the request and build its request and response objects.

package/package.json

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

package/src/compression.js

@@ -36,7 +36,23 @@ limitations under the License.
 const zlib = require("zlib");
 const bytes = require("bytes");
 const compressible = require("compressible");
-const { negotiateEncoding, ENCODING_ANY, memoizeByString } = require("./utils.js");
+const {
+    negotiateEncoding,
+    ENCODING_ANY,
+    ENCODING_BR,
+    ENCODING_GZIP,
+    ENCODING_DEFLATE,
+    memoizeByString
+} = require("./utils.js");
+
+// what the `encodings` option may name, and the mask each name contributes. identity is 0: an
+// uncompressed answer is always on offer, naming it only makes the list read complete
+const ENCODING_MASKS = new Map([
+    ["br", ENCODING_BR],
+    ["gzip", ENCODING_GZIP],
+    ["deflate", ENCODING_DEFLATE],
+    ["identity", 0]
+]);
 
 // Cache-Control: no-transform forbids recoding the body, which is what this does
 const NO_TRANSFORM = /(?:^|,)\s*?no-transform\s*?(?:,|$)/;
@@ -135,6 +151,11 @@ function toBuffer(chunk, encoding) {
  * @param {string} [options.enforceEncoding] what to use when the request carries no
  *   Accept-Encoding at all. Default "identity", which is to say nothing is compressed.
  * @param {object} [options.brotli] brotli options, `params` included. The default quality is 4.
+ * @param {string[]} [options.encodings] the encodings this middleware may answer with, out of
+ *   "br", "gzip" and "deflate". What is not named is never used, however the client ranks it: a
+ *   server that prefers cheap gzip over brotli passes ["gzip", "deflate"]. An uncompressed answer
+ *   is always on offer, and enforceEncoding stays its own explicit choice, outside this list.
+ *   This option is fulmine's own, the compression module has no equivalent.
  * @param {number} [options.level] zlib compression level, for gzip and deflate.
  * @param {number} [options.chunkSize] zlib chunk size.
  * @param {number} [options.memLevel] zlib memory level.
@@ -157,6 +178,22 @@ function compression(options) {
     // bytes.parse reads "1kb" and hands back null for anything it cannot, an absent option
     // included, which is where the default comes in
     const threshold = bytes.parse(/** @type {any} */ (opts.threshold)) ?? 1024;
+    // the mask handed to the negotiation, built once here: a name nobody knows is a config
+    // mistake and throws now rather than serving the wrong bytes later
+    let allowed = ENCODING_ANY;
+    if (opts.encodings !== undefined) {
+        if (!Array.isArray(opts.encodings)) {
+            throw new TypeError("encodings must be an array of encoding names");
+        }
+        allowed = 0;
+        for (const name of opts.encodings) {
+            const mask = ENCODING_MASKS.get(name);
+            if (mask === undefined) {
+                throw new TypeError(`unknown encoding "${name}" in encodings`);
+            }
+            allowed |= mask;
+        }
+    }
 
     /**
      * A whole body, compressed on this thread. Blocks the event loop for as long as it takes,
@@ -213,8 +250,14 @@ function compression(options) {
         // 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);
+        // straight from the raw entries where this request keeps them: reading req.headers here
+        // built the whole object for one name. Folded, so a repeated Accept-Encoding still reads
+        // as the joined list the headers object would have shown
+        const accept =
+            typeof req._foldedHeader === "function"
+                ? req._foldedHeader("accept-encoding")
+                : req.headers["accept-encoding"];
+        let chosen = negotiateEncoding(accept === undefined ? "" : accept, allowed);
         if (accept === undefined && ENFORCEABLE.has(enforceEncoding)) {
             chosen = enforceEncoding;
         }

package/src/request.js

@@ -951,6 +951,35 @@ module.exports = class Request extends LazyReadable {
         return undefined;
     }
 
+    /**
+     * The same, with repeats folded exactly as the headers object folds them, so a reader of one
+     * name per request does not build the whole object to stay correct on a repeated header.
+     * Not for set-cookie, whose folded form is an array.
+     *
+     * @param {string} name lowercase
+     * @returns {string|undefined}
+     */
+    _foldedHeader(name) {
+        if (this.#cachedHeaders !== null) {
+            return this.#cachedHeaders[name];
+        }
+        const entries = this.#rawHeadersEntries;
+        let value;
+        for (let i = 0, len = entries.length; i < len; i += 2) {
+            if (entries[i] === name) {
+                if (value === undefined) {
+                    value = entries[i + 1];
+                } else {
+                    if (discardedDuplicates.has(name)) {
+                        continue;
+                    }
+                    value += (name === "cookie" ? "; " : ", ") + entries[i + 1];
+                }
+            }
+        }
+        return value;
+    }
+
     /**
      * Whether there is any point still reading the body: once the response is finished or the
      * connection is gone, uWS has nothing left to hand over.

package/src/types.d.ts

@@ -50,6 +50,12 @@ declare module "fulmine.js" {
             enforceEncoding?: string;
             /** Brotli options. The default quality is 4. */
             brotli?: BrotliOptions;
+            /**
+             * The encodings this middleware may answer with; what is not named is never used,
+             * however the client ranks it. Fulmine's own option, the compression module has no
+             * equivalent. An uncompressed answer is always on offer.
+             */
+            encodings?: ("br" | "gzip" | "deflate" | "identity")[];
         }
         // what listen() decided about each route, for a test to hold on to
         interface RouteVerdict {

package/src/utils.js

@@ -1644,6 +1644,7 @@ module.exports = {
     negotiateEncoding,
     ENCODING_BR,
     ENCODING_GZIP,
+    ENCODING_DEFLATE,
     ENCODING_ANY,
     memoizeByString,
     isRangeFresh,