Clarify and fix use of @internal Request response headers (#59)

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

@@ -9,17 +9,23 @@ export abstract class BufferResponse<A> extends Response<A> {
     /**
      * Fetch the buffer to send in the response body.
      */
-    protected abstract readBuffer(): Uint8Array | Promise<Uint8Array>;
+    protected abstract readonly buffer: Uint8Array;
 
-    protected override async send(res: http.ServerResponse, req?: Request<A>): Promise<void> {
-        const buffer = await this.readBuffer();
+    public override allHeaders(res: http.ServerResponse, req?: Request<A>) {
+        const headers = super.allHeaders(res, req);
         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 (!headers.has("transfer-encoding"))
+                    headers.set("transfer-encoding", "chunked");
+            }
+            else if (!headers.has("content-length"))
+                headers.set("content-length", this.buffer.byteLength.toString());
         }
+        return headers;
+    }
+
+    protected override async send(res: http.ServerResponse, req?: Request<A>): Promise<void> {
         this.writeHead(res, req);
-        res.end(buffer);
+        res.end(this.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);

src/response/TextResponse.ts

@@ -1,13 +1,12 @@
+import http from "node:http";
+import {Request} from "../Request.js";
 import {BufferResponse} from "./BufferResponse.js";
 
 /**
  * An HTTP response with a plain text body.
  */
 export class TextResponse<A> extends BufferResponse<A> {
-    /**
-     * The plain text body of the response.
-     */
-    protected readonly text: string;
+    protected override readonly buffer: Uint8Array;
     private readonly encoder = new TextEncoder();
 
     /**
@@ -18,12 +17,13 @@ export class TextResponse<A> extends BufferResponse<A> {
      */
     public constructor(text: string, statusCode = 200, headers?: HeadersInit) {
         super(statusCode, headers);
-        this.text = text;
-        if (!this.headers.has("content-type"))
-            this.headers.set("content-type", "text/plain");
+        this.buffer = this.encoder.encode(text);
     }
 
-    public override readBuffer() {
-        return this.encoder.encode(this.text);
+    public override allHeaders(res: http.ServerResponse, req?: Request<A>): Headers {
+        const headers = super.allHeaders(res, req);
+        if (!headers.has("content-type"))
+            headers.set("content-type", "text/plain");
+        return headers;
     }
 }