HTTP Caching, CDN Invalidation & Cache-Control Architecture Runbook

# Private Cache: Stored exclusively in the user's browser (contains PII / auth tokens)
HTTP/1.1 200 OK
Cache-Control: private, max-age=300, must-revalidate
Vary: Authorization, Cookie

# Shared Edge Cache: Cached by CDN edge nodes globally for all anonymous users
HTTP/1.1 200 OK
Cache-Control: public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800
Surrogate-Key: product_catalog tenant_42
Age: 1420

The s-maxage directive overrides max-age exclusively for shared CDN caches, while the Age header indicates how many seconds the response has resided in edge memory.

# Maximum performance recipe for hashed static assets (/assets/main.a9f4c1.js)
HTTP/1.1 200 OK
Content-Type: application/javascript; charset=utf-8
Cache-Control: public, max-age=31536000, immutable

# HTML Root Recipe (index.html: must revalidate instantly on deploy)
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Cache-Control: no-cache

The immutable token signals that the resource representation will never change under this URI, instructing modern browsers to skip conditional validation even when the user hits reload.

# 1. Client sends conditional request with stored ETag
GET /api/v1/pricing HTTP/1.1
Host: api.mayonlinetools.com
If-None-Match: "e29-6238ab20"
If-Modified-Since: Tue, 20 Oct 2026 14:00:00 GMT

# 2. Server detects matching hash and returns empty 304 response
HTTP/1.1 304 Not Modified
ETag: "e29-6238ab20"
Cache-Control: public, max-age=600
Content-Length: 0

A 304 response sends zero response body, cutting bandwidth consumption by over 99% while renewing the client freshness clock.

# Origin tags API response with relational entity IDs
HTTP/1.1 200 OK
Surrogate-Key: user_942 org_12 team_billing
Cache-Control: public, s-maxage=604800, stale-while-revalidate=86400

# When user_942 updates their profile, purge exclusively matching keys via API:
curl -X POST "https://api.fastly.com/service/SERVICE_ID/purge/user_942" \
  -H "Fastly-Key: ${FASTLY_API_TOKEN}" \
  -H "Accept: application/json"

Purging by Surrogate-Key takes under 150ms globally and invalidates only affected user representations, leaving the rest of the edge cache completely warm.

# Nginx production block implementing optimal caching headers
server {
    listen 443 ssl http2;
    server_name mayonlinetools.com;

    # 1. Root HTML: Never cache statically, force revalidation
    location = /index.html {
        add_header Cache-Control "no-cache, must-revalidate";
        add_header X-Content-Type-Options "nosniff";
    }

    # 2. Immutable assets: Versioned with content hash (/assets/chunk-[hash].js)
    location ~* \.(?:js|css|woff2|webp|svg)$ {
        expires 1y;
        add_header Cache-Control "public, max-age=31536000, immutable";
        access_log off;
    }
}

When a new release ships, index.html updates instantly with new hashed asset paths (e.g., chunk-b24.js), eliminating stale asset collisions completely.