CDN Caching Reference

Cache-Control directives

Response directives (server to CDN/browser)

Common patterns

# Static assets with content hash (app.a1b2c3.js)
Cache-Control: public, max-age=31536000, immutable

# HTML pages - always fresh but fast
Cache-Control: public, max-age=0, must-revalidate
# or with stale-while-revalidate for speed
Cache-Control: public, max-age=60, stale-while-revalidate=86400

# API responses - short TTL
Cache-Control: public, s-maxage=10, stale-while-revalidate=30

# Personalized content - browser only
Cache-Control: private, max-age=300

# Sensitive data - no caching anywhere
Cache-Control: no-store

Vary header

The Vary header tells caches to store separate versions based on request header values.

# Different response per encoding
Vary: Accept-Encoding

# Different response per auth token (effectively uncacheable at CDN)
Vary: Authorization

# Multiple varies
Vary: Accept-Encoding, Accept-Language, Cookie

Critical rule: If your response depends on cookies or auth headers, you MUST set Vary appropriately or risk serving one user's content to another.

Performance impact: Each unique combination of Vary header values creates a separate cache entry. Vary: Cookie effectively disables CDN caching because cookies differ per user. Prefer Vary on specific, low-cardinality headers.

Surrogate keys / cache tags

Surrogate keys allow targeted cache invalidation without purging entire zones.

Cloudflare (Enterprise)

# Response header
Surrogate-Key: product-123 category-shoes homepage

# Purge by tag via API
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
  -H "Authorization: Bearer {token}" \
  -d '{"tags": ["product-123"]}'

Fastly

# Response header
Surrogate-Key: product-123 category-shoes

# Purge
curl -X POST "https://api.fastly.com/service/{id}/purge/product-123" \
  -H "Fastly-Key: {token}"

CloudFront (invalidation paths)

# CloudFront uses path-based invalidation, not tags
aws cloudfront create-invalidation \
  --distribution-id E1234 \
  --paths "/products/123" "/category/shoes/*"

CloudFront invalidations are slow (5-15 minutes) and limited to 1000 free/month. For frequent invalidation, use versioned URLs instead.

Cache key design

The cache key determines what makes a request "unique" for caching purposes.

Default cache key components

Most CDNs use: scheme + host + path + query string as the default cache key.

Custom cache key strategies

// Cloudflare Workers - normalize cache key
function getCacheKey(request: Request): Request {
  const url = new URL(request.url);

  // Strip tracking query params that don't affect content
  const stripParams = ['utm_source', 'utm_medium', 'utm_campaign', 'fbclid', 'gclid'];
  stripParams.forEach((p) => url.searchParams.delete(p));

  // Sort remaining params for consistency
  url.searchParams.sort();

  // Normalize to lowercase path
  url.pathname = url.pathname.toLowerCase();

  return new Request(url.toString(), request);
}

Common cache key mistakes

Tiered caching

How tiers work

User -> L1 Edge PoP (closest) -> L2 Regional Shield -> Origin

L1 cache miss: check L2 before going to origin
L2 cache miss: fetch from origin, populate both L2 and L1

Configuration

Cloudflare Tiered Cache: Enable in dashboard or via API. Argo Tiered Cache uses Cloudflare's network to route cache misses through optimal regional PoPs.

CloudFront Origin Shield: Enable per-origin, choose the region closest to your origin server. Costs $0.0090/10,000 requests.

Fastly Shielding: Configure a shield PoP per backend in VCL or UI.

Benefits

• Reduces origin load by 50-90% (L1 misses are absorbed by L2)
• Improves cache hit ratio because L2 aggregates requests from many L1 PoPs
• Fewer origin connections means lower origin cost

Cache invalidation strategies

Best practice: combine strategies

Static assets: versioned URLs (app.abc123.js) + immutable cache
HTML pages:    short TTL (60s) + stale-while-revalidate (24h) + surrogate key purge on publish
API responses: short TTL (5-10s) + stale-while-revalidate (30s)
User data:     private, no-store, or short max-age with Vary: Authorization

ETag and conditional requests

# Origin response
ETag: "abc123"
Cache-Control: public, max-age=60

# After TTL expires, CDN sends conditional request
If-None-Match: "abc123"

# Origin responds 304 Not Modified (no body transferred)
# CDN refreshes TTL and serves cached body

ETags reduce bandwidth but still require an origin round-trip on revalidation. For truly static content, prefer long max-age with versioned URLs to avoid revalidation entirely.

CDN-specific headers

Cloudflare Workers Reference

Runtime environment

Workers run on V8 isolates with Web Platform APIs. Key differences from Node.js:

