fulmine.js 5.19.2 → 5.19.4

package/src/response.js

@@ -38,22 +38,29 @@ const {
     withUtf8Charset,
     asStatError,
     httpError,
+    headersSentError,
+    applyWriteHead,
     contentTypeFor,
     statTag,
     cachedStat,
     NullObject
 } = require("./utils.js");
-const { Writable } = require("stream");
 const { isAbsolute } = require("path");
 const fs = require("fs");
 const Path = require("path");
 const statuses = require("statuses");
 const { sign } = require("cookie-signature");
-// events is faster at init, tseep is faster at sending events
-// since we create a ton of objects and dont send a ton of events, its better to use events here
-const { EventEmitter } = require("events");
-const http = require("http");
 const ms = require("ms");
+const Socket = require("./socket.js");
+const { LazyWritable } = require("./lazy-writable.js");
+const {
+    kOutHeaders,
+    kShapeMode,
+    VALIDATED_HEADER_NAMES,
+    HEADER_NAME_BUF,
+    HEADER_VALUE_BUF,
+    statusLine
+} = require("./response-utils.js");
 
 // How much a chunked response may gather before it is handed to uWS. Measured on uWS alone with
 // 33 KB written in 500 pieces: 16.2ms handed over one piece at a time, 0.79ms in 4 KB blocks,
@@ -67,48 +74,6 @@ const COALESCE_LIMIT = 16 * 1024;
 // here up goes straight through.
 const COALESCE_BELOW = 4 * 1024;
 
-const outgoingMessage = new http.OutgoingMessage();
-const symbols = Object.getOwnPropertySymbols(outgoingMessage);
-// if a future node renames it, fall back to a private symbol rather than writing a property
-// literally named "undefined", which is what indexing with undefined would do
-const kOutHeaders = symbols.find((s) => s.toString() === "Symbol(kOutHeaders)") ?? Symbol("kOutHeaders");
-// node's emitters tombstone a removed listener's slot instead of deleting it when this flag is
-// set, which is what keeps _events in a stable shape. EventEmitter.init sets it, and never runs
-// for the lazily-materialized response, so it is set by hand; a future rename degrades to the
-// delete, not to an error
-const kShapeMode =
-    Object.getOwnPropertySymbols(new EventEmitter()).find((s) => s.toString() === "Symbol(shapeMode)") ??
-    Symbol("shapeMode");
-// names setHeader has validated and lowercased, so the constant names middleware writes per
-// request are one Map hit. Insert-only after validation, bounded; only setHeader may insert,
-// the never-throwing readers keep their plain toLowerCase
-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 just misses the lookup and crosses as the string it was. Names must stay lowercase,
-// which is how writeHeaders receives them.
-const HEADER_NAME_BUF = { __proto__: null };
-const HEADER_VALUE_BUF = { __proto__: null };
-for (const s of ["connection", "keep-alive", "content-type", "vary", "x-powered-by", "content-encoding"]) {
-    HEADER_NAME_BUF[s] = Buffer.from(s);
-}
-for (const s of [
-    "keep-alive",
-    "timeout=10",
-    "close",
-    "Fulmine",
-    "Accept-Encoding",
-    "text/html; charset=utf-8",
-    "text/plain; charset=utf-8",
-    "application/json; charset=utf-8",
-    "application/octet-stream",
-    "gzip",
-    "br",
-    "deflate",
-    "zstd"
-]) {
-    HEADER_VALUE_BUF[s] = Buffer.from(s);
-}
 const HIGH_WATERMARK = 128 * 1024;
 // the exact string json() writes, so send() can skip recomputing the charset on it
 const JSON_UTF8 = "application/json; charset=utf-8";
@@ -116,283 +81,8 @@ const JSON_UTF8 = "application/json; charset=utf-8";
 // than written out, since a year is already longer than any cache will honour.
 const MAX_MAXAGE = 60 * 60 * 24 * 365 * 1000;
 
