From d6873d607929e4f97e21897139ae2378ed5b724b Mon Sep 17 00:00:00 2001
From: "Kamat, Trivikram" <16024985+trivikr@users.noreply.github.com>
Date: Sun, 6 Oct 2024 23:31:53 -0700
Subject: [PATCH] fetch: add docs on why forbidden header names are not
 supported

---
 lib/web/fetch/headers.js | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/lib/web/fetch/headers.js b/lib/web/fetch/headers.js
index 44b1f52bb3f..3c5e294c9de 100644
--- a/lib/web/fetch/headers.js
+++ b/lib/web/fetch/headers.js
@@ -89,8 +89,9 @@ function appendHeader (headers, name, value) {
   // 1. Normalize value.
   value = headerValueNormalize(value)
 
-  // 2. If name is not a header name or value is not a
-  //    header value, then throw a TypeError.
+  // 2. If validating (name, value) for headers returns false, then return.
+  //    1. If name is not a header name or value is not a header value,
+  //    then throw a TypeError.
   if (!isValidHeaderName(name)) {
     throw webidl.errors.invalidArgument({
       prefix: 'Headers.append',
@@ -105,24 +106,28 @@ function appendHeader (headers, name, value) {
     })
   }
 
-  // 3. If headers’s guard is "immutable", then throw a TypeError.
-  // 4. Otherwise, if headers’s guard is "request" and name is a
-  //    forbidden header name, return.
-  // 5. Otherwise, if headers’s guard is "request-no-cors":
-  //    TODO
-  // Note: undici does not implement forbidden header names
+  //    2. If headers’s guard is "immutable", then throw a TypeError.
   if (getHeadersGuard(headers) === 'immutable') {
     throw new TypeError('immutable')
   }
 
-  // 6. Otherwise, if headers’s guard is "response" and name is a
-  //    forbidden response-header name, return.
+  //    3. If headers’s guard is "request" and (name, value) is a forbidden
+  //    request-header, then return.
+  //    4. If headers’s guard is "response" and name is a forbidden
+  //    response-header name, then return.
+  // Note: undici deviates from the spec, and does not implement forbidden
+  // header names to match the behavior of Deno and node-fetch. A server-side
+  // fetch unable to pass all kinds of headers around is not useful.
 
-  // 7. Append (name, value) to headers’s header list.
+  // 3. If headers’s guard is "request-no-cors":
+  // TODO
+
+  // 4. Append (name, value) to headers’s header list.
   return getHeadersList(headers).append(name, value, false)
 
-  // 8. If headers’s guard is "request-no-cors", then remove
+  // 5. If headers’s guard is "request-no-cors", then remove
   //    privileged no-CORS request headers from headers
+  // TODO
 }
 
 // https://fetch.spec.whatwg.org/#concept-header-list-sort-and-combine