fulmine.js 5.21.2 → 5.21.4

package/src/optimizer.js

@@ -20,6 +20,8 @@ limitations under the License.
 /** @typedef {import("./router.js")} Router */
 /** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
 /** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("uWebSockets.js").HttpRequest} UwsRequest */
+/** @typedef {import("uWebSockets.js").HttpResponse} UwsResponse */
 
 const {
     patternToRegex,
@@ -44,6 +46,7 @@ const {
     hasErrorMiddleware,
     couldAnswer,
     shadowsLeaf,
+    headEntersGuard,
     guardsInside,
     supportedUwsMethods,
     regExParam
@@ -79,6 +82,8 @@ function optimizeRoute(router, route, routes) {
     const strictHere = (route.owner ?? router)._strictRouting();
     /** @type {string[]|null} earlier literals a case variant could smuggle a request past */
     let caseGuards = null;
+    // whether the HEAD twin has to stay generic, see headEnters
+    let headGeneric = false;
 
     for (let i = 0; i < routes.length; i++) {
         const r = routes[i];
@@ -95,6 +100,12 @@ function optimizeRoute(router, route, routes) {
                 if (route.use && typeof route.path === "string" && couldAnswer(r, route.path)) {
                     return false;
                 }
+                // Express exempts HEAD from the method check: a HEAD enters a matching route of
+                // any verb and its param() callbacks run, as the generic walk does. The chain
+                // cannot say whether such a route matches, so the HEAD twin stays generic
+                if (route.method === "GET" && headEnters(r, route, caseSensitive, strictHere)) {
+                    headGeneric = true;
+                }
                 continue;
             }
         }
@@ -115,7 +126,7 @@ function optimizeRoute(router, route, routes) {
                 route.path.slice(0, matched[0].length) === matched[0] &&
                 (route.path.length === matched[0].length || route.path[matched[0].length] === "/");
             if (runsAlways) {
-                if (r.callbacks.some((c) => c instanceof Router)) {
+                if (r.callbacks.some((/** @type {unknown} */ c) => c instanceof Router)) {
                     return false;
                 }
                 optimizedPath.push(r);
@@ -137,7 +148,7 @@ function optimizeRoute(router, route, routes) {
                     (!caseSensitive && r.pattern.toLowerCase() === routePathFolded) ||
                     r.pattern === "/*"))
         ) {
-            if (r.callbacks.some((c) => c instanceof Router)) {
+            if (r.callbacks.some((/** @type {unknown} */ c) => c instanceof Router)) {
                 return false;
             }
             optimizedPath.push(r);
@@ -164,7 +175,7 @@ function optimizeRoute(router, route, routes) {
         }
         // the same path lands on the same µWS registration, so the earlier route runs from the chain
         if (rPathFolded === routePathFolded) {
-            if (r.callbacks.some((c) => c instanceof Router)) {
+            if (r.callbacks.some((/** @type {unknown} */ c) => c instanceof Router)) {
                 return false;
             }
             optimizedPath.push(r);
@@ -186,10 +197,45 @@ function optimizeRoute(router, route, routes) {
     }
     optimizedPath.push(route);
     route._caseGuards = caseGuards;
+    route._headGeneric = headGeneric;
 
     return optimizedPath;
 }
 
+/**
+ * Whether a HEAD of some path this GET route answers would enter the earlier route of another
+ * verb for its param() callbacks: the router has callbacks and the paths can meet. A wrong yes
+ * costs the HEAD twin its native registration and nothing else.
+ *
+ * @param {RouteEntry} r the earlier route, of another verb
+ * @param {RouteEntry} route the GET route
+ * @param {boolean} caseSensitive
+ * @param {boolean} strictHere
+ * @returns {boolean}
+ */
+function headEnters(r, route, caseSensitive, strictHere) {
+    if (r.paramCallbacks.size === 0 || typeof route.path !== "string") {
+        return false;
+    }
+    if (!route.path.includes(":")) {
+        if (typeof r.pattern === "string") {
+            return (
+                r.pattern === "/*" ||
+                (caseSensitive ? r.pattern === route.path : r.patternLower === route.path.toLowerCase())
+            );
+        }
+        return r.pattern.test(route.path) || (!strictHere && r.pattern.test(route.path + "/"));
+    }
+    if (typeof r.path !== "string" || !canBeOptimizedWithParams(r.path)) {
+        return true;
+    }
+    return pathsCanOverlap(
+        caseSensitive ? r.path : r.path.toLowerCase(),
+        caseSensitive ? route.path : route.path.toLowerCase(),
+        r.use
+    );
+}
+
 /**
  * Hands every route reachable by path alone to the native uWS router, walking into mounted
  * routers with their prefix. Runs once, at listen.
@@ -284,6 +330,16 @@ function compileOptimizedRoutes(root) {
                     route._whyGeneric = "something before it in the same router overlaps its paths";
                     continue;
                 }
+                // a route of another verb before the mount that a HEAD would enter, see headEnters
+                if (
+                    !route._headGeneric &&
+                    route.method === "GET" &&
+                    outerGuards.length > 0 &&
+                    typeof route.path === "string" &&
+                    outerGuards.some((g) => headEntersGuard(g, pathPrefix + route.path))
+                ) {
+                    route._headGeneric = true;
+                }
                 // an earlier parameter route in the same router would take this literal path
                 if (leafPath.length > 1) {
                     const shadow = leafPath[leafPath.length - 2];
@@ -360,6 +416,7 @@ function registerUwsRoute(router, route, optimizedPath) {
      * @param {import("./router-utils.js").NativePreset|undefined} preset
      * @param {{skipHeaders: boolean, skipQuery: boolean}} skips
      * @param {string|null} wireMethod
+     * @returns {(res: UwsResponse, req: UwsRequest) => unknown} what µWS calls
      */
     const makeHandler = (chain, preset, skips, wireMethod) => {
         // where a granted skip lives, so a middleware added after listen can take it back: the
@@ -395,10 +452,11 @@ function registerUwsRoute(router, route, optimizedPath) {
                 return router._refuseRequest(response);
             }
             if (optimizedParams) {
-                // slicing them out of the path instead measured a wash
+                // slicing them out of the path instead measured a wash. The index is one the
+                // registered path declares, so the value is never undefined
                 request.optimizedParams = new NullObject();
                 for (let i = 0; i < optimizedParams.length; i++) {
-                    request.optimizedParams[optimizedParams[i]] = req.getParameter(i);
+                    request.optimizedParams[optimizedParams[i]] = /** @type {string} */ (req.getParameter(i));
                 }
             }
             const walk = new Walk(router, request, response, chain, true, skipUntil, nativeDone, nativeFail);
@@ -513,7 +571,7 @@ function registerUwsRoute(router, route, optimizedPath) {
                   ? makeHandler(getChain, makePreset(route.path + "/", route.method, getSkips), getSkips, wireMethod)
                   : fn;
         router.uwsApp[method](replacedPath + "/", slashFn);
-        if (method === "get") {
+        if (method === "get" && !route._headGeneric) {
             router.uwsApp.head(
                 replacedPath + "/",
                 makeHandler(
@@ -525,7 +583,7 @@ function registerUwsRoute(router, route, optimizedPath) {
             );
         }
     }
-    if (method === "get") {
+    if (method === "get" && !route._headGeneric) {
         // its own handler, the shared one would carry GET
         router.uwsApp.head(
             replacedPath,

package/src/options.d.ts

@@ -43,7 +43,7 @@ export interface SendFileOptions {
     /** Extra headers for the response. */
     headers?: Record<string, string>;
     /** Internal: express.static's setHeaders, which res.sendFile itself does not take. */
-    _setHeaders?: (res: any, path: string, stat: any) => void;
+    _setHeaders?: ((res: any, path: string, stat: any) => void) | undefined;
     /** First byte of the window to send. */
     start?: number;
     /** Last byte of the window to send. */

package/src/request.js

@@ -43,6 +43,7 @@ const {
 
 // whose headers #collectHeader is filling: uWS's forEach is synchronous, so one callback serves
 // every request
+/** @type {import("./request.js")|null} */
 let currentRequest = null;
 
 module.exports = class Request extends LazyReadable {
@@ -83,6 +84,12 @@ module.exports = class Request extends LazyReadable {
     /** @type {string[]|null} */
     #cachedSubdomains = null;
 
+    /** The socket stand-in `req.connection` once built, see the getter. @type {import("./socket.js")|null} */
+    #cachedConnection = null;
+
+    /** Behind `req.signal`, made on the first read. @type {AbortController|undefined} */
+    #abortController;
+
     /**
      * Copies one header out of uWS and notices what the constructor decides by. One function for
      * every request through currentRequest, an arrow per request cost a closure.
@@ -91,7 +98,8 @@ module.exports = class Request extends LazyReadable {
      * @param {string} value
      */
     static #collectHeader = (headerKey, value) => {
-        const r = currentRequest;
+        // set by the two forEach callers, never null while uWS is calling back
+        const r = /** @type {Request} */ (currentRequest);
         r.#rawHeadersEntries.push(headerKey, value);
         // the response, built right after, must not answer keep-alive to a client that said close
         if (headerKey.length === 10 && headerKey === "connection" && saysClose(value)) {
@@ -321,7 +329,10 @@ module.exports = class Request extends LazyReadable {
     /** The verbs a path answers, for an OPTIONS; null on every other method. @type {Set<string>|null} */
     _matchedMethods = null;
 
-    /** What each app.param() callback was called with, per router, made on first use. @type {Map<any, Map<any, any>>|null} */
+    /**
+     * What each app.param() callback was called with, per router, made on first use.
+     * @type {Map<Map<string, Function[]>, Map<string, import("./router.js").ParamCall>>|null}
+     */
     _paramCalled = null;
 
     /**
@@ -573,9 +584,6 @@ module.exports = class Request extends LazyReadable {
         return this.res?.finished || this.res?.aborted;
     }
 
-    /** @type {AbortController|undefined} */
-    #abortController;
-
     /**
      * node's `req.signal`, fired when the request is over: `@angular/ssr` reads it to give up a
      * render. Made on the first ask.
@@ -630,7 +638,10 @@ module.exports = class Request extends LazyReadable {
         return this;
     }
 
-    /** Readable's pull: uWS pushes, so this only lifts the backpressure a full queue put on it. */
+    /**
+     * Readable's pull: uWS pushes, so this only lifts the backpressure a full queue put on it.
+     * @override
+     */
     _read() {
         // first, so a bodyless stream still ends for a consumer arriving after the response
         if (this.#emptyBody) {
@@ -1011,9 +1022,6 @@ module.exports = class Request extends LazyReadable {
         return ip;
     }
 
-    /** @type {import("./socket.js")|null} */
-    #cachedConnection = null;
-
     /**
      * The socket stand-in, the same object as `res.socket`, kept here so it still answers once
      * the response is over and `res.socket` is null.
@@ -1214,8 +1222,8 @@ module.exports = class Request extends LazyReadable {
      *
      * @param {number} size length of the resource being served
      * @param {{combine?: boolean}} [options] combine adjacent and overlapping ranges
-     * @returns {Array|number|undefined} the ranges, -1 when unsatisfiable, -2 when malformed,
-     *   or undefined when there is no Range header
+     * @returns {import("range-parser").Ranges|-1|-2|undefined} the ranges, -1 when unsatisfiable,
+     *   -2 when malformed, or undefined when there is no Range header
      */
     range(size, options) {
         const range = this.headers["range"];
@@ -1302,10 +1310,8 @@ module.exports = class Request extends LazyReadable {
         return this.#rawHeadersEntries.slice();
     }
 
-    // the three below report work this request was made to do, for src/work.js
-
     /**
-     * Whether the folded `req.headers` object was built.
+     * Whether the folded `req.headers` object was built, which src/work.js reports.
      * @returns {boolean}
      */
     get _headersBuilt() {
@@ -1313,7 +1319,7 @@ module.exports = class Request extends LazyReadable {
     }
 
     /**
-     * Whether the query string was parsed at least once.
+     * Whether the query string was parsed at least once, which src/work.js reports.
      * @returns {boolean}
      */
     get _queryParsed() {
@@ -1321,7 +1327,7 @@ module.exports = class Request extends LazyReadable {
     }
 
     /**
-     * Whether the socket stand-in `req.connection` was allocated.
+     * Whether the socket stand-in `req.connection` was allocated, which src/work.js reports.
      * @returns {boolean}
      */
     get _socketBuilt() {

package/src/response-utils.js

@@ -38,9 +38,12 @@ const kShapeMode =
 const VALIDATED_HEADER_NAMES = new Map();
 // The names and values that recur on every response, kept as Buffers for the uWS crossing: a Buffer
 // is memcpy'd as it is, a string pays a UTF-8 scan and copy per call. A header that is not here
-// crosses as the string it was. Names must stay lowercase, as writeHeaders receives them.
-const HEADER_NAME_BUF = { __proto__: null };
-const HEADER_VALUE_BUF = { __proto__: null };
+// crosses as the string it was. Names must stay lowercase, as writeHeaders receives them. The
+// casts are for the __proto__ key, which the type checker reads as a property
+/** @type {Record<string, Buffer>} */
+const HEADER_NAME_BUF = /** @type {any} */ ({ __proto__: null });
+/** @type {Record<string, Buffer>} */
+const HEADER_VALUE_BUF = /** @type {any} */ ({ __proto__: null });
 for (const s of ["connection", "keep-alive", "content-type", "vary", "x-powered-by", "content-encoding"]) {
     HEADER_NAME_BUF[s] = Buffer.from(s);
 }
@@ -81,11 +84,45 @@ function statusLine(code, text) {
     return `${code} ${text ?? statuses.message[code] ?? "unknown"}`.trim();
 }
 
+/**
+ * The TypeError node throws for a chunk that is not a string, a Buffer or a Uint8Array, worded as
+ * node words it.
+ *
+ * @param {unknown} chunk what end() was handed, known here not to be a string or a Uint8Array
+ * @returns {NodeJS.ErrnoException}
+ */
+function invalidChunkError(chunk) {
+    let received;
+    if (chunk === null) {
+        received = "null";
+    } else if (typeof chunk === "object" || typeof chunk === "function") {
+        const name = /** @type {any} */ (chunk).constructor?.name;
+        received = name ? `an instance of ${name}` : "an instance of Object";
+    } else if (typeof chunk === "bigint") {
+        received = `type bigint (${chunk}n)`;
+    } else if (typeof chunk === "symbol") {
+        received = `type symbol (${String(chunk)})`;
+    } else {
+        received = `type ${typeof chunk} (${chunk})`;
+    }
+    /** @type {NodeJS.ErrnoException} */
+    const err = new TypeError(
+        `The "chunk" argument must be of type string or an instance of Buffer or Uint8Array. Received ${received}`
+    );
+    err.code = "ERR_INVALID_ARG_TYPE";
+    // as node: the bracketed name goes into the stack's first line, then err.name reads TypeError
+    err.name = "TypeError [ERR_INVALID_ARG_TYPE]";
+    void err.stack;
+    delete (/** @type {Record<string, unknown>} */ (/** @type {unknown} */ (err)).name);
+    return err;
+}
+
 module.exports = {
     kOutHeaders,
     kShapeMode,
     VALIDATED_HEADER_NAMES,
     HEADER_NAME_BUF,
     HEADER_VALUE_BUF,
-    statusLine
+    statusLine,
+    invalidChunkError
 };