Extend warning in Set-Cookie article

[amaralis]

Description

Extends the first warning of the article, also related to browser behavior, to alert readers to a relatively obscure and hard to debug characteristic of the Set-Cookie response header. This should have been part of PR #34798 and I apologize for the added work load.

Motivation

Alert readers to this obscure behavior, about which I found nothing up to the 5th page of Google. Tie together the additions in PR #34798, offering the most relevant links to better help developers understand and fix issues if they arise (especially relevant if a developer isn't using an http client library, such as Axios). From this addition, readers have a central point to read up on the various moving parts of the problem, and those articles also link between themselves regularly.

Additional details

Research was done and testing confirms what I am submitting. Sources include the fetch spec and links are included in the submitted text.

Related issues and pull requests

Relates to PR #34798

[github-actions]

Preview URLs

• /en-US/docs/Web/HTTP/Headers/Set-Cookie

External URLs (1)

URL: /en-US/docs/Web/HTTP/Headers/Set-Cookie
Title: Set-Cookie

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

(comment last updated: 2024-07-14 20:31:22)

[hamishwillee]

Fly by comment, - perhaps make it clear this is a fetch request.

Suggested change

> When a request [uses CORS](/en-US/docs/Web/HTTP/CORS#what_requests_use_cors), [browsers will ignore `Set-Cookie` headers](https://fetch.spec.whatwg.org/#cors-protocol-examples) present in the server's response unless the request has a value of `'include'` set for the `credentials` property of the {{domxref("RequestInit")}} object passed as the `options` argument to the {{domxref("Request.Request","Request()")}} constructor. See also section [4.6, #15](https://fetch.spec.whatwg.org/#http-network-fetch) of the [Fetch Living Standard](https://fetch.spec.whatwg.org/), and [Using the Fetch API - Including credentials](/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials) for more guidance.

> When a [Fetch API](/en-US/docs/Web/API/Fetch_API/Using_Fetch) request [uses CORS](/en-US/docs/Web/HTTP/CORS#what_requests_use_cors), [browsers will ignore `Set-Cookie` headers](https://fetch.spec.whatwg.org/#cors-protocol-examples) present in the server's response unless the request has a value of `'include'` set for the `credentials` property of the {{domxref("RequestInit")}} object passed as the `options` argument to the {{domxref("Request.Request","Request()")}} constructor. See also section [4.6, #15](https://fetch.spec.whatwg.org/#http-network-fetch) of the [Fetch Living Standard](https://fetch.spec.whatwg.org/), and [Using the Fetch API - Including credentials](/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials) for more guidance.

[amaralis]

Fly by comment, - perhaps make it clear this is a fetch request.

You raise a valid point. I'm trying to be brief, but the problem exists with XmlHttpRequest as well. This makes the issue apply to a variety of http client libraries too, along with jquery ajax requests.
Picking up where you left off, could it be more reasonable to remove the mentions of concrete elements here and address the credentials issue in more generic terms, linking to the relevant documentation more towards the end? Technical aspects aside, I believe it may make the syntax less convoluted than my initial commit. I also suggest a more convenient link for the fetch spec below, as well as removing the "for more guidance" final part, which is what this documentation does, not the standards. Something like:

Suggested change

> When a request [uses CORS](/en-US/docs/Web/HTTP/CORS#what_requests_use_cors), [browsers will ignore `Set-Cookie` headers](https://fetch.spec.whatwg.org/#cors-protocol-examples) present in the server's response unless the request has a value of `'include'` set for the `credentials` property of the {{domxref("RequestInit")}} object passed as the `options` argument to the {{domxref("Request.Request","Request()")}} constructor. See also section [4.6, #15](https://fetch.spec.whatwg.org/#http-network-fetch) of the [Fetch Living Standard](https://fetch.spec.whatwg.org/), and [Using the Fetch API - Including credentials](/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials) for more guidance.

> When a [Fetch API](/en-US/docs/Web/API/Fetch_API/Using_Fetch) or [XMLHttpRequest API](en-US/docs/Web/API/XMLHttpRequest_API) request [uses CORS](/en-US/docs/Web/HTTP/CORS#what_requests_use_cors), browsers will ignore `Set-Cookie` headers present in the server's response unless the request includes credentials. Visit [Using the Fetch API - Including credentials](/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials) and the [XMLHttpRequest article](en-US/docs/Web/API/XMLHttpRequest_API) to learn how to include credentials. See also the [credentials mode section](https://fetch.spec.whatwg.org/#concept-request-credentials-mode) of the [Fetch Living Standard](https://fetch.spec.whatwg.org/), and [the withCredentials attribute](https://xhr.spec.whatwg.org/#the-withcredentials-attribute) of the [XMLHttpRequest Living Standard](https://xhr.spec.whatwg.org/).

Does this seem like a more appropriate approach?

[hamishwillee]

I'm OK with forward linking, but we should not link to the specs. The spec wording is often designed for browser authors not developers, which is why MDN exists.

[hamishwillee]

Note, I have only made fly by comment, which means that I haven't fully reviewed or tested this. Don't have bandwidth for the next couple of weeks.

[amaralis]

I'm OK with forward linking, but we should not link to the specs. The spec wording is often designed for browser authors not developers, which is why MDN exists.

I wouldn't presume to demand your time, and will keep watch until you have the opportunity to take a look at it. As for linking the specs, I was under the impression it was good practice, as there are already links to them in this same warning text bubble. But from my perspective, I find it easier to read without the spec links, and the issues I faced would have been prevented without them anyway, since the remaining linked pages have the topic pretty much covered already. The problem here isn't complexity, it's that I couldn't find any information about this anywhere else. I'll leave the suggested change below until it can be reviewed. The links to the specs in my previous suggestion should make the review process relatively painless when it happens.

Suggested change

> When a request [uses CORS](/en-US/docs/Web/HTTP/CORS#what_requests_use_cors), [browsers will ignore `Set-Cookie` headers](https://fetch.spec.whatwg.org/#cors-protocol-examples) present in the server's response unless the request has a value of `'include'` set for the `credentials` property of the {{domxref("RequestInit")}} object passed as the `options` argument to the {{domxref("Request.Request","Request()")}} constructor. See also section [4.6, #15](https://fetch.spec.whatwg.org/#http-network-fetch) of the [Fetch Living Standard](https://fetch.spec.whatwg.org/), and [Using the Fetch API - Including credentials](/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials) for more guidance.

> When a [Fetch API](/en-US/docs/Web/API/Fetch_API/Using_Fetch) or [XMLHttpRequest API](en-US/docs/Web/API/XMLHttpRequest_API) request [uses CORS](/en-US/docs/Web/HTTP/CORS#what_requests_use_cors), browsers will ignore `Set-Cookie` headers present in the server's response unless the request includes credentials. Visit [Using the Fetch API - Including credentials](/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials) and the [XMLHttpRequest article](en-US/docs/Web/API/XMLHttpRequest_API) to learn how to include credentials.