fulmine.js 5.19.3 → 5.19.5

package/src/response.js

@@ -34,11 +34,13 @@ const {
     validateHeaderName,
     validateHeaderValue,
     headerIsWritable,
-    withDefaultCharset,
     withUtf8Charset,
     asStatError,
     httpError,
+    headersSentError,
+    applyWriteHead,
     contentTypeFor,
+    contentTypeSet,
     statTag,
     cachedStat,
     NullObject
@@ -47,6 +49,35 @@ const { isAbsolute } = require("path");
 const fs = require("fs");
 const Path = require("path");
 const statuses = require("statuses");
+
+/**
+ * The TypeError node throws for a chunk that is not a string, a Buffer or a Uint8Array, named the
+ * way node names it: a primitive by type and value, an object by its constructor.
+ *
+ * @param {unknown} chunk what end() was handed, known here not to be a string or a Uint8Array
+ * @returns {NodeJS.ErrnoException}
+ */
+function invalidChunkError(chunk) {
+    let received;
+    if (chunk === null) {
+        received = "null";
+    } else if (typeof chunk === "object" || typeof chunk === "function") {
+        const name = /** @type {any} */ (chunk).constructor?.name;
+        received = name ? `an instance of ${name}` : "an instance of Object";
+    } else if (typeof chunk === "bigint") {
+        received = `type bigint (${chunk}n)`;
+    } else if (typeof chunk === "symbol") {
+        received = `type symbol (${String(chunk)})`;
+    } else {
+        received = `type ${typeof chunk} (${chunk})`;
+    }
+    /** @type {NodeJS.ErrnoException} */
+    const err = new TypeError(
+        `The "chunk" argument must be of type string or an instance of Buffer or Uint8Array. Received ${received}`
+    );
+    err.code = "ERR_INVALID_ARG_TYPE";
+    return err;
+}
 const { sign } = require("cookie-signature");
 const ms = require("ms");
 const Socket = require("./socket.js");
@@ -75,10 +106,17 @@ const COALESCE_BELOW = 4 * 1024;
 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";
+
+// The Keep-Alive every response is seeded with, kept as a constant so setHeader can tell it apart
+// from one the application set itself.
+const SEEDED_KEEP_ALIVE = "timeout=10";
 // send's ceiling for maxAge, one year in milliseconds. Anything larger is clamped to it rather
 // than written out, since a year is already longer than any cache will honour.
 const MAX_MAXAGE = 60 * 60 * 24 * 365 * 1000;
 
+// 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} */
     #socket = null;
@@ -106,15 +144,21 @@ module.exports = class Response extends LazyWritable {
     /** Whether a flush is already booked for the end of this turn. */
     #flushBooked = false;
 
-    /** @type {any} */
-    #outHeaders = null;
+    /** Whether the status line and the headers have reached uWS, which only a body write does. */
+    #headOut = false;
 
     /**
-     * Whether node's writeHead has run, which only the per-app subclass sets. _sendOptionsReply
-     * refuses to write a second head over it, as node's setHeader does.
-     * @type {boolean|undefined}
+     * 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}
      */
-    _headWritten;
+    #status = 200;
+
+    /** @type {string|undefined} */
+    #statusText = undefined;
+
+    /** @type {Response["headers"]|null} */
+    #outHeaders = null;
 
     /**
      * The request this response answers, linked so either reaches the other.
@@ -127,10 +171,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. Loose because the per-app subclass in
-     *   application.js inherits this constructor and its own shape has to stay assignable
-     * @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();
@@ -139,6 +182,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,
@@ -176,7 +220,7 @@ module.exports = class Response extends LazyWritable {
                 ? {}
                 : {
                       connection: "keep-alive",
-                      "keep-alive": "timeout=10"
+                      "keep-alive": SEEDED_KEEP_ALIVE
                   };
         // the client asked for the connection to be closed, and uWS closes it, so saying otherwise
         // would be telling the client something the transport contradicts. A declarative response
@@ -191,7 +235,7 @@ 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
@@ -206,8 +250,7 @@ module.exports = class Response extends LazyWritable {
         //
         // 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.
-        // cast because _events and _eventsCount are EventEmitter's own bookkeeping and have no type
-        const self = /** @type {any} */ (this);
+        const self = this;
         const events = self._events;
         if (
             self._eventsCount === 0 &&
@@ -252,7 +295,7 @@ module.exports = class Response extends LazyWritable {
      * 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] whatever the caller is destroying the response with
+     * @param {Error} [error] whatever the caller is destroying the response with
      * @returns {this}
      */
     destroy(error) {
@@ -282,7 +325,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) {
@@ -337,7 +380,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) {
@@ -428,13 +471,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");
             }
@@ -503,8 +548,9 @@ 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: a content-type given here keeps the value it was given, where res.set would append
@@ -512,38 +558,33 @@ module.exports = class Response extends LazyWritable {
      * @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) {
+        if (this.headersSent) {
+            throw headersSentError("write");
+        }
         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]);
+        let reason;
+        try {
+            reason = applyWriteHead(this, statusMessage, headers);
+        } catch (err) {
+            // node fixes the phrase before it reads the headers and keeps it, so a 500 after a
+            // writeHead that threw goes out as "500 OK"
+            if (!this.statusText) {
+                this.statusText = typeof statusMessage === "string" ? statusMessage : statuses.message[statusCode];
             }
-            return this;
+            throw err;
         }
-        for (const header in headers) {
-            this.setHeader(header, headers[header]);
+        if (reason !== undefined) {
+            this.statusText = reason;
         }
+        this.#status = statusCode;
+        this.#statusText = this.statusText;
+        this.headersSent = true;
         return this;
     }
 
@@ -597,16 +638,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);
+        }
     }
 
     /**
@@ -645,17 +689,38 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * @param {any} [data] the last body piece, or the callback in node's two-argument shape
-     * @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;
+        }
+        // node refuses a chunk that is not a string, a Buffer or a Uint8Array, and writes it only
+        // `if (chunk)`, so end(0) sends nothing. A number reached uWS and answered nothing at all.
+        // The typeof goes first so a string body, which is nearly every body, leaves on it alone
+        if (typeof data !== "string" && data !== undefined && !(data instanceof Uint8Array)) {
+            if (data) {
+                throw invalidChunkError(data);
+            }
+            data = 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) {
@@ -667,7 +732,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
@@ -683,23 +752,23 @@ 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 the last body piece
-     * @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) {
+        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.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(true);
         }
@@ -714,7 +783,7 @@ module.exports = class Response extends LazyWritable {
         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.
@@ -739,7 +808,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
@@ -774,7 +843,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
@@ -788,6 +858,16 @@ module.exports = class Response extends LazyWritable {
         // that happens to be empty: no content-type and no ETag for send(), both for send(null)
         // and send("").
         if (body === undefined) {
+            // still through freshness and the bodiless statuses, as every express send is: a 204
+            // answered with json(undefined) loses the type json had set
+            if (this.req.fresh) {
+                this.status(304);
+            }
+            if (this.statusCode === 204 || this.statusCode === 304) {
+                delete this.headers["content-type"];
+                delete this.headers["content-length"];
+                delete this.headers["transfer-encoding"];
+            }
             return this.end("");
         }
         // null is an object as far as Express's switch is concerned, so it becomes the empty
@@ -805,8 +885,15 @@ module.exports = class Response extends LazyWritable {
             return this.json(body);
         } else if (typeof body === "boolean") {
             return this.json(body);
-        } else if (!isBuffer) {
-            body = String(body);
+        } else if (!isBuffer && typeof body !== "string") {
+            // a symbol, a bigint or a function: express sizes it with byteLength or from(), and
+            // neither takes it, so what node throws is the answer. A string never gets here: it
+            // is the common body, and measuring it twice cost 157us per thousand requests
+            const generateETag = !this.headers["etag"] && typeof this.app._hot().etagFn === "function";
+            if (!generateETag && body.length < 1000) {
+                Buffer.byteLength(body, "utf8");
+            }
+            Buffer.from(body, "utf8");
         }
         if (typeof body === "string" && !isBuffer) {
             const contentType = this.headers["content-type"];
@@ -874,10 +961,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) {
@@ -890,7 +978,7 @@ 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();
@@ -900,7 +988,7 @@ module.exports = class Response extends LazyWritable {
         // 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();
@@ -914,7 +1002,9 @@ module.exports = class Response extends LazyWritable {
         // 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") {
@@ -1005,14 +1095,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);
             }
@@ -1040,8 +1131,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
@@ -1090,7 +1183,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")>} */ (
@@ -1103,10 +1199,13 @@ module.exports = class Response extends LazyWritable {
                 }
 
                 if (ranges === -1) {
-                    // the header goes on the response itself, as send writes it before raising
-                    // the error, and the status stays on the error for the handler to apply
-                    this.headers["content-range"] = `bytes */${len}`;
-                    return done(httpError(416));
+                    // on the response as send writes it, and on the error too: the error page
+                    // drops the content headers and writes back only what the error carries
+                    const unsatisfiable = `bytes */${len}`;
+                    this.headers["content-range"] = unsatisfiable;
+                    const err = httpError(416);
+                    err.headers = { "Content-Range": unsatisfiable };
+                    return done(err);
                 }
                 if (ranges !== -2 && ranges.length === 1) {
                     this.status(206);
@@ -1149,7 +1248,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);
                         }
