Mental model
Content Delivery Networks (CDNs) cache static assets and SSG HTML pages on geographically distributed edge servers near users, offloading origin servers and reducing global latency.
User Requests Resource
CDN Edge Node Check
Edge HIT -> Return Local Cache (<10ms)
Edge MISS -> Fetch from Origin Server
Store at Edge with s-maxage & stale-while-revalidate
Theory
max-agevss-maxage:max-agedictates browser cache duration;s-maxagedictates public CDN edge cache duration.stale-while-revalidate: Instructs the CDN edge node to serve a stale cached response immediately while asynchronously fetching an updated version from the origin server in the background.- Edge Invalidation: Programmatically purging cached URLs at CDN edge nodes via API when underlying content changes.
python(11 lines)
1from fastapi import FastAPI, Response
2
3app = FastAPI()
4
5@app.get("/api/v1/catalog")
6async def get_catalog(response: Response):
7 # Instruct CDN Edge to cache for 1 hour, serve stale for 1 day while revalidating
8 response.headers["Cache-Control"] = "public, max-age=300, s-maxage=3600, stale-while-revalidate=86400"
9 response.headers["Vary"] = "Accept-Encoding"
10 return {"status": "success", "catalog": [...]}
Alternatives and trade-offs
- Direct Origin Serving: Simple; expensive bandwidth costs, high latency for distant global users, origin crashes under traffic spikes.
- CDN Edge Caching: Sub-20ms global response times; requires managing cache invalidation hooks on content updates.
Failure modes and misconceptions
- Caching Authenticated API Responses: Sending
s-maxageon endpoints returning user PII causes CDN edge nodes to serve private user data to other users. Always setCache-Control: private, no-storeon authenticated routes. - Missing
VaryHeaders: Failing to setVary: Accept-Encodingcauses CDNs to serve uncompressed Gzip responses to clients requesting Brotli compression.
Reflect before revealing the guide
Decision scenario
Use Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400 on public catalog and static content routes to achieve sub-20ms CDN edge responses globally.
Learning outcomes
- Structure HTTP
Cache-Controldirectives (max-age,s-maxage,stale-while-revalidate). - Programmatically trigger CDN edge cache purges on content updates.
- Prevent security vulnerabilities caused by caching private authenticated endpoints.
Trade-offs
CDN edge caching eliminates origin traffic load and delivers ultra-low latency, but requires strict handling of private endpoint header restrictions and purge APIs.