• No require() or CommonJS - use ES modules (import/export)
• No process, Buffer global, fs, path - use TextEncoder, crypto.subtle, Web Streams
• CPU time limit: 10ms (free), 50ms (paid), measured as actual CPU, not wall-clock
• Memory limit: 128MB per isolate
• Max request body: 100MB (free plan restricted further)
• Subrequest limit: 50 fetch calls per request (1000 on paid)

Module format

// The standard Workers module format (recommended)
export interface Env {
  MY_KV: KVNamespace;
  MY_R2: R2Bucket;
  MY_DB: D1Database;
  MY_DO: DurableObjectNamespace;
  MY_SECRET: string; // from wrangler secret
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // handle request
    return new Response('Hello');
  },

  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
    // cron trigger handler
    ctx.waitUntil(doWork(env));
  },

  async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void> {
    // queue consumer handler
    for (const msg of batch.messages) {
      console.log(msg.body);
      msg.ack();
    }
  },
};

Wrangler CLI

# Create new project
npx wrangler init my-worker

# Dev server with live reload
npx wrangler dev

# Deploy to production
npx wrangler deploy

# Tail production logs
npx wrangler tail

# Manage secrets
npx wrangler secret put MY_API_KEY
npx wrangler secret list

# KV namespace management
npx wrangler kv:namespace create MY_KV
npx wrangler kv:key put --namespace-id=<id> "key" "value"
npx wrangler kv:key get --namespace-id=<id> "key"

# D1 database
npx wrangler d1 create my-database
npx wrangler d1 execute my-database --command "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"

wrangler.toml configuration

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# KV binding
[[kv_namespaces]]
binding = "MY_KV"
id = "abc123"
preview_id = "def456"

# R2 bucket
[[r2_buckets]]
binding = "MY_R2"
bucket_name = "my-bucket"

# D1 database
[[d1_databases]]
binding = "MY_DB"
database_name = "my-database"
database_id = "xyz789"

# Durable Object
[durable_objects]
bindings = [
  { name = "MY_DO", class_name = "MyDurableObject" }
]

[[migrations]]
tag = "v1"
new_classes = ["MyDurableObject"]

# Cron triggers
[triggers]
crons = ["*/5 * * * *"]  # every 5 minutes

# Environment-specific overrides
[env.staging]
name = "my-worker-staging"
routes = [{ pattern = "staging.example.com/*", zone_name = "example.com" }]

[env.production]
name = "my-worker-production"
routes = [{ pattern = "example.com/*", zone_name = "example.com" }]

KV Namespace API

// Write
await env.MY_KV.put('key', 'value');
await env.MY_KV.put('key', JSON.stringify(data), {
  expirationTtl: 3600,     // seconds until auto-delete
  metadata: { version: 1 }, // small metadata object (max 1024 bytes)
});

// Read
const value = await env.MY_KV.get('key');                    // string | null
const data = await env.MY_KV.get('key', 'json');             // parsed JSON
const binary = await env.MY_KV.get('key', 'arrayBuffer');    // ArrayBuffer
const withMeta = await env.MY_KV.getWithMetadata('key', 'json');
// { value: T | null, metadata: M | null }

// Delete
await env.MY_KV.delete('key');

// List keys (paginated, max 1000 per call)
const list = await env.MY_KV.list({ prefix: 'user:', limit: 100 });
// { keys: Array<{ name: string, expiration?: number, metadata?: unknown }>, list_complete: boolean, cursor?: string }

Durable Objects

export class RateLimiter {
  private state: DurableObjectState;
  private requests: number[] = [];

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    // Load persisted state on construction
    this.state.blockConcurrencyWhile(async () => {
      this.requests = (await this.state.storage.get<number[]>('requests')) ?? [];
    });
  }

  async fetch(request: Request): Promise<Response> {
    const now = Date.now();
    const windowMs = 60_000;
    const maxRequests = 100;

    // Prune old entries
    this.requests = this.requests.filter((t) => now - t < windowMs);

    if (this.requests.length >= maxRequests) {
      return new Response('Rate limited', { status: 429 });
    }

    this.requests.push(now);
    await this.state.storage.put('requests', this.requests);

    return new Response('OK', { status: 200 });
  }
}

Key Durable Object properties:

• Single-threaded - only one instance of a named DO exists globally
• Strong consistency - reads and writes within a DO are serialized
• Location-aware - the DO runs near its first requester, then stays put
• Storage API - state.storage.get/put/delete/list with transactional semantics
• Hibernation - idle DOs are evicted from memory but state persists

D1 (SQLite at the edge)

