fulmine.js 5.5.1 → 5.6.0

package/src/response.js

@@ -228,9 +228,10 @@ module.exports = class Response extends LazyWritable {
      * measured on uWS alone, 500 writes of 66 bytes take 13ms against 0.06ms for 100 of them.
      * Handing it the same bytes in blocks costs 0.4ms. Nothing here changes what goes on the wire,
      * only how many calls it takes to put it there.
-     * @type {Buffer[]}
+     * Null until the first chunked write, since a res.send never queues anything.
+     * @type {Buffer[]|null}
      */
-    #queued = [];
+    #queued = null;
 
     /** How many bytes {@link #queued} holds, kept alongside so the flush does not add them up. */
     #queuedBytes = 0;
@@ -437,12 +438,12 @@ module.exports = class Response extends LazyWritable {
      * @param {((err?: Error|null) => void)|null} callback the stream's, when there is one waiting
      */
     #flushQueued(callback) {
-        if (this.#queuedBytes === 0) {
+        if (this.#queued === null || this.#queuedBytes === 0) {
             if (callback) callback(null);
             return;
         }
         const body = this.#queued.length === 1 ? this.#queued[0] : Buffer.concat(this.#queued, this.#queuedBytes);
-        this.#queued = [];
+        this.#queued = null;
         this.#queuedBytes = 0;
 
         const ok = this._res.write(body);
@@ -467,13 +468,16 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * The booked flush. An arrow so it can be handed to nextTick without binding it every write.
+     * The booked flush. Static, so a response that never writes in pieces allocates nothing for it:
+     * nextTick forwards the receiver as an argument.
+     *
+     * @param {any} res
      */
-    #flushOnTick = () => {
-        this.#flushBooked = false;
-        if (this.aborted || this.finished || this.#queuedBytes === 0) return;
-        this._res.cork(() => this.#flushQueued(null));
-    };
+    static #flushOnTick(res) {
+        res.#flushBooked = false;
+        if (res.aborted || res.finished || res.#queuedBytes === 0) return;
+        res._res.cork(() => res.#flushQueued(null));
+    }
 
     /**
      * Writable's sink. Sends the headers if they have not gone yet, then hands the chunk to uWS,
@@ -520,7 +524,7 @@ module.exports = class Response extends LazyWritable {
                 // turn or once it is big enough to be worth a call. A stream that writes once per
                 // turn, an SSE feed for instance, still leaves on its own turn: the queue only ever
                 // gathers what was written without yielding in between.
-                this.#queued.push(/** @type {Buffer} */ (chunk));
+                (this.#queued ??= []).push(/** @type {Buffer} */ (chunk));
                 this.#queuedBytes += /** @type {Buffer} */ (chunk).byteLength;
                 // a chunk that is already big enough to be worth its own call leaves with whatever
                 // was waiting in front of it, rather than paying for a copy it does not need
@@ -529,7 +533,7 @@ module.exports = class Response extends LazyWritable {
                 } else {
                     if (!this.#flushBooked) {
                         this.#flushBooked = true;
-                        process.nextTick(this.#flushOnTick);
+                        process.nextTick(Response.#flushOnTick, this);
                     }
                     this.writingChunk = false;
                     callback(null);
@@ -786,7 +790,10 @@ module.exports = class Response extends LazyWritable {
                 // remembered rather than measured: only a caller that asks for content-length pays
                 // for it, and uWS is measuring the same bytes for the wire anyway
                 this._sentBody = data ?? "";
-                this._res.end(data);
+                // and null is sent as the empty body it means. uWS answers end(null) with a
+                // response the client never sees the end of, where node and express send an empty
+                // 200: res.end(null) is what the compression module's own test suite does
+                this._res.end(data ?? "");
             }
         }
 
@@ -1329,11 +1336,16 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * Sends the status line and the headers now, without waiting for a body, which is node's
+     * Hands the status line and the headers over now, without waiting for a body, which is node's
      * flushHeaders(). Callers use it to let the client start on the head while the body is still
      * being produced, and one of them is `@angular/ssr`'s writeResponseToNodeResponse, which calls
      * it before streaming a rendered page.
      *
+     * **The head does not reach the wire here.** uWS holds it until the first body chunk, so a
+     * client sees nothing until then, where express answers at once. `beginWrite` is uWS's API for
+     * this and is unusable: it emits a stray CRLF before the first chunk size, which node's parser
+     * rejects as HPE_INVALID_CHUNK_SIZE. Checked against v20.69.0, the latest release.
+     *
      * A second call does nothing, as node's does. Nothing is written for a response already
      * finished or aborted: uWS has let go of it by then.
      *
@@ -1425,10 +1437,6 @@ module.exports = class Response extends LazyWritable {
      * @param {Record<string, string>|[string, string][]} [headers]
      * @returns {void}
      */
-
-    /**
-     *
-     */
     addTrailers(headers) {}
 
     /**
@@ -1440,10 +1448,6 @@ module.exports = class Response extends LazyWritable {
      * @param {() => void} [callback]
      * @returns {this}
      */
-
-    /**
-     *
-     */
     setTimeout(msecs, callback) {
         if (typeof callback === "function") {
             this.once("timeout", callback);
@@ -1458,20 +1462,12 @@ module.exports = class Response extends LazyWritable {
      * @param {any} [socket]
      * @returns {void}
      */
-
-    /**
-     *
-     */
     assignSocket(socket) {}
 
     /**
      * @param {any} [socket]
      * @returns {void}
      */
-
-    /**
-     *
-     */
     detachSocket(socket) {}
 
     /**
@@ -2005,12 +2001,6 @@ module.exports = class Response extends LazyWritable {
         return this.set("content-type", ct);
     }
 
-    /**
-     * express carries both names for the same method, and middleware reaches for either.
-     * @type {(type: string) => any}
-     */
-    contentType = this.type;
-
     /**
      * Adds a field to Vary, without repeating one already there.
      * @param {string|string[]} field
@@ -2040,3 +2030,7 @@ module.exports = class Response extends LazyWritable {
         return this.finished;
     }
 };
+
+// res.contentType is res.type under express's other name. On the prototype rather than an instance
+// field, which wrote one own property per response in the constructor.
+/** @type {any} */ (module.exports.prototype).contentType = module.exports.prototype.type;

package/src/router.js

@@ -446,7 +446,7 @@ class Walk {
             return this.step(undefined);
         }
         if (kind === CALLBACK_ROUTER) {
-            if (callback.constructor.name === "Application") {
+            if (callback._isApplication) {
                 rememberApp(this, route, req);
                 useApp(req, callback);
             }
@@ -616,10 +616,15 @@ function nativeFail(err) {
  * @returns {number}
  */
 function mountPrefixLength(route, req) {
-    const path = req._opPath;
+    // a use with no path is EMPTY_REGEX, which matches "" at 0 whatever the path is. Answered
+    // without the exec, since this runs per hop and most middleware is pathless
+    if (route.pattern === EMPTY_REGEX) {
+        return 0;
+    }
     if (typeof route.pattern === "string") {
         return route.pattern.length;
     }
+    const path = req._opPath;
     const matched = route.pattern.exec(path === "" ? "/" : path);
     return matched ? Math.min(matched[0].length, path.length) : 0;
 }
@@ -1057,7 +1062,7 @@ function guardsInside(router, mount, pathPrefix, chain, inherited) {
  * @param {any} req
  */
 function rememberApp(walk, route, req) {
-    if (walk.router._isApplication && route.callbacks[0]?.constructor.name === "Application") {
+    if (walk.router._isApplication && route.callbacks[0]?._isApplication) {
         (req._appStack ??= []).push(route, req.app);
     }
 }
@@ -2536,6 +2541,24 @@ module.exports = class Router extends EventEmitter {
         });
     }
 
+    /**
+     * The same walk without the promise pair, for a uWS handler that never awaited it. nativeDone
+     * and nativeFail defer their epilogues to the microtask the await used to resume on, so the
+     * visible order holds.
+     *
+     * @param {any} req
+     * @param {any} res
+     */
+    _routeRequestDirect(req, res) {
+        const walk = new Walk(this, req, res, this._routes, false, undefined, nativeDone, nativeFail);
+        try {
+            walk.dispatch(0);
+        } catch (err) {
+            // what a throw inside a promise executor did: reject, once
+            nativeFail.call(walk, err);
+        }
+    }
+
     /**
      * Mounts middleware, or a whole router, at a path. The path is optional, and a mount matches
      * everything under it, which is what separates it from all(). Mounting a Router sets its

package/src/types.d.ts

@@ -17,6 +17,7 @@ limitations under the License.
 declare module "fulmine.js" {
     import e from "express";
     import uWS from "uWebSockets.js";
+    import { ZlibOptions, BrotliOptions } from "zlib";
 
     type Settings = {
         uwsOptions?: uWS.AppOptions;
@@ -37,6 +38,24 @@ declare module "fulmine.js" {
         export import static = e.static;
         // export import query = e.query;
 
+        // express has no compression middleware, so there is nothing to re-export: these are the
+        // compression module's options, which this one takes as they are
+        interface CompressionOptions extends ZlibOptions {
+            /** The smallest body worth compressing, in bytes or as "1kb". Default 1024. */
+            threshold?: number | string;
+            /** Whether this response should be compressed at all. */
+            filter?: (req: e.Request, res: e.Response) => boolean;
+            /** What to use when the request carries no Accept-Encoding. Default "identity". */
+            enforceEncoding?: string;
+            /** Brotli options. The default quality is 4. */
+            brotli?: BrotliOptions;
+        }
+        export function compression(options?: CompressionOptions): e.RequestHandler;
+        export namespace compression {
+            /** The default filter: any compressible content type. */
+            function filter(req: e.Request, res: e.Response): boolean;
+        }
+
         export import urlencoded = e.urlencoded;
 
         export import RouterOptions = e.RouterOptions;

package/src/utils.js

@@ -788,6 +788,113 @@ function stringify(value, replacer, spaces, escape) {
     return json;
 }
 
+// What negotiateEncoding may answer with, since a caller can only offer what it can produce
+const ENCODING_BR = 1;
+const ENCODING_GZIP = 2;
+const ENCODING_DEFLATE = 4;
+const ENCODING_ANY = ENCODING_BR | ENCODING_GZIP | ENCODING_DEFLATE;
+
+/**
+ * The encoding to answer with, read straight off Accept-Encoding rather than through negotiator:
+ * the header is a short list of names with an optional q, and building a Negotiator per response
+ * to read it costs more than the scan does.
+ *
+ * The tie-break is negotiator's, for the list the compression module hands it: brotli first, then
+ * gzip, then deflate, and identity last.
+ *
+ * Only the encodings named in `allowed` are on offer, since the caller may not be able to
+ * produce all three: express.static offers the two it can have lying on disk. An uncompressed
+ * answer is always on offer, and is what an empty header ends up choosing.
+ *
+ * @param {string} accept the header, or "" when the request carried none
+ * @param {number} allowed ENCODING_BR, ENCODING_GZIP and ENCODING_DEFLATE, or'd together
+ * @returns {string} "br", "gzip", "deflate", "identity", or "" when nothing is acceptable
+ */
+function negotiateEncoding(accept, allowed) {
+    // -1 while a name has not appeared: q=0 is a refusal and has to be told apart from silence
+    let br = -1;
+    let gzip = -1;
+    let deflate = -1;
+    let identity = -1;
+    let star = -1;
+    // the lowest q anything was named with, which is what an unnamed identity is worth, see below
+    let minQuality = 1;
+    let index = 0;
+    while (index < accept.length) {
+        let end = accept.indexOf(",", index);
+        if (end === -1) {
+            end = accept.length;
+        }
+        let semi = accept.indexOf(";", index);
+        if (semi === -1 || semi > end) {
+            semi = end;
+        }
+        const name = accept.slice(index, semi).trim().toLowerCase();
+        let q = 1;
+        if (semi < end) {
+            const params = accept.slice(semi + 1, end);
+            const at = params.indexOf("q=");
+            if (at !== -1) {
+                const parsed = parseFloat(params.slice(at + 2));
+                // a q nobody can read is a refusal, which is how negotiator reads it too
+                q = parsed === parsed ? parsed : 0;
+            }
+        }
+        if (q < minQuality) {
+            minQuality = q;
+        }
+        switch (name) {
+            case "br":
+                br = q;
+                break;
+            case "gzip":
+                gzip = q;
+                break;
+            case "deflate":
+                deflate = q;
+                break;
+            case "identity":
+                identity = q;
+                break;
+            case "*":
+                star = q;
+                break;
+        }
+        index = end + 1;
+    }
+    if (br < 0) br = star;
+    if (gzip < 0) gzip = star;
+    if (deflate < 0) deflate = star;
+    // An uncompressed answer that the request did not name is worth the lowest q it named
+    // anything with, which is negotiator's rule and not the obvious one: "br;q=0.5, gzip;q=0.9"
+    // means gzip, because identity comes in at 0.5 rather than at 1 and does not win the list.
+    // A "*" names identity as much as it names anything else, so its q is identity's.
+    if (identity < 0) identity = star < 0 ? minQuality : star;
+
+    if (!(allowed & ENCODING_BR)) br = -1;
+    if (!(allowed & ENCODING_GZIP)) gzip = -1;
+    if (!(allowed & ENCODING_DEFLATE)) deflate = -1;
+
+    let best = "";
+    let bestQ = 0;
+    if (br > bestQ) {
+        best = "br";
+        bestQ = br;
+    }
+    if (gzip > bestQ) {
+        best = "gzip";
+        bestQ = gzip;
+    }
+    if (deflate > bestQ) {
+        best = "deflate";
+        bestQ = deflate;
+    }
+    if (identity > bestQ) {
+        best = "identity";
+    }
+    return best;
+}
+
 const defaultSettings = {
     "jsonp callback name": "callback",
     env: () => process.env.NODE_ENV ?? "development",
@@ -1102,6 +1209,11 @@ function createETagGenerator(options) {
         if (body instanceof Stats) {
             return statTag(body, options.weak);
         }
+        // crypto.hash reads a string as the utf8 bytes Buffer.from would have produced, so the tag
+        // is the same one without copying the whole body first
+        if (typeof body === "string" && (encoding === undefined || encoding === "utf8" || encoding === "utf-8")) {
+            return entityTag(body, options.weak);
+        }
         const buf = !Buffer.isBuffer(body) ? Buffer.from(body, encoding) : body;
         return entityTag(buf, options.weak);
     };
@@ -1300,6 +1412,10 @@ module.exports = {
     entityTag,
     statTag,
     contentTypeFor,
+    negotiateEncoding,
+    ENCODING_BR,
+    ENCODING_GZIP,
+    ENCODING_ANY,
     memoizeByString,
     isRangeFresh,
     findIndexStartingFrom,