@@ -1267,7 +1367,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
@@ -1275,7 +1376,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
@@ -1300,6 +1401,14 @@ module.exports = class Response extends LazyWritable {
         // catch it
         const out = Array.isArray(value) ? value.map(String) : String(value);
         validateHeaderValue(field, out);
+        // node writes Connection and Keep-Alive as a pair, and writes neither once the response has
+        // set Connection itself, so the seeded Keep-Alive goes with it. Anything that opens an
+        // event stream sets Connection: the MCP transport does, and so does every SSE library.
+        if (key === "connection" && this.headers["keep-alive"] === SEEDED_KEEP_ALIVE) {
+            // through an index signature: the seeded pair is not optional in what the constructor
+            // infers, so a plain delete of it is a type error
+            delete (/** @type {Record<string, string|string[]>} */ (this.headers)["keep-alive"]);
+        }
         this.headers[key] = out;
         return this;
     }
@@ -1338,15 +1447,17 @@ module.exports = class Response extends LazyWritable {
      * @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
@@ -1403,10 +1514,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");
         }
     }
 
@@ -1439,7 +1547,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] node takes one here and there is none to take
+     * @param {import("net").Socket} [socket] node takes one here and there is none to take
      * @returns {void}
      */
     assignSocket(socket) {}
@@ -1447,7 +1555,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] node takes one here and there is none to take
+     * @param {import("net").Socket} [socket] node takes one here and there is none to take
      * @returns {void}
      */
     detachSocket(socket) {}