// Query
const result = await env.MY_DB.prepare('SELECT * FROM users WHERE id = ?')
  .bind(userId)
  .first<User>();

// Batch queries (single round-trip)
const results = await env.MY_DB.batch([
  env.MY_DB.prepare('INSERT INTO users (name) VALUES (?)').bind('Alice'),
  env.MY_DB.prepare('INSERT INTO users (name) VALUES (?)').bind('Bob'),
]);

// Raw query for dynamic SQL
const { results: rows } = await env.MY_DB.prepare(
  'SELECT * FROM users WHERE name LIKE ? LIMIT ?'
).bind('%search%', 10).all<User>();

Cache API

// Use the Workers Cache API for fine-grained cache control
const cache = caches.default;

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const cacheKey = new Request(request.url, request);

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

    // Fetch from origin
    response = await fetch(request);

    // Clone and cache (response body can only be read once)
    const responseToCache = new Response(response.body, response);
    responseToCache.headers.set('Cache-Control', 'public, max-age=3600');

    // waitUntil so caching doesn't block response
    ctx.waitUntil(cache.put(cacheKey, responseToCache.clone()));

    return responseToCache;
  },
};

Other edge platforms comparison

Latency Optimization Reference

Understanding latency sources

Every HTTP request accumulates latency from multiple sources:

DNS lookup:        1-50ms   (cached: ~0ms)
TCP handshake:     10-100ms (one RTT)
TLS handshake:     20-200ms (one or two RTTs)
TTFB (server):     10-500ms (processing time + network)
Content transfer:  varies   (depends on size and bandwidth)

Total cold request: 50-850ms before first byte of content arrives. Warm/cached request: 0-10ms if served from edge cache.

The goal of edge computing is to eliminate as many of these layers as possible by serving responses from the nearest PoP.

TTFB reduction techniques

1. Serve from edge cache (eliminate origin)

The single biggest TTFB win. If the response is in edge cache, the entire origin round-trip (50-200ms) is eliminated.

// Cloudflare Worker: aggressive caching with background revalidation
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const cache = caches.default;
    const cacheKey = request;

    let response = await cache.match(cacheKey);
    if (response) {
      // Check if stale - if so, revalidate in background
      const age = parseInt(response.headers.get('Age') ?? '0');
      const maxAge = 60; // seconds
      if (age > maxAge) {
        ctx.waitUntil(revalidateAndCache(request, cache, cacheKey));
      }
      return response;
    }

    // Cache miss - fetch and cache
    response = await fetch(request);
    const cachedResponse = new Response(response.body, response);
    cachedResponse.headers.set('Cache-Control', 'public, max-age=60, stale-while-revalidate=86400');
    ctx.waitUntil(cache.put(cacheKey, cachedResponse.clone()));
    return cachedResponse;
  },
};

async function revalidateAndCache(
  request: Request,
  cache: Cache,
  cacheKey: Request
): Promise<void> {
  const fresh = await fetch(request);
  const toCache = new Response(fresh.body, fresh);
  toCache.headers.set('Cache-Control', 'public, max-age=60, stale-while-revalidate=86400');
  await cache.put(cacheKey, toCache);
}

2. Connection reuse and keep-alive

Reusing TCP/TLS connections to origin eliminates handshake latency (30-300ms per new connection).

// Cloudflare Workers automatically reuse connections to origin
// But ensure your origin supports keep-alive:
//   - Set Connection: keep-alive (HTTP/1.1 default)
//   - Enable HTTP/2 on your origin for multiplexing
//   - Set reasonable keep-alive timeout (60-120s)

3. Early hints (103)

Send the browser a 103 Early Hints response before the full response is ready, allowing it to preload critical resources while the server processes the request.

// Cloudflare supports Early Hints via Link headers
export default {
  async fetch(request: Request): Promise<Response> {
    const response = await fetch(request);
    const newResponse = new Response(response.body, response);

    // These Link headers are sent as 103 Early Hints by Cloudflare
    newResponse.headers.append('Link', '</styles/main.css>; rel=preload; as=style');
    newResponse.headers.append('Link', '</scripts/app.js>; rel=preload; as=script');
    newResponse.headers.append('Link', '</fonts/inter.woff2>; rel=preload; as=font; crossorigin');

    return newResponse;
  },
};

4. Request collapsing / coalescing

When multiple users request the same uncached resource simultaneously, only send one request to origin and share the response.

Cloudflare does this automatically for cacheable content. For Workers:

// Manual request coalescing with in-flight map
const inFlight = new Map<string, Promise<Response>>();

