Network Flow, or how you stop explaining CORS
Hello there!
You know the message. Red text, a long line in the console, usually sent to you as a screenshot:
Access to fetch at 'https://api.example.net/v1/account/limits' from origin
'https://example.com' has been blocked by CORS policy: No
'Access-Control-Allow-Origin' header is present on the requested resource. And you know what comes next. Someone asks what is wrong with the frontend. You take a breath, and you explain it again. Origins. Headers. Preflights. Why the fix is not in the component that called fetch().
The first time, it is fine. The fifth time, you notice you are using the same words. Somewhere around the tenth, you realise the problem is no longer CORS. The problem is that you are a human copy-paste of the same explanation, and that is a problem you can actually solve.
So you stop explaining it and start showing it, once, properly, in a way you can hand over and walk away from. That is what Network Flow is.
Why a CORS error is not a frontend bug
CORS (Cross-Origin Resource Sharing) is a rule the browser enforces: a page may read a response from another origin only if that response says it is allowed to, with the Access-Control-Allow-Origin header.
Here is the thing that makes CORS feel like a frontend problem: the error shows up in the browser, in the page, in the frontend developer’s console. Of course it looks like their bug.
But open the third step of the CORS walkthrough, Missing header: sent, answered, blocked, and watch what actually happens. The request leaves the browser. It crosses the router and the internet. The API server receives it, runs its code and answers 200. The response travels all the way back.
Nothing on the wire is wrong.
Then the browser looks at the response, does not find Access-Control-Allow-Origin, and refuses to let the page read it. fetch() rejects with a network error, and the page sees neither the status nor the body. The server did its job. It just never said that https://example.com was allowed to read the answer.
That is the whole point, and it is much easier to see than to say: CORS limits what a page may read, not what a client may ask. The fix lives where the response is made.
Eleven steps, one connection
The CORS scenario walks through eleven steps, grouped into simple requests, preflight, credentials, and caching and limits:
- a simple
GET, where the browser quietly adds anOriginheader, - the server opting in with
Access-Control-Allow-Origin, - the missing header from above,
- a
PUTwithAuthorizationthat triggers anOPTIONSpreflight, answered with204and the allowed methods, - credentials, where a wildcard
*origin gets rejected, and the fix with an exact origin andVary, Max-Age, where a laterPUTskips the preflight because the answer is cached for 600 seconds,- and the ending I like most:
curlasks the same endpoint as step three, sends noOrigin, and reads the exact response the browser blocked.
That last step tends to settle the argument. Same server, same answer, different client. The browser is the one enforcing the rule.
Four ways to look at the same moment
You can press play and let it run, or click through step by step. Every step shows the same moment in a few different ways:
- Network: packets moving across a small isometric network, from your browser through the home router and the internet to the API server,
- Sequence: the same exchange as a sequence diagram, if arrows between columns are more your thing,
- Packets: a Wireshark-style table of everything on the wire,
- Headers: click any packet and you get its headers, layer by layer.
Switching between the network and sequence views keeps the time, the step and the selected packet, so you never lose your place.
And the address bar holds the whole state. #/cors/3 is step three. That is the feature I wanted most: the next time someone sends you that red screenshot, you send back a link instead of a paragraph.
Not only CORS
Once the engine existed, the other protocols I kept half-explaining came along with it. There is a journey of a single URL from the address bar to the painted page, plus walkthroughs for TCP, UDP, IP, DHCP, DNS, HTTP and HTTPS, TLS, CDNs and email over SMTP, POP3 and IMAP.
Pick one in the sidebar and step through it. Press ? for keyboard shortcuts, V to switch views, and space to play or pause.
The small print, the good kind
Everything runs in your browser from static files. There is no backend, no account and no analytics, and after the first load the app makes no network requests at all. The addresses, names and ports in the scenarios are documentation values, so nothing points at a real host except the DNS root and .com servers that the DNS steps name.
The scenarios are also checked by a validator that runs with the tests and looks at more than the shape of the data: addresses, TCP sequence numbers and IP fragments have to add up. If your system asks for reduced motion, packets jump between devices instead of flying, and the ambient animation stops.
The code is on GitHub, and the app is live on GitHub Pages.
Next time
That is the real win here. Not a nicer diagram, but one less conversation you have to repeat word for word. If you keep explaining the same thing over and over, it is probably worth building it once.
So, the next time CORS lands on your desk as a frontend bug, you do not need the whiteboard. Send the link, let them press play, and wait for step three.
Greetings,
Maciej