content-delivery

name: content-delivery description: This skill should be used when the user asks about a "CDN", "edge caching", "static asset delivery", "media / video delivery", "geo distribution of content" or "edge POP selection", "push vs pull CDN", "cache-control headers" / "TTL for static assets", "origin offload", or "origin shield". It gives the recipe for serving bytes from the edge close to users. Use it whenever a design serves images, video, JS/CSS, or downloads to a wide geography, or the origin is saturated by repeat reads of the same files, even if the user doesn't say "CDN".

Content Delivery

Push bytes to the network edge so requests terminate close to the user and never reach the origin. A CDN is the outermost cache layer of a system: get it right and most static/media traffic and a chunk of latency vanish before they hit your servers; get it wrong and you serve stale assets, leak origin load, or pay egress twice.

When to reach for this

The same files (images, video, JS/CSS bundles, downloads, fonts) are read repeatedly by a geographically spread audience; the origin or its bandwidth is the bottleneck for static reads; or cross-region latency on first byte hurts (a cross-continent round trip is ~100 ms — see back-of-the-envelope). A CDN buys latency and origin offload at once.

When NOT to

Highly personalized, per-request dynamic responses with no cacheable shape (a CDN adds a hop and caches nothing). Tiny single-region audiences where the origin already serves reads comfortably (YAGNI — a CDN is another vendor, another bill, another invalidation problem). Strictly fresh data that cannot tolerate any staleness window — that belongs at the origin or behind consistency-coordination, not a TTL-based edge. Naming a CDN before a number shows static reads or geography is the problem is a red flag.

Clarify first

• Content mix — what fraction is cacheable static/media vs uncacheable dynamic/personalized? (Only the cacheable part benefits.)
• Update cadence & staleness budget — how often do assets change, and how stale may an edge copy be? (Drives TTL and invalidation strategy.)
• Geography — where are users, and how concentrated? (Decides whether edge PoPs and geo-routing matter at all.)
• Object size & egress volume — average asset size × requests = egress; this sizes the bill and the offload (→ back-of-the-envelope).
• Origin shape — object store (S3/GCS/blob) or dynamic app server? Can it survive a cold-cache stampede if the edge flushes?

The options

Distribution model — how content reaches the edge

• Pull (origin-pull): the edge fetches on first miss, caches per TTL, serves the rest. Use when traffic is high and content is large or churny — the edge holds only what's actually requested. The default for most systems.
• Push: you upload assets to the CDN ahead of demand and rewrite URLs. Use when the catalog is small/static or launch spikes can't tolerate a cold first-miss (you pre-warm); you accept managing storage and uploads yourself.

Caching key & TTL — what the edge keys on and for how long

• Long TTL + fingerprinted URLs (app.4f9a.js, image.png?v=2): immutable assets cached for months; a content change is a new URL, not an invalidation. Use when you control asset URLs — the cleanest model.
• Short TTL / stale-while-revalidate: bound staleness for content that changes on a schedule. Use when URLs are stable but content updates.

Edge proximity & routing — how a user reaches the nearest PoP

• Anycast / DNS geo-routing: route each user to the closest healthy edge. Use when the audience is multi-region (almost always, for a CDN). Shared with load-balancing — see there for the routing mechanics.

Origin protection — shrinking the origin's exposed surface

• Origin shield / mid-tier cache: a single regional cache layer in front of the origin that all edges pull through, collapsing N edge misses into one origin fetch. Use when origin offload or stampede protection matters more than a little extra latency on cold misses.

Trade-offs

Behavior under stress

A CDN usually absorbs load spikes — that's its job — but it has its own failure shapes, and they tend to dump straight onto the origin.

• Cold cache / mass eviction: after a purge, config push, or TTL synchronized expiry, edge hit rate craters and every PoP pulls from the origin at once. This is a caching thundering herd at global scale. Mitigate: origin shield to collapse misses, TTL jitter, stale-while-revalidate so the edge serves stale while it refetches, staged purges.
• Cache busting / low hit rate: unbounded query-string variation or cookies in the cache key explode the keyspace so nothing stays cached — the origin sees full traffic while you still pay the CDN. Mitigate: normalize/whitelist cache-key params; strip cookies on static paths.
• Hot object: one viral file can exceed a single PoP's capacity, but CDNs scale this far better than an origin — the real risk is a hot uncacheable path punching through to the origin.
• CDN outage / partial PoP failure: the edge is now a dependency in front of everything. Plan origin fallback (clients or DNS failover to origin) and accept the origin must briefly take full load, or use a second CDN (multi-CDN).
• Egress surprise: a misconfigured no-cache or a hot uncacheable asset can 10× the origin egress bill silently.

Monitor: edge hit ratio (cache hit rate), origin offload %, origin request rate (the number that spikes when the edge fails), p95 edge latency by region, egress bytes, and 4xx/5xx at the edge vs origin.

How to apply

