Cloudflare Introduces Granular Control Over HTTP Vary Header Caching
New Cache Rules allow precise management of header-based response variations to optimize cache efficiency.
1HTTP Vary's core challenge
The Vary header tells caches which request headers affect responses but doesn't specify which differences actually matter. This leads to cache fragmentation when minor header variations create separate cache entries for identical responses. Cloudflare's analysis found sites using Vary with up to 47 different header fields, exponentially multiplying cache variants.
2Cache fragmentation consequences
When caches treat every raw header variation as distinct, identical responses scatter across multiple entries. These cold variants consume capacity, reduce hit ratios, and increase origin load. A study of 120M responses showed 3,000 sites varying on 4+ fields, with some extreme cases reaching 47 fields. This creates cache entries that are technically correct but practically useless.
3Three-tiered header handling
Cloudflare's solution introduces three actions for Vary headers: normalize (standardize equivalent values), passthrough (preserve exact differences), and bypass (don't cache). Normalization handles cases like Accept-Language where en-US and en-GB can map to the same response. Passthrough maintains distinctions when casing or whitespace matters, while bypass protects sensitive or highly variable data.
4Normalization mechanics
For Accept, Accept-Language, and Accept-Encoding headers, normalization includes lowercasing, quality-sorting, and parameter stripping. Regional tags like en-US reduce to base languages (en) unless configured otherwise. This processing happens before the origin request, keeping cache matching aligned with server-side content selection while preventing trivial variations from creating cache duplicates.
5Implementation workflow
When a request arrives, Cloudflare first checks for cached variants using normalized header values. On cache miss, it forwards normalized headers to origin. The origin's Vary response determines which headers participate in variant matching. Subsequent requests use the same normalization to find matching variants directly, avoiding linear searches through all stored variations.
6Configuration options
Administrators configure Vary handling through Cache Rules in the Cloudflare dashboard or Rulesets API. They set default actions and specify individual header behaviors. The system supports filtering Accept and Accept-Language to predefined media types and languages. Rules can maintain backward compatibility while gradually introducing Vary optimizations for specific endpoints.
7Cache key architecture
The caching system uses a two-level key structure: a base key (URL + configured fields) plus normalized Vary header values. This differs from custom cache keys that unconditionally add dimensions. Vary-driven caching only activates when the origin explicitly declares header dependencies, making it response-driven rather than rule-driven.
8Edge case handling
Special cases include Vary: * which always bypasses cache, and error responses that must consistently include Vary headers when they differ by request. Cloudflare forwards normalized headers to origin when Respect Strong ETags is enabled. Purging affects all variants of a resource, and configuration changes don't automatically purge existing variants.
9Migration considerations
Teams implementing Vary rules should test with different header combinations that should normalize to the same variant. Verification involves checking CF-Cache-Status headers and confirming expected content formats. Documentation recommends starting with normalize as default, using passthrough for exact-value requirements, and bypass for high-cardinality headers like User-Agent.
10Performance tradeoffs
The solution balances correctness against efficiency—preserving necessary variation while eliminating wasteful fragmentation. It avoids requiring workers or duplicated application logic for common cases. For APIs serving JSON/HTML from same URLs or multilingual sites, properly configured Vary rules can significantly improve cache hit ratios compared to blanket bypass approaches.
11Comparison to custom keys
Custom cache keys unconditionally add dimensions to every matching request, while Vary rules respond to origin declarations. This makes Vary more precise for mixed-content endpoints where only some responses vary by header. The system maintains backward compatibility with existing cache key features while adding this more granular control layer.
12Strategic caching impact
This Vary implementation represents a fundamental shift in handling negotiated content at scale. By separating variation declaration from variation handling, it allows organizations to optimize caching behavior without modifying application code. The solution particularly benefits content-heavy sites serving multiple formats, languages, or regional variations through shared URLs.