# Configuring Stale-While-Revalidate for Tile CDNs

stale-while-revalidate is the directive that lets a mutable tile layer be fast and fresh at the same time, and stale-if-error is what keeps it available when the origin is not. Together they decouple a consumer’s latency from the origin’s health — and, configured without a matching observability signal, they hide an origin outage so completely that every dashboard reports a healthy afternoon. This guide configures both, bounds the staleness they introduce, and adds the metric that stops them from concealing the thing they are absorbing. It applies the cache-control specification from Edge Caching and Tile Delivery Topology within Federated Ownership & Routing Architecture, and assumes the key work in Choosing Cache Keys for Vector Tile Endpoints is already done.

# Prerequisites

The addressing row decides whether this guide applies at all. Under immutable addressing a tile can never change at its address, so unbounded caching is correct and revalidation is unnecessary. These directives are for layers whose address means “current”.

# Step-by-Step Implementation

# 1. Derive the staleness bound from the product’s cadence

The bound is not a preference. It is the maximum age at which a consumer acting on the tile is still acting correctly, and it comes from the product’s declared cadence and the consequence of being wrong.

Worst-case age is s-maxage + stale-while-revalidate, and it is the number that belongs in a conversation with consumers — not the individual directives.

# 2. Set the directives at the origin

Cache-control belongs at the origin so every layer of cache receives the same instruction, rather than each edge applying its own default.

# tile_cache_control.py — directives derived from the layer's declared cadence.
CADENCE_PROFILE = {
    "P1M": {"s_maxage": 86_400, "swr": 604_800},
    "P3M": {"s_maxage": 21_600, "swr": 86_400},
    "P1D": {"s_maxage": 900,    "swr": 3_600},
    "PT1H": {"s_maxage": 120,   "swr": 300},
    "PT1M": {"s_maxage": 10,    "swr": 20},
}


def cache_control(cadence: str, origin_healthy: bool = True) -> str:
    """s-maxage bounds shared-cache freshness; stale-while-revalidate lets the edge
    answer immediately from cache while it refreshes in the background; stale-if-error
    keeps it answering through an origin outage rather than failing the consumer."""
    p = CADENCE_PROFILE.get(cadence, CADENCE_PROFILE["P1D"])
    return (
        f"public, max-age={min(p['s_maxage'], 60)}, "
        f"s-maxage={p['s_maxage']}, "
        f"stale-while-revalidate={p['swr']}, "
        f"stale-if-error=86400"
    )


def provenance(version: str, materialized_at: str, served_stale: bool) -> dict:
    """Degradation must be visible. A consumer that cannot tell a fresh tile from a
    stale one cannot decide whether to act on it — which turns an availability
    incident into a correctness one."""
    return {
        "X-Spatial-Version": version,
        "X-Spatial-Materialized": materialized_at,
        "X-Spatial-Freshness": "stale" if served_stale else "fresh",
    }

Verify the directives reach the edge intact — an edge that overrides them silently is a common surprise:

curl -sS -o /dev/null -D - "https://${TILE_HOST}/${PRODUCT}/12/2048/1361.mvt" \
  | grep -iE '^(cache-control|age|x-spatial-freshness):'

# 3. Confirm revalidation happens in the background, not in the request

The whole value of the directive is that a consumer never waits on the origin. Prove it by measuring a request made immediately after expiry.

# Warm the object, wait past s-maxage, then time the next request.
curl -sS -o /dev/null "https://${TILE_HOST}/${PRODUCT}/12/2048/1361.mvt"
sleep "$(( $(curl -sS -o /dev/null -D - "https://${TILE_HOST}/${PRODUCT}/12/2048/1361.mvt" \
          | grep -i '^cache-control' | grep -o 's-maxage=[0-9]*' | cut -d= -f2) + 2 ))"

curl -sS -o /dev/null -w 'ttfb=%{time_starttransfer}s code=%{http_code}\n' \
  -D /tmp/h "https://${TILE_HOST}/${PRODUCT}/12/2048/1361.mvt"
