HTTP Caching & CDN

Why HTTP Caching Exists

Every HTTP response can carry instructions about how it should be cached — by browsers, proxies, and CDN edge nodes. When these instructions are set correctly, repeat requests for the same resource never reach your server at all.

The problem it solves: serving the same bytes to millions of users is wasteful. A 500KB JavaScript bundle served from a single origin to 10 million users is 5TB of transfer. HTTP caching means most of those users never contact your origin.

Cache-Control Header

The primary mechanism. Controls who can cache, for how long, and under what conditions.

Cache-Control: public, max-age=31536000, immutable

Key directives:

Directive	Meaning
public	CDNs and proxies can cache this
private	Only the browser can cache (not CDN)
no-store	Never cache anywhere
no-cache	Cache but revalidate before serving
max-age=N	Fresh for N seconds
s-maxage=N	CDN freshness (overrides max-age for CDNs)
stale-while-revalidate=N	Serve stale for N seconds while refreshing
immutable	Never revalidate during max-age (browser hint)
must-revalidate	Must contact origin when stale, never serve expired

// Express/Node.js — set cache headers
app.get('/api/products/:id', async (req, res) => {
  const product = await getProduct(req.params.id);

  // Public, 5 minute CDN cache, serve stale for 30s while revalidating
  res.set('Cache-Control', 'public, max-age=300, stale-while-revalidate=30');
  res.json(product);
});

// Immutable assets (content-hashed filenames)
app.use('/assets', express.static('dist/assets', {
  setHeaders: (res) => {
    res.set('Cache-Control', 'public, max-age=31536000, immutable');
  },
}));

// Private, user-specific data
app.get('/api/me', authenticate, (req, res) => {
  res.set('Cache-Control', 'private, max-age=60');
  res.json(req.user);
});

ETag and Conditional Requests

An ETag is a fingerprint of the response body. On subsequent requests, the browser sends it back; the server validates and either returns fresh data or 304 Not Modified (no body, saves bandwidth).

import { createHash } from 'crypto';

function generateETag(content: string): string {
  return `"${createHash('md5').update(content).digest('hex')}"`;
}

app.get('/api/config', async (req, res) => {
  const config = await getConfig();
  const body = JSON.stringify(config);
  const etag = generateETag(body);

  // Client sends If-None-Match: "abc123" on repeat requests
  if (req.headers['if-none-match'] === etag) {
    return res.status(304).end(); // Not Modified — no body sent
  }

  res.set('ETag', etag);
  res.set('Cache-Control', 'public, max-age=60, must-revalidate');
  res.json(config);
});

Last-Modified / If-Modified-Since — older, timestamp-based equivalent:

app.get('/api/posts/:id', async (req, res) => {
  const post = await getPost(req.params.id);
  const lastModified = post.updatedAt.toUTCString();

  if (req.headers['if-modified-since'] === lastModified) {
    return res.status(304).end();
  }

  res.set('Last-Modified', lastModified);
  res.set('Cache-Control', 'public, max-age=300');
  res.json(post);
});

CDN Edge Caching

A CDN places servers (PoPs — points of presence) close to users worldwide. Requests hit the nearest PoP. If the PoP has the response cached, it serves it without ever contacting your origin.

User (London) → Cloudflare London PoP → cached response (2ms)
                                       ↓ cache miss
                                       → Your origin (Frankfurt) → 20ms

// Cloudflare Cache API (Workers)
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const cacheKey = new Request(request.url, request);
    const cache = caches.default;

    // Check edge cache
    let response = await cache.match(cacheKey);
    if (response) return response;

    // Cache miss — fetch from origin
    response = await fetch(request);

    // Cache the response at the edge
    const responseToCache = new Response(response.body, response);
    responseToCache.headers.set('Cache-Control', 'public, max-age=300');
    await cache.put(cacheKey, responseToCache);

    return response;
  },
};

CDN cache purging — when content changes, purge the CDN cache:

// Cloudflare API purge
async function purgeCloudflare(urls: string[]): Promise<void> {
  await fetch(`https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${CLOUDFLARE_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ files: urls }),
  });
}

// On product update, purge CDN cache
async function updateProduct(id: string, data: Partial<Product>): Promise<void> {
  await db.products.update(id, data);
  await purgeCloudflare([
    `https://yoursite.com/api/products/${id}`,
    `https://yoursite.com/products/${id}`,
  ]);
}

Vary Header

Tells CDNs to cache different versions based on request headers:

// Different response for mobile vs desktop
res.set('Vary', 'User-Agent'); // ⚠️ terrible — too many variations

// Better: use a normalized hint
res.set('Vary', 'Accept-Encoding'); // compressed vs uncompressed
res.set('Vary', 'Accept');          // JSON vs HTML

Common Caching Patterns

Static assets (JS, CSS, images):

Cache-Control: public, max-age=31536000, immutable

Cache forever. When the file changes, the URL changes (content hash).

API responses (cacheable):

Cache-Control: public, max-age=60, stale-while-revalidate=30

Fresh for 1 minute, serve stale for 30 extra seconds while revalidating.

User-specific API responses:

Cache-Control: private, max-age=30

Browser can cache, CDN cannot.

Never cache:

Cache-Control: no-store

Mutations, payments, sensitive user data.

HTML pages (SPA shell):

Cache-Control: public, max-age=0, must-revalidate
ETag: "abc123"

Always revalidate but serve the cached version if ETag matches (304 response).

Cache-Control Strategy by Resource Type

function getCacheHeaders(resource: 'asset' | 'api' | 'html' | 'user-data'): string {
  switch (resource) {
    case 'asset':
      return 'public, max-age=31536000, immutable';
    case 'api':
      return 'public, max-age=60, stale-while-revalidate=30';
    case 'html':
      return 'public, max-age=0, must-revalidate';
    case 'user-data':
      return 'private, max-age=30';
    default:
      return 'no-store';
  }
}

Debugging HTTP Cache

# Check response headers
curl -I https://yoursite.com/api/products/1

# Check cache status (Cloudflare adds cf-cache-status)
# HIT = served from CDN edge
# MISS = fetched from origin
# EXPIRED = stale, re-fetched
# BYPASS = cache bypassed

# Chrome DevTools → Network → Response Headers → Cache-Control, Age, cf-cache-status
# Age header tells you how old the cached response is (seconds since origin served it)

The Age header is your best debugging tool. If Age: 0, the CDN just fetched from origin. If Age: 240, this response has been cached for 4 minutes.