Document the Headers class

[harrishancock]

The Headers class is pretty straightforward, but its behavior is the source of some frequently asked questions. We should document its behavior in at least these regards:

• The comma-concatenation behavior of Headers.get(). If a Headers object is constructed from a message with multiple instances of the same header, Headers.get() will return a single string (not an array) with each of the multiple header values concatenated together with intervening ", ".
• The comma-concatenation described above is a valid transformation for any well-behaved header, with one infamous exception: Set-Cookie. For this reason, we implement the old, removed Headers.getAll() function, but only for the Set-Cookie header (it throws if you try to access anything else). You can read the saga behind this here: Use case for Headers getAll whatwg/fetch#973
• The Cloudflare Workers implementation of Headers.get() returns a USVString (or null, of course), not a ByteString as required by the spec. In English, this means we interpret the header bytes on the wire as UTF-8, decode them, and expose them as Unicode strings in JavaScript. We once tried to "fix" this by switching to ByteStrings, but ByteStrings are difficult to use correctly, and in practice it is common to set a header from the contents of URLSearchParams.get(), which returns a USVString, and would thus produce a corrupt header.
• Related to the above, we warn in the preview if a script does try to add a ByteString to a Headers object. Example: https://cloudflareworkers.com/#2b9b84913d7147de5592b6306404e128:https://tutorial.cloudflareworkers.com

/cc @ispivey

[Apro123]

I cannot even get the request headers. It either ends up empty or undefined.
These are the guides I followed, but nothing I did worked.
https://community.cloudflare.com/t/request-headers-comes-as-an-empty-object/181787
https://developers.cloudflare.com/workers/examples/logging-headers

[davidtsong]

Related I think to this issue from the archived docs cloudflare/workers-docs#954

[davidtsong]

@Apro123 the example code seems to be working

[Apro123]

interesting. I have been passing the request object from method to method, so maybe the headers get stripped somewhere, although that might be impossible. I will have to investigate the issue. Thanks @davidtsong

[PierBover]

The example here seems to be broken:

console.log(new Map(request.headers))

// returns

"{unknown map}"