[whatwg/fetch] Add a flow diagrams for in-browser/client-side request flow and response flow (#1227)

It would be great if the Fetch spec had flow/branching diagrams that illustrate the request flow and response flow — with a key piece being to show the decisions the browser makes about whether a particular request gets sent out or instead blocked, and whether the browser exposes the response to frontend code, or instead blocks access to response.

The diagrams would need to include/reference the various other mechanisms, such as CSP, that come into play.

For example, somewhere in the diagram there would be a decision point where the browser checks the configured CSP policy, and looks at any connect-src directive it might have, to determine whether or not the request is blocked by any CSP policy.

And so on.

And in the response diagram, there’d be a decision point that looks at whether or not the response has an Access-Control-Allow-Origin header. And so on.

https://en.wikipedia.org/wiki/Cross-origin_resource_sharing#/media/File:Flowchart_showing_Simple_and_Preflight_XHR.svg is an existing example of the kind of thing that I think it would be useful to have in the spec itself.

![image](https://user-images.githubusercontent.com/194984/116670882-38c07100-a9db-11eb-8abe-ff3763c50b3a.png)

Understanding the in-browser/client-side request flow and response flow is a major pain point for developers. It’s (somewhat) more understandable to any developers who take time to read through the actual algorithms in the spec. But most developers are never going to do that. And regardless, diagrams make it much easier for developers to actually visualize it all, and to conceptualize it all from that visualization, and to form a mental model they can hold in their heads and they’re trying to troubleshoot problems they run into, and understand at what points the problems are happening.

From my experience at reading a lot of Stack Overflow questions and MDN issues, currently none of this is very clear at all to developers. It seems that in the thinking of a lot of working developers, they tend to up calling it all “CORS” — by which what they often mean is the same-origin policy, or just “cross-origin” in general. And then they wonder why CORS doesn’t have any defined mechanisms for blocking requests — and not knowing that there is a defined mechanism: CSP connect-src.

So the diagrams would help developers know where to look — when to look at CSP documentation, for example, rather than looking at CORS documentation.

cc @dontcallmedom 

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/issues/1227