RFC 9211 Cache-Status

RFC 9211 Cache-Status response header builder + parser. The Cache-Status header documents which intermediate cache (CDN, reverse proxy, application cache) handled a request — operators diagnosing why a request was slow / stale / not-cached read the header and see the entire cache-decision chain instead of guessing from elapsed-time metrics.

Each cache in the response path appends a comma-separated entry:

Cache-Status: ExampleCache; hit; fwd=stale; ttl=600

Where: - The first token is the cache identifier (sf-string) - Parameters follow as key or key=value pairs - Standard parameters per RFC 9211 §2: hit, fwd, fwd-status, ttl, stored, collapsed, key, detail

b.cacheStatus.append(prevHeader, entry) builds a single well-formed entry and appends to whatever previous caches in the chain wrote. b.cacheStatus.parse(headerValue) returns the parsed chain as an array of { cache, params } records.

b.cacheStatus.append(prevHeader, entry) #

{
  cache:      string,  // required — cache identifier (e.g. "ExampleCDN")
  hit:        boolean, // true if served from cache
  fwd:        string,  // one of: bypass | method | uri-miss | vary-miss
                       //          | miss | request | stale | partial
  fwdStatus:  number,  // HTTP status the upstream returned (when fwd)
  ttl:        number,  // remaining freshness lifetime in seconds
  stored:     boolean, // true if the response was newly stored
  collapsed:  boolean, // true if request-collapsing merged this with another
  key:        string,  // operator-defined cache-key shape
  detail:     string,  // free-form diagnostic note
}

Append a Cache-Status entry to an existing chain header. prevHeader is the inbound Cache-Status string (empty / undefined / null means "this is the first entry"). entry is an object describing the current cache's decision. Returns the combined header string.

res.setHeader("Cache-Status",
  b.cacheStatus.append(req.headers["cache-status"], {
    cache: "blamejs",
    hit:   false,
    fwd:   "miss",
    stored: true,
    ttl:   3600,
  }));
// → "ExampleCDN; hit; ttl=300, blamejs; fwd=miss; stored; ttl=3600"

b.cacheStatus.entry(entry) #

Format a single Cache-Status entry without combining with a prior chain. Useful when the operator wants to write the header without regard to upstream entries (e.g. an origin-only deployment).

res.setHeader("Cache-Status", b.cacheStatus.entry({
  cache: "blamejs", hit: true, ttl: 600,
}));
// → "blamejs; hit; ttl=600"

b.cacheStatus.parse(headerValue) #

Parse a Cache-Status header into an array of { cache, params } records, one per cache in the chain. The params object carries the RFC 9211 §2 standard parameters as proper types (hit/stored/ collapsed as booleans, ttl/fwdStatus as numbers, fwd as the raw enum string, key/detail as unquoted strings). Unknown params survive as raw string values so operators inspecting custom cache implementations can read them.

Empty / non-string / malformed inputs return [] — defensive request-shape reader returns sane defaults rather than throwing.

var chain = b.cacheStatus.parse(
  'ExampleCDN; hit; ttl=300, blamejs; fwd=miss; stored; ttl=3600');
// chain[0] = { cache: "ExampleCDN", params: { hit: true, ttl: 300 } }
// chain[1] = { cache: "blamejs", params: { fwd: "miss", stored: true, ttl: 3600 } }

Last updated 2026-08-08T16:39:49.652Z by seeder.