HTTP CORS documentation is unclear on who participates in server requests/responses

[szentpali-janos]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

What specific section or headline is this issue about?

Examples of access control scenarios

What information was incorrect, unhelpful, or incomplete?

CORS is about a client and at least two servers. Throughout the examples it is unclear which server participates in the example transaction. There is a single example where the Host header hints at the identity of the server taking part in the transaction. As is the documentation is a guesswork for the reader, so not really a documentation. It would help immensely if the transaction diagrams and exchange request/responses would clearly state which server requests from which server.

What did you expect to see?

Servers clearly identified both in drawings and transaction payloads.

Do you have any supporting links, references, or citations?

No

Do you have anything more you want to share?

No

MDN metadata

Page report details

• Folder: en-us/web/http/cors
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/http/cors/index.md
• Last commit: f75b2c8
• Document last modified: 2024-10-01T22:01:14.000Z

[Josh-Cena]

CORS is about a client and at least two servers.

Your confusion seems to be based on this, but I fail to see how this claim is true. CORS only involves one client and one server, where the client is on a different origin as the server. All our existing diagrams in the section in question only involve one client and one server because there are no more parties at play.

[szentpali-janos]

Sorry, but if there is one server and one client, why is CORS needed at all? Cross origin between which one server?

[Josh-Cena]

Cross-origin between the client and the server. For example you call fetch("some-origin") in a page that's on another origin.

[szentpali-janos]

So

in a page that's on another origin
does not mean a different domain (server) (or scheme)?

[Josh-Cena]

The scheme and domain are both parts of the origin.

For example, suppose the client-side JS of https://developer.mozilla.org sends a request to https://github.com. That would be a CORS request and subject to the CORS constraints.

[szentpali-janos]

OK, so while physically "developer.mozilla.org" and "github.com" can be the same host, that is invisible to clients and are technically two server/domains.
And in the docs it would be nice to be clear which of those (or the code served from which of those) accesses which other.

[Josh-Cena]

I'll defer the decision to @wbamberg, but I think the current example is clear enough. There's only one server responding to requests (and handling CORS), which is the destination of fetch. While technically "developer.mozilla.org" is also a server, it does little more than responding to GET requests by responding with HTML/JS assets. It only functions as a client.

[wbamberg]

Josh is right. There's only one server in these example scenarios.

Sorry, but if there is one server and one client, why is CORS needed at all? Cross origin between which one server?

Well sort of. You might say, the bit with the first server took place before these scenarios.

So this is what happens in full:

1. The user types https://foo.example into their address bar.
2. The browser makes a request to the server at https://foo.example, gets back the response, and renders it.
3. Now the origin of this document in the browser (i.e. the client) is https://foo.example ("origin" literally means "the place this came from")
4. In this document, the user (for instance) clicks a button that wants to make a request to https://bar.other. This is a cross-origin request.
5. The browser starts the CORS process.

The examples in this section of the docs omit the first two steps here: they start with a document served from (="with an origin of") https://foo.example. All the interaction after that point is with https://bar.other. From that point on really, the server at https://foo.example might have exploded, and the rest of the flow would not be affected.

This is I guess implicit in bits like this:

For example, suppose web content at https://foo.example wishes to fetch JSON content from domain https://bar.other.

I wonder if "web content served from https://foo.example" might be better than "web content at https://foo.example"? I wonder if annotating the sequence diagrams to include the document's origin might help? I wonder if talking a bit more about the initial exchange with the first server might help?

[wbamberg]

What do you think about something like this:

I am a little concerned that this doesn't distinguish the difference between the annotations, that "foo.example" is the origin and "bar.other" is the URL. I tried that but it looks a bit noisy:

Interested in what people think. If we don't think this is an improvement I think we should just close this issue, or just change:

For example, suppose web content at https://foo.example/ wishes to fetch JSON content from domain https://bar.other/.

to "web content served from https://foo.example", but I think a change like that is unlikely to help people much.

[szentpali-janos]

That is very good as far as I am concerned.
Only thing that I'd do differently is the domain (name) of the origin (foo.example) and resource (bar.other) in that I'd use the same domain (names) as the ones at the beginning of the article: domain-a.com and domain-b.com.
Maybe the Origin: https://foo.exampe on the "Client" box is not necessary as it is implied by the "Origin" header below the "GET" request?

[wbamberg]

Only thing that I'd do differently is the domain (name) of the origin (foo.example) and resource (bar.other) in that I'd use the same domain (names) as the ones at the beginning of the article: domain-a.com and domain-b.com.

Yeah, I agree we should do this too. For me at least foo.example and bar.other are better as names though (more obviously different) so I would prefer to use them everywhere.

[szentpali-janos]

Yes, I agree, for someone learning about CORS, using foo.example and bar.other vs. domain-a and domain-b might be less distracting/confusing. As long as it is used consistently.