CDN Architecture & Edge Caching

This reference explains how content delivery networks function at the edge, covering cache behavior, invalidation, and configuration patterns for distributed caching systems. It applies when designing or operating global applications that need low-latency access to static assets or dynamic content.

Cache Behavior and Invalidation

Edge caches store copies of resources locally near end users. A request first hits the nearest edge node, which checks if it has a cached version that satisfies the cache policy.

Cache Control Headers

The Cache-Control header controls caching behavior:

Cache-Control: max-age=3600, public

This tells edge nodes to cache content for one hour and allow public caching. The public directive indicates the response may be cached by any cache, including shared caches.

Cache Invalidation

Invalidation removes stale content from edge nodes. Most systems support invalidation via API endpoints or command-line tools.

Example: Purge Cache

curl -X DELETE \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.example.com/v1/cache/purge" \
  -d '{"urls": ["/images/logo.png", "/css/main.css"]}'

A purge request returns a JSON response indicating success or failure:

{
  "status": "success",
  "purged": [
    "/images/logo.png",
    "/css/main.css"
  ],
  "failed": []
}

If a URL doesn't exist in the cache, the system reports it as failed but does not error.

Cache Hit vs Miss Behavior

When a request hits an edge node:

Cache Hit: The node returns the cached resource with X-Cache: HIT header
Cache Miss: The node fetches from origin and caches the result, returning X-Cache: MISS

Edge Node Configuration

Edge nodes must be configured to handle both cacheable and non-cacheable content. This involves setting up rules for which requests to cache and how long.

Cache Rules

A typical rule defines a URL pattern and associated caching behavior:

{
  "pattern": "/static/*",
  "ttl": 3600,
  "cacheable": true,
  "vary": ["Accept-Encoding", "User-Agent"]
}

The vary field tells the edge node which request headers determine cache keys. If a client sends different Accept-Encoding headers, the system treats them as separate cached entries.

TTL and Expiration

Edge nodes respect TTL values in response headers:

Cache-Control: max-age=3600

If no explicit TTL is set, most systems default to a 1-hour cache period. When content changes, you must either wait for TTL expiration or explicitly invalidate the cache.

Cache Invalidation Patterns

Partial Invalidation

Some systems support partial invalidation by URL path:

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.example.com/v1/cache/invalidate" \
  -d '{"paths": ["/blog/*", "/assets/images/"]}'

This invalidates all resources matching a wildcard pattern.

Cache Invalidation with Tags

Some platforms support tag-based invalidation:

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.example.com/v1/cache/invalidate" \
  -d '{"tags": ["blog-post-123", "image-gallery"]}'

Invalidating by tag purges all content associated with those tags.

Cache Storage and Memory Management

Edge nodes maintain a cache in local memory or disk storage. The cache size is limited by configuration parameters.

Cache Size Configuration

Each edge node has a configured maximum size:

{
  "cache_size_mb": 1024,
  "max_object_size_mb": 50
}

Objects larger than the maximum size may not be cached at all.

Failure Modes and Silent Failures

Cache Invalidation Failures

A purge request may silently succeed even if some URLs were not invalidated:

{
  "status": "success",
  "purged": ["/images/logo.png"],
  "failed": ["/css/main.css"]
}

The system logs the failure but does not return an HTTP error code.

Cache Miss During Invalidation

During cache invalidation, a client might receive a cached version of content that was recently invalidated:

GET /api/users/123
HTTP/1.1 200 OK
X-Cache: MISS
Cache-Control: max-age=60

In this case, the edge node fetched from origin and cached it, but if the origin had changed between fetch and cache, the client receives a stale version.

TTL Misconfiguration

If TTL is set too low, clients frequently hit origin servers. If TTL is too high, stale content persists longer than intended:

Cache-Control: max-age=300

This short TTL means each request may miss the cache and fetch from origin.

Cache Key Generation

Edge nodes generate cache keys based on URL and request headers. The key determines which cached version to serve.

Example Cache Key Calculation

For a request to /static/css/main.css, with Accept-Encoding: gzip:

Cache-Key: /static/css/main.css?Accept-Encoding=gzip

If a different Accept-Encoding is used, the system treats it as a separate cache entry.

Content Negotiation and Vary Headers

The Vary header tells edge nodes to store multiple versions of content based on request headers:

Vary: Accept-Encoding, User-Agent

This means the same URL might have different cached versions depending on client capabilities.

Cache Warm-Up

Edge nodes can be preloaded with content using batch operations or API calls. A warm-up process populates caches before traffic arrives:

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.example.com/v1/cache/warmup" \
  -d '{"urls": ["/index.html", "/about.html"]}'

HTTP Status Codes and Cache Behavior

Edge nodes return specific status codes to indicate cache behavior:

200 OK with X-Cache: HIT indicates a cache hit
200 OK with X-Cache: MISS indicates a cache miss that fetched from origin
304 Not Modified indicates the client's cached version is still valid

Example: Cache Hit Response

HTTP/1.1 200 OK
X-Cache: HIT
Content-Type: text/html
Cache-Control: max-age=3600

Example: Cache Miss Response

HTTP/1.1 200 OK
X-Cache: MISS
Content-Type: text/html
Cache-Control: max-age=3600

Cache Configuration Best Practices

Set Appropriate TTL Values

Use reasonable TTL values for different content types:

Static assets: 1 hour to 1 week
Dynamic content: minutes to hours
API responses: minutes to 1 hour

Use Vary Headers Strategically

Include Vary headers when serving different content based on request headers:

Vary: Accept-Encoding

This prevents returning compressed content to a client that doesn't support it.

Monitor Cache Hit Ratios

Monitor cache hit ratios to optimize performance. Low hit ratios indicate poor cache configuration or frequent invalidations.

Troubleshooting Edge Caching Issues

Diagnosing Cache Misses

If requests frequently miss the cache, check:

Cache-Control headers on responses
Vary headers that might cause key mismatches
Content size limits for caching
Origin server behavior during fetches

Handling Cache Invalidation Errors

When invalidation fails silently, inspect logs for:

Failed URLs in purge requests
Timeouts during cache updates
Configuration issues preventing invalidation

Monitoring Cache Performance

Use headers like X-Cache to monitor performance:

X-Cache: HIT
X-Cache-Time: 0.005

These headers help identify caching behavior and performance issues.

Edge Node Behavior During Failures

If an edge node cannot reach origin, it may serve stale content if configured to do so:

Cache-Control: stale-while-revalidate=60

This directive allows serving cached content while attempting to revalidate with origin. If origin is unreachable, the system serves the stale version for up to 60 seconds.

This page was rewritten on 16 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.