docs operator edge cache

Edge cache operations (P08-T06)

Public reads cache at the edge; identity, location and private payloads never do. The origin owns Cache-Control/ETag semantics; the edge only stores what the origin marks shared, keyed on method+URL, and purges on moderation or schedule.

Allowlist: what caches

Route	Cache-Control	ETag/304	Notes
GET /v1/stations?...	public, max-age=60	yes	Non-sensitive queries only
GET /v1/stations/{id}	public, max-age=30, s-maxage=60	yes	Provenance/quality metadata
GET /v1/stations/{id}/prices	public, max-age=60	yes	Community section carries expires_at; clients must honor projection expiry over the TTL
GET /v1/stations/{id}/official-prices?...	public, max-age=60	yes	Revision-aware history
GET /v1/stations/nearby?...	no-store	n/a	Request position never cached, logged or echoed
All writes/owner reads/uploads/exports	no-store	n/a	Signed and owner-scoped
All error envelopes	no-store	n/a	Owner data never sits in shared caches

DISPUTED/UNKNOWN projections render null amounts (never an ANP fill-in), so a cached disputed price cannot mislead: there is no price in it. Expired projections serve STALE/excluded-from-ranking at query time regardless of worker health (B-BR-008).

Key policy

• Key = method + URL only. Caddy strips Cookie and Authorization on the four shared-cacheable shapes (invariance proven by the *IgnoreIdentity unit tests: identical bodies with and without identity headers, no Vary on identity).
• Never add contributor, station or observation IDs to cache keys or log fields; purge procedures take URL prefixes, never identities.

CDN rules (Cloudflare, provisioned at deploy)

1. Cache GET /v1/stations* except /v1/stations/nearby*; honor origin Cache-Control (bounded 30–60 s); bypass cache when the origin says no-store.
2. Do not vary on Cookie/Authorization for cached paths (origin already strips them on the shared set).
3. TLS 1.2+ to origin with strict origin authentication; trusted proxy ranges only (mirrors Caddyfile).
4. CDN outage serves from origin, never from a disabled-security shortcut.

Purge procedure

Moderation actions, dispute resolutions and projection rebuilds that change public prices purge the affected URL prefixes:

# Purge by URL prefix after a moderation decision (operator host)
curl -sS -X POST "https://api.cloudflare.com/client/v4/zones/${CF_ZONE}/purge_cache" \
  -H "Authorization: Bearer ${CF_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"prefixes":["https://'"${CANONICAL_HOST}"'/v1/stations/<station_id>/"]}'

Bounded TTLs (≤60 s) cap any missed purge window; expires_at on community sections bounds semantic staleness independently.

Signature through proxy

Signed owner writes verify through the proxy unchanged: the proxy forwards method/authority/path/query/content headers verbatim and only strips Cookie/Authorization on the shared-cacheable GET set (which carries no signed traffic). The regression suite below covers headers; protocol vectors cover signatures (P03-T01, frozen).

Rollback

Disable the CDN cache rule, purge the affected prefixes, and fall back to secured origin reads. Origin Cache-Control stays correct without the edge, so reads degrade to slower but safe.

Regression suite

# Against a live origin or staging edge (read-only GETs + one 304 round-trip)
BASE_URL=https://staging.example.invalid bash scripts/cache-regression.sh

The suite asserts the allowlist matrix above, ETag/304 round-trips, no-store on nearby/private/errors, identity invariance, and that no response varies on Cookie/Authorization. Live edge runs happen at staging deploy; the same matrix runs as unit tests in CI.