Add a flow diagrams for in-browser/client-side request flow and response flow

[sideshowbarker]

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.

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

[annevk]

I think this would be great. Another one would be for illustrating how the various fetch algorithms end up invoking each other. My main problem with diagrams has always been finding the right tool that spits out workable non-bloated SVG that can be made accessible somehow and more importantly, allows for ongoing maintenance. (And perhaps I have that problem because I never put a lot of time into it, but if someone has suggestions...)

[dontcallmedom]

when @sideshowbarker and I discussed this, I thought the conversion into diagram might indeed be an obstacle to maintenance - I know there are a number of tools that takes a text format and turn them into SVG charts, although I haven't reviewed yet how well they would work for this.

My guess is that we should start documenting the flow in any kind of structured text form (which helps with maintenance and is already useful in itself), and restructure it into whatever input format the final tool we would find would work with.

[dontcallmedom]

(maybe https://github.com/adrai/flowchart.js )

[mozfreddyb]

Mermaid-js can create flow charts from a text-format and creates SVGs with text/tspan elements. I don't know if that's accessible enough, but it seems like a library worthy looking into.