Clarify and fix use of @internal Request response headers

Author: zefir-git

src/Request.ts

@@ -261,7 +261,9 @@ export class Request<A> {
     }
 
     /**
-     * Response headers that the Response to this request should include.
+     * Set in advance response headers that the Response to this request should include. Do not use if a Response
+     * context is available (use {@link Response#headers} instead). Responses cannot see these headers and may overwrite
+     * them if there is a collision.
      * @internal
      */
     public _responseHeaders = new Headers();

src/response/BufferResponse.ts

@@ -14,10 +14,12 @@ export abstract class BufferResponse<A> extends Response<A> {
     protected override async send(res: http.ServerResponse, req?: Request<A>): Promise<void> {
         const buffer = await this.readBuffer();
         if (req !== undefined) {
-            if (res.chunkedEncoding)
-                req._responseHeaders.set("transfer-encoding", "chunked");
-            else
-                req._responseHeaders.set("content-length", buffer.byteLength.toString());
+            if (res.chunkedEncoding) {
+                if (!this.headers.has("transfer-encoding"))
+                    this.headers.set("transfer-encoding", "chunked");
+            }
+            else if (!this.headers.has("content-length"))
+                this.headers.set("content-length", buffer.byteLength.toString());
         }
         this.writeHead(res, req);
         res.end(buffer);

src/response/Response.ts

@@ -67,7 +67,8 @@ export abstract class Response<A> {
     }
 
     /**
-     * Set the HTTP response status code and headers.
+     * Set and send the HTTP response status code and headers. No more headers can be sent after this.
+     * @final
      */
     protected writeHead(res: http.ServerResponse, req?: Request<A>) {
         const headers = this.allHeaders(res, req);