CDN Cache-Control Headers — Why Black Friday Had 0% Hits

# Origin server Nginx configuration
# This tells CDN edge servers HOW to cache each type of content

server {
    listen 80;
    server_name origin.theforge.io;

    # Static assets — cache aggressively at the edge for 1 year
    # The CDN will serve these without touching origin on repeat requests
    location ~* \.(js|css|png|jpg|woff2|svg)$ {
        root /var/www/static;

        # 'public' means CDN edge servers ARE allowed to cache this
        # 'max-age=31536000' = 1 year in seconds
        # 'immutable' tells the browser: don't even check for updates
        add_header Cache-Control "public, max-age=31536000, immutable";

        # ETag lets CDN validate freshness without re-downloading
        etag on;
    }

    # HTML pages — short cache, must check origin for updates
    location ~* \.html$ {
        root /var/www/html;

        # 'stale-while-revalidate' serves cached copy instantly
        # while refreshing it in the background — best of both worlds
        add_header Cache-Control "public, max-age=300, stale-while-revalidate=60";
    }

    # API responses — personalised data must NOT be cached at CDN level
    # 'private' means only the user's browser can cache it, not edge servers
    location /api/user/ {
        proxy_pass http://app_backend;
        add_header Cache-Control "private, no-store";
    }

    # Public API data (e.g. product catalogue) — safe to cache at edge
    location /api/products/ {
        proxy_pass http://app_backend;
        add_header Cache-Control "public, max-age=600"; # 10 minutes
    }
}

// Cloudflare Worker — code that runs ON the edge server, not your origin
// This runs in 300+ cities simultaneously with ~0ms cold start

adaddEventListener('fetch', event => {
    event.respondWith(handleRequest(event.request));
});

async function handleRequest(incomingRequest) {
    const requestUrl = new URL(incomingRequest.url);

    // --- PERSONALISED CACHING STRATEGY ---
    // We can't cache the full page for logged-in users,
    // but we CAN cache the static shell and inject user data at the edge

    const isStaticAsset = requestUrl.pathname.startsWith('/static/');
    const isApiRequest  = requestUrl.pathname.startsWith('/api/');

    if (isStaticAsset) {
        // Let the CDN cache handle this — fetch from cache or origin
        const cachedResponse = await caches.default.match(incomingRequest);

        if (cachedResponse) {
            // CACHE HIT: add a header so we can monitor hit rates in logs
            const hitResponse = new Response(cachedResponse.body, cachedResponse);
            hitResponse.headers.set('X-Cache-Status', 'HIT');
            return hitResponse;
        }

        // CACHE MISS: fetch from origin and store at this edge location
        const originResponse = await fetch(incomingRequest);
        const responseToCache = originResponse.clone(); // clone before consuming body

        event.waitUntil(
            caches.default.put(incomingRequest, responseToCache) // store asynchronously
        );

        const missResponse = new Response(originResponse.body, originResponse);
        missResponse.headers.set('X-Cache-Status', 'MISS');
        return missResponse;
    }

    if (isApiRequest) {
        // For API requests, add geographic context so origin
        // can serve localised data without client needing to send it
        const modifiedRequest = new Request(incomingRequest, {
            headers: {
                ...Object.fromEntries(incomingRequest.headers),
                'X-User-Country':  incomingRequest.cf.country,   // e.g. 'JP'
                'X-User-City':     incomingRequest.cf.city,      // e.g. 'Tokyo'
                'X-User-Timezone': incomingRequest.cf.timezone   // e.g. 'Asia/Tokyo'
            }
        });
        return fetch(modifiedRequest); // pass through to origin with enriched headers
    }

    // Default: pass through everything else unchanged
    return fetch(incomingRequest);
}

#!/bin/bash
# Push CDN deployment script — used in a CI/CD pipeline after a new build
# This pre-warms edge servers so users NEVER see a cache miss on launch day

set -e # Exit immediately if any command fails

CDN_PROVIDER_API="https://api.bunny.net"
CDN_API_KEY="${BUNNY_API_KEY}"         # Loaded from CI/CD secrets, never hardcoded
STORAGE_ZONE="theforge-assets"         # Your CDN storage zone name
BUILD_DIR="./dist"                      # Local build output directory

echo "=== Starting Push CDN Deployment ==="
echo "Build directory: $BUILD_DIR"
echo "Target storage zone: $STORAGE_ZONE"

