fulmine.js 5.12.1 → 5.12.2

package/README.md

@@ -285,6 +285,7 @@ A single-stage `node:26-trixie-slim` image works too if you `apt-get install -y
 - `app.listen()` returns the app rather than a separate server object, and the app answers as an `http.Server`: `app instanceof http.Server` is true, which is what the graceful shutdown wrappers and the connection trackers look for. There is still no node server underneath, the socket belongs to µWS, so what is answered is the surface and not the plumbing. There: `close()`, `address()`, `listening`, `getConnections()`, `ref()`, `unref()`, `setTimeout()` and the `keepAliveTimeout` family. Not there: nothing emits `connection`, `request` or `upgrade`, `getConnections()` counts the requests in flight rather than sockets, and the timeouts belong to µWS and are set through `uwsOptions.idleTimeout`. Anything that wants to serve its own protocol on the socket, socket.io being the usual case, still wants `app.uwsApp`. Runnable: [`examples/graceful-shutdown.js`](./examples/graceful-shutdown.js).
 - `x-powered-by` is disabled by default. Express sends `X-Powered-By: Express` unless you turn it off; Fulmine does not send it unless you turn it on with `app.set("x-powered-by", true)`. The header only tells anyone asking which framework is running.
 - request body is only read for POST, PUT, PATCH and QUERY requests by default. You can add additional methods by setting `body methods` to array with uppercased methods.
+- **A request whose `Content-Length` cannot be trusted is refused by hanging up, with no answer at all.** Node's parser refuses two of these with a `400` and Fulmine refuses the same two: a repeated `Content-Length`, whatever the values say, and one that is not a plain count of bytes, an empty value included. µWS accepts both and frames the request on the first value, or on no body at all, so what the client sent as a body is read as the next request on the connection: that is request smuggling, and a proxy in front reading the other value is all it takes. The answer differs from Express because it cannot be helped. µWS only skips the request it has already queued when the response is closed rather than completed, and writing the `400` completes it, so the choice is between telling the client and stopping the smuggled request. Nothing well behaved sends two content-lengths.
 - **A compiled route answers `connection: keep-alive` to a client that sent `Connection: close`.** A handler simple enough to be read at registration time is answered by µWS from a response written once at `listen()`, and that response cannot read the request. The socket still closes, so what is wrong is the header and not the transport. A response that would carry a validator is never compiled, so conditional requests behave as on Express; `app.set("declarative responses", false)` turns compiling off.
 - **Informational responses go nowhere.** `res.writeEarlyHints()`, `res.writeContinue()` and `res.writeProcessing()` are all there, take what node's take and throw what node's throw once the head has gone out, but nothing reaches the wire: µWebSockets.js has no API for a `1xx`. They exist so that code written for Express keeps running rather than dying on "is not a function", which is the only thing a drop-in can honestly promise here. `res.addTrailers()` is the same story, and `res.setTimeout()` and `req.setTimeout()` register the listener without changing anything, since µWS runs its own idle timeout through `uwsOptions.idleTimeout`.
 - For HTTPS, instead of doing this:

package/package.json

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

package/src/router.js

@@ -241,7 +241,18 @@ class Walk {
             // was one closure per hop of every request not on a compiled chain
             for (; routeIndex < routes.length; routeIndex++) {
                 const r = routes[routeIndex];
-                if (!(r.all || r.method === req.method || req._isOptions || (r.gettable && req._isHead))) {
+                // A HEAD request enters a route whose path matched even when its verb cannot serve
+                // one: express exempts HEAD from the method check ("if (!hasMethod && method !==
+                // 'HEAD')" in router/index.js), so the layer's parameters are captured and its
+                // param() callbacks run before the route is dropped. Only asked when the router has
+                // callbacks to run, since entering a route to step straight back out of it is
+                // otherwise pure cost with nothing to show for it. runRoute steps over it.
+                if (!(
+                    r.all ||
+                    r.method === req.method ||
+                    req._isOptions ||
+                    (req._isHead && (r.gettable || r.paramCallbacks.size > 0))
+                )) {
                     // taken only to fail: _preprocessRequest decodes again and turns it into the
                     // error, so the handlers of a route this request cannot run never see it
                     if (mayFailDecode && router._pathMatches(r, req) && router._paramsFailToDecode(r, req)) {
@@ -514,20 +525,20 @@ class Walk {
                     if (parentMethods !== null) {
                         req._matchedMethods = parentMethods;
                     }
-                    if (req._isOptions && childMethods.size) {
+                    if (req._isOptions && childMethods.size && !req._error) {
                         // OPTIONS routing is different, it stops in the router if matched.
                         // Express answers as the router hands back, so a throw while answering,
                         // a head already written being the way, walks on to later error handlers
-                        if (!req._error) {
-                            try {
-                                router._sendOptionsReply(req, res, childMethods);
-                                return this.resolve(true);
-                            } catch (err) {
-                                return this.step(err);
-                            }
+                        try {
+                            router._sendOptionsReply(req, res, childMethods);
+                            return this.resolve(true);
+                        } catch (err) {
+                            return this.step(err);
                         }
-                        return this.resolve(false);
                     }
+                    // An error carried out of the mount is not answered by the automatic reply, and
+                    // stopping here handed it to the default page: express walks on to the error
+                    // handlers written after the mount, for OPTIONS as for any other method.
                     this.step(undefined);
                 })
                 // a rejection out of the nested walk, or a throw above, must reject this one
@@ -550,6 +561,11 @@ class Walk {
                     }
                     return this.step(undefined);
                 }
+                // entered only so its param callbacks could run, see the scan in dispatch: the verb
+                // cannot serve a HEAD, so nothing here answers it
+                if (req._isHead && !route.all && !route.gettable && route.method !== "HEAD") {
+                    return this.step(undefined);
+                }
 
                 const out = callback(req, res, this.next);
                 if (out instanceof Promise) {
@@ -671,6 +687,42 @@ function setMountedPath(req) {
     req._lastUrl = req.url;
 }
 
+const NO_PARAM_NAMES = [];
+
+/**
+ * The parameter names a route captures with its own pattern.
+ *
+ * This is the set express runs param callbacks for. A name that reached req.params from a mount
+ * above, through mergeParams, belongs to that mount's router and not to this one, and express does
+ * not call this router's param() for it: it walks the keys the layer itself matched. Reading
+ * req.params instead ran a callback for every inherited name too, which is visible whenever such a
+ * callback does anything, and turned a 200 into a 500 when one of them refused the value.
+ *
+ * Worked out once per route and kept, since it follows from the pattern and never changes.
+ *
+ * @param {any} route
+ * @returns {string[]}
+ */
+function ownParamNames(route) {
+    let names = route._ownParamNames;
+    if (names !== undefined) {
+        return names;
+    }
+    if (route.optimizedParams) {
+        // µWS matched the pattern and hands the values back by position, under these names
+        names = route.optimizedParams;
+    } else if (route.pattern instanceof RegExp) {
+        const meta = getPatternMeta(route.pattern);
+        // outputNames is what _extractParams writes into params; a RegExp the application wrote
+        // itself was never compiled here, so its capture groups are the names
+        names = meta ? meta.outputNames : regexpGroupKeys(route.pattern);
+    } else {
+        names = NO_PARAM_NAMES;
+    }
+    route._ownParamNames = names;
+    return names;
+}
+
 /**
  * Whether this route reads the parameters of the mounts above it, which is its own router asking
  * for them. The stack holds what a mergeParams router captured on the way in, and a plain router
@@ -2514,8 +2566,14 @@ module.exports = class Router extends EventEmitter {
 
         // the route's own router's callbacks: an optimized chain is walked by the app even when it
         // ends in a mounted router's route
+        //
+        // A route an OPTIONS request reaches only to have its verb counted for the automatic reply
+        // is not a route this request runs, and express does not run its app.param() callbacks for
+        // it. The same condition runRoute counts the verb under, see the OPTIONS branch there. The
+        // decoding above still happens either way, because express decodes a layer whose path
+        // matched whatever its method is, which is what answers 400 for a malformed escape.
         const paramCallbacks = route.paramCallbacks;
-        if (paramCallbacks.size > 0) {
+        if (paramCallbacks.size > 0 && !(req._isOptions && !route.all && route.method !== "OPTIONS")) {
             return this._runParamCallbacks(req, res, route, paramCallbacks);
         }
         return true;
@@ -2558,9 +2616,14 @@ module.exports = class Router extends EventEmitter {
      * @returns {Promise<true|"route">|true}
      */
     _runParamCallbacks(req, res, route, paramCallbacks) {
+        // the names this route captured itself, not everything in req.params: a merged-in name
+        // belongs to the mount that captured it, see ownParamNames
         let names;
-        for (const name in req.params) {
-            if (paramCallbacks.has(name)) {
+        const own = ownParamNames(route);
+        for (let i = 0; i < own.length; i++) {
+            const name = own[i];
+            // an optional group that did not match leaves no parameter to call anything for
+            if (paramCallbacks.has(name) && req.params[name] !== undefined) {
                 (names ??= []).push(name);
             }
         }

package/src/utils.js

@@ -596,13 +596,23 @@ function canBeOptimizedWithParams(pattern) {
     return true;
 }
 
+// What makes a segment something other than the text it is written as: a parameter, a wildcard, an
+// optional group, or an escape. Only two plain literals can prove that two paths never meet, so
+// anything carrying one of these has to be read as "could be anything".
+const NOT_A_LITERAL = /[:*{}\\]/;
+
 /**
  * Whether two paths could both match the same request.
  *
- * Only asked about paths µWS could match itself, so the answer is structural: the same number of
- * segments, and no position where two different literals meet. `/orders/:id` and `/invoices/:id`
- * cannot both match, `/users/:id` and `/users/me` can. Anything else is not asked, and the caller
- * reads "do not know" as yes.
+ * The answer is structural: no position where two different literals meet, and, when neither path
+ * can change length, the same number of segments. `/orders/:id` and `/invoices/:id` cannot both
+ * match, `/users/:id` and `/users/me` can. The caller reads "do not know" as yes, so every doubt
+ * answers true: saying two paths overlap only costs a native registration, while missing one lets
+ * µWS answer a request that belonged to an earlier route.
+ *
+ * A parameter is not the only shape that matches more than itself. A wildcard and an optional group
+ * do too, and reading `{:opt}` or `*splat` as the literal text it is written as reported "cannot
+ * overlap" for a route that plainly could, which took the earlier route's turn away.
  *
  * @param {string} a
  * @param {string} b
@@ -612,15 +622,19 @@ function canBeOptimizedWithParams(pattern) {
 function pathsCanOverlap(a, b, aIsPrefix = false) {
     const left = a.split("/");
     const right = b.split("/");
-    if (aIsPrefix ? left.length > right.length : left.length !== right.length) {
+    // An optional group matches its segment or nothing at all and a wildcard matches several, so a
+    // path carrying either one matches more than one length and the count settles nothing.
+    const fixedLength =
+        a.indexOf("{") === -1 && b.indexOf("{") === -1 && a.indexOf("*") === -1 && b.indexOf("*") === -1;
+    if (fixedLength && (aIsPrefix ? left.length > right.length : left.length !== right.length)) {
         return false;
     }
-    for (let i = 0; i < left.length; i++) {
+    const shared = left.length < right.length ? left.length : right.length;
+    for (let i = 0; i < shared; i++) {
         if (left[i] === right[i]) {
             continue;
         }
-        // a parameter matches whatever is in that segment, so only two different literals settle it
-        if (left[i].charCodeAt(0) === 0x3a || right[i].charCodeAt(0) === 0x3a) {
+        if (NOT_A_LITERAL.test(left[i]) || NOT_A_LITERAL.test(right[i])) {
             continue;
         }
         return false;
@@ -1436,6 +1450,32 @@ function withUtf8Charset(value) {
 const HEADER_TOKEN = /^[\^_`a-zA-Z\-0-9!#$%&'*+.|~]+$/;
 const HEADER_VALUE = /[^\t\x20-\x7e\x80-\xff]/;
 