grep -i 'x-spatial-freshness' /tmp/h
# Expect a fast response marked "stale" — the edge served from cache and is refreshing.
# A slow response marked "fresh" means SWR is not active and every expiry is synchronous.

# 4. Add the metric that stops the directives hiding an outage

stale-if-error is designed to make an origin failure invisible to consumers. Without an explicit metric, it makes it invisible to operators too.

# tile-staleness-rules.yaml — the signal that survives stale-if-error.
groups:
  - name: tile_staleness_recording
    interval: 30s
    rules:
      - record: tile:stale_served_ratio:5m
        expr: |
          sum(rate(tile_responses_total{freshness="stale"}[5m])) by (domain, product)
          / sum(rate(tile_responses_total[5m])) by (domain, product)

      # Age of the newest artifact any edge is serving, against the declared cadence.
      - record: tile:max_served_age_seconds:5m
        expr: max(tile_response_age_seconds) by (domain, product)

  - name: tile_staleness_alerts
    rules:
      # Elevated staleness means the origin is failing revalidation. Consumers are
      # fine; the origin is not, and nothing else will say so.
      - alert: TileOriginFailingBehindStaleIfError
        expr: tile:stale_served_ratio:5m > 0.05
        for: 10m
        labels: { severity: page }
        annotations:
          summary: "{{ $labels.product }} serving {{ $value | humanizePercentage }} stale tiles"
          description: "stale-if-error is absorbing an origin failure — check the origin, not the edge."

      # A tile older than twice the declared cadence is stale by the product's own contract.
      - alert: TileServedBeyondCadence
        expr: tile:max_served_age_seconds:5m > 2 * on(domain, product) product_cadence_seconds
        for: 15m
        labels: { severity: ticket }

Verify the alert fires by taking the origin out deliberately in a non-production environment:

edgectl origin disable --product "$PRODUCT" --duration 15m
sleep 660
curl -sS "$PROM/api/v1/query" --data-urlencode \
  'query=tile:stale_served_ratio:5m{product="'"$PRODUCT"'"}' | jq -r '.data.result[0].value[1]'
# Expect a ratio near 1.0 and a firing alert, while consumers see no errors at all.

# Configuration Reference

must-revalidate deserves the warning. It instructs caches never to serve a stale response, which directly contradicts both directives above — and it is a frequent default in generic security-hardening configurations, applied estate-wide without anyone noticing it disabled the tile layer’s entire staleness strategy.

# Common Failure Modes & Fixes

Every expiry produces a slow request. Root cause: stale-while-revalidate absent, unsupported by the edge, or defeated by must-revalidate. Fix: confirm the directive survives to the edge and remove must-revalidate from any global policy.

Origin load spikes at regular intervals. Root cause: expiries synchronised, because a whole tile range was cached at the same moment during a warm-up and now expires together. Fix: apply a small random jitter to s-maxage per object, so expiry spreads rather than aligning.

Consumers act on data hours out of date and nobody noticed. Root cause: stale-if-error working exactly as designed, with no staleness metric. Fix: the recording rules above; the ratio is the only signal that distinguishes a healthy cache from a hidden outage.

Stale ratio is permanently elevated at a low level. Root cause: a subset of tiles whose revalidation always fails — usually a range the renderer errors on. Fix: break the ratio down by zoom and tile range; a constant low ratio is a persistent partial failure, not noise.

Freshness header is absent on cache hits. Root cause: the header is set by the origin and the edge does not synthesise it when serving from cache. Fix: have the edge set it, since only the edge knows whether the object it served was stale.

# FAQ

# Related

• Edge Caching and Tile Delivery Topology — the parent topic and the full cache specification
• Purging Tile Caches After a Partition Republish — closing the gap a republish opens
• Choosing Cache Keys for Vector Tile Endpoints — the key these directives apply to