Edge Cache and CDN Platform  ·  View 13 of 29  ·  4 · Data

The Cache Key Contract

How a request becomes a key, the five points where the platform refuses, and why every refusal is counted.

Editable source SVG draw.io All views
Resolve Host + SNI exactly one property Known host? no → 421 Match Path rule declared pattern Cacheable declared? no → bypass Normalise Normaliser case · %-encoding · order Allow-list other params dropped Compose Key parts declared list only Key hash BLAKE3 · 128 bit Store gate Private response? no-store · Set-Cookie Vary inside key? else config error Outcome Stored under key + tags Refused counted · owner alerted mismatch The Cache Key — How a Request Becomes a Key, and When It Refuses Application we own Decision point Data store Opportunity Risk / gap failure / alternate One Rust library computes this in the cache plugin, the validator and the explain API, so the three cannot disagree. v 1.0 · owner Edge Platform · date 2026-09

The contract

  • A key is scheme, host, normalised path, the declared query parameters in sorted order, the declared request headers, and optionally a device or geography class. Nothing else enters it, ever.
  • Normalisation happens once, deterministically: host lowercased, percent-encoding normalised, parameters sorted, anything outside the allow-list removed.
  • A response that is private, no-store, sets a session cookie or carries credentials is not stored, whatever the rule says. The refusal is counted per path and shown to the owner.

Vary

  • If the origin sends Vary naming a header the key does not include, the object is not stored and the owner is alerted. Honouring it silently would fragment the cache, and ignoring it would leak. Neither is the platform's decision to make.
  • Accept-Encoding is the one normalised exception: the edge stores br, gzip and identity as three declared variants rather than re-encoding per request.

Risks

  • Declared keys give a lower hit ratio than permissive ones, and the gap shows in cost per terabyte. It is accepted: a hit ratio can be tuned later, a disclosure cannot be undone.
◀  Control-Plane Data Model All views Access Records — From Request to Offload and Cost  ▶
Solution Architecture v1.0 · Edge Architecture · 2026-09 · 29 views · open source, fully on-premises13-cache-key-contract