+/**
+ * One of node's header errors, built the way node builds it.
+ *
+ * Assigning the code is not the whole of it. Node also puts the code in the first line of the
+ * stack, by naming the error "TypeError [THE_CODE]" while V8 formats that line and then taking
+ * the name back off. Whatever prints a stack therefore says which code it was, and the default
+ * error page prints exactly that: without this, the same refusal reads "TypeError:" here and
+ * "TypeError [ERR_INVALID_CHAR]:" behind Express. Found by fuzzing against express.
+ *
+ * @param {string} message
+ * @param {string} code
+ * @returns {NodeJS.ErrnoException}
+ */
+function headerError(message, code) {
+    /** @type {NodeJS.ErrnoException} */
+    const err = new TypeError(message);
+    err.name = `TypeError [${code}]`;
+    // reading it is what makes V8 format the line, and it formats it from the name above
+    void err.stack;
+    // back to the prototype's "TypeError", which is what node leaves behind. Cast because Error
+    // declares name as always present, and this deletes the own property to uncover it again
+    delete (/** @type {any} */ (err).name);
+    err.code = code;
+    return err;
+}
+
 /**
  * Refuses a header name that is not an HTTP token, the way node's setHeader does and with its
  * error, so an application catching ERR_INVALID_HTTP_TOKEN behind Express catches it here.
@@ -1446,10 +1486,7 @@ const HEADER_VALUE = /[^\t\x20-\x7e\x80-\xff]/;
  */
 function validateHeaderName(name) {
     if (typeof name !== "string" || !HEADER_TOKEN.test(name)) {
-        /** @type {NodeJS.ErrnoException} */
-        const err = new TypeError(`Header name must be a valid HTTP token ["${name}"]`);
-        err.code = "ERR_INVALID_HTTP_TOKEN";
-        throw err;
+        throw headerError(`Header name must be a valid HTTP token ["${name}"]`, "ERR_INVALID_HTTP_TOKEN");
     }
 }
 
@@ -1471,10 +1508,7 @@ function validateHeaderValue(name, value) {
         return;
     }
     if (HEADER_VALUE.test(value)) {
-        /** @type {NodeJS.ErrnoException} */
-        const err = new TypeError(`Invalid character in header content ["${name}"]`);
-        err.code = "ERR_INVALID_CHAR";
-        throw err;
+        throw headerError(`Invalid character in header content ["${name}"]`, "ERR_INVALID_CHAR");
     }
 }