HTTP cache — HOT, COLD and invalidation

RustProxy provides an optional shared HTTP response cache with a bounded in-memory HOT tier and optional persistent-disk COLD tier. Both the global cache and a Vhost's effective policy must permit caching. COLD storage is disabled by default, and newly created Vhosts do not automatically cache dynamic content.

Enable caching safely

Open Settings → Cache, enable the global cache and choose memory limits. Enable COLD only if you want durable disk storage and have enough private disk capacity.
On the appropriate Vhost, enable cache for public, repeatable responses. Restrict or disable it for login, personalized pages, uploads, APIs and responses carrying secrets.
Ensure the origin supplies a valid public freshness policy, or configure a safe default TTL where supported. Cache-Control: private and no-store must prevent shared storage.
Optionally enable HIT-only diagnostics. Send repeated identical requests using curl, then inspect Cache → Domains / Stored objects for MISS → HIT.
Check TTL, revalidation and invalidation after updating the origin's content or configuration.

Vhost editor options

In Vhosts → Cache, overrides for static extensions, bypass path prefixes and unsafe force targets each place the enable/override checkbox immediately above the associated multiline list. The fields are disabled while their individual override is off; their saved values and cache policy are unchanged. Never enable unsafe forced caching for personalized responses.

Stored object rules

Reuse is scoped by frontend scheme, Host, exact client URL, Vhost/content policy and eligible Vary dimensions. HTTP and HTTPS objects do not cross-share.
GET and suitable HEAD requests may reuse a full object; changing request methods do not silently invalidate all cached GET results.
Authorization, dynamic cookies, Set-Cookie, sticky-affinity cookies, Tinyauth and other private signals normally cause BYPASS. A limited static-file cookie exception exists for configured static extensions and does not override private, no-store, Set-Cookie or Vary: Cookie.
Origin status, response size, TTL, unsupported metadata, range/conditional semantics and request/client cache directives can prevent fill or require validation.
A Web Service selected as a Vhost source uses the same cache policy for eligible local files. File changes can be checked with ETag / Last-Modified; a 304 validation may refresh a stored body without downloading it again.

Freshness and diagnostics

State	Interpretation
`MISS`	No suitable fresh cached representation was found; the origin was consulted. The response may still be ineligible for storage.
`HIT`	A matching stored object was reused.
`BYPASS`	Cache was disabled or a policy intentionally skipped it (for example authorization, cookies or a path exclusion).
Revalidated	An existing representation was checked against the origin; a `304` can retain the body.

Age is total HTTP age, not only the time spent in RustProxy. The optional X-Cache-Resident-Age reports the cache residency interval. Debug headers such as X-Cache, X-Cache-Hits and reason labels are optional and should be enabled deliberately. Browser hard reloads commonly force revalidation, so test with curl when investigating.

Example, replacing the listener and Host values with yours:

for n in 1 2 3; do
  curl -sS -D - -o /dev/null -H 'Host: app.example.com' \
    http://127.0.0.1:8080/public.css
  sleep 2
done

Look for cache reason labels including request_cookie, request_authorization, response_cache_control, route_disabled and cache_hit when diagnostic headers are enabled. A MISS alone does not prove the object was admitted to HOT/COLD.

Advanced behavior

Budget limits: HOT RAM capacity, object count/size, transient fill memory and optional COLD byte/object limits. Configure based on real workload and monitor disk/RSS.
HOT/COLD movement: entries may be demoted, recovered or expired; a periodic/explicit COLD cleanup is available. Cache storage is not a permanent archive.
Request collapsing: eligible concurrent MISS requests can share a bounded fill, limiting origin bursts.
Stale-if-error and refresh: conditional options can help on eligible backend failures, but are not an unconditional stale-serving guarantee. Web Server local-file validation has a distinct policy.
Compression/transformation: cached variants and validators must remain compatible with client encoding and content-modification settings.

Clear or invalidate content

Authenticated Cache page/API operations can purge selected entries, domains or larger scopes. The optional public HTTP PURGE/BAN interface is disabled by default. Enable it only by listing trusted client IPs/CIDRs under Settings → Cache → HTTP BAN / PURGE IP allowlist; operations are additionally subject to Vhost binding and normal access controls. PURGE addresses an exact URL; BAN applies the supported bounded matching rules. Never allow untrusted Internet clients to purge all tenants' objects.

In 0.34.0, changing operational Vhost settings is intended to preserve compatible HOT/COLD objects; content-affecting changes invalidate affected scopes and COLD carries an additional fingerprint against stale resurrection. This new behavior still needs release-level verification, so validate cache after configuration edits and during upgrades. Earlier persistent cache entries may need refilling following format/compatibility transitions.

Troubleshooting

Always BYPASS: check both cache enable switches, login/cookies, exclusion rules, methods, Tinyauth and sticky sessions.
MISS never becomes HIT: check response Cache-Control, status, object size, Vary, Set-Cookie, incomplete origin streams and whether the same scheme/Host/query is used.
Content unexpectedly old: inspect Age, TTL, validators, stale rules and previous invalidation; purge only affected content after confirming its identity.
Memory/disk pressure: review HOT/COLD budgets and cleanup, rather than increasing limits without measurements.

See Monitoring for cache telemetry and Security for privacy boundaries.

6.2 KiB Raw Blame History