# Step 1: Upload all new static assets to the CDN storage zone
# The CDN then distributes these to ALL edge PoPs proactively
for asset_file in $(find "$BUILD_DIR" -type f); do

    # Derive the remote path by stripping the local build prefix
    remote_path="${asset_file#$BUILD_DIR/}"

    echo "Uploading: $remote_path"

    # Determine content type based on file extension for correct headers
    content_type="application/octet-stream" # safe default
    case "$asset_file" in
        *.js)    content_type="application/javascript" ;;
        *.css)   content_type="text/css" ;;
        *.html)  content_type="text/html" ;;
        *.webp)  content_type="image/webp" ;;
        *.woff2) content_type="font/woff2" ;;
    esac

    # PUT the file to CDN storage — CDN propagates it to all PoPs
    curl --silent --show-error \
        --request PUT \
        --header "AccessKey: $CDN_API_KEY" \
        --header "Content-Type: $content_type" \
        --data-binary "@$asset_file" \
        "$CDN_PROVIDER_API/storage/v2/$STORAGE_ZONE/$remote_path"
done

# Step 2: Purge old cached versions so users get the new files immediately
# Without this step, edge servers serve stale content until TTL expires
echo "=== Purging stale CDN cache ==="
curl --silent --show-error \
    --request POST \
    --header "AccessKey: $CDN_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{"async": true}' \
    "$CDN_PROVIDER_API/pullzone/theforge-zone/purgeCache"

echo "=== Push CDN Deployment Complete ==="
echo "Assets pre-positioned at all edge PoPs. First users globally get cache HITs."

// CDN Cache Invalidation Service
// Programmatic cache purging after a content update
// Real-world scenario: a product image was updated on the CMS

const https = require('https');

// --- CONFIGURATION ---
const CDN_ZONE_ID   = process.env.CDN_ZONE_ID;   // Your CDN zone identifier
const CDN_API_TOKEN = process.env.CDN_API_TOKEN;  // Never hardcode credentials

/**
 * Purges specific URLs from CDN cache.
 * Call this from a CMS webhook when content is updated.
 *
 * @param {string[]} urlsToInvalidate - Full CDN URLs that need immediate cache eviction
 * @returns {Promise<object>} - Purge job status from CDN provider
 */
async function purgeUrlsFromCdnCache(urlsToInvalidate) {

    console.log(`Purging ${urlsToInvalidate.length} URL(s) from CDN cache...`);

    // Cloudflare Cache Purge API payload format
    const purgePayload = JSON.stringify({
        files: urlsToInvalidate  // Accepts up to 30 URLs per request
    });

    return new Promise((resolve, reject) => {
        const options = {
            hostname: 'api.cloudflare.com',
            path: `/client/v4/zones/${CDN_ZONE_ID}/purge_cache`,
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${CDN_API_TOKEN}`,
                'Content-Type':  'application/json',
                'Content-Length': Buffer.byteLength(purgePayload)
            }
        };

        const apiRequest = https.request(options, (apiResponse) => {
            let responseBody = '';

            apiResponse.on('data', chunk => { responseBody += chunk; });

            apiResponse.on('end', () => {
                const parsed = JSON.parse(responseBody);

                if (parsed.success) {
                    console.log('Cache purge successful:', parsed.result);
                    resolve(parsed.result);
                } else {
                    // Cloudflare returns structured errors — log them clearly
                    console.error('Cache purge failed:', parsed.errors);
                    reject(new Error(parsed.errors[0].message));
                }
            });
        });

        apiRequest.on('error', reject);
        apiRequest.write(purgePayload);
        apiRequest.end();
    });
}

// --- EXAMPLE USAGE ---
// Triggered by a CMS webhook when a product image is updated
async function handleProductImageUpdate(updatedProductId) {
    const affectedUrls = [
        `https://assets.theforge.io/products/${updatedProductId}/hero.webp`,
        `https://assets.theforge.io/products/${updatedProductId}/thumbnail.webp`,
        // Also purge the product page HTML so it reflects the new image
        `https://www.theforge.io/products/${updatedProductId}`
    ];

    try {
        await purgeUrlsFromCdnCache(affectedUrls);
        console.log(`Product ${updatedProductId} is now live at all edge nodes.`);
    } catch (error) {
        console.error('Failed to purge CDN cache. Users may see stale content:', error.message);
        // In production: alert on-call team, fallback to shorter TTL, or retry with backoff
    }
}

handleProductImageUpdate('forge-keyboard-pro-2024');

# Nginx configuration for origin server behind a CDN
# Restricts access to CDN IP ranges only
# Ensures TLS between CDN and origin (optional but recommended)

server {
    listen 443 ssl http2;
    server_name origin.theforge.io;

    # Only allow requests from the CDN's public IP ranges
    # (Cloudflare IPs as of 2026, check official list regularly)
    allow 173.245.48.0/20;
    allow 103.21.244.0/22;
    # ... add all CDN IP ranges
    deny all;

    ssl_certificate     /etc/ssl/certs/origin.crt;
    ssl_certificate_key /etc/ssl/private/origin.key;

    location / {
        proxy_pass http://app_backend:3000;

        # Trust the CDN's forwarded headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $http_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;

        # Prevent CDN from forwarding malicious headers
        proxy_set_header X-XSS-Protection "1; mode=block";
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    }
}