Cache

Use cache when Fluxheim sits in front of an origin and repeated responses should be served faster.

Proxy cache example

[cache]
enabled = true
default_ttl_secs = 300
max_object_bytes = "32MiB"
status_header = "X-Cache-Status"

[cache.memory]
enabled = true
max_size_bytes = "256MiB"

[cache.disk]
enabled = true
path = "/var/cache/fluxheim/site"
max_size_bytes = "10GiB"

Cache backends

Backend	Use it when
`memory`	You need the fastest cache and can keep objects in RAM.
`disk`	You need cache capacity that survives process restarts.
`tiered`	You want memory for hot objects and disk for larger capacity.
`storage-bin`	You expect high churn and want bounded disk allocation.
`encrypted disk`	You need cache-at-rest protection for disk objects.

Route cache policy

[[vhosts.routes]]
name = "assets"
path_prefix = "/assets/"
action = "proxy"

[vhosts.routes.proxy]
upstreams = ["127.0.0.1:3000"]

[vhosts.routes.cache]
enabled = true
status_ttls = { "200" = 3600, "404" = 60 }
content_types = ["text/css", "application/javascript", "image/*"]
extensions = ["css", "js", "png", "webp", "svg"]
include_query = false
stale_while_revalidate_secs = 30
stale_if_error_secs = 120

Advanced cache controls

Control	Purpose
`lock`	Collapse concurrent misses so one request fills the cache.
`range.slice`	Cache fixed byte slices for large files and resumable downloads.
`peer_fill`	Let one edge fill from another edge before using origin.
`origin_protection`	Limit concurrent origin fills during high pressure.
`cache_purger`	Clean stale disk entries in bounded batches.

Use cache carefully

Requests carrying Authorization or Proxy-Authorization always bypass shared-cache lookup and storage.
Malformed or conflicting response Cache-Control directives are rejected instead of falling back to configured TTLs; s-maxage takes priority over max-age.
must-revalidate, proxy-revalidate, and s-maxage prohibit stale reuse after freshness expires.
Keep cache keys bounded and predictable.
Use one storage-bin root per running Fluxheim process; ownership uses an advisory filesystem lock and shared multi-writer roots are unsafe without verified external locking.
Use purge or short TTLs when content changes often.
Bypass on cookies, preview headers, and unsafe query strings.

Encrypted-cache upgrade note

Fluxheim 1.7.12 moves encrypted disk cache objects to root-bound data and index keys with durable nonce state. The first startup against an older encrypted root, and every local-key rotation, intentionally cold-purges that cache before serving traffic.

Encrypted cache data is disposable and must not be treated as authoritative data.
Give every cache root persistent private storage and do not copy nonce state between independent roots.
Make sure the origin server can handle the first cache warm-up after an upgrade or key rotation.