@@ -1508,10 +1616,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);
     }
 
     /**
@@ -1526,15 +1634,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;
     }
@@ -1551,8 +1659,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] the header value, or nothing when the first argument is an object
+     * @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) {
@@ -1581,9 +1689,17 @@ module.exports = class Response extends LazyWritable {
                 if (Array.isArray(out)) {
                     throw new TypeError("Content-Type cannot be set to an Array");
                 }
-                // every type the mime database gives a charset, not a list of three. The list was
-                // missing application/manifest+json among others, which Express does charset.
-                out = withDefaultCharset(out);
+                // an extension becomes its media type here, charset included
+                const resolved = contentTypeSet(out);
+                if (resolved === false) {
+                    // what the mime database knows nothing about is stored as the false express
+                    // stores, so send() and json() read it as unset and write their own type.
+                    // Through setHeader first, for the checks, then the boolean over the string
+                    this.setHeader(field, "false");
+                    this.headers[name] = /** @type {any} */ (false);
+                    return this;
+                }
+                out = resolved;
             }
             // the name as it was written, not the lowercased one: setHeader lowercases it itself,
             // and it is the name that a refused header is reported by, which Express takes from
@@ -1644,6 +1760,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) {
@@ -1677,12 +1796,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) {
@@ -1720,7 +1840,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
@@ -1739,7 +1859,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) {
@@ -1784,7 +1904,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) {
@@ -1822,11 +1942,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);
     }
 
     /**
@@ -1878,7 +2001,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) {
@@ -1981,7 +2104,8 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Sets Content-Type. An extension is looked up as a mime type and gets a charset; anything
-     * containing a slash is used as written. Also available as `contentType()`.
+     * containing a slash is used as written. An extension the database does not know falls back
+     * to octet-stream here, which res.set does not do. Also available as `contentType()`.
      * @param {string} type
      * @returns {this}
      */
@@ -2001,7 +2125,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;
     }
 
@@ -2036,4 +2160,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;