Skip to content

[Workers] Document Workers Caching#30018

Open
danlapid wants to merge 3 commits into
productionfrom
dlapid/workersCache
Open

[Workers] Document Workers Caching#30018
danlapid wants to merge 3 commits into
productionfrom
dlapid/workersCache

Conversation

@danlapid

Copy link
Copy Markdown
Contributor

Add docs for Workers Caching — caching HTTP responses from a Worker so that Cloudflare serves them without executing the Worker.

New pages under src/content/docs/workers/cache/:

  • configuration.mdx — enabling caching, Cache-Control semantics, TTL and stale-while-revalidate guidance, cf-cache-status, Cache-Tag
  • cache-keys.mdx — what the cache key includes, multi-tenant safety with ctx.props, invalidating cache across deployments
  • purge.mdx — ctx.cache.purge() with tags, pathPrefixes, and purgeEverything; versioned purging with the version metadata binding
  • debugging.mdx — diagnosing why caching is not behaving as expected
  • limitations.mdx — unsupported scenarios, limits, relationship to zone cache, the Cache API, and fetch() subrequests

index.mdx as a landing page with a quickstart showing wrangler deploy + curl observing HIT/MISS, plus a Durable Object wrapping pattern for caching DO responses.

workers/platform/pricing.mdx gets a worked example showing CPU savings with an 80% cache hit rate.

Summary

Screenshots (optional)

Documentation checklist

  • Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
  • The change adheres to the documentation style guide.
  • If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
  • Files which have changed name or location have been allocated redirects.

@danlapid danlapid requested a review from dcpena as a code owner April 17, 2026 03:00
@danlapid danlapid requested a review from a team April 17, 2026 03:00
@github-actions github-actions Bot added product:workers Related to Workers product product:cache Issues or PRs related to Cache size/xl labels Apr 17, 2026
@github-actions

github-actions Bot commented Apr 17, 2026

Copy link
Copy Markdown
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/cache/ @cloudflare/product-owners, @ack-cf
/src/content/docs/workers/ @cloudflare/workers-docs, @GregBrimble, @irvinebroque, @mikenomitch, @korinne, @WalshyDev, @cloudflare/deploy-config, @cloudflare/product-owners, @cloudflare/wrangler, @MattieTK, @cloudflare/dev-plat-leads, @vy-ton

@github-actions

github-actions Bot commented Apr 17, 2026

Copy link
Copy Markdown
Contributor

Preview URL: https://50f868d4.preview.developers.cloudflare.com
Preview Branch URL: https://dlapid-workerscache.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/workers/cache/examples/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/cache/examples/
https://developers.cloudflare.com/workers/cache/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/cache/
https://developers.cloudflare.com/workers/cache/purge/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/cache/purge/
https://developers.cloudflare.com/workers/cache/configuration/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/cache/configuration/
https://developers.cloudflare.com/workers/cache/cache-keys/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/cache/cache-keys/
https://developers.cloudflare.com/workers/cache/debugging/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/cache/debugging/
https://developers.cloudflare.com/workers/cache/limitations/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/cache/limitations/
https://developers.cloudflare.com/workers/platform/pricing/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/platform/pricing/
https://developers.cloudflare.com/workers/reference/how-the-cache-works/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/reference/how-the-cache-works/
https://developers.cloudflare.com/cache/interaction-cloudflare-products/workers/ https://dlapid-workerscache.preview.developers.cloudflare.com/cache/interaction-cloudflare-products/workers/
https://developers.cloudflare.com/workers/runtime-apis/cache/ https://dlapid-workerscache.preview.developers.cloudflare.com/workers/runtime-apis/cache/

@danlapid danlapid force-pushed the dlapid/workersCache branch from ff4b423 to 6482d35 Compare April 28, 2026 01:07
@danlapid danlapid force-pushed the dlapid/workersCache branch from 1819b5e to fe7dc09 Compare May 7, 2026 23:33
@danlapid danlapid force-pushed the dlapid/workersCache branch from fe7dc09 to ce681af Compare May 19, 2026 03:26
@danlapid danlapid requested a review from a team as a code owner May 19, 2026 03:26
@danlapid danlapid force-pushed the dlapid/workersCache branch from ce681af to c153be0 Compare May 19, 2026 21:23
Add docs for Workers Caching — caching HTTP responses from a Worker
so that Cloudflare serves them without executing the Worker.

