[Cache] Add missing purge edge-case documentation - #33306
Conversation
Review
Code ReviewThis code review is in beta and may not always be helpful — use your judgment. No code review issues found. Conventions❌ This review could not complete this run; results may be incomplete. It will retry on the next push. Style Guide ReviewNo style-guide issues found. CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
- index.mdx: note that HTTP 200 does not confirm eviction - purge-by-single-file.mdx: redirect responses subsection - purge-everything.mdx: caution callout for origin cache-fill spike
3476a0b to
2d2fece
Compare
🚀 Deploying Preview to Cloudflare 🚀Preview URL: https://cache-purge-edge-case-docs-dee1922.previews.developers.cloudflare.com (commit f2b050e)This URL reflects your latest Preview deploymentPreview Deployments by commit
|
|
[AI] Addressing CR-83b35cfca815, SG-75a49e9ab491, and SG-406b148f414d in the next commit. Note on CR-83b35cfca815: agreed that the current |
CR-83b35cfca815: replace curl example that only showed first redirect hop
and matched content-location. Use curl -Ls -o /dev/null -w '%{url_effective}'
which follows all redirects with GET and outputs the final URL directly.
SG-75a49e9ab491: wrap HTTP status codes 301 and 302 in backticks per
Cloudflare style guide (monospace for HTTP status codes).
SG-406b148f414d: wrap HTTP 200 in backticks in index.mdx for the same
reason.
|
[AI] Addressing both findings in the next commit. CR-0ff315b2aa28: The text/command mismatch is real — fixing by rewording the surrounding text to match the command, rather than changing the command. The SG-f41779aeedad: Applying the bot's suggested active voice rewrite verbatim. |
CR-0ff315b2aa28: fix text/command mismatch in redirect purge section. Keep curl -Ls url_effective (follows all redirects with GET, outputs final URL). Reword surrounding text to match: 'follow the redirect chain to its end' / 'outputs the final URL after following all redirects'. Not using bot's curl -sI suggestion as -I sends HEAD. SG-f41779aeedad: rewrite passive voice in index.mdx to active voice. 'the request was received' -> 'Cloudflare received the request' 'the targeted content was cached' -> 'Cloudflare cached the targeted content' 'any content was evicted' -> 'evicted any content'
|
|
||
| :::note | ||
| A successful purge request returns `HTTP 200`. This indicates that Cloudflare received the request — it does not confirm that Cloudflare cached the targeted content or evicted any content. To verify a purge, request the asset after purging and confirm that `CF-Cache-Status` is no longer `HIT`. | ||
| ::: |
There was a problem hiding this comment.
Is there a link how to get this / headers?
There was a problem hiding this comment.
[AI] Added a link to CF-Cache-Status in f2b050e so readers can find the header documentation and understand how to inspect it.
| To maintain optimal site performance, Cloudflare strongly recommends using single-file (by URL) purging instead of a complete cache purge. | ||
|
|
||
| Purging everything instantly clears all resources from your CDN cache in all Cloudflare data centers. Each new request for a purged resource returns to your origin server to validate the resource. If Cloudflare cannot validate the resource, Cloudflare fetches the latest version from the origin server and replaces the cached version. When a site with heavy traffic contains a lot of assets, requests to your origin server can increase substantially and result in slow site performance. | ||
| Purging everything instantly clears all resources from your CDN cache in all Cloudflare data centers. Each new request for a purged resource returns to your origin server to validate the resource. If Cloudflare cannot validate the resource, Cloudflare fetches the latest version from the origin server and replaces the cached version. |
There was a problem hiding this comment.
unsure what the last sentence means?
There was a problem hiding this comment.
[AI] This is pre-existing text, not part of our change. You're right that "validate the resource" is ambiguous. Rewritten in f2b050e to: "If the cached version is no longer valid, Cloudflare fetches the latest version from your origin server and caches it."
| Purging everything instantly clears all resources from your CDN cache in all Cloudflare data centers. Each new request for a purged resource returns to your origin server to validate the resource. If Cloudflare cannot validate the resource, Cloudflare fetches the latest version from the origin server and replaces the cached version. | ||
|
|
||
| :::caution | ||
| When you purge everything, all cached content for your zone is removed at once. Every subsequent request must be served from your origin until the cache is repopulated. On high-traffic sites with many assets, this can cause a large spike in origin requests and may significantly slow down your site or overload your origin server. |
There was a problem hiding this comment.
can we add a link details on Tiered Caching to help here.
There was a problem hiding this comment.
[AI] Added in f2b050e: "If your zone uses Tiered Cache, cache repopulation also propagates across cache tiers, which can further increase origin load during this period."
Add link to CF-Cache-Status docs in index.mdx note so readers can find documentation on the header and how to inspect it. Clarify pre-existing sentence in purge-everything.mdx: 'cannot validate the resource' was ambiguous — rewritten to 'if the cached version is no longer valid' for clarity. Add Tiered Cache link in caution block: zones with Tiered Cache see purge propagation across cache tiers, which further increases origin load during cache repopulation after purge-everything.
4 participants
Add three missing edge cases to the cache purge documentation.
DEE-1922
index.mdx — note that a 200 response from the purge API does not confirm eviction. The API returns 200 even when the targeted URL was not in cache, which is a frequent source of confusion in support cases.
purge-by-single-file.mdx — new "Redirect responses" subsection explaining that purging a URL that returns a 301/302 removes the cached redirect response, not the destination resource. Customers need to purge the final destination URL.
purge-everything.mdx — promote the existing performance warning to a
:::cautioncallout and recommend targeted purge methods first to reduce origin load.