CDN cache keys and response variants

What it means

A response variant is a version of a resource's representation—for example, a version using a particular content coding. Cache selection asks which stored response is a candidate for a request; it does not, by itself, establish that the response may be reused now.

The important misconception is that a shared key proves requests need interchangeable responses. It proves no such thing if a content-changing distinction was omitted. This example isolates encoding and assumes that the requester accepts only the selected coding.

Try it

Simulation: start with the documented baseline, then change Effective key distinguishes encoding? from yes to no. Inspect the result and its explanation, then select Compare with baseline to place the two outcomes together. This changes only the local example, not a CDN policy.

The baseline result is Cache miss; seek correct variant. The simulated lookup respects the selected cache-key dimension and request representation. After the change to no, the result becomes Unsafe variant mix risk because the lookup no longer separates the stored gzip representation from a request that accepts only br.

Keep Only accepted encoding in this example at br and Stored encoding at gzip. Only Effective key distinguishes encoding? changes from yes to no.

Reset restores Only accepted encoding in this example to br, Stored encoding to gzip and Effective key distinguishes encoding? to yes. It clears input errors and the baseline comparison. It preserves your independent choices to open or close FAQ answers and About this model.

How it works

The causal chain is: request distinction → candidate selection → possible reuse. When the effective key distinguishes encoding, the simulated lookup compares the requested coding with the stored coding. A mismatch excludes that stored variant and produces a miss in this example. The model does not calculate which response would be obtained next.

When the effective key ignores encoding, the same stored variant is no longer separated from the request by that dimension. If the codings differ, an incompatible response can become a candidate, producing a wrong-variant risk. The apparent gain is broader reuse; the lost safeguard is the distinction that made selection appropriate.

Vary is part of HTTP's mechanism for identifying request-header variation. The scene's yes/no control represents whether encoding is effectively distinguished during lookup, not merely whether a Vary header is present. It does not parse that header or reproduce a provider's configuration rules. RFC 9111, Sections 2 and 4.1, covers cache operation and Vary-based selection; the CloudFront source describes provider-specific key controls.

Correct selection is necessary but not sufficient for reuse. A matching variant can still fail other cacheability, freshness or authorization conditions. Conversely, a miss that avoids an incompatible representation is the correct outcome here, not a performance defect to eliminate at any cost.

Worked example

This is a synthetic baseline, not a captured request or production measurement.

The calculated result is Cache miss; seek correct variant. The simulated lookup respects the selected cache-key dimension and request representation.

The intermediate fact is the encoding mismatch: br is requested, but gzip is stored. Because the effective key distinguishes encoding, that stored response is excluded rather than treated as a suitable match. The result does not claim that another variant exists or that an origin request has occurred.

What changes when the condition changes

Change Effective key distinguishes encoding? to no, keeping Only accepted encoding in this example = br and Stored encoding = gzip.

The result becomes Unsafe variant mix risk. The key ignores a content-coding difference, which can lead to an incorrect variant. The stored bytes have not changed; what changed is whether the lookup separates an incompatible representation from the request. This is a risk prediction, not evidence that a real cache delivered the wrong response.

Ignoring encoding does not make every individual lookup incompatible. If you then change Stored encoding to br, the result is Representation matches, even with the effective-key setting still at no. The two encodings happen to agree. That one match does not establish that the policy will handle a request needing a different encoding correctly.

In practice

Start with a read-only review of a staging or test distribution you administer, or one you are explicitly authorized to inspect. Identify the exact test resource, request method, applicable cache policy and any request differences that may affect content or access. STOP if authorization, test scope or access boundaries are unclear; do not probe private content or weaken access controls to obtain a comparison.

For an authorized controlled observation, keep the URI, method and other request conditions fixed while varying one relevant encoding request header. Record the request headers, response encoding, applicable variation metadata and effective policy. The expected observation is that a request is not satisfied with a coding it does not accept; different requests need not always receive different encoded bodies. Inspect the selected representation, not just a hit/miss label.

If a response appears incompatible, or you cannot establish which policy applied, stop the experiment and retain the evidence. The cause remains unknown until the request, selected response and policy can be reconciled. This simulation cannot diagnose that deployment.

Do not remove a key dimension merely to improve hit rate, especially when it may affect content or access. This investigation does not require a configuration edit or purge. Any later change needs a separate provider- and version-specific plan: preserve the prior configuration, limit the edit to the approved scope, verify both matching and differing variants, and specify how to restore and reverify the prior configuration if results differ from expectations.

Limits and unknowns

The scene models one request header as a cache dimension, not a full HTTP cache or CDN policy implementation. It assumes the requester accepts only the selected coding. It does not evaluate freshness, authorization, other variation dimensions or all conditions governing storage and reuse. A result of Representation matches means only that the selected encodings agree.

The encoding controls support br and gzip; the effective-key control supports yes and no. Unsupported or empty input is invalid: no calculated outcome applies until the input is corrected or Reset is used. Valid selections produce one of the model's three outcomes; there is no separate unknown verdict for them. Whether an actual CDN has the same effective behavior remains unknown without deployment evidence.

No network request, account inspection or production change occurs. Without JavaScript, the initial example and explanation remain readable, but the interactive controls are unavailable.

What to carry forward

Treat a cache hit as useful only when the selected response is suitable for the request. Before simplifying a key, establish which request differences change the required representation. If that evidence is missing, keep the distinction and investigate rather than treating a higher hit rate as proof of correctness.