-class Socket extends EventEmitter {
-    /**
-     * The Socket's own error listener, shared across sockets: an error on the stand-in closes it,
-     * which is the close the connection trackers wait for. EventEmitter calls it with this = the
-     * emitter.
-     *
-     * @this {any}
-     * @param {any} err
-     */
-    static _onError(err) {
-        this.emit("close");
-    }
-
-    /**
-     * Enough of a node socket for the middleware that reaches for one. There is no socket object
-     * in uWS to hand over, so this stands in and forwards what it can to the response.
-     *
-     * @param {any} response
-     */
-    constructor(response) {
-        super();
-        this.response = response;
-        this[kShapeMode] = true;
-        // middleware assigns to this one, which is why it is a field rather than a getter: express
-        // reads socket.encrypted for req.protocol and a proxy shim writes it
-        this.encrypted = response.req.app.ssl;
-        this.localPort = response.req.app.port;
-        // on-finished reads socket.readable before anything else, and a socket without one reads
-        // as a request that is already over
-        this.readable = true;
-
-        // shared, not an arrow: one per process instead of one per materialized socket
-        this.on("error", Socket._onError);
-    }
-
-    /** Whether anything more can be written, which stops being true once the response is done. */
-    get writable() {
-        return !this.response.finished;
-    }
-
-    /** The peer, as node reports it. Reading it out of µWS is slow, so the request caches it. */
-    get remoteAddress() {
-        return this.response.req.parsedIp;
-    }
-
-    /** A native µWS call almost no caller makes, so it stays behind its getter. */
-    get remotePort() {
-        return this.response.req._res.getRemotePort();
-    }
-
-    /**
-     * node's socket carries these three and applications call them on a request they mean to hold
-     * open, almost always to take the timeout off. µWS has no per socket timeout reachable from
-     * javascript, so they do nothing and hand the socket back the way node's do. n8n's chat trigger
-     * calls setTimeout on every webhook, and without it the workflow answered 500.
-     * @returns {this}
-     */
-    setTimeout() {
-        return this;
-    }
-
-    /** @returns {this} */
-    setKeepAlive() {
-        return this;
-    }
-
-    /** @returns {this} */
-    setNoDelay() {
-        return this;
-    }
-
-    /**
-     * Finishes the response through the socket, which is how the middleware that only knows
-     * about sockets ends one.
-     * @param {any} [body]
-     */
-    end(body) {
-        this.response.end(body);
-    }
-
-    /**
-     * What a server side socket answers about itself. µWS owns the connection, so these follow the
-     * response: it is open until the response is over, and it was never a socket being dialled.
-     */
-    get destroyed() {
-        return this.response.finished === true;
-    }
-
-    /** @returns {string} "open" until the response is over, as a served socket reads. */
-    get readyState() {
-        return this.response.finished === true ? "closed" : "open";
-    }
-
-    /** @returns {boolean} never: this end was accepted, not dialled. */
-    get connecting() {
-        return false;
-    }
-
-    /** @returns {boolean} never, for the same reason. */
-    get pending() {
-        return false;
-    }
-
-    /**
-     * The end of the connection node reports here. There is no address to read back from µWS, so
-     * this is the port the application bound and the family the peer arrived on.
-     * @returns {{address: string|undefined, family: string, port: number|undefined}}
-     */
-    address() {
-        const remote = this.response.req.parsedIp;
-        return {
-            address: this.response.req.app._listenHost,
-            family: remote?.includes(":") ? "IPv6" : "IPv4",
-            port: this.localPort
-        };
-    }
-
-    /**
-     * Drops the connection, which is what an application does to a client it will not serve. node
-     * takes an error and re-emits it; this closes and says so through 'close', since there is no
-     * socket underneath to carry an error of its own.
-     * @returns {this}
-     */
-    destroy() {
-        this.close();
-        return this;
-    }
-
-    /** @returns {this} */
-    destroySoon() {
-        this.close();
-        return this;
-    }
-
-    /**
-     * Holds and resumes the body arriving on this connection, which is the only half of node's
-     * pause() that means anything here: the response is written when the application writes it.
-     * @returns {this}
-     */
-    pause() {
-        this.response.req.pause();
-        return this;
-    }
-
-    /** @returns {this} */
-    resume() {
-        this.response.req.resume();
-        return this;
-    }
-
-    /**
-     * node writes these bytes past the response, straight onto the connection. There is no way
-     * past µWS's framing here, so they go through the response instead, which is what the
-     * middleware writing to a socket means by it.
-     *
-     * @param {any} chunk
-     * @param {any} [encoding]
-     * @param {any} [callback]
-     * @returns {boolean}
-     */
-    write(chunk, encoding, callback) {
-        return this.response.write(chunk, encoding, callback);
-    }
-
-    /** The event loop is µWS's, so there is nothing to hold open or let go. @returns {this} */
-    ref() {
-        return this;
-    }
-
-    /** @returns {this} */
-    unref() {
-        return this;
-    }
-
-    /** Closes the connection outright, without finishing a response first. */
-    close() {
-        if (this.response.finished) {
-            return;
-        }
-        this.response.finished = true;
-        this.emit("close");
-        this.response._res.close();
-    }
-}
-
-// One status line per code, built on first use: the default path, with no custom reason phrase,
-// paid a template string and a trim per request for a line that never changes. Bounded to real
-// HTTP codes so a wild writeHead value cannot grow the array or flip it into dictionary mode.
-const STATUS_LINES = [];
-/**
- * @param {number} code
- * @param {string|undefined} text an explicit reason phrase, which bypasses the cache
- * @returns {string} the uWS status line, e.g. "200 OK"
- */
-function statusLine(code, text) {
-    if (text === undefined && Number.isInteger(code) && code >= 100 && code <= 999) {
-        return STATUS_LINES[code] ?? (STATUS_LINES[code] = code + " " + (statuses.message[code] ?? "unknown"));
-    }
-    return `${code} ${text ?? statuses.message[code] ?? "unknown"}`.trim();
-}
-
-/**
- * A Writable that has not built its state yet, the mirror of LazyReadable in request.js and there
- * for the same reason: a response is a Writable because middleware expects one, and the ordinary
- * one never uses it. `send()` reaches `end()`, which is overridden here and goes straight to
- * _finish, so the WritableState is allocated for every response and read by nobody. It is needed
- * only by res.write(), by a stream piped into the response, by cork and by the writableX getters.
- *
- * `Response extends LazyWritable`, whose prototype is Writable's, so `res instanceof Writable`
- * stays true and every Writable method is reachable; what is missing is `_writableState`, built on
- * the first touch. Measured at 45 nanoseconds a response on the machine this was written on.
- *
- * As on the Readable side the wrapping is generated rather than written out: every own member of
- * Writable's prototype gets a version that materialises first, so there is no list to keep in step.
- * Missing one would not be a slow path, it would be a TypeError on `undefined._writableState`.
- */
-class LazyWritableBase {}
-Object.setPrototypeOf(LazyWritableBase.prototype, Writable.prototype);
-Object.setPrototypeOf(LazyWritableBase, Writable);
-
-// what the chain says at runtime, said again for the type checker, which cannot see a prototype
-// being reassigned
-const LazyWritable = /** @type {typeof Writable} */ (/** @type {unknown} */ (LazyWritableBase));
-
-/**
- * Builds the stream this object has been pretending to be. Idempotent: everything reachable 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 both the shape the constructor
- * wrote and any listener added before this survive it.
- *
- * @param {any} stream
- */
-function materialiseWritable(stream) {
-    if (stream._writableState === undefined) {
-        Writable.call(stream);
-    }
-}
-
-for (const member of [
-    ...Object.getOwnPropertyNames(Writable.prototype),
-    ...Object.getOwnPropertySymbols(Writable.prototype)
-]) {
-    if (member === "constructor") {
-        continue;
-    }
-    const descriptor = /** @type {PropertyDescriptor} */ (Object.getOwnPropertyDescriptor(Writable.prototype, member));
-    if (typeof descriptor.value === "function") {
-        const inner = descriptor.value;
-        Object.defineProperty(LazyWritableBase.prototype, member, {
-            ...descriptor,
-            /** @this {any} @param {...any} args */
-            value: function (...args) {
-                materialiseWritable(this);
-                return inner.apply(this, args);
-            }
-        });
-    } else if (descriptor.get || descriptor.set) {
-        const innerGet = descriptor.get;
-        const innerSet = descriptor.set;
-        Object.defineProperty(LazyWritableBase.prototype, member, {
-            ...descriptor,
-            get: innerGet
-                ? /** @this {any} */ function () {
-                      materialiseWritable(this);
-                      return innerGet.call(this);
-                  }
-                : undefined,
-            set: innerSet
-                ? /** @this {any} @param {any} value */ function (value) {
-                      materialiseWritable(this);
-                      innerSet.call(this, value);
-                  }
-                : undefined
-        });
-    }
-}
+// what send takes as a range request: the bytes unit, checked on the header's text before parsing
+const BYTES_RANGE = /^ *bytes=/;
 
 module.exports = class Response extends LazyWritable {
     /** @type {Socket|null} */
@@ -409,10 +99,8 @@ module.exports = class Response extends LazyWritable {
      *
      * uWS charges for a write against everything already buffered behind it, so a chunked response
      * written in many small pieces costs quadratically once it passes the socket's own buffer:
-     * 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.
-     * Null until the first chunked write, since a res.send never queues anything.
+     * measured on uWS alone, 500 writes of 66 bytes take 13ms against 0.06ms for 100 of them, and
+     * the same bytes in blocks cost 0.4ms. Null until the first chunked write.
      * @type {Buffer[]|null}
      */
     #queued = null;
@@ -423,7 +111,20 @@ module.exports = class Response extends LazyWritable {
     /** Whether a flush is already booked for the end of this turn. */
     #flushBooked = false;
 
-    /** @type {any} */
+    /** Whether the status line and the headers have reached uWS, which only a body write does. */
+    #headOut = false;
+
+    /**
+     * The status line as writeHead settled it, which is the one the wire gets: node stores the
+     * head at writeHead, so a status set later never reaches the client.
+     * @type {number}
+     */
+    #status = 200;
+
+    /** @type {string|undefined} */
+    #statusText = undefined;
+
+    /** @type {Response["headers"]|null} */
     #outHeaders = null;
 
     /**
@@ -437,9 +138,9 @@ module.exports = class Response extends LazyWritable {
      * two that describe the connection, since every response carries them, and x-powered-by only
      * when the setting asks for it.
      *
-     * @param {any} res the uWS response
-     * @param {any} req the Request, already built, which is where the connection header is read from
-     * @param {any} app the application or router this request arrived at
+     * @param {import("uWebSockets.js").HttpResponse} res the uWS response
+     * @param {InstanceType<typeof import("./request.js")>} req the Request, already built
+     * @param {import("./application.js").Application} app the application this request arrived at
      */
     constructor(res, req, app) {
         super();
@@ -448,6 +149,7 @@ module.exports = class Response extends LazyWritable {
         // the order node's own Writable constructor lays down, so the hidden class is the one every
         // other stream in the process has, and node's init keeps this object when the state is
         // finally built
+        /** @type {Record<string, Function|undefined>} */
         this._events = {
             close: undefined,
             error: undefined,
@@ -500,26 +202,22 @@ module.exports = class Response extends LazyWritable {
         this.body = undefined;
         // what was handed to uWS, kept so a caller asking for content-length after the fact can be
         // answered, see get(). Undefined until the response ends, and for one that sends no body
-        /** @type {string|Buffer|undefined} */
+        /** @type {string|Buffer|Uint8Array|undefined} */
         this._sentBody = undefined;
         // false while the uWS route handler is still in its synchronous window, where uWS holds
         // the socket corked itself; the two uWS entry points flip it once that window closes
         this._corkNeeded = false;
-        // shared methods, not arrows: two closures and a once() wrapper here were four
-        // allocations per request. EventEmitter calls listeners with this = the emitter.
+        // shared methods, not arrows: two closures and a once() wrapper here were four allocations
+        // per request. EventEmitter calls listeners with this = the emitter.
         //
         // Written into the map rather than through on(). A stream arrives with its _events already
         // shaped, "close" and "error" among the keys and every value undefined, so filling two of
-        // them is the same hidden class on() would have produced and none of its work: the argument
-        // check, the newListener emission, the is-there-one-already branch and the max listener
-        // count. Two calls per response, and the profile put them at 6% of a hello-world.
+        // them is the same hidden class on() would produce and none of its work. Two calls per
+        // response, and the profile put them at 6% of a hello-world.
         //
-        // The condition is the whole safety of it: a fresh response has no listeners, so both slots
-        // are free, and anything else falls back to on(). Adding one later goes through on() as
-        // usual and finds what this wrote, because this wrote what on() writes.
-        // cast because _events and _eventsCount are EventEmitter's own bookkeeping and carry no
-        // type: they are what on() writes, and this writes the same two entries
-        const self = /** @type {any} */ (this);
+        // The condition is the safety of it: a fresh response has no listeners, so both slots are
+        // free, and anything else falls back to on(), which finds what this wrote.
+        const self = this;
         const events = self._events;
         if (
             self._eventsCount === 0 &&
@@ -556,17 +254,15 @@ module.exports = class Response extends LazyWritable {
     /**
      * Drops the connection, which is how an application abandons a response it cannot finish: a
      * download whose source dies mid-transfer has to leave the client with a reset rather than a
-     * truncated body it would take for the whole file. node destroys the socket here and µWS's
-     * close() is the same thing; without it the client waited for bytes that were never coming and
-     * the request hung until its own timeout. LibreChat's download route is written exactly that
-     * way, `stream.on("error", () => res.destroy())`.
+     * truncated body. node destroys the socket here and uWS's close() is the same thing; without it
+     * the client waited for bytes that never came. LibreChat's download route is written that way,
+     * `stream.on("error", () => res.destroy())`.
      *
-     * A response that is over, or one whose client is already gone, only tears the stream down:
-     * there is nothing left to close, and touching an aborted µWS response is a use after free.
-     * One difference from node stays: writableEnded reads true after this, because it is answered
-     * from the same finished flag the close sets, where node leaves it false until end() is called.
+     * A response that is over, or one whose client is gone, only tears the stream down: touching an
+     * aborted uWS response is a use after free. writableEnded reads true after this, where node
+     * leaves it false until end() is called.
      *
-     * @param {any} [error]
+     * @param {Error} [error] whatever the caller is destroying the response with
      * @returns {this}
      */
     destroy(error) {
@@ -596,7 +292,7 @@ module.exports = class Response extends LazyWritable {
             return;
         }
         this._pendingLinked = false;
-        const pending = /** @type {any} */ (this)._pendingIn;
+        const pending = /** @type {{_pendingIn?: {head: Response|null}}} */ (this)._pendingIn;
         const prev = this._pendingPrev;
         const next = this._pendingNext;
         if (prev) {
@@ -613,12 +309,9 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Where node keeps the outgoing headers of an OutgoingMessage. Only code going through node's
-     * own header path ever looks, cookie-session being the one in this project's tests, so the
-     * proxy standing in for it is built on the first look rather than on every response: it was a
-     * proxy, a handler object and two closures each time, for something almost nothing reads.
-     *
-     * A setter as well, because node assigns to this slot when it resets the headers, and a getter
-     * on its own would make that throw.
+     * own header path looks, cookie-session being the one in this project's tests, so the proxy
+     * standing in for it is built on the first look: it was a proxy, a handler object and two
+     * closures per response otherwise. A setter too, because node assigns to this slot on a reset.
      */
     get [kOutHeaders]() {
         if (!this.#outHeaders) {
@@ -654,7 +347,7 @@ module.exports = class Response extends LazyWritable {
      * over, as node's does; the request's `socket` is the same object and stays, so it comes
      * through here instead.
      *
-     * @returns {any}
+     * @returns {Socket}
      */
     _socketShim() {
         if (!this.#socket) {
@@ -712,7 +405,8 @@ module.exports = class Response extends LazyWritable {
      * 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
+     * @param {any} res the response whose queue is being flushed. Loose because naming the class
+     *   inside its own body makes the checker see two unrelated `this` types
      */
     static #flushOnTick(res) {
         res.#flushBooked = false;
@@ -726,7 +420,7 @@ module.exports = class Response extends LazyWritable {
      * said how much there would be. Backpressure comes back as onWritable, which is what defers the
      * callback rather than dropping the chunk.
      *
-     * @param {any} chunk
+     * @param {any} chunk whatever a Writable was handed, which node does not narrow
      * @param {BufferEncoding} encoding
      * @param {(err?: Error|null) => void} callback
      */
@@ -744,13 +438,15 @@ module.exports = class Response extends LazyWritable {
 
         this.writingChunk = true;
         this._res.cork(() => {
-            if (!this.headersSent) {
-                this.writeHead(this.statusCode);
+            if (!this.#headOut) {
+                if (!this.headersSent) {
+                    this.writeHead(this.statusCode);
+                }
                 // "unknown" and not the bare number: node writes that reason phrase for a code it
                 // has no message for, so the raw status lines match. The default 200 with no
                 // phrase is uWS's own head, byte for byte, so it is not written at all
-                if (this.statusCode !== 200 || this.statusText !== undefined) {
-                    this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+                if (this.#status !== 200 || this.#statusText !== undefined) {
+                    this._res.writeStatus(statusLine(this.#status, this.#statusText));
                 }
                 this.writeHeaders(typeof chunk === "string");
             }
@@ -819,61 +515,43 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Sets the status and, optionally, a batch of headers, the way node does. The second argument
-     * is either the status message or the headers, since node allows both shapes.
-     *
-     * Nothing is written here despite the name: the headers go out when the body does.
+     * is either the status message or the headers, since node allows both shapes. The bytes go out
+     * with the body, but the head is settled here, as node's is: headersSent reads true from now
+     * on, what is set later throws, and a status written later never reaches the wire.
      *
      * Every header goes through setHeader and not through set. This is node's method, not
-     * Express's: Express does not override it, so a content-type given here keeps the value it was
-     * given, where `res.set("content-type", "text/html")` would have a charset appended to it. A
-     * handler that builds its own response and writes it with writeHead is how every meta-framework
-     * on top of Express answers, @astrojs/node and @sveltejs/adapter-node included, so the charset
-     * was being added to pages nobody asked it for.
+     * Express's: a content-type given here keeps the value it was given, where res.set would append
+     * a charset. Every meta-framework on Express answers with writeHead, @astrojs/node and
+     * @sveltejs/adapter-node included, so the charset was added to pages nobody asked it for.
      *
      * @param {number} statusCode
-     * @param {string|Record<string, any>|any[]} [statusMessage] the reason phrase, or the headers
-     * @param {Record<string, any>|any[]} [headers]
+     * @param {string|import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [statusMessage] the
+     *   reason phrase, or the headers
+     * @param {import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [headers]
      * @returns {this}
      */
     writeHead(statusCode, statusMessage, headers) {
-        this.statusCode = statusCode;
-        if (typeof statusMessage === "string") {
-            this.statusText = statusMessage;
-        }
-        if (!headers) {
-            if (!statusMessage) return this;
-            // the two-argument shape, where what looked like a reason phrase is the headers. A
-            // string reaching here was already taken as the phrase above and simply has no keys.
-            headers = /** @type {Record<string, any>} */ (statusMessage);
-        }
-        if (Array.isArray(headers)) {
-            // node takes a flat list here, name then value, and not a list of pairs. An odd length
-            // is the caller's mistake and node names the argument in what it throws
-            if (headers.length % 2 !== 0) {
-                /** @type {NodeJS.ErrnoException} */
-                const err = new TypeError(`The argument 'headers' is invalid. Received ${JSON.stringify(headers)}`);
-                err.code = "ERR_INVALID_ARG_VALUE";
-                throw err;
-            }
-            for (let i = 0; i < headers.length; i += 2) {
-                this.setHeader(headers[i], headers[i + 1]);
-            }
-            return this;
+        if (this.headersSent) {
+            throw headersSentError("write");
         }
-        for (const header in headers) {
-            this.setHeader(header, headers[header]);
+        this.statusCode = statusCode;
+        const reason = applyWriteHead(this, statusMessage, headers);
+        if (reason !== undefined) {
+            this.statusText = reason;
         }
+        this.#status = statusCode;
+        this.#statusText = this.statusText;
+        this.headersSent = true;
         return this;
     }
 
     /**
-     * Writes every header set so far to uWS, which is the point of no return. Content-Length is
-     * not one of them: uWS wants the length through tryEnd or endWithoutBody, so it is taken out
-     * here and kept on totalSize, where it also turns chunked framing off.
+     * Writes every header set so far to uWS, which is the point of no return. Content-Length is not
+     * one of them: uWS wants the length through tryEnd or endWithoutBody, so it is taken out here
+     * and kept on totalSize, where it also turns chunked framing off.
      *
-     * One writeHeader per header on purpose. Packing the whole head into a single writeStatus
-     * works on the wire, and was measured slower: constant header strings cross the boundary
-     * already flat, while the packed head is concatenated fresh per response, see issue #11.
+     * One writeHeader per header on purpose. Packing the whole head into a single writeStatus works
+     * on the wire and measured slower: constant header strings cross already flat, see issue #11.
      *
      * @param {boolean} utf8 unused, kept because node's equivalent takes it and the two callers
      *   differ on what they know about the body
@@ -890,12 +568,10 @@ module.exports = class Response extends LazyWritable {
         // the value here is nearly always the 10-char "keep-alive", which paid a scan per response
         const closing =
             typeof connection === "string" && connection.length === 5 && connection.toLowerCase() === "close";
-        // for..in over an object some responses delete from, which is the shape the request side
-        // was taken off for #rawHeadersEntries. It stays here, and the difference is where the
-        // deletes are: a 200 with a body performs none. Only 204, 304, 205, the freshness branch of
-        // sendFile and removeHeader do, this object is built fresh per response, so a dictionary one
-        // of them made costs that response and nothing after it. The request side deleted on every
-        // request, which is what made it worth a different structure
+        // for..in over an object some responses delete from, the shape the request side was taken
+        // off for #rawHeadersEntries. It stays here because the deletes are rare: only 204, 304,
+        // 205, the freshness branch of sendFile and removeHeader do it, and this object is built
+        // fresh per response. The request side deleted on every request
         for (const header in headers) {
             if (closing && header === "keep-alive") {
                 continue;
@@ -919,16 +595,19 @@ module.exports = class Response extends LazyWritable {
             }
         }
         this.headersSent = true;
+        this.#headOut = true;
     }
 
     /**
-     * What node calls before writing a body when the caller never called writeHead. Here there is
-     * nothing to flush, since the headers are written with the body, so this only fixes the status.
+     * What node calls before writing a body when the caller never called writeHead: it settles the
+     * head, and nothing is flushed, since the headers are written with the body. Not once the head
+     * is settled: the compression module calls this on the strength of node's _header, which this
+     * response does not keep, so the guard is here instead of there.
      */
     _implicitHeader() {
-        // compatibility function
-        // usually should send headers but this is useless for us
-        this.writeHead(this.statusCode);
+        if (!this.headersSent) {
+            this.writeHead(this.statusCode);
+        }
     }
 
     /**
@@ -967,17 +646,29 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * @param {any} [data]
-     * @param {any} [cb]
+     * @param {string|Buffer|Uint8Array|null|(() => void)} [data] the last body piece, or the callback in
+     *   node's one-argument shape
+     * @param {BufferEncoding|(() => void)} [encoding] how a string body is encoded, or the callback in
+     *   node's two-argument shape
+     * @param {() => void} [cb]
      * @returns {this}
      */
-    end(data, cb) {
+    end(data, encoding, cb) {
         if (typeof data === "function") {
             cb = data;
             data = undefined;
+            encoding = undefined;
+        } else if (typeof encoding === "function") {
+            cb = encoding;
+            encoding = undefined;
         }
         if (typeof cb !== "function") {
-            cb = undefined; // silence the error?
+            cb = undefined;
+        }
+        // uWS takes a string as utf-8 and nothing else, so any other encoding is applied here, the
+        // way write() applies it: res.end(data, "binary") is how old code sends an image
+        if (typeof data === "string" && encoding !== undefined && encoding !== "utf8" && encoding !== "utf-8") {
+            data = Buffer.from(data, encoding);
         }
 
         if (this.writingChunk) {
@@ -989,7 +680,11 @@ module.exports = class Response extends LazyWritable {
         if (this.finished) {
             return this;
         }
-        this.writeHead(this.statusCode);
+        // as node's end() calls _implicitHeader: not after an explicit writeHead, which settled the
+        // head already and told on-headers' listeners
+        if (!this.headersSent) {
+            this.writeHead(this.statusCode);
+        }
         // uWS holds the socket corked for the synchronous window of its route handler, and
         // cork inside cork is a passthrough: the wrapper and its closure are only paid once the
         // answer has outlived that window, which is what _corkNeeded records
@@ -1005,42 +700,38 @@ module.exports = class Response extends LazyWritable {
      * The corked tail of end(): status, headers, body and the finish events. Split out so a
      * synchronous answer calls it straight, already inside uWS's own cork.
      *
-     * @param {any} data
-     * @param {any} cb
+     * @param {string|Buffer|Uint8Array|null|undefined} data the last body piece
+     * @param {(() => void)|undefined} cb
      */
     _finish(data, cb) {
         // read before the head is written below, which is what sets the flag: what matters further
         // down is whether something had already committed the framing, a flushHeaders() or a first
         // res.write(), not whether this call is about to write the head itself
-        const headWasAlreadyOut = this.headersSent;
-        if (!this.headersSent) {
-            // freshness is not decided here. node's end() knows nothing about conditional
-            // requests, and Express answers 304 from send() and from sendFile(), each of
-            // which strips the entity headers first. Deciding it here meant res.end("body")
-            // answered 304 and dropped the body that the caller had just written.
-            // "unknown" for a code without a message, as node's status line has it.
-            // The default 200 with no phrase is not written at all: uWS emits the identical
-            // "HTTP/1.1 200 OK" head on its own, and the crossing costs more than it says
-            if (this.statusCode !== 200 || this.statusText !== undefined) {
-                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+        const headWasAlreadyOut = this.#headOut;
+        if (!this.#headOut) {
+            // freshness is not decided here. node's end() knows nothing about conditional requests,
+            // and Express answers 304 from send() and from sendFile(), each of which strips the
+            // entity headers first. Deciding it here made res.end("body") answer 304 and drop the
+            // body the caller had just written.
+            // "unknown" for a code without a message, as node's status line has it. The default 200
+            // with no phrase is not written at all: uWS emits the identical head on its own
+            if (this.#status !== 200 || this.#statusText !== undefined) {
+                this._res.writeStatus(statusLine(this.#status, this.#statusText));
             }
             this.writeHeaders(true);
         }
         const contentLength = this.headers["content-length"];
         // The client said this connection ends here, and it is this end() that has to make it so.
-        // µWS closes by itself for a bare "close" and not for a list, so "keep-alive, close" left
-        // the socket open and the bytes after that request were read as another one: node closes
-        // there, and a server that does not is a server the client and it disagree with about how
-        // many requests were sent. See saysClose.
+        // uWS closes by itself for a bare "close" and not for a list, so "keep-alive, close" left
+        // the socket open and the bytes after that request were read as another one. See saysClose.
         //
-        // Only where a length goes out with it. endWithoutBody takes the flag as its second
+        // Only where a length goes out with it: endWithoutBody takes the flag as its second
         // argument and reads the first as the length whatever it holds, so asking it to close
-        // without one writes "Content-Length: 9223372036854775808" onto a 204. Those two paths keep
-        // µWS's own rule, which closes for a bare "close" and not for a list.
+        // without one writes "Content-Length: 9223372036854775808" onto a 204.
         const closeConnection = this.req._connectionClose === true;
         // 204 and 304 carry no body, so no Content-Length may describe one either; 1xx is the
         // third case, by range
-        if (this.statusCode === 204 || this.statusCode === 304 || this.statusCode < 200) {
+        if (this.#status === 204 || this.#status === 304 || this.#status < 200) {
             // no body and no length describing one, whatever the caller passed. node decides
             // this the same way, from the status alone, so res.status(304).end("x") sends the
             // status and nothing else on either.
@@ -1051,11 +742,9 @@ module.exports = class Response extends LazyWritable {
             // whatever is still queued goes first: end() must not overtake the body written before it
             this.#flushQueued(null);
             // The head has already gone out without a length, which is what flushHeaders() and the
-            // first res.write() both do, so this response is committed to chunked framing and a
-            // length can no longer describe it. node is committed the same way: after a flush,
-            // res.end("body") sends a chunk, not a Content-Length. Handing the body to uWS's end()
-            // here would have it append a length to a head that already said otherwise, which is
-            // what the comparison test caught.
+            // first res.write() both do, so this response is committed to chunked framing. node is
+            // committed the same way: after a flush, res.end("body") sends a chunk. Handing the
+            // body to uWS's end() here would append a length to a head that already said otherwise
             if (data) {
                 this._res.write(data);
                 this._sentBody = data;
@@ -1067,7 +756,7 @@ module.exports = class Response extends LazyWritable {
             if (this.req.method === "HEAD") {
                 const length = Buffer.byteLength(data ?? "");
                 this.headers["content-length"] = String(length);
-                this._res.endWithoutBody(length.toString(), closeConnection);
+                this._res.endWithoutBody(length, closeConnection);
             } else {
                 // 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
@@ -1102,7 +791,8 @@ module.exports = class Response extends LazyWritable {
      */
     send(body) {
         if (this.headersSent) {
-            throw new Error("Can't write body: Response was already sent");
+            // what express's send meets first once the head is out is setHeader's refusal
+            throw headersSentError("set");
         }
         // a typed array is bytes to send, not an object to serialise: res.send(new Uint8Array([104,
         // 101, 121])) is "hey" and not {"0":104,"1":101,"2":121}. Uint8Array and not every view
@@ -1157,13 +847,10 @@ module.exports = class Response extends LazyWritable {
         }
         // the ETag belongs here rather than in end(): node's end() does not produce one, so
         // res.end() and res.redirect() must not either. It has to be set before end() reads
-        // req.fresh, which compares If-None-Match against it.
-        // body is defined by the time it gets here, so an empty one still earns an ETag. Testing
-        // its truthiness instead meant send("") and send(null) came back without one.
-        // Every method by default, not only GET and HEAD: gating it looked safe, freshness being
-        // defined over those two alone, and express's own suite failed on it, "should send ETag
-        // in response to <METHOD> request" exists per method. The "etag methods" setting is that
-        // gate as an opt-in, see issue #10.
+        // req.fresh, which compares If-None-Match against it. body is defined by the time it gets
+        // here, so an empty one still earns an ETag; testing truthiness left send("") and
+        // send(null) without one. Every method by default, not only GET and HEAD: express's own
+        // suite has "should send ETag in response to <METHOD> request" per method, see issue #10
         const hot = this.app._hot();
         const etagFn = hot.etagFn;
         if (
@@ -1205,10 +892,11 @@ module.exports = class Response extends LazyWritable {
      * options position is the callback.
      *
      * Options: `root`, `maxAge`, `lastModified`, `headers`, `dotfiles` ("allow", "deny" or
-     * "ignore"), `acceptRanges`, `cacheControl`, `immutable`, `etag` and `setHeaders`.
+     * "ignore"), `acceptRanges`, `cacheControl`, `immutable` and `etag`.
      *
      * @param {string} path
-     * @param {import("./options").SendFileOptions} [options]
+     * @param {import("./options").SendFileOptions|((err?: Error) => void)} [options] or the callback in
+     *   its place
      * @param {(err?: Error) => void} [callback] called once sent, or with the error
      */
     sendFile(path, options = new NullObject(), callback) {
@@ -1221,20 +909,17 @@ module.exports = class Response extends LazyWritable {
             throw new TypeError("path must be a string to res.sendFile");
         }
         if (typeof options === "function") {
-            callback = /** @type {any} */ (options);
+            callback = options;
             options = new NullObject();
         }
         if (!options) options = new NullObject();
-        // the callback is optional: without one, errors go to next(). The router assigns req.next
-        // before any handler can run, so by the time sendFile is reachable it is always there.
-        // Express's completion handler, exactly: a callback hears everything and the response is
-        // left alone, so it can still answer 200 after a 404 error. Without one, a directory
-        // falls through as a plain next(), and aborts and write errors go nowhere.
-        // the router's next and not the route's: express reports a file it could not serve past
-        // the rest of the route, so a four argument handler written inside the route never sees
-        // it. _leaveRoute is that; req.next is kept for everything else, see Walk#stepOutOfRoute
+        // the callback is optional: without one, errors go to next(). Express's completion handler
+        // exactly: a callback hears everything and the response is left alone, so it can still
+        // answer 200 after a 404 error. Without one, a directory falls through as a plain next().
+        // The router's next and not the route's: express reports a file it could not serve past the
+        // rest of the route, so a four argument handler inside the route never sees it
         const next = this.req._leaveRoute ?? this.req.next;
-        const done = /** @type {(err?: any) => void} */ (
+        const done = /** @type {(err?: NodeJS.ErrnoException) => void} */ (
             (err) => {
                 if (callback) return callback(err);
                 if (err && err.code === "EISDIR") return next();
@@ -1242,16 +927,15 @@ module.exports = class Response extends LazyWritable {
             }
         );
         // default options
-        // Normalised the way send does, and it is not fussiness: max-age takes a non-negative
-        // integer count of seconds, so 0.5, -1 and Infinity are all invalid, and a client that
-        // cannot read the directive may throw away the whole Cache-Control header with it. A
-        // fractional maxAge came out as "max-age=0.5" here, a negative one as "max-age=-1" and
-        // Infinity as "max-age=Infinity".
-        // Number() around the lot, and not only around the branch that is already a number: ms()
-        // answers undefined for a duration it cannot read, and Number.isNaN(undefined) is false,
-        // so an unreadable string reached the header as "max-age=NaN".
+        // Normalised the way send does: max-age takes a non-negative integer count of seconds, so
+        // 0.5, -1 and Infinity are all invalid, and a client that cannot read the directive may
+        // throw away the whole Cache-Control header. Number() around the lot and not only around
+        // the branch that is already a number: ms() answers undefined for a duration it cannot
+        // read, and Number.isNaN(undefined) is false, so an unreadable string reached it as NaN
         const maxAge = Number(
-            typeof options.maxAge === "string" ? ms(/** @type {any} */ (options.maxAge)) : options.maxAge
+            typeof options.maxAge === "string"
+                ? ms(/** @type {import("ms").StringValue} */ (options.maxAge))
+                : options.maxAge
         );
         options.maxAge = Number.isNaN(maxAge) ? 0 : Math.min(Math.max(0, maxAge), MAX_MAXAGE);
         if (typeof options.lastModified === "undefined") {
@@ -1342,14 +1026,15 @@ module.exports = class Response extends LazyWritable {
             } catch (err) {
                 // the fs error itself, carrying its errno and path, with send's status written on
                 // it: a missing file is the request's 404, an unreadable one is the server's 500
-                return done(asStatError(/** @type {any} */ (err)));
+                return done(asStatError(/** @type {import("./utils.js").HttpError} */ (err)));
             }
             if (stat.isDirectory()) {
                 // Express reports a directory as an EISDIR with no status, because send tells it
                 // apart from an error: it emits "directory", and res.sendFile has no listener for
                 // one. So this is not a 404, and an error handler reading err.code sees the code
                 // it expects. Without a callback, done() turns it into a plain next().
-                const err = /** @type {any} */ (new Error("EISDIR, read"));
+                /** @type {NodeJS.ErrnoException} */
+                const err = new Error("EISDIR, read");
                 err.code = "EISDIR";
                 return done(err);
             }
@@ -1377,8 +1062,10 @@ module.exports = class Response extends LazyWritable {
                 this.setHeader(header, options.headers[header]);
             }
         }
-        if (options.setHeaders) {
-            options.setHeaders(/** @type {any} */ (this), fullpath, stat);
+        // express.static's setHeaders, which res.sendFile does not take: express ignores it here,
+        // so it travels under a name only the middleware writes
+        if (options._setHeaders) {
+            options._setHeaders(this, fullpath, stat);
         }
 
         // etag, from the stat and never from the app's "etag fn". send computes this itself with
@@ -1427,7 +1114,10 @@ module.exports = class Response extends LazyWritable {
 
         // range requests
         if (options.acceptRanges) {
-            if (this.req.headers.range) {
+            // only the bytes unit, and send checks the header's text for it before parsing:
+            // "items=0-1" or "Bytes=0-1" is not a range request, and answers the whole file
+            const rangeHeader = this.req.headers.range;
+            if (rangeHeader !== undefined && BYTES_RANGE.test(rangeHeader)) {
                 // the branch above established the header is there, so range() cannot answer
                 // the undefined it uses to mean "no Range header"
                 let ranges = /** @type {ReturnType<typeof import("range-parser")>} */ (
@@ -1486,7 +1176,8 @@ module.exports = class Response extends LazyWritable {
                         // ECONNABORTED to a callback and never to next(), so aborts stay out of
                         // the error middleware.
                         if (this.aborted && callback) {
-                            const err = /** @type {any} */ (new Error("Request aborted"));
+                            /** @type {NodeJS.ErrnoException} */
+                            const err = new Error("Request aborted");
                             err.code = "ECONNABORTED";
                             callback(err);
                         }
@@ -1604,7 +1295,8 @@ module.exports = class Response extends LazyWritable {
      * what a media type is. res.set does that, and is what Express code should use.
      *
      * @param {string} field
-     * @param {any} value an array sends the header once per entry
+     * @param {number|string|readonly string[]|undefined} value an array sends the header once per
+     *   entry; undefined is refused, as node refuses it
      * @returns {this}
      * @throws {Error} once the headers have gone out
      * @throws {TypeError} if the name is not a token, the value is undefined, or the value holds a
@@ -1612,7 +1304,7 @@ module.exports = class Response extends LazyWritable {
      */
     setHeader(field, value) {
         if (this.headersSent) {
-            throw new Error("Cannot set headers after they are sent to the client");
+            throw headersSentError("set");
         }
         // one Map hit for a name already validated and lowercased: middleware writes the same
         // constant names on every request. Insert-only after validation, so no bad name can enter
@@ -1642,14 +1334,13 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * Throws away any header that could not be written, so that flushing this response cannot fail
-     * on one. setHeader refuses these on the way in, but `res.headers` is the live object, so an
+     * Throws away any header that could not be written, so flushing this response cannot fail on
+     * one. setHeader refuses these on the way in, but `res.headers` is the live object, so an
      * assignment into that still gets a value in here.
      *
      * Only the error page calls it. A throw out of the flush there is not recoverable: the error
-     * page is what runs after a throw, so it would be the second one, with nobody left to catch
-     * it, and on the node shim that is the process. Everything writable is left alone, since a
-     * middleware's own headers belong on the error response too.
+     * page is what runs after a throw, so nobody is left to catch it. Everything writable is left
+     * alone, since a middleware's own headers belong on the error response too.
      *
      * @returns {void}
      */
@@ -1663,30 +1354,30 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * 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.
+     * flushHeaders(). `@angular/ssr`'s writeResponseToNodeResponse calls it before streaming a 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.
+     * rejects as HPE_INVALID_CHUNK_SIZE. Checked against v20.69.0.
      *
      * 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.
+     * finished or aborted.
      *
      * @returns {void}
      */
     flushHeaders() {
-        if (this.headersSent || this.finished || this.aborted) {
+        if (this.#headOut || this.finished || this.aborted) {
             return;
         }
         this._res.cork(() => {
-            this.writeHead(this.statusCode);
+            if (!this.headersSent) {
+                this.writeHead(this.statusCode);
+            }
             // the same rule the chunked write path follows: uWS emits the 200 head itself, byte for
             // byte, so writing it again would only cost a crossing
-            if (this.statusCode !== 200 || this.statusText !== undefined) {
-                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+            if (this.#status !== 200 || this.#statusText !== undefined) {
+                this._res.writeStatus(statusLine(this.#status, this.#statusText));
             }
             // true, as the chunked path passes for a string chunk: what follows a flush is a body
             // written in pieces, and the framing has to be the one that allows them
@@ -1695,13 +1386,11 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * node's `writeEarlyHints`, which sends a `103` carrying the resources the page will want, so a
-     * browser can start fetching them while the server is still rendering.
+     * node's `writeEarlyHints`, which sends a `103` carrying the resources the page will want.
      *
-     * **Nothing is sent here.** µWebSockets.js has no API for an informational response, so the
-     * hints cannot reach the wire, and this exists so that code written for Express keeps running
-     * rather than dying on "res.writeEarlyHints is not a function". The callback is still called,
-     * because node calls it once the hints are out and a caller may be waiting on it.
+     * **Nothing is sent here.** uWebSockets.js has no API for an informational response, so this
+     * exists only so code written for Express keeps running instead of dying on
+     * "res.writeEarlyHints is not a function". The callback is still called, as node calls it.
      *
      * `writeContinue` and `writeProcessing` below are the same story with `100` and `102`.
      *
@@ -1745,10 +1434,7 @@ module.exports = class Response extends LazyWritable {
      */
     #refuseInformationAfterHead() {
         if (this.headersSent) {
-            /** @type {NodeJS.ErrnoException} */
-            const err = new Error("Cannot write headers after they are sent to the client");
-            err.code = "ERR_HTTP_HEADERS_SENT";
-            throw err;
+            throw headersSentError("write");
         }
     }
 
@@ -1781,7 +1467,7 @@ module.exports = class Response extends LazyWritable {
      * node's `assignSocket`, which the http server uses when a response is
      * handed a raw socket. There is no such socket here.
      *
-     * @param {any} [socket]
+     * @param {import("net").Socket} [socket] node takes one here and there is none to take
      * @returns {void}
      */
     assignSocket(socket) {}
@@ -1789,7 +1475,7 @@ module.exports = class Response extends LazyWritable {
     /**
      * node's `detachSocket`, which the http server uses when a response is
      * handed a raw socket. There is no such socket here.
-     * @param {any} [socket]
+     * @param {import("net").Socket} [socket] node takes one here and there is none to take
      * @returns {void}
      */
     detachSocket(socket) {}
@@ -1850,10 +1536,10 @@ module.exports = class Response extends LazyWritable {
         const key = name.toLowerCase();
         const current = this.headers[key];
         if (current === undefined) {
-            return this.setHeader(name, /** @type {any} */ (value));
+            return this.setHeader(name, value);
         }
-        const merged = [].concat(/** @type {any} */ (current), /** @type {any} */ (value));
-        return this.setHeader(name, /** @type {any} */ (merged));
+        const merged = /** @type {string[]} */ ([]).concat(current, value);
+        return this.setHeader(name, merged);
     }
 
     /**
@@ -1868,15 +1554,15 @@ module.exports = class Response extends LazyWritable {
         if (typeof Headers === "function" && headers instanceof Headers) {
             for (const name of new Set([...headers.keys()])) {
                 if (name === "set-cookie") {
-                    this.setHeader(name, /** @type {any} */ (headers.getSetCookie()));
+                    this.setHeader(name, headers.getSetCookie());
                 } else {
-                    this.setHeader(name, /** @type {any} */ (headers.get(name)));
+                    this.setHeader(name, /** @type {string} */ (headers.get(name)));
                 }
             }
             return this;
         }
         for (const [name, value] of headers) {
-            this.setHeader(name, /** @type {any} */ (value));
+            this.setHeader(name, value);
         }
         return this;
     }
@@ -1893,8 +1579,8 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * The Express name for set(), including the charset it adds to a content-type.
-     * @param {any} field a header name, or an object of them
-     * @param {any} [value]
+     * @param {string|object} field a header name, or an object of them
+     * @param {string|string[]} [value] the header value, or nothing when the first argument is an object
      * @returns {this}
      */
     header(field, value) {
@@ -1986,6 +1672,9 @@ module.exports = class Response extends LazyWritable {
      * @param {string} field
      */
     removeHeader(field) {
+        if (this.headersSent) {
+            throw headersSentError("remove");
+        }
         const key = field.toLowerCase();
         // the delete is a runtime call, and helmet removes a header most responses never carry
         if (key in this.headers) {
@@ -2019,12 +1708,13 @@ module.exports = class Response extends LazyWritable {
      * Renders a view and sends it. With a callback the result goes to the callback instead, and
      * nothing is sent. A function in the options position is taken as the callback.
      * @param {string} view view name
-     * @param {Record<string, any>} [options] locals for the view
+     * @param {Record<string, any>|((err: Error|null, html?: string) => void)} [options] locals for the
+     *   view, or the callback in its place
      * @param {(err: Error|null, html?: string) => void} [callback]
      */
     render(view, options, callback) {
         if (typeof options === "function") {
-            callback = /** @type {any} */ (options);
+            callback = /** @type {(err: Error|null, html?: string) => void} */ (options);
             options = {};
         }
         if (!options) {
@@ -2062,7 +1752,7 @@ module.exports = class Response extends LazyWritable {
         const opt = { ...(options ?? {}) }; // create a new ref because we change original object (https://github.com/dimdenGD/ultimate-express/issues/68)
         // cookie-parser hangs the secret on the request, so it is read off it rather than
         // declared here: without that middleware there is none, which is what this checks
-        const req = /** @type {any} */ (this.req);
+        const req = /** @type {{secret?: string}} */ (this.req);
         if (opt.signed && !req.secret) {
             // the message has to read like this: it is the one Express throws, and it names the
             // thing that is actually missing rather than the library that noticed
@@ -2081,7 +1771,7 @@ module.exports = class Response extends LazyWritable {
             delete opt.maxAge;
         }
         if (opt.signed) {
-            val = "s:" + sign(val, req.secret);
+            val = "s:" + sign(val, /** @type {string} */ (req.secret));
         }
 
         if (opt.path == null) {
@@ -2126,7 +1816,7 @@ module.exports = class Response extends LazyWritable {
      * Answers according to the Accept header, calling the handler whose key matches best. A
      * `default` key catches everything else; without one an unmatched request gets 406.
      * Sets Vary: Accept.
-     * @param {Record<string, any>} object handlers keyed by extension or mime type
+     * @param {Record<string, Function>} object handlers keyed by extension or mime type
      * @returns {this}
      */
     format(object) {
@@ -2164,11 +1854,14 @@ module.exports = class Response extends LazyWritable {
      * @returns {this}
      */
     json(body) {
+        const hot = this.app._hot();
+        // serialised before the type is set, as express orders it: a body JSON.stringify refuses,
+        // a BigInt for one, throws out of here with the response's headers as they were
+        const json = stringify(body, hot.jsonReplacer, hot.jsonSpaces, hot.jsonEscape);
         if (!this.headers["content-type"]) {
             this.headers["content-type"] = JSON_UTF8;
         }
-        const hot = this.app._hot();
-        return this.send(stringify(body, hot.jsonReplacer, hot.jsonSpaces, hot.jsonEscape));
+        return this.send(json);
     }
 
     /**
@@ -2220,7 +1913,7 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Adds to the Link header, one entry per key, the key being the rel.
-     * @param {Record<string, any>} links rel to url
+     * @param {Record<string, string>} links rel to url
      * @returns {this}
      */
     links(links) {
@@ -2343,7 +2036,7 @@ module.exports = class Response extends LazyWritable {
     vary(field) {
         // the vary package decides: it throws when there is no field at all, and does nothing at
         // all for an empty list, which is not the same thing and used to be refused here as well
-        vary(/** @type {any} */ (this), field);
+        vary(/** @type {import("http").ServerResponse} */ (/** @type {unknown} */ (this)), field);
         return this;
     }
 
@@ -2365,10 +2058,9 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Whether end() has been called. node sets this one there and writableFinished later, once the
-     * bytes are out; here end() hands the whole response to µWS, so the two are the same moment.
+     * bytes are out; here end() hands the whole response to uWS, so the two are the same moment.
      * Without it the base property answered false forever, and an application that asks whether it
-     * has already answered - LibreChat's agent stream does, before it decides whether to keep a
-     * subscription - carried on writing to a response that was over.
+     * has already answered, as LibreChat's agent stream does, kept writing to a dead response.
      */
     // @ts-expect-error TS2611, the accessor replacing the base property is deliberate. Expect
     // rather than ignore, so it fails loudly if it ever stops applying.
@@ -2379,4 +2071,5 @@ module.exports = class Response extends LazyWritable {
 
 // 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;
+/** @type {{contentType?: typeof module.exports.prototype.type}} */ (module.exports.prototype).contentType =
+    module.exports.prototype.type;