Name: System Design Masterclass
Availability: InStock

A path is in the address bar. A hostname is in public . Both are facts you have published, and both get bookmarked, linked and indexed.

A header is none of those things, and that is the entire reason to route on one.

A five-row comparison of path, hostname and header. Visible to the user: yes in the address bar, yes in the address bar, no. Chosen by the user: yes they typed it, yes they typed it, sometimes. Public: indexed and linkable, in public DNS, no. Changeable per request: only by changing the link, no, yes. Costs a certificate: no, yes, no. — FigureFigure 1. The header is the only routing field the user cannot see
It can express a distinction you do not want to announce, it can change from one request to the next, and it costs no DNS record and no certificate.

That invisibility comes with two consequences, and the rest of this lesson is those two consequences. The first is that a client can invent a header and you cannot tell. The second is that making a response depend on a header makes every cache key in front of you wrong.

Neither is subtle. Both are one request to demonstrate.

Here is what a backend actually receives.

A recorded terminal session. A header name in lower case is received as X-Api-Version=v2. The same header sent twice arrives at the backend directly as v1,v2 and through the proxy as v2 alone. A client sending X-Internal-Role admin and X-Forwarded-For 10.0.0.9 has both arrive untouched. The identical request through an edge that strips and sets arrives with X-Internal-Role anonymous and X-Forwarded-For 127.0.0.1. — RecordedFigure 2. What the backend received, and what a proxy changed
A plain curl invented an internal-sounding header and an X-Forwarded-For of its own choosing, and both arrived at the backend untouched.

Read the third block again. There is nothing special about X-Internal-Role. The X- prefix is a convention, the word "internal" is a word, and none of it is enforced by anything. A client can write that header, and by the time it reaches a backend it is indistinguishable from one your edge wrote.

A hand-drawn diagram. On the left in red: the client sent it, Accept, User-Agent, Cookie and anything else it liked, described as a hint never a fact. On the right in green: the edge set it, after verifying something it can actually check, described as a fact for this hop only. An arrow labelled delete points from left to right. Two notes read: a backend cannot tell these apart, so the edge has to, and which means deleting the client's copy before writing its own. — SketchFigure 3. Both kinds look identical by the time they arrive
There is no field marking a header as internal. The backend has no way to tell which hop wrote it.

So the edge has to. And it has to do it in a specific order.

A sequence diagram with three lifelines: a client, the edge and a backend. The client sends GET slash orders with X-Internal-Role admin, noted as the client simply wrote this itself. The edge deletes every X-Internal header, noted as unconditionally, before looking at anything. The edge verifies the token and sets the role from it. It forwards GET slash orders with X-Internal-Role anonymous. — SequenceFigure 4. Delete, then verify, then set
Any other order leaves a case where a value the client wrote reaches a backend that trusts it.

The word doing the work there is "unconditionally". A very common rule reads "set the header if it is not already present", which sounds careful and is the opposite. A client that sets it first now controls its own routing.

There is a second reason to strip rather than to overwrite selectively: write the rule as a deny-list of internal prefixes and you will miss one, probably the one somebody adds next year. Write it as an allow-list of the headers you forward and you cannot, because everything not on the list is dropped by default.

Five edge rules with what each prevents. Strip every internal header always, not only when it is missing, or a client picks its own routing. Set them from something verified, a token you checked or a name you resolved, or a hint becomes an identity. Reject duplicate copies of one header, because two hops may pick different ones, or one routes and one authorises. Match on the name case insensitively because the specification says it is, or a lowercase spelling slips past. Decide what happens when it is absent, because most requests will not have it, or everything falls to one default. — FigureFigure 5. Five rules at the edge, each one line of configuration
Together they turn a field anybody can write into a field only your infrastructure can write.

The duplicate-header row is worth connecting to the capture. Sent straight at the backend, two copies of one header arrived joined as v1,v2. Sent through the , only v2 survived. One hop dropped a copy, which means two components in the chain were looking at two different requests. If one of them routes and the other authorises, that gap is the bug.

None of this means client headers are unusable. It means knowing which kind you have.

Five header sources with a verdict. A claim from a verified token, where the edge checked a signature: trustworthy. A client certificate's subject, where the handshake proved it: trustworthy. Accept or Accept-Language, the client's own preference: a hint, and that is fine. User-Agent, the client's own claim about itself: a hint, and often a lie. X-Anything the client sent, where nothing checked it at all: not evidence of anything. — FigureFigure 6. Two headers that mean something, and three that are a client describing itself
The bottom three are perfectly good to route on. They are not good to authorise on, and the difference is the one that gets forgotten.

The line is not between standard headers and custom ones. It is between values something verified and values something asserted.

Header-Based Routing

The rest of this lesson

Continue this lesson

The Field Nobody Can See

Who Wrote This Header?