rs2 / restspace

9.4 Caching: the universal caching config

Caching in RS2 is a host-applied, per-mount concern — one config key works on any service's responses. The default is deliberately conservative, and you opt in to caching where it's safe.

Default: no-store everywhere

Every response that didn't opt in gets Cache-Control: no-store — errors, discovery docs, preflights, everything. Nothing is cacheable by accident. You turn caching on per mount.

The caching config

"caching": { "mode": "cache", "maxAgeSeconds": 3600, "public": true, "immutable": true }

mode is the main dial:

mode Cache-Control Use for
noStore (default) no-store Anything dynamic/sensitive
revalidate no-cache Stored but always revalidated — pair with conditional GETs
cache max-age=… Genuinely cacheable assets

The host applies this only when the response sets no Cache-Control of its own, and never to error or Set-Cookie responses.

revalidate + conditional GETs = always fresh, near-zero bandwidth

In revalidate mode the client stores the response but revalidates every time. Because file and data answer a matching If-None-Match with 304 (4.2), the revalidation is cheap: the client confirms freshness without re-downloading the body unless it actually changed. This is the sweet spot for content that changes occasionally but must never be stale.

public is clamped on authenticated mounts

public lets a shared cache (a CDN) store the response. It's honored only on anonymously readable mounts (access absent/open/read: "all"). On an authenticated mount the host clamps public to private and adds Vary: Authorization, Cookie — so a shared cache can never serve one principal's response to another. You don't have to remember this; the host enforces it.

The static-site / CDN recipe

The canonical setup for a public site or asset bundle (4.3):

"caching": { "mode": "cache", "maxAgeSeconds": 86400, "public": true, "immutable": true }

immutable tells caches the body won't change for the lifetime of the URL — ideal for content-hashed asset filenames.

Picking a mode

  • Sensitive or per-user data → leave it noStore.
  • Data that changes but must be fresh → revalidate (lean on ETags).
  • Public, rarely-changing assets → cache + public (+ immutable for hashed names).

Next: the limits and containment behavior that keep one tenant (or one bad request) from harming others.

← Previous: 9.3 Idempotency keys and replay · Manual home · Next: 9.5 Limits and containment →