New pages under src/content/docs/workers/cache/:

- configuration.mdx — enabling caching, Cache-Control semantics,
  TTL and stale-while-revalidate guidance, cf-cache-status, Cache-Tag
- cache-keys.mdx — what the cache key includes, multi-tenant safety
  with ctx.props, invalidating cache across deployments
- purge.mdx — ctx.cache.purge() with tags, pathPrefixes, and
  purgeEverything; versioned purging with the version metadata binding
- debugging.mdx — diagnosing why caching is not behaving as expected
- limitations.mdx — unsupported scenarios, limits, relationship to
  zone cache, the Cache API, and fetch() subrequests

index.mdx as a landing page with a quickstart showing wrangler deploy +
curl observing HIT/MISS, plus a Durable Object wrapping pattern for
caching DO responses.

workers/platform/pricing.mdx gets a worked example showing CPU savings
with an 80% cache hit rate.
@danlapid danlapid force-pushed the dlapid/workersCache branch from c153be0 to 651ebf1 Compare May 27, 2026 16:42
@github-actions

Copy link
Copy Markdown
Contributor

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

@github-actions github-actions Bot added the stale label Jun 11, 2026
* [Workers] Correct and expand Workers Caching docs

Round of corrections and additions based on review against pingora-origin
and edgeworker cache-handler source.

Corrections:

- Responses with no Cache-Control are cached by default via RFC 9111
  heuristic freshness; the docs previously said the opposite. Add a
  table of the 10 default-cacheable status codes and their TTLs.
- s-maxage, must-revalidate, and proxy-revalidate disable both
  stale-while-revalidate and stale-if-error, not just s-maxage with SWR.
- no-cache caches with zero freshness rather than bypassing. Document
  the EXPIRED, REVALIDATED, and UPDATING outcomes precisely.
- x-forwarded-scheme rule was reworded incorrectly; restored.

Additions:

- Request collapsing section with the 20s cache lock.
- stale-if-error section, including the default (infinite) and the
  carve-out for s-maxage / must-revalidate / proxy-revalidate.
- 520-526 and 206 are never cached, even with explicit Cache-Control.
- Cache Deception Armor activation conditions for the heuristic-
  freshness path.
- GET and HEAD share a single cache entry; HEAD on a cold cache is
  converted to GET internally.
- Custom RPC methods and WebSocket upgrades bypass the cache.
- Cloudflare-Workers-Version-Key request header is part of the cache key.
- Cache-Tag character set (printable ASCII), 1024 chars per tag,
  1000 tags per response, case-insensitive purge matching, silent
  drop of invalid tags.
- Standardized the Cf-Cache-Status value list across files.
- tags and pathPrefixes can be combined in a single purge() call.
- Cf-Cache-Status: STALE debugging section.

* [Workers] Style fixes from docs bot review

Address style guide warnings from the cloudflare-docs-bot review on
PR #31149:

- Replace directional words ('table below', 'listed above') with
  direct references.
- Replace 'doesn't' with 'does not'.
- Replace 'see [link]' with 'refer to [link]' in newly added text.
- Remove 'Note that' filler.
- Break a semicolon-joined sentence into two.
@elithrar elithrar requested review from ack-cf and vy-ton as code owners June 12, 2026 19:32
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

Review

⏸️ Automatic reviews for this PR are paused.

This PR has already received 2 automatic reviews. To run another review, a codeowner can comment /review or /full-review. To permanently lift the limit for this PR, a codeowner can comment /ignore-review-limit.

Tip: Keep PRs in draft mode until they are ready for review — the bot skips draft PRs automatically.

@github-actions

github-actions Bot commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

CI run failed: build logs

@github-actions

Copy link
Copy Markdown
Contributor

Broken Links

Found 1 broken link(s) across 1 file(s).

File Link Position Error
workers/cache/index.mdx /email-routing/email-workers/ 209:302 invalid link

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

product:cache Issues or PRs related to Cache product:workers Related to Workers product size/xl stale

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants