fulmine.js 5.19.2 → 5.19.4

package/src/request.js

@@ -22,414 +22,32 @@ const accepts = require("accepts");
 const typeis = require("type-is");
 const parseRange = require("range-parser");
 const proxyaddr = require("proxy-addr");
-const { isIP } = require("node:net");
 const fresh = require("fresh");
 const parseQuery = require("./parse-query.js");
-const { Readable } = require("stream");
-
-// accepts, type-is, proxy-addr and fresh all declare a node IncomingMessage and read nothing off
-// it but .headers. This request is deliberately not one, so it is handed over as itself and the
-// declared shape is stepped around at each call.
-const asMessage = (req) => /** @type {any} */ (req);
-
-/**
- * Writes an address the way node writes socket.remoteAddress, which is inet_ntop's output and so
- * RFC 5952: leading zeros dropped from each group, the longest run of two or more zero groups
- * written as "::", and the last four bytes written in dotted form for the addresses that carry an
- * IPv4 one. uWS hands over the sixteen bytes, and writing them out in full gave req.ip
- * "0000:0000:0000:0000:0000:0000:0000:0001" where Express says "::1".
- *
- * @param {number[]} groups the eight 16-bit groups, most significant first
- * @returns {string}
- */
-function formatIPv6(groups) {
-    // longest run of zero groups, leftmost on a tie, which is the run inet_ntop replaces
-    let bestStart = -1;
-    let bestLength = 0;
-    for (let i = 0; i < 8; i++) {
-        if (groups[i] !== 0) continue;
-        let run = 1;
-        while (i + run < 8 && groups[i + run] === 0) run++;
-        if (run > bestLength) {
-            bestStart = i;
-            bestLength = run;
-        }
-        i += run - 1;
-    }
-    // a single zero group is written as "0", not as "::"
-    if (bestLength < 2) {
-        bestStart = -1;
-        bestLength = 0;
-    }
-
-    // ::ffff:a.b.c.d, and the deprecated ::a.b.c.d. The test is inet_ntop's own, including that a
-    // run of seven leading zeros never reaches it, since group 6 is inside the run by then.
-    const mixed =
-        bestStart === 0 &&
-        (bestLength === 6 || (bestLength === 7 && groups[7] !== 1) || (bestLength === 5 && groups[5] === 0xffff));
-
-    let out = "";
-    for (let i = 0; i < 8; i++) {
-        if (bestStart !== -1 && i >= bestStart && i < bestStart + bestLength) {
-            if (i === bestStart) out += ":";
-            continue;
-        }
-        if (i !== 0) out += ":";
-        if (mixed && i === 6) {
-            out += `${groups[6] >> 8}.${groups[6] & 0xff}.${groups[7] >> 8}.${groups[7] & 0xff}`;
-            break;
-        }
-        out += groups[i].toString(16);
-    }
-    // a run reaching the end leaves a trailing group to close the "::"
-    if (bestStart !== -1 && bestStart + bestLength === 8) out += ":";
-    return out;
-}
-
-/**
- * Whether these sixteen bytes are an IPv4-mapped address, ::ffff:0:0/96: ten zero bytes and then
- * 0xffff. Ten comparisons rather than a loop, because this runs on every address that is read and
- * the first mismatch answers immediately for a real IPv6 peer.
- *
- * @param {Uint8Array} bytes exactly sixteen of them
- * @returns {boolean}
- */
-function isMappedIPv4(bytes) {
-    return (
-        bytes[10] === 0xff &&
-        bytes[11] === 0xff &&
-        bytes[0] === 0 &&
-        bytes[1] === 0 &&
-        bytes[2] === 0 &&
-        bytes[3] === 0 &&
-        bytes[4] === 0 &&
-        bytes[5] === 0 &&
-        bytes[6] === 0 &&
-        bytes[7] === 0 &&
-        bytes[8] === 0 &&
-        bytes[9] === 0
-    );
-}
-
-/**
- * Whether node would report an IPv4 peer of this app in mapped form, "::ffff:a.b.c.d". Node maps
- * it whenever the listener is dual stack, which is every listen() not given an IPv4 address to
- * bind. uWS already hands mapped peers over as sixteen bytes; four bytes only reach req.ip from a
- * v4-bound native listener or through the node shim, whose server supertest binds dual stack.
- *
- * @param {any} app the application the request arrived at
- * @returns {boolean}
- */
-function mapsIPv4Peer(app) {
-    const host = app._listenHost;
-    return !(host && isIP(host) === 4);
-}
-
-/** What µWS returns for a proxied address when no PROXY protocol preamble arrived. */
-const emptyAddress = new ArrayBuffer(0);
-
-const discardedDuplicates = new Set([
-    "age",
-    "authorization",
-    "content-length",
-    "content-type",
-    "etag",
-    "expires",
-    "from",
-    "host",
-    "if-modified-since",
-    "if-unmodified-since",
-    "last-modified",
-    "location",
-    "max-forwards",
-    "proxy-authorization",
-    "referer",
-    "retry-after",
-    "server",
-    "user-agent"
-]);
-
-// 128 KB of body buffered before uWS is asked to pause
-const READABLE_OPTIONS = { highWaterMark: 128 * 1024 };
-
-// The methods node's parser accepts, which is the set a request can arrive with behind Express and
-// the set a route can be registered for here. µWS accepts any token, so without this a line like
-// `{"a":1}GET /path HTTP/1.1` is a request to it, with `{"A":1}GET` as the method. See _mustRefuse.
-const KNOWN_METHODS = new Set(require("http").METHODS);
-
-/**
- * Whether a request target is bytes node's parser would have accepted, which is printable ASCII
- * and nothing else.
- *
- * µWS takes the target as it finds it and decodes it as UTF-8, so `GET /café` arrives here
- * as a path with an é in it and the overlong encoding of a slash arrives as replacement
- * characters. Node refuses both with a 400 before any application sees them, and it has to: what
- * reaches req.url otherwise is not what is on the wire, and a proxy in front reading the same
- * bytes can disagree with this server about which path was asked for. Control characters are µWS's
- * own to refuse and it does, so the test is one comparison per character rather than two.
- *
- * @param {string} target the path or the query string, as µWS decoded it
- * @returns {boolean}
- */
-function isAsciiTarget(target) {
-    for (let i = 0; i < target.length; i++) {
-        if (target.charCodeAt(i) > 0x7e) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/**
- * Whether a transfer-encoding leaves the body's length knowable, which is RFC 9112's rule that
- * `chunked` comes last. `gzip, chunked` is fine and `chunked, gzip` is not: with a coding applied
- * after the framing one, nothing can say where the body ends, and node answers 400 rather than
- * guess. µWS guesses, and what it guesses wrong becomes the next request on the connection.
- *
- * Read per header rather than over the joined value, so a request splitting the list across two
- * transfer-encoding headers is refused even when the codings would be legal joined up. That is
- * stricter than node by a hair, on a shape nothing sends, and stricter is the safe direction here.
- *
- * @param {string} value one transfer-encoding header, as uWS hands it over
- * @returns {boolean}
- */
-function endsWithChunked(value) {
-    const last = value.slice(value.lastIndexOf(",") + 1).trim();
-    // a coding may carry parameters, which are not part of its name
-    const semicolon = last.indexOf(";");
-    if ((semicolon === -1 ? last : last.slice(0, semicolon)).trim().toLowerCase() !== "chunked") {
-        return false;
-    }
-    // and only once. "chunked, chunked" ends with it and is still nonsense: a sender may not frame
-    // a body twice, and where node refuses the request outright µWS frames it as one chunked body
-    // and reads whatever follows as the next request on the connection
-    const codings = value.split(",");
-    let chunkedCount = 0;
-    for (const coding of codings) {
-        const parameter = coding.indexOf(";");
-        if ((parameter === -1 ? coding : coding.slice(0, parameter)).trim().toLowerCase() === "chunked") {
-            chunkedCount++;
-        }
-    }
-    return chunkedCount === 1;
-}
-
-/**
- * Whether a Connection header says the connection ends with this response.
- *
- * It is a list, and "keep-alive, close" closes as much as "close" alone does. Compared against an
- * exact "close", this server kept a connection the client had said it was done with, and then read
- * the bytes after it as another request: node closes there, so the two disagreed on how many
- * requests the same bytes carried, which is what a desync is.
- *
- * Written as a scan rather than a split and a lowercase, because almost every request that carries
- * this header carries "keep-alive", and both of those allocate per request.
- *
- * @param {string} value as µWS hands it over
- * @returns {boolean}
- */
-function saysClose(value) {
-    // what clients actually send, almost always: two interned compares answer before the scan
-    if (value === "keep-alive") {
-        return false;
-    }
-    if (value === "close") {
-        return true;
-    }
-    const length = value.length;
-    let at = 0;
-    while (at < length) {
-        while (at < length && (value.charCodeAt(at) === 0x20 || value.charCodeAt(at) === 0x09)) {
-            at++;
-        }
-        const start = at;
-        while (at < length && value.charCodeAt(at) !== 0x2c) {
-            at++;
-        }
-        let end = at;
-        while (end > start && (value.charCodeAt(end - 1) === 0x20 || value.charCodeAt(end - 1) === 0x09)) {
-            end--;
-        }
-        if (
-            end - start === 5 &&
-            (value.charCodeAt(start) | 0x20) === 0x63 &&
-            (value.charCodeAt(start + 1) | 0x20) === 0x6c &&
-            (value.charCodeAt(start + 2) | 0x20) === 0x6f &&
-            (value.charCodeAt(start + 3) | 0x20) === 0x73 &&
-            (value.charCodeAt(start + 4) | 0x20) === 0x65
-        ) {
-            return true;
-        }
-        at++;
-    }
-    return false;
-}
-
-/**
- * The path of the url a request carries right now, without the query.
- *
- * Express reads it off req.url on every access, so a middleware that assigns req.url is seen by
- * whatever runs next, the callback after it in the same route included: the router only takes a
- * rewrite over at its next hop. The cached field answers while the two agree, which is every read
- * of a request nobody rewrote.
- *
- * @param {any} req
- * @returns {string}
- */
-function currentPath(req) {
-    const url = req.url;
-    if (url === req._lastUrl) {
-        return req._path;
-    }
-    const query = url.indexOf("?");
-    return query === -1 ? url : url.slice(0, query);
-}
-
-/**
- * Whether a content-length is a plain count of bytes, which is the only thing RFC 9112 allows.
- *
- * uWS trims the spaces around the value and then takes whatever is left, so "", "abc", "+1", "-1",
- * "0x10" and "1e2" all arrive here. Every one of them makes uWS frame the request as carrying no
- * body, and what the client sent as a body is then read as the next request on the connection.
- * Node's parser refuses all of them outright, and so does this.
- *
- * @param {string} value as uWS hands it over
- * @returns {boolean}
- */
-function isByteCount(value) {
-    if (value.length === 0) {
-        return false;
-    }
-    for (let i = 0; i < value.length; i++) {
-        const code = value.charCodeAt(i);
-        if (code < 0x30 || code > 0x39) {
-            return false;
-        }
-    }
-    // A count nothing can represent is not a count. Node refuses one that overflows, and µWS framed
-    // the request as if it had said something else, which put the bytes after it in a request of
-    // their own. The length test first, so an ordinary value never parses.
-    if (value.length > 15 && Number(value) > Number.MAX_SAFE_INTEGER) {
-        return false;
-    }
-    return true;
-}
+const { isIP } = require("node:net");
+const { LazyReadable } = require("./lazy-readable.js");
+const {
+    asMessage,
+    formatIPv6,
+    isMappedIPv4,
+    mapsIPv4Peer,
+    emptyAddress,
+    discardedDuplicates,
+    KNOWN_METHODS,
+    isAsciiTarget,
+    endsWithChunked,
+    saysClose,
+    currentPath,
+    isByteCount
+} = require("./request-utils.js");
 
 // Whose headers the shared collector below is filling. uWS's forEach is synchronous and runs no
 // user code, so the handoff cannot interleave; module-level so the callback exists once instead
 // of once per request.
 let currentRequest = null;
 
-/**
- * A Readable that has not been built yet.
- *
- * Every request pays for the stream and almost none of them use it: a GET carries no body, and the
- * bodies that do arrive are collected by µWS and handed to the parsers without the stream being
- * touched. Measured on this machine, running Readable's constructor costs about 90ns of the 900ns
- * a hello-world request costs in total, which is a tenth of it for a facility nobody asked for.
- *
- * So the chain says Readable and the constructor does not run. `Request extends LazyReadable`, and
- * LazyReadable's prototype is Readable's, which keeps `req instanceof Readable` true and every
- * Readable method reachable; what is missing is `_readableState`, and that is built on the first
- * touch. A derived class cannot skip its super() call, but a base class with nothing in it costs
- * nothing to call.
- *
- * The wrapping below is generated rather than written out, and deliberately: every own member of
- * Readable's prototype gets a version that materialises first, so there is no list to keep in step
- * and no door left unguarded. Missing one would not be a slow path, it would be a TypeError on
- * `undefined._readableState` in whatever corner of a stream nobody tested.
- */
-class LazyReadableBase {}
-Object.setPrototypeOf(LazyReadableBase.prototype, Readable.prototype);
-Object.setPrototypeOf(LazyReadableBase, Readable);
-
-// what the chain says at runtime, said again for the type checker, which cannot see a prototype
-// being reassigned: everything a Readable offers is reachable from a Request, and is a Readable's
-const LazyReadable = /** @type {typeof Readable} */ (/** @type {unknown} */ (LazyReadableBase));
-
-/**
- * Builds the stream this object has been pretending to be. Idempotent: everything that can be
- * reached from outside goes through it, so it is called far more often than it does anything.
- *
- * EventEmitter's init keeps an _events that is already there, so listeners added before this
- * survive it.
- *
- * @param {any} stream
- */
-function materialise(stream) {
-    if (stream._readableState === undefined) {
-        Readable.call(stream, READABLE_OPTIONS);
-    }
-}
-
-for (const member of [
-    ...Object.getOwnPropertyNames(Readable.prototype),
-    ...Object.getOwnPropertySymbols(Readable.prototype)
-]) {
-    // the constructor is not a door, and `readable` is handled below because a request writes it
-    // and writing it must not build the very thing this is avoiding
-    if (member === "constructor" || member === "readable") {
-        continue;
-    }
-    const descriptor = /** @type {PropertyDescriptor} */ (Object.getOwnPropertyDescriptor(Readable.prototype, member));
-    if (typeof descriptor.value === "function") {
-        const inner = descriptor.value;
-        Object.defineProperty(LazyReadableBase.prototype, member, {
-            ...descriptor,
-            /** @this {any} @param {...any} args */
-            value: function (...args) {
-                materialise(this);
-                return inner.apply(this, args);
-            }
-        });
-    } else if (descriptor.get || descriptor.set) {
-        const innerGet = descriptor.get;
-        const innerSet = descriptor.set;
-        Object.defineProperty(LazyReadableBase.prototype, member, {
-            ...descriptor,
-            get: innerGet
-                ? /** @this {any} */ function () {
-                      materialise(this);
-                      return innerGet.call(this);
-                  }
-                : undefined,
-            set: innerSet
-                ? /** @this {any} @param {any} value */ function (value) {
-                      materialise(this);
-                      innerSet.call(this, value);
-                  }
-                : undefined
-        });
-    }
-}
-
-const nodeReadable = /** @type {PropertyDescriptor} */ (
-    Object.getOwnPropertyDescriptor(Readable.prototype, "readable")
-);
-
-// `readable` on its own: a request sets it while it is being built, and node's setter is a no-op
-// without the state anyway, so the flag is kept as a plain field until there is a stream to ask
-Object.defineProperty(LazyReadableBase.prototype, "readable", {
-    configurable: true,
-    enumerable: false,
-    /** @this {any} */
-    get: function () {
-        return this._readableState === undefined
-            ? this._readableFlag === true
-            : /** @type {any} */ (nodeReadable.get).call(this);
-    },
-    /** @this {any} @param {any} value */
-    set: function (value) {
-        if (this._readableState === undefined) {
-            this._readableFlag = !!value;
-            return;
-        }
-        /** @type {any} */ (nodeReadable.set).call(this, value);
-    }
-});
-
 module.exports = class Request extends LazyReadable {
-    /** @type {Record<string, any>|null} */
+    /** @type {import("http").IncomingHttpHeaders|null} */
     #cachedHeaders = null;
 
     /** @type {Record<string, string[]>|null} */
@@ -438,10 +56,9 @@ module.exports = class Request extends LazyReadable {
     /**
      * Every header, flat: name then value, name then value.
      *
-     * An array of pairs meant one array allocated per header on every request, and a request
-     * carries eight or ten of them, so everything that reads this walks it two at a time. The
-     * names are lowercase by contract: uWS lowers them on the wire and the node shim lowers
-     * them in its forEach, so readers compare without lowering again.
+     * An array of pairs meant one array per header on every request, and a request carries eight or
+     * ten, so everything that reads this walks it two at a time. The names are lowercase by
+     * contract: uWS lowers them on the wire and the node shim lowers them in its forEach.
      *
      * @type {string[]}
      */
@@ -458,10 +75,9 @@ module.exports = class Request extends LazyReadable {
 
     // `body` is deliberately not declared here. A class field would put the property on every
     // request, and on Express there is none until a body parser assigns one. `"body" in req` is how
-    // a library asks whether the body has already been read, and tRPC's express adapter asks
-    // exactly that: answering yes on a request nobody had parsed handed it an undefined body and
-    // turned every mutation into "Unexpected end of JSON input". Its type lives in types.d.ts,
-    // where the rest of the public request surface is described.
+    // a library asks whether the body was read, and tRPC's express adapter does exactly that:
+    // answering yes turned every mutation into "Unexpected end of JSON input". Its type is in
+    // types.d.ts, with the rest of the public request surface.
 
     /**
      * The response this request arrived with, linked so either reaches the other.
@@ -566,7 +182,7 @@ module.exports = class Request extends LazyReadable {
     /**
      * next() as the router means it: the rest of the route is skipped. res.sendFile reports its
      * failures here, because express reports them to the router and not to the route.
-     * @type {((err?: any) => void)|undefined}
+     * @type {((err?: unknown) => void)|undefined}
      */
     _leaveRoute;
 
@@ -619,22 +235,21 @@ module.exports = class Request extends LazyReadable {
     _sawContentLength;
 
     /**
-     * Whether this request must not be routed at all. Node's parser refuses each of these outright
-     * and answers 400; every one of them is a way for bytes the client did not send as a request to
-     * be served as one, which is request smuggling.
+     * Whether this request must not be routed at all. Node's parser refuses each of these and
+     * answers 400; every one is a way for bytes the client did not send as a request to be served
+     * as one, which is request smuggling.
      *
      *   a repeated content-length     uWS frames on the first and drops the rest, so a proxy in
-     *                                 front reading the last one instead forwards bytes uWS then
-     *                                 answers as a second, pipelined request
+     *                                 front reading the last one forwards bytes uWS then answers
+     *                                 as a second, pipelined request
      *   one that is not a byte count  uWS keeps whatever is left after trimming, an empty value
-     *                                 included, and frames the request as carrying no body at all,
-     *                                 which turns the body the client sent into that same second
-     *                                 request. See isByteCount
-     *   a method nobody defines       uWS takes any token as the method, so anything at all
-     *                                 followed by a space and a path is a request line to it. A
-     *                                 request with no content-length and no transfer-encoding has
-     *                                 no body, so the bytes after it are the next request: node
-     *                                 reads them and answers 400, uWS served them. See KNOWN_METHODS
+     *                                 included, and frames the request as carrying no body, which
+     *                                 turns the body the client sent into that second request.
+     *                                 See isByteCount
+     *   a method nobody defines       uWS takes any token as the method, so anything followed by a
+     *                                 space and a path is a request line to it. With no
+     *                                 content-length and no transfer-encoding there is no body, so
+     *                                 the bytes after it are the next request. See KNOWN_METHODS
      *
      * Declared for the same reason as rawIp.
      *
@@ -653,13 +268,16 @@ module.exports = class Request extends LazyReadable {
      * through the request. Declared rather than left to appear on assignment: runRoute sets it
      * on every request, and an undeclared property is a shape change on each one.
      *
+     * Typed loosely for the same reason as `res`: it is set by runRoute rather than here, and the
+     * honest `|undefined` would put a check in front of every call.
+     *
      * @type {any}
      */
     next;
 
     /**
      * What the chain threw or passed to next(err), waiting for an error handler.
-     * @type {any}
+     * @type {unknown}
      */
     _error;
 
@@ -687,14 +305,15 @@ module.exports = class Request extends LazyReadable {
      * because uWS only lends them for this call, everything derived from them waits until something
      * asks, and the body is subscribed to only for the methods that carry one.
      *
-     * @param {any} req the uWS request, readable only during this call
-     * @param {any} res the uWS response
-     * @param {any} app the application or router this request arrived at
-     * @param {any} [preset] a literal native registration's constants: µWS matched the URL byte
-     *   for byte against that exact pattern and dispatched by method, so path, method and what
-     *   derives from them are known without asking
-     * @param {any} [skipHolder] where a granted header skip lives: the preset itself for a
-     *   literal registration, a holder of its own for a parameterised one
+     * @param {import("uWebSockets.js").HttpRequest} req the uWS request, readable only during this call
+     * @param {import("uWebSockets.js").HttpResponse} res the uWS response
+     * @param {import("./application.js").Application} app the application this request arrived at
+     * @param {import("./router-utils.js").NativePreset} [preset] a literal native registration's
+     *   constants: uWS matched the URL byte for byte against that exact pattern and dispatched by
+     *   method, so path, method and what derives from them are known without asking
+     * @param {import("./router-utils.js").SkipHolder} [skipHolder] where a granted header skip
+     *   lives: the preset itself for a literal registration, a holder of its own for a
+     *   parameterised one
      */
     constructor(req, res, app, preset, skipHolder) {
         // nothing: the stream is built on the first touch, see LazyReadable
@@ -705,33 +324,25 @@ module.exports = class Request extends LazyReadable {
             // The chain behind this registration provably never reads a header, so instead of
             // copying them all out of uWS the constructor asks for the ones that steer the
             // framework itself: body framing, keep-alive, and the conditional pair. A GET that
-            // does declare a body is the rare case, and the parsers and the stream want the
-            // whole picture, so it takes the full copy.
+            // declares a body takes the full copy.
             //
-            // A handful of named reads against one forEach looks like it should lose, and does
-            // not: measured at seven reads they were flat at 0.75us however many headers are on
-            // the wire, since each one is a napi crossing and the scan behind it is nothing,
-            // while the copy pays a hop back into JS per header and grows, 1.16us at four
-            // headers, 1.61 at eight, 2.90 at sixteen. They do not cross, and the gap widens
-            // exactly where real traffic lives, since a browser sends a dozen or more. The body
-            // case pays two reads and then copies anyway, which is 0.2us on a request that is
-            // about to read a body.
+            // A handful of named reads beats one forEach: measured at seven reads they are flat at
+            // 0.75us however many headers are on the wire, since each one is a napi crossing, while
+            // the copy pays a hop back into JS per header and grows, 1.16us at four headers, 1.61
+            // at eight, 2.90 at sixteen. The body case pays two reads and then copies anyway, 0.2us.
             //
-            // accept is not read: nothing on a granted chain consumes it, the error and 404
-            // pages are fixed HTML that never negotiate.
+            // accept is not read: nothing on a granted chain consumes it, the error and 404 pages
+            // are fixed HTML that never negotiate.
             const length = req.getHeader("content-length");
             const transferEncoding = req.getHeader("transfer-encoding");
             // A content-length of "0" declares no body and used to stay on the cheap side, but
-            // getHeader only ever returns the first of a repeated header, so a duplicate cannot be
-            // seen from here, and a duplicate has to be refused rather than routed: see
-            // _mustRefuse. Anything that says a word about framing takes the full copy instead.
+            // getHeader only returns the first of a repeated header, so a duplicate cannot be seen
+            // from here and has to be refused rather than routed, see _mustRefuse. Anything that
+            // says a word about framing takes the full copy instead.
             //
             // One shape stays invisible here, a content-length present with an empty value: uWS
-            // answers "" for that and for a header that was never sent, and nothing in its API
-            // tells them apart. It frames both as carrying no body, which is the right reading of
-            // the second, so this server stays consistent with itself either way. The full copy
-            // below does refuse it, which is every request except a GET whose whole chain provably
-            // reads no header at all.
+            // answers "" for that and for a header never sent, and nothing in its API tells them
+            // apart. It frames both as carrying no body. The full copy below does refuse it.
             if (length !== "" || transferEncoding !== "") {
                 currentRequest = this;
                 this._req.forEach(Request.#collectHeader);
@@ -772,11 +383,9 @@ module.exports = class Request extends LazyReadable {
         }
         this.routeCount = 1;
         this.app = app;
-        // both forms are kept, because both are asked for: the query with its "?" goes into
-        // req.url, and req.query parses the raw one. Keeping only the first meant slicing the "?"
-        // back off for every request that reads req.query. When the chain provably reads
-        // neither, the native call is not made at all: the framework's own answers, the 404
-        // included, are written from the path alone
+        // both forms are kept because both are asked for: the query with its "?" goes into req.url,
+        // and req.query parses the raw one. When the chain provably reads neither, the native call
+        // is not made at all: the framework's own answers are written from the path alone
         if (skipHolder !== undefined && skipHolder.skipQuery) {
             this._rawQuery = "";
             this.urlQuery = "";
@@ -831,12 +440,10 @@ module.exports = class Request extends LazyReadable {
                 this._isHead = skipHolder.isHead;
             } else {
                 this.method = rawMethod.toUpperCase();
-                // node's parser knows a fixed set and refuses everything else; µWS takes the token
+                // node's parser knows a fixed set and refuses everything else, uWS takes the token
                 // as it finds it, so a request line is anything with a space in it. Compared before
-                // the uppercasing on purpose: a method is case sensitive, node refuses "post", and
-                // µWS folds it to POST and serves it. Only asked of a method the framework cannot
-                // route anyway, since a route can only be registered for one of these, see the loop
-                // that builds the verb methods at the end of router.js
+                // the uppercasing on purpose: a method is case sensitive, node refuses "post" and
+                // uWS folds it to POST and serves it
                 if (!KNOWN_METHODS.has(rawMethod)) {
                     this._mustRefuse = true;
                 }
@@ -857,12 +464,10 @@ module.exports = class Request extends LazyReadable {
         // Two Sets per request, for two things almost no request needs.
         //
         // _matchedMethods collects the verbs a path answers so an OPTIONS request can be told what
-        // they are, and every place that reads it asks _isOptions first, so it is built only for
-        // the requests that are one.
+        // they are, and every reader asks _isOptions first, so it is built only for those.
         //
-        // _paramCalled remembers, per router, what each app.param() callback was called with and
-        // what it left behind, so it is only wanted by an application that uses app.param at all.
-        // The router builds it the first time it has something to put in it.
+        // _paramCalled remembers, per router, what each app.param() callback was called with, so
+        // only an application using app.param wants it. The router builds it when it has something.
         this._matchedMethods = this._isOptions ? new Set() : null;
         this._paramCalled = null;
         // null for the same reason as the two above: a request that never enters a mount never
@@ -892,11 +497,9 @@ module.exports = class Request extends LazyReadable {
         }
 
         // A body exists on the wire only when the request declares one, content-length or
-        // transfer-encoding, whatever the verb, and that evidence was spotted during the header
-        // copy. The verb list and the "body methods" settings read this branch used to pay per
-        // request said nothing the headers had not already said; the setting still gates the
-        // body parsers, which is where it matters
-        if (/** @type {any} */ (this)._declaresBody) {
+        // transfer-encoding, whatever the verb, and that was spotted during the header copy. The
+        // verb list this used to read said nothing the headers had not already said
+        if (this._declaresBody) {
             this._subscribeBody();
         } else {
             this.receivedData = true;
@@ -948,7 +551,8 @@ module.exports = class Request extends LazyReadable {
      */
     _rawHeader(name) {
         if (this.#cachedHeaders !== null) {
-            return this.#cachedHeaders[name];
+            // a string for every name but set-cookie, which the callers never ask for
+            return /** @type {string|undefined} */ (this.#cachedHeaders[name]);
         }
         const entries = this.#rawHeadersEntries;
         for (let i = 0, len = entries.length; i < len; i += 2) {
@@ -969,7 +573,7 @@ module.exports = class Request extends LazyReadable {
      */
     _foldedHeader(name) {
         if (this.#cachedHeaders !== null) {
-            return this.#cachedHeaders[name];
+            return /** @type {string|undefined} */ (this.#cachedHeaders[name]);
         }
         const entries = this.#rawHeadersEntries;
         let value;
@@ -1004,8 +608,7 @@ module.exports = class Request extends LazyReadable {
      * a visitor who has gone away can be stopped. `@angular/ssr` reads it when it builds a web
      * Request out of this one, which is how an SSR render learns to give up.
      *
-     * Made on the first ask rather than for every request: most requests never look at it, and an
-     * AbortController each would be an allocation nobody reads.
+     * Made on the first ask: most requests never look at it.
      *
      * @returns {AbortSignal}
      */
@@ -1095,11 +698,9 @@ module.exports = class Request extends LazyReadable {
         if (this._mountSlash !== true) {
             return this._originalPath.slice(0, this._consumed);
         }
-        // Express drops one trailing slash off each mount before joining them, so this is a join
-        // of the pieces rather than one slice of the path: a RegExp mount ending in "/" matched
-        // against "/a//b" takes "/a/" and reads back as "/a", and what the mount below it took is
-        // appended to that rather than to the original. Only a RegExp mount can take a trailing
-        // slash, a registered path having had it removed, so almost every request answers above.
+        // Express drops one trailing slash off each mount before joining them, so this is a join of
+        // the pieces and not one slice of the path: a RegExp mount ending in "/" matched against
+        // "/a//b" takes "/a/" and reads back as "/a". Only a RegExp mount can take a trailing slash
         let out = "";
         let at = 0;
         for (let taken of this._stack) {
@@ -1165,7 +766,7 @@ module.exports = class Request extends LazyReadable {
     /**
      * The authority, port included, from Host or from X-Forwarded-Host behind a trusted proxy.
      * `hostname` is the same value without the port.
-     * @returns {string}
+     * @returns {string|undefined} undefined when the request carries no Host
      */
     get host() {
         return this.#authority;
@@ -1173,7 +774,7 @@ module.exports = class Request extends LazyReadable {
 
     /**
      * The host without the port.
-     * @returns {string}
+     * @returns {string|undefined}
      */
     get hostname() {
         return this.#host;
@@ -1244,7 +845,8 @@ module.exports = class Request extends LazyReadable {
         if (!trust(this.parsedIp, 0)) {
             return proto;
         }
-        const header = this.headers["x-forwarded-proto"] || proto;
+        // folded to one string, as every header but set-cookie is
+        const header = /** @type {string|undefined} */ (this.headers["x-forwarded-proto"]) || proto;
         const index = header.indexOf(",");
 
         return index !== -1 ? header.slice(0, index).trim() : header.trim();
@@ -1324,37 +926,33 @@ module.exports = class Request extends LazyReadable {
      * object, so a key like "__proto__" cannot reach Object.prototype. No setter, so assigning to
      * req.query throws as it does on Express.
      *
-     * Every read answers a new object, because express's getter re-parses on every read and so hands
-     * one back too. Two consequences an application can see, and both of them bite: `req.query` is
-     * never the object another reader holds, and a write to a key of it is gone by the next read.
-     * That second one is how express-validator's sanitisers behave: `.trim()` on a query parameter
-     * changes nothing an ordinary handler will see, which is why it also offers matchedData(). With
-     * the parse cached and handed out as itself, the sanitised value leaked into req.query here and
-     * a handler written against express read a trimmed value where express gives it the raw one.
+     * Every read answers a new object, because express re-parses on every read and hands one back
+     * too. So req.query is never the object another reader holds, and a write to a key of it is
+     * gone by the next read. That is how express-validator's sanitisers behave: `.trim()` on a
+     * query parameter changes nothing an ordinary handler sees. With the parse cached and handed
+     * out as itself, the sanitised value leaked into req.query here.
      *
-     * And that is why there is no cache of the object: the fresh object comes from the raw
-     * string, not from copying a kept parse. As first shipped this was parse-once-copy-per-read,
-     * and the copy was the expensive half: Object.assign between null-prototype objects, which
-     * live in V8's dictionary mode, measured 638ns for a two-parameter query where parsing the
-     * same string measures 119ns, and on a benchmark whose every request carries such a query it
-     * cost +1.5us of CPU per request, which a public arena saw as -8% on its query-carrying rows.
+     * So there is no cache of the object: the fresh object comes from the raw string, not from
+     * copying a kept parse. Parse-once-copy-per-read was the first shape shipped, and the copy was
+     * the expensive half: Object.assign between null-prototype objects, which live in V8's
+     * dictionary mode, measured 638ns for a two-parameter query where parsing the same string
+     * measures 119ns, so +1.5us of CPU per request, which a public arena saw as -8% on its
+     * query-carrying rows.
      *
-     * The default parser does keep the decoded pairs of its first parse, and a later read of the
-     * same raw string replays the stores into a fresh null-prototype object: identical output,
-     * still nothing shared between reads. A repeated key cannot be replayed and re-parses.
+     * The default parser keeps the decoded pairs of its first parse and replays the stores into a
+     * fresh null-prototype object: same output, nothing shared between reads. A repeated key
+     * cannot be replayed and re-parses.
      *
      * @returns {Record<string, any>}
      */
     get query() {
         const qp = this.app._hot().queryParserFn;
-        // the vendored default already answers on a bare null prototype, so it goes out as is;
-        // any other parser is copied onto one, which is what kept fast-querystring's result from
-        // inspecting as "Empty <[Object: null prototype] {}>" where Express shows the bare form
-        // A parser of the application's own is handed what express hands it, which is
-        // parseurl's `query`: null when the url carries no "?" at all, and the text after it
-        // otherwise, the empty string included. Passing "" for both meant a parser written for
-        // express, which may check for null before it reads the string, saw a request that had no
-        // query as one with an empty query. The two built in parsers take the raw string.
+        // the vendored default already answers on a bare null prototype, so it goes out as is; any
+        // other parser is copied onto one, which kept fast-querystring's result from inspecting as
+        // "Empty <[Object: null prototype] {}>" where Express shows the bare form.
+        // A parser of the application's own is handed what express hands it, parseurl's `query`:
+        // null when the url carries no "?", the text after it otherwise, empty string included.
+        // Passing "" for both made a parser written for express see no query as an empty query.
         if (!qp) {
             return Object.create(null);
         }
@@ -1436,12 +1034,11 @@ module.exports = class Request extends LazyReadable {
      * The peer address bytes, from the socket or, when the application asked for it, from a PROXY
      * protocol preamble the load balancer in front of this server sent ahead of the request.
      *
-     * The setting is off by default and has to stay that way. µWS parses the preamble from whoever
-     * sends it, with nothing to ask for it at listen time and no way to restrict who may, so an
-     * application that took the address unconditionally would let any client claim any address:
-     * the first sixteen bytes of a connection are enough to become 10.0.0.1 for a rate limiter, an
-     * allow list or an audit log. Turn it on only when nothing can reach this server except the
-     * proxy in front of it.
+     * The setting is off by default and has to stay that way. uWS parses the preamble from whoever
+     * sends it, with no way to restrict who may, so an application that took the address
+     * unconditionally would let any client claim any address: the first sixteen bytes of a
+     * connection are enough to become 10.0.0.1 for a rate limiter or an allow list. Turn it on only
+     * when nothing can reach this server except the proxy in front of it.
      *
      * @returns {ArrayBuffer} the socket's own address when no preamble arrived
      */
@@ -1498,11 +1095,9 @@ module.exports = class Request extends LazyReadable {
         } else if (rawIp.byteLength === 16) {
             const bytes = new Uint8Array(rawIp);
             if (isMappedIPv4(bytes)) {
-                // ::ffff:a.b.c.d, which is what a dual stack listener hands over for every IPv4
-                // peer, so it is what nearly every request here is. The general path below reaches
-                // the same string through a DataView, an array of eight groups and a scan for the
-                // longest run of zeros, and measured 157ns more per request for it. Anything that
-                // reads req.ip pays that once, and morgan reads it on every line it writes.
+                // ::ffff:a.b.c.d, what a dual stack listener hands over for every IPv4 peer, so
+                // nearly every request here. The general path below reaches the same string through
+                // a DataView and a scan for the longest zero run, 157ns more per request
                 ip = "::ffff:" + bytes[12] + "." + bytes[13] + "." + bytes[14] + "." + bytes[15];
             } else {
                 // ipv6
@@ -1520,7 +1115,7 @@ module.exports = class Request extends LazyReadable {
         return ip;
     }
 
-    /** @type {object|null} */
+    /** @type {import("./socket.js")|null} */
     #cachedConnection = null;
 
     /**
@@ -1528,7 +1123,7 @@ module.exports = class Request extends LazyReadable {
      * stand-in for the pair, as node has one socket for both. Built on first read and kept, so it
      * keeps its identity across reads, and kept here as well so that it still answers once the
      * response is over and `res.socket` has gone null.
-     * @returns {any}
+     * @returns {import("./socket.js")}
      */
     get connection() {
         return (this.#cachedConnection ??= this.res._socketShim());
@@ -1543,13 +1138,12 @@ module.exports = class Request extends LazyReadable {
     }
 
     /**
-     * Cuts this request loose from the µWS response it arrived on, keeping the two things only
+     * Cuts this request loose from the uWS response it arrived on, keeping the two things only
      * that response could answer.
      *
-     * A websocket upgrade hands the request to the socket, which outlives the response by the
-     * whole life of the connection. Reading the peer address through the freed response is not
-     * an error but a use after free, so the values are taken while it is still alive and an
-     * inert stand-in answers anything that asks later.
+     * A websocket upgrade hands the request to the socket, which outlives the response. Reading the
+     * peer address through the freed response is a use after free, so the values are taken while it
+     * is still alive and an inert stand-in answers later.
      */
     _detachFromResponse() {
         const uwsRes = this._res;
@@ -1558,18 +1152,21 @@ module.exports = class Request extends LazyReadable {
         }
         const remotePort = uwsRes.getRemotePort();
         const rawIp = this.rawIp;
-        this._res = {
-            getRemoteAddress: () => rawIp,
-            // whatever a preamble said is already in rawIp, and asking again is the use after free
-            // this method exists to avoid
-            getProxiedRemoteAddress: () => emptyAddress,
-            getRemotePort: () => remotePort,
-            // a body cannot arrive on an upgraded socket, and a stray reader must not reach µWS
-            onData() {},
-            pause() {},
-            resume() {},
-            close() {}
-        };
+        // a stand-in with the members a detached request still asks for, told to the checker once
+        this._res = /** @type {import("uWebSockets.js").HttpResponse} */ (
+            /** @type {unknown} */ ({
+                getRemoteAddress: () => rawIp,
+                // whatever a preamble said is already in rawIp, and asking again is the use after free
+                // this method exists to avoid
+                getProxiedRemoteAddress: () => emptyAddress,
+                getRemotePort: () => remotePort,
+                // a body cannot arrive on an upgraded socket, and a stray reader must not reach µWS
+                onData() {},
+                pause() {},
+                resume() {},
+                close() {}
+            })
+        );
     }
 
     /**
@@ -1653,7 +1250,7 @@ module.exports = class Request extends LazyReadable {
      *   acceptable type when called with no arguments
      */
     accepts(...types) {
-        return accepts(asMessage(this)).types(.../** @type {any} */ (types));
+        return accepts(asMessage(this)).types(.../** @type {string[]} */ (types));
     }
 
     /**
@@ -1662,7 +1259,7 @@ module.exports = class Request extends LazyReadable {
      * @returns {string|string[]|false}
      */
     acceptsCharsets(...charsets) {
-        return accepts(asMessage(this)).charsets(.../** @type {any} */ (charsets));
+        return accepts(asMessage(this)).charsets(.../** @type {string[]} */ (charsets));
     }
 
     /**
@@ -1671,7 +1268,7 @@ module.exports = class Request extends LazyReadable {
      * @returns {string|string[]|false}
      */
     acceptsEncodings(...encodings) {
-        return accepts(asMessage(this)).encodings(.../** @type {any} */ (encodings));
+        return accepts(asMessage(this)).encodings(.../** @type {string[]} */ (encodings));
     }
 
     /**
@@ -1680,7 +1277,7 @@ module.exports = class Request extends LazyReadable {
      * @returns {string|string[]|false}
      */
     acceptsLanguages(...languages) {
-        return accepts(asMessage(this)).languages(.../** @type {any} */ (languages));
+        return accepts(asMessage(this)).languages(.../** @type {string[]} */ (languages));
     }
 
     /**
@@ -1756,14 +1353,14 @@ module.exports = class Request extends LazyReadable {
     }
 
     /**
-     * The request headers as node presents them: lowercased names, and repeats folded the way
-     * node folds them. Set-Cookie stays an array, Cookie is joined with "; ", the fields listed in
-     * discardedDuplicates keep only the first value, and everything else is joined with ", ".
+     * The request headers as node presents them: lowercased names, and repeats folded the way node
+     * folds them. Set-Cookie stays an array, Cookie is joined with "; ", the fields listed in
+     * discardedDuplicates keep only the first value, everything else is joined with ", ".
      *
-     * Built on first read and cached, since the raw entries are what routing works from and most
-     * requests never ask for this at all.
+     * Built on first read and cached: routing works from the raw entries and most requests never
+     * ask for this.
      *
-     * @returns {Record<string, any>}
+     * @returns {import("http").IncomingHttpHeaders}
      */
     get headers() {
         // https://nodejs.org/api/http.html#messageheaders
@@ -1774,6 +1371,7 @@ module.exports = class Request extends LazyReadable {
         // half-filled object cached. A plain object because node's is one and inspect prints the
         // difference; Object.hasOwn keeps a header named "constructor" or "toString" from finding
         // Object.prototype's member and folding a first value into it.
+        /** @type {import("http").IncomingHttpHeaders} */
         const headers = {};
         const entries = this.#rawHeadersEntries;
         for (let index = 0, len = entries.length; index < len; index += 2) {
@@ -1789,7 +1387,7 @@ module.exports = class Request extends LazyReadable {
                 if (key === "cookie") {
                     headers[key] += "; " + value;
                 } else if (key === "set-cookie") {
-                    headers[key].push(value);
+                    /** @type {string[]} */ (headers[key]).push(value);
                 } else {
                     headers[key] += ", " + value;
                 }
@@ -1877,4 +1475,5 @@ module.exports = class Request extends LazyReadable {
 
 // req.header is req.get under Express's other name. On the prototype rather than an instance
 // field, which wrote one own property per request in the constructor.
-/** @type {any} */ (module.exports.prototype).header = module.exports.prototype.get;
+/** @type {{header?: typeof module.exports.prototype.get}} */ (module.exports.prototype).header =
+    module.exports.prototype.get;