async function fetchWithCoalescing(url: string): Promise<Response> {
  const existing = inFlight.get(url);
  if (existing) return existing.then((r) => r.clone());

  const promise = fetch(url).then((r) => {
    inFlight.delete(url);
    return r;
  });

  inFlight.set(url, promise);
  return promise.then((r) => r.clone());
}

Note: In Workers, the in-flight map only persists within a single isolate instance. Cross-isolate coalescing requires Durable Objects or CDN-level features.

5. Streaming responses

Start sending bytes to the client before the full response is assembled. Reduces perceived TTFB because the browser can start parsing HTML/rendering while the rest streams in.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { readable, writable } = new TransformStream();
    const writer = writable.getWriter();
    const encoder = new TextEncoder();

    // Start streaming immediately
    const streamBody = async () => {
      // Send HTML head immediately (browser starts loading CSS/JS)
      await writer.write(encoder.encode('<!DOCTYPE html><html><head><link rel="stylesheet" href="/style.css"></head><body>'));

      // Fetch data (this takes time)
      const data = await fetch('https://api.example.com/data').then((r) => r.json());

      // Stream the body content
      await writer.write(encoder.encode(`<main>${renderContent(data)}</main>`));
      await writer.write(encoder.encode('</body></html>'));
      await writer.close();
    };

    // Don't await - let it stream
    streamBody();

    return new Response(readable, {
      headers: { 'Content-Type': 'text/html; charset=utf-8' },
    });
  },
};

6. Prefetching and preconnecting

Instruct the browser to start connections early:

<!-- DNS prefetch for third-party domains -->
<link rel="dns-prefetch" href="https://api.example.com">

<!-- Preconnect: DNS + TCP + TLS (saves 100-300ms) -->
<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin>

<!-- Prefetch: download resource for likely next navigation -->
<link rel="prefetch" href="/next-page.html">

<!-- Preload: download critical resource for current page -->
<link rel="preload" href="/hero-image.webp" as="image">

Edge-side includes (ESI)

Compose pages from cached fragments with different TTLs:

<!-- Main page template cached for 24 hours -->
<html>
<body>
  <header>
    <!-- User-specific nav cached for 5 minutes -->
    <esi:include src="/fragments/nav?user=123" />
  </header>
  <main>
    <!-- Product content cached for 1 hour -->
    <esi:include src="/fragments/product/456" />
  </main>
  <footer>
    <!-- Static footer cached indefinitely -->
    <esi:include src="/fragments/footer" />
  </footer>
</body>
</html>

Workers equivalent (no ESI needed):

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Fetch fragments in parallel with different cache policies
    const [nav, product, footer] = await Promise.all([
      fetchCached('/fragments/nav', 300),      // 5 min
      fetchCached('/fragments/product/456', 3600), // 1 hour
      fetchCached('/fragments/footer', 86400),  // 24 hours
    ]);

    const html = `<html><body>
      <header>${nav}</header>
      <main>${product}</main>
      <footer>${footer}</footer>
    </body></html>`;

    return new Response(html, {
      headers: { 'Content-Type': 'text/html' },
    });
  },
};

async function fetchCached(path: string, ttl: number): Promise<string> {
  const response = await fetch(`https://origin.example.com${path}`, {
    cf: { cacheTtl: ttl, cacheEverything: true },
  });
  return response.text();
}

Measuring latency correctly

Real User Monitoring (RUM)

// Collect Navigation Timing data from real users
function collectTimings(): void {
  const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;

  const metrics = {
    dns: nav.domainLookupEnd - nav.domainLookupStart,
    tcp: nav.connectEnd - nav.connectStart,
    tls: nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0,
    ttfb: nav.responseStart - nav.requestStart,
    download: nav.responseEnd - nav.responseStart,
    domReady: nav.domContentLoadedEventEnd - nav.fetchStart,
    fullLoad: nav.loadEventEnd - nav.fetchStart,
  };

  // Send to analytics endpoint
  navigator.sendBeacon('/analytics/timing', JSON.stringify(metrics));
}

// Run after page load
window.addEventListener('load', () => setTimeout(collectTimings, 0));

Geographic breakdown

Always segment latency data by geography. A global P50 of 150ms might hide:

• US users at 50ms
• EU users at 120ms
• Southeast Asia users at 400ms (no nearby PoP, or origin in US-East)

Synthetic monitoring

# Test from multiple regions with curl
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nTCP: %{time_connect}s\nTLS: %{time_appconnect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://example.com

# Use tools like:
# - Catchpoint / Pingdom for multi-region synthetic checks
# - WebPageTest for full waterfall analysis
# - Cloudflare Observatory for integrated testing

Latency budget template

Aim for 90%+ cache hit rate to keep the average close to the cache-hit budget.