1. Clarify the inputs — content mix (cacheable fraction), staleness budget, geography, object size × volume, and origin shape (see Clarify first). If the cacheable fraction is near zero or the audience is single-region, stop here.
2. Pick the distribution model and cache key from the trade-off table: default to pull; switch to push/pre-warm only when cold-miss latency or launch spikes hurt. Prefer long TTL + fingerprinted URLs when you control URLs, else short TTL / stale-while-revalidate.
3. Set the knobs — Cache-Control (max-age, immutable, stale-while-revalidate), the cache key (URL path + whitelisted params; strip cookies on static paths), Vary only where you truly differ, and add an origin shield if offload or stampede protection matters.
4. Stress-test the design — walk a global purge, a config push, and a CDN/PoP outage. Confirm TTL jitter + stale-while-revalidate + shield keep the origin survivable, and that a client/DNS fallback to origin exists.
5. Size it with numbers — estimate hit ratio (target 90%+), origin offload %, and egress (requests × avg object size) via back-of-the-envelope. If egress or origin request rate is alarming, revisit the cache key and TTL.
6. Pick a provider — default to the generic recipe; if a cloud is named, read its provider file for the service mapping and limits (see Choosing a provider).

Dos and don'ts

Do

• Fingerprint immutable assets and cache them for months — turn updates into new URLs, not invalidations.
• Whitelist cache-key params and strip cookies on static paths to keep hit ratio high.
• Add stale-while-revalidate and TTL jitter so synchronized expiry can't stampede the origin.
• Add an origin shield when many edges would otherwise miss to the origin at once.
• Plan an origin/DNS fallback (or multi-CDN) for a CDN or PoP outage.
• Monitor edge hit ratio and origin request rate — the number that spikes when the edge fails.

Don't

• Reach for a CDN before a number shows static reads or geography is the bottleneck.
• Let unbounded query strings or Vary: Cookie explode the keyspace and gut caching.
• Treat a single-region origin shield as free — it is a new chokepoint/SPOF.
• Cache strictly-fresh data on a TTL when zero staleness is required.
• Ship a careless no-cache on a hot asset — it can silently 10× origin egress.

Numbers that matter

The decisive quantities are hit ratio (90%+ is the goal; below 80% question whether content is cacheable), origin offload % (1 − origin-requests/total), and egress (requests × avg object size). Edge-vs-origin latency is the payoff: an edge hit is a same-region round trip (ms to tens of ms) instead of a cross-continent one (~100 ms). Do the egress and offload math with back-of-the-envelope — don't restate its tables here; egress is the line item that usually dominates a CDN bill.

Interface sketch

The contract is mostly HTTP cache headers the origin sets and the edge obeys:

• Cache-Control: public, max-age=31536000, immutable for fingerprinted static.
• Cache-Control: public, max-age=60, stale-while-revalidate=600 for stable URLs with periodic updates.
• ETag / Last-Modified to enable cheap revalidation (304 Not Modified).
• Vary only on headers you truly serve differently on (a careless Vary: Cookie destroys hit rate).
• The cache key: URL path + an explicit whitelist of query params; decide which cookies/headers (if any) are part of it. Invalidation is a PURGE/invalidation API call or (preferably) a URL version bump. Versioned URLs sidestep the purge-propagation race entirely.

Choosing a provider

Default to the generic recipe above. If the user names a cloud, read references/providers/<provider>.md for the managed-service mapping, quotas/limits, and provider-specific trade-offs. If no file exists for that provider, the generic recipe is the answer.

Diagram

To visualize the edge → shield → origin pull path (and the dashed cold-miss arrow, plus geo-routing from clients to the nearest PoP), use the in-plugin architecture-diagram skill. Sketch the edge nodes in the cache color and the origin in its store color; do not embed Mermaid here.

Related building blocks

• caching — owned-concept lives in: invalidation, eviction, TTL, and thundering-herd theory live there; the CDN is the edge tier above the app/distributed cache and alternative to origin reads for static/media.
• load-balancing — owned-concept lives in: the geo/anycast routing and origin health checks that send users to the nearest edge.
• back-of-the-envelope — feeds into this: supplies the egress, offload %, and latency-payoff numbers that justify a CDN.
• data-storage — depends on: the object store that is usually the CDN's origin.
• consistency-coordination — alternative to this for data that cannot tolerate any staleness window (serve from origin, not a TTL-based edge).
• system-design — pairs with (back-link): the orchestrator that routes here when a design serves static/media at geographic scale.

References

• references/deep-dive.md — cache-key normalization, Cache-Control directive semantics, push vs pull mechanics, origin shield / tiered topology, invalidation vs versioning races, multi-CDN, and media-specific delivery (segmented HLS/DASH, range requests, signed URLs). Read when designing the edge layer in detail.
• references/providers/{generic,aws,azure,gcp}.md — service mappings, limits, and pitfalls per environment.