Caching Overview

PreviewProxy uses a two-level cache to avoid redundant fetches and transforms. Once an image has been fetched and processed, subsequent requests for the same image and parameters are served from cache.

Two-level cache architecture​

L1: In-memory cache​

The L1 cache stores transformed images in RAM using Moka, a high-performance concurrent cache library. It is the fastest cache level - a cache hit here avoids both disk I/O and recomputation.

The L1 cache is lost when the process restarts.

L2: Disk cache​

The L2 cache stores transformed images on disk. It is slower than L1 but survives restarts, making it suitable as a durable cache layer.

Cache key​

The cache key is derived from the combination of:

• Source image URL - the full upstream URL
• Transform parameters - all request parameters except sig

Two requests with the same URL and parameters always resolve to the same cache key, regardless of parameter order.

Request flow​

Inflight deduplication​

If multiple requests for the same image and parameters arrive simultaneously (before the first request has finished), PreviewProxy ensures that only one fetch and transform is performed. All other concurrent requests wait for the result and then receive it. This prevents thundering herd problems under high concurrency.

Configuration reference​

L1 (memory) settings​

Variable	Default	Description
CACHE_MEMORY_MAX_MB	256	Maximum size of the in-memory cache in megabytes
CACHE_MEMORY_TTL_SECS	3600	How long entries remain in the memory cache (seconds)

L2 (disk) settings​

Variable	Default	Description
CACHE_DIR	/tmp/previewproxy	Directory where cached files are written
CACHE_DISK_TTL_SECS	86400	How long entries remain on disk before expiry (seconds)
CACHE_DISK_MAX_MB	unlimited	Maximum total size of the disk cache in megabytes

Maintenance​

Variable	Default	Description
CACHE_CLEANUP_INTERVAL_SECS	600	How often the background job scans for and removes expired disk cache entries (seconds)