add doc for Headers.getSetCookie()

[chrisdavidmills]

Description

The Headers.getSetCookie() method has been added to Chrome 113. This PR adds a reference document for this new method.

This is a pretty straightforward addition. You can find other useful links in my research document.

One question I had — the Set-Cookie header page includes a note:

Warning: Browsers block frontend JavaScript code from accessing the Set-Cookie header, as required by the Fetch spec, which defines Set-Cookie as a forbidden response-header name that must be filtered out from any response exposed to frontend code.

This sounds contradictory to the purpose of getSetCookie() — has this note interpreted the spec correctly, and if so, should I update it to list getSetCookie() as an exception to this rule?

Motivation

Additional details

Related issues and pull requests

Fix #24266

[github-actions]

Preview URLs

• /en-US/docs/Web/API/Headers/getSetCookie
• /en-US/docs/Web/API/Headers

Flaws (1)

Note! 1 document with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Headers/getSetCookie
Title: Headers: getSetCookie() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.Headers.getSetCookie

External URLs (1)

URL: /en-US/docs/Web/API/Headers/getSetCookie
Title: Headers: getSetCookie() method

• https://fetch.spec.whatwg.org/ (2 times) (Note! This may be a new URL 👀)

(comment last updated: 2023-04-17 17:10:45)

[Josh-Cena]

This sounds contradictory to the purpose of getSetCookie() — has this note interpreted the spec correctly, and if so, should I update it to list getSetCookie() as an exception to this rule?

AFAICT, this method is intended for server environments, such as Cloudflare workers and Node.js. Client code cannot create or obtain a response with Set-Cookie, but that's not fundamentally contradictory to this method's presence on an existing response. See: whatwg/fetch#973

[ricea]

Because the Set-Cookie header is stripped from responses on the network, the example as it stands is misleading. I haven't been able to come up with a compelling example, but you can do something like:

const headers = new Headers({
    "Set-Cookie": "name=value",
});
headers.getSetCookie();

[chrisdavidmills]

This sounds contradictory to the purpose of getSetCookie() — has this note interpreted the spec correctly, and if so, should I update it to list getSetCookie() as an exception to this rule?

AFAICT, this method is intended for server environments, such as Cloudflare workers and Node.js. Client code cannot create or obtain a response with Set-Cookie, but that's not fundamentally contradictory to this method's presence on an existing response. See: whatwg/fetch#973

Thanks @Josh-Cena , that makes total sense.

[chrisdavidmills]

Because the Set-Cookie header is stripped from responses on the network, the example as it stands is misleading. I haven't been able to come up with a compelling example, but you can do something like:

Thanks @ricea. I've updated the page now; let me know what you think

[ricea]

lgtm with nitpick

[ricea]

This will work in the browser too, so you can remove the words "on the server".

It's only when communicating with the network that the Set-Cookie header is removed. As long as you stay in JavaScript, you can use it (it's just not very useful).

[chrisdavidmills]

Makes sense. I've updated the wording again but tried something slightly different to get all the points across that you made in the above message.

[Josh-Cena]

Another random drive-by: the motivation for the method is to retrieve multiple Set-Cookie values. Would be cool to have an example like that.

[chrisdavidmills]

Another random drive-by: the motivation for the method is to retrieve multiple Set-Cookie values. Would be cool to have an example like that.

Makes sense; I've updated the second example to show this.

[Josh-Cena]

This is against how JS object literals work: later properties always override the former, so the Headers constructor cannot possibly see both properties. You need to set the header later.

const headers = new Headers({
  "Set-Cookie": "name1=value1",
});
headers.append("Set-Cookie", "name2=value2");
headers.getSetCookie();

(Can't test because my Chrome Canary doesn't seem to have this yet)

[chrisdavidmills]

Darnit; that was a silly mistake. This is what happens when you try to do things quickly. Fixed now; thanks ;-)

And I tested the code on my Canary just to make sure.

[ricea]

lgtm, thanks!

[chrisdavidmills]

lgtm, thanks!

@ricea super, thanks for the review.

@Elchi3 , I know you merged the BCD for this one. Can you give the method page a quick look and merge? Thanks in advance.

[Elchi3]

Thanks Chris and everyone! 👍