Cache and storage

Two independent layers

Fast cache: RAM, Valkey, Memcached or none. Persistent storage: disk or S3. These choices can be combined independently.

Valkey and Memcached replace the local RAM cache. There is no hidden RAM fallback when an external backend fails. Cache errors allow processing to continue through the next layer or the source.

Minimal disk pool

cache_pools:
  local:
    retention: 168h
    max_entry_bytes: 52428800
    write_timeout: 5s
    memory:
      backend: in_process
      capacity_bytes: 536870912
      max_entry_bytes: 5242880
      ttl: 15m
    storage:
      backend: disk
      directory: /cache/disk
      capacity_bytes: 10737418240
      min_free_bytes: 1073741824

One process owns each disk pool directory. Different pools must not overlap with each other or with source directories. For multiple instances, use S3 and optionally a shared fast cache.

Three distinct lifetimes

Setting	Meaning
retention	Maximum result lifetime
memory.ttl	Lifetime of one entry in the fast layer
revalidate_after	HTTPS source revalidation interval

A cache hit does not extend TTL. Revalidation does not extend retention. Local file changes are checked on requests.

S3

S3 stores ordinary WebP/AVIF objects and a separate manifest with validators and a checksum. The image is published before its manifest. Missing or damaged objects trigger processing from the source again.

Use a separate prefix for each deployment. The service needs GetObject, PutObject and DeleteObject; your provider may also require scoped ListBucket. It does not create buckets or change bucket policies.

Lifecycle rules should retain objects longer than the maximum retention with a safety margin. Configure noncurrent versions and delete markers separately on versioned buckets. Supply credentials through environment variables or the standard AWS credential chain.

External CDN

You can place a CDN in front of the HTTP service. Respect format negotiation in the cache key and Vary: Accept. Direct S3 delivery needs separate URL mapping and authorization; the service currently provides no presigned redirect or public purge API.