/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

| Option | What it solves | What it worsens | Change it when | |---|---|---|---| | Pull CDN | Edge holds only requested content; no upload pipeline | First request per object is a slow miss; redundant re-pulls when TTL expires before content changes | Cold-miss latency or launch spikes hurt → push / pre-warm | | Push CDN | No cold miss; full control of what's cached and when | You own upload + storage + URL rewriting; pay to store rarely-read assets | Catalog grows or churns → pull | | Long TTL + fingerprinted URLs | Near-permanent caching; updates are new URLs (no invalidation race) | Requires build/URL control; old versions linger at edge until aged out | URLs are not under your control → short TTL | | Short TTL / stale-while-revalidate | Bounded staleness on stable URLs | More origin revalidation traffic; synchronized expiry can stampede | Content is truly immutable → fingerprint + long TTL | | Geo-routing / anycast | Users hit the nearest edge; lower latency | More PoPs to reason about; routing can send users to a degraded PoP | Single-region audience → skip it | | Origin shield | Collapses edge misses into one origin fetch; protects origin | Extra hop on cold path; the shield is a new chokepoint/SPOF if single-region | Origin is robust and offload is already enough → drop it |

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 busti