Cache the right derivative without multiplying variants endlessly.
Define identity first
A cache key for transformed media needs the source version and every option that changes bytes: dimensions, crop, format, quality, and sometimes content negotiation. Normalize option order and defaults. Two equivalent requests should hit one cache entry; different outputs must never collide.
Bound the variant space
Arbitrary widths and quality values let a single asset produce thousands of expensive misses. Use named presets or round widths to a short approved list. Monitor unique variants per source and the ratio of cache hits to transformation requests.
Make invalidation explicit
Immutable versioned URLs are simpler than purging every edge when source bytes or recipes change. If mutable URLs are necessary, document purge timing and stale behavior. Test a replacement end to end on a plain URL after caches have been populated.
A concrete acceptance test
Warm a transform in the CDN, request equivalent options in a different order, then publish a new source version. Verify a shared hit for the equivalent URL and fresh bytes for the new version. Run this test with a realistic asset and record the observed state, output URL, and failure reason.
Implementation check
- Include every byte-changing option in the cache key.
- Limit allowed dimensions and quality values.
- Use source versions to avoid ambiguous purges.
Related guides
Primary reference: Official documentation.
Related field note
Continue with A migration plan for CDN cache keys.