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.

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.

The L2 disk cache has two sub-stores, both rooted under PP_CACHE_DIR:

The origin sub-store allows the same source file to be fetched only once. If the same URL is later requested with different transform parameters, PreviewProxy reads the raw bytes from the origin sub-store and applies the new transforms locally, skipping the upstream fetch entirely. This applies to HTTP and S3 sources.

For HTTP sources the TTL of an origin entry is derived from the upstream response headers (Cache-Control: max-age or Expires), falling back to PP_CACHE_DISK_TTL_SECS when no headers are present.

The transformed cache key is derived from:

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

The origin cache key is derived from the source URL only (no transform parameters).

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

flowchart TD
    A[Incoming request] --> B[Check L1 memory]
    B -->|hit| Z[Return response]
    B -->|miss| C[Check L2 transformed]
    C -->|hit| D[Store in L1] --> Z
    C -->|miss| OC[Check L2 origin\nHTTP and S3 only]
    OC -->|hit| F[Apply transforms]
    OC -->|miss| E[Fetch upstream]
    E --> WO[Write to L2 origin]
    WO --> F
    F --> G[Write to L2 transformed]
    G --> H[Store in L1 memory]
    H --> Z

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.