Cache-Status
The grammar of the Cache-Status header Weir writes, and what every parameter and value means.
Every response carries a Cache-Status header in the RFC 9211 format. The member name is Weir; change it with Config.CacheStatus or drop the header with Config.NoCacheStatus.
Shape
Cache-Status: Weir; hit; ttl=43
Cache-Status: Weir; fwd=uri-miss; fwd-status=200; stored
Cache-Status: Weir; fwd=uri-miss; fwd-status=200; stored; collapsed
Cache-Status: Weir; hit; ttl=-10; detail=stale-while-revalidate
Cache-Status: Weir; hit; ttl=1; detail=negativeA response is either a hit with a ttl, or was forwarded with a fwd reason. collapsed and detail can follow either.
Parameters
| Parameter | Meaning |
|---|---|
hit | answered from the store without waiting for the origin |
ttl=N | seconds of freshness left. Negative on a stale hit: ttl=-10 is ten seconds past expiry |
fwd=REASON | the origin was asked, and why (values below) |
fwd-status=N | the status the origin answered with |
stored | the forwarded response was stored |
collapsed | this request joined another request's fetch (coalescing) |
detail=TEXT | more about the decision (values below) |
fwd values
| Value | The origin was asked because |
|---|---|
bypass | a Bypass.Cookies or Bypass.Headers rule matched, or the engine is in bypass mode |
method | the method is not GET or HEAD |
uri-miss | nothing is stored for this URL |
vary-miss | something is stored for this URL, but not for these Vary header values |
request | the client asked for revalidation and Client.HonorRevalidation is on |
stale | the stored entry was stale and had to be refetched or revalidated |
detail values
On a stale hit, detail names why stale content was served:
| Value | Stale content was served because |
|---|---|
stale-while-revalidate | inside the SWR window; a background refresh is running |
stale-if-error | the origin failed and the entry is inside its SIE window |
shed | the limiter shed this request |
circuit-open | the breaker is open |
coalesce-timeout | this follower waited Coalesce.FollowerMaxWait for a slow flight |
Other values: negative marks a negative-cache answer, and hit-for-miss marks a request sent to the origin without coalescing because this URL recently produced a response that could not be shared.
detail and fwd are free-text values that may gain members in a minor release. Parse them with a default case.
What is never in the header
The key parameter that RFC 9211 allows is never emitted (FR-SRV-9, T-27). A cache key in a response header tells an attacker exactly which inputs are keyed.
The value lists on this page are read from cachestatus.go at build time.