ETags and conditional requests: 304 saves the bytes, not the round-trip

The dashboard polls /api/config every 30 seconds. You added ETags to “save bandwidth,” shipped it, and the egress bill didn’t move. You open DevTools: every poll is a clean 200 OK with the full 8 KB body. Not one 304. The config hasn’t changed in days. The bug isn’t in the client — you scaled the API to three pods last month, each computes its own ETag from a per-process counter, and the load balancer round-robins every request to a different pod. The client’s If-None-Match never matches whoever answers next.

The mechanism: fingerprint, echo, compare

A conditional request is a two-party agreement about a resource version. On the first response the server attaches an ETag header — an opaque token, usually quoted, that identifies this exact version of the body: ETag: "a3f5c901". The client stores it next to the cached copy.

On the next request the client asks “give me this only if it changed” by echoing the token in If-None-Match: "a3f5c901". The server recomputes (or looks up) the current ETag and compares:

• Match → the client already has the current version. The server replies 304 Not Modified with no body and refreshed headers. The client serves its cached copy.
• Mismatch → the version moved. The server replies 200 OK with the full new body and a new ETag.

The token is opaque on purpose: only the origin that minted it gets to interpret it. The client never parses it, never reasons about it — it just stores and echoes. That opacity is what lets you change your ETag scheme (hash → version number → mtime+size) without touching a single client.

What 304 actually saves — and what it doesn’t

This is the number that decides whether ETags are worth it: a 304 saves the body bytes, but you still pay the full round-trip. The client must send the request and wait for the response before it knows the body is unchanged. If your RTT to origin is 80 ms, every poll still costs 80 ms of latency whether the answer is 200 or 304.

So the win is purely egress and download time. An 8 KB JSON config that returns 304 ships ~200 bytes of response headers instead of 8 KB — a 40× reduction on the wire, multiplied across every polling client. For a 2 MB product image that rarely changes, a 304 saves the entire 2 MB transfer on every revalidation. The bigger and more rarely-changing the resource, the better the trade.

But ETags are not free on the server. To answer a conditional request you must know the current ETag, which usually means reading or recomputing the resource — hashing the file, querying the row, rendering the response — just to compare and then throw the body away. That is the core CPU-vs-bandwidth tradeoff: you spend origin CPU to avoid network bytes. If the ETag is a cheap lookup (a stored version column, a file’s mtime+size from stat), the trade is obviously good. If it means SHA-256 hashing a 2 MB body on every request, you may burn more CPU than the bandwidth was worth.

Strong vs weak: byte-identical vs semantically equivalent

ETags come in two strengths, and the difference is a W/ prefix:

• Strong — ETag: "a3f5c901" — promises byte-for-byte identity. Two strong ETags match only if the representations are exactly equal, every byte. Strong validators are required for range requests (If-Range): if you’re resuming a download at byte 1,000,000, “semantically equivalent” isn’t good enough — you need the exact same bytes.
• Weak — ETag: W/"a3f5c901" — promises only semantic equivalence. A weakly-tagged page might differ in a timestamp comment or an ad slot but is “the same enough” to reuse. Use weak when computing a byte-exact tag is expensive or when trivial differences shouldn’t bust the cache.

The subtlety: If-None-Match always uses the weak comparison algorithm. For revalidation, W/"x" and "x" are treated as a match — the prefix is ignored. The strong/weak distinction only bites where byte-exactness is mandatory, which in practice means range requests. So for plain “did this change?” caching, picking weak vs strong rarely changes the outcome; for resumable downloads, it absolutely does.

ETag vs Last-Modified: the one-second blind spot

Before ETags there was Last-Modified / If-Modified-Since, a timestamp-based validator. It still works and is cheaper (just a stat on a file), but it has a hard limitation: HTTP dates have one-second resolution. If a resource changes twice within the same second — common for hot config, generated files, or high-write rows — Last-Modified can’t tell the two versions apart, and the client serves a stale 304. ETags don’t have that blind spot: a content hash or version counter changes on every real change regardless of timing.

The senior default: when both are present, ETags take precedence, and clients are expected to prefer If-None-Match over If-Modified-Since. Many servers emit both so dumb caches that only understand timestamps still get some revalidation, while ETag-aware clients get the precise one. The cost of emitting both is one extra header line.

Why it breaks in prod: the per-node ETag

The Hook’s bug is the canonical ETag failure, and it’s worth dwelling on because it’s invisible in single-server dev. The contract is simple: the same content must produce the same ETag, no matter which server answers. Break that and no client ever sees a 304.

Three classic ways to break it, all from the same root — the ETag depends on something local to one node instead of on the content:

1. Inode-based ETags. Apache’s default FileETag historically included the file’s inode number. Identical files deployed to three servers have three different inodes, so three different ETags. Apache 2.4 dropped inode from the default precisely because it poisoned clustered caching; the fix is FileETag MTime Size (content-derived, identical everywhere).
2. Timestamp/mtime drift across replicas. Even mtime-based ETags break if your deploy copies files at slightly different wall-clock times to each replica, or if a CI rebuild touches files. Same bytes, different mtime, different ETag.
3. Per-process state. A counter, a random salt, or a startup timestamp baked into the ETag means each pod mints its own namespace — exactly the Hook’s failure.

And one more that surprises people: compression changes the ETag, or should. The gzipped and identity versions of a resource are different byte streams, so a strong ETag must differ between them — otherwise a client that sent Accept-Encoding: gzip and got a gzipped 200 could later revalidate, hit a node serving identity, and the byte-exact If-Range semantics break. Some proxies strip or weaken the ETag when they compress on the fly; if yours doesn’t, a compression layer added between deploys can silently invalidate every cached validator at once.