Caching
How Tuzzle caches transformed images for fast delivery.
Tuzzle automatically caches transformed images to avoid reprocessing on every request.
How Caching Works
When a transformation is requested:
- The CDN checks for a cached variant matching the same parameters
- If found, the cached version is served directly (no processing)
- If not found, the original is fetched, transformed, cached, and returned
Cache Keys
Each unique combination of file and transformation parameters produces a distinct cache entry.
# These produce two separate cache entries:
?w=400&h=300&f=webp
?w=800&h=600&f=webp
Cache-Control Headers
All CDN responses include:
Cache-Control: public, max-age=2592000
This sets a 30-day cache lifetime, allowing downstream caches (browsers, CDN edge nodes) to cache the response.
Cache Metadata
Each cached variant stores metadata alongside the image:
| Key | Description |
|---|---|
tzzl-blurhash | Base64-encoded blurhash string |
tzzl-modifier-applied | Query string of transformations used |
tzzl-modifier-warnings | JSON of any validation warnings |
tzzl-modifier-duration | Processing time for the transformation |
tzzl-output-width | Width of the processed image |
tzzl-output-height | Height of the processed image |
tzzl-original-width | Width of the source image |
tzzl-original-height | Height of the source image |
Cache Invalidation
When a file is deleted through the API, Tuzzle removes the original file and all cached transformed variants.
Blurhash Caching
Blurhash values are generated on first request and cached automatically. All subsequent requests use the cached value.
Performance
Cached responses are served without any image processing. This means:
- First request: full processing pipeline (fetch, transform, cache, return)
- Subsequent requests: served directly from cache
- No CPU cost for cached variants
- No memory pressure from repeated transformations