Mirroring an origin¶
A pull zone puts a cache in front of something that already answers HTTP. Nothing is uploaded: the first request for a path fetches it from the origin, keeps a copy, and serves that copy until it expires.
Then set the kind to pull and give it an origin on the zone's settings page, or create it from the browser and pick pull there.
What it is for¶
- Putting a cache in front of an origin that is slow, far away, or paid for by the request.
- Serving an application's media without moving it out of the application.
- Surviving the origin's bad afternoon.
How long a copy is kept¶
The origin decides, within a window you set. Its Cache-Control: max-age is clamped between the zone's minimum and maximum TTL, so an origin that says five seconds does not turn into five requests a second upstream, and one that says a year does not pin a stale copy for a year.
| setting | what it does |
|---|---|
| minimum TTL | the shortest the origin can persuade us to keep a copy |
| maximum TTL | the longest |
| negative TTL | how long a 404 from the origin is believed |
An origin that sends no-store, no-cache or private is not cached at all. Negative caching matters more than it looks: without it, a path that does not exist upstream is a request upstream every time someone asks, which is what a crawler does.
When the origin is down¶
A copy that has expired is still a copy. If the origin cannot be reached, the stale one is served with X-Cache: STALE rather than an error — a reader gets slightly old content instead of a broken page. That behaviour is what the acceptance test for pull zones exercises: an origin is started, mirrored, switched off mid-test, and the next request answers 200.
One fetch at a time¶
When ten requests for the same uncached path arrive together, one goes to the origin and the other nine wait for it. Without that, a popular path expiring is a thundering herd upstream at exactly the moment the origin is busiest.
Loops¶
A pull zone whose origin points back at this service would fetch from itself. Every outgoing request carries a Via header, and a request that arrives already carrying ours is refused rather than served, so a misconfiguration fails immediately instead of spinning.
What a pull zone cannot do¶
- Accept uploads. Its content is the origin's. Writing into one is refused.
- List what it has not seen. A storage zone knows its paths from the index; a pull zone only knows what it has fetched, so a listing or a prefix purge covers the cached copies and nothing else.
- Delete from the origin. Purging forgets a local copy; the next request fetches it again.
Purging¶
cdn purge acme-images img/logo.png # named paths
cdn purge acme-images --prefix img/ # everything under a prefix
cdn purge acme-images --all # the whole zone
Purging never deletes anything: a storage zone's objects stay in S3 and a pull zone's stay at the origin. That is what makes it safe to hand to anyone with the purge scope. In the browser, emptying a whole zone additionally requires the owner role and the zone's name typed out, because it is a thundering herd at the origin and should take a moment of deliberate typing.