docs operator edge cache - AlexandreZanata/Abastevo GitHub Wiki

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.

⚠️ **GitHub.com Fallback** ⚠️