docs: Workers Cache re-architecture proposal (Chapter 14)#46
Draft
scottmessinger wants to merge 1 commit into
Draft
docs: Workers Cache re-architecture proposal (Chapter 14)#46scottmessinger wants to merge 1 commit into
scottmessinger wants to merge 1 commit into
Conversation
Design proposal for adopting Cloudflare's July 2026 Workers Cache (per-entrypoint cache via the exports map, ctx.exports caching, immutable + arbitrary Vary, ctx.cache.purge). Proposes a Gateway (auth/CORS, always runs) + cached Reader WorkerEntrypoint split so auth stays in front of the cache, plus immutable content-addressed frames and frame-polling to decouple DO load from watcher count. Documents the storage-layer prerequisites (reads are not immutable at a fixed offset today), the silent-failure cache-keying hazards (ctx.props sharding, Authorization -> BYPASS, per-subscriber key fragmentation, unverified cross-colo tiering), and the relay-DO-tree non-goal for low-latency push beyond ~32K/stream. Status: PROPOSED — gated on Stage 0 staging verification and two sign-off decisions. Supersedes Chapters 4-7 if adopted. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015zpKb8VddYgqXP5xygVj5r
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
durable-streams-demo-draw | bb38102 | Jul 06 2026, 04:33 PM |
scottmessinger
pushed a commit
that referenced
this pull request
Jul 8, 2026
…napshot The pkg.pr.new tarball for @cloudflare/vitest-pool-workers@11632 was republished with different content, so pnpm install --frozen-lockfile failed with ERR_PNPM_TARBALL_INTEGRITY on every CI job (also red on PR #46). Update the lockfile to the checksum the registry now serves. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WBPrsDvrFACta2rq8qGLVF
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/14-workers-cache-rearchitecture.md(+ index links) — a design proposal for adopting Cloudflare's July 2026 Workers Cache feature. Docs only; no production code changes.This is a plan for review, not an implementation. It went through three rounds of adversarial subagent review (CloudFlare-platform facts, scaling/fan-out, correctness/protocol/security) and is written to record what survived and what didn't.
The proposal in one paragraph
Model a stream as immutable content-addressed frames + one moving tail, and split the worker into a Gateway entrypoint (auth/CORS/routing, always runs, never cached) in front of a cached Reader
WorkerEntrypointreached viactx.exports. Auth then always runs before the cache; private streams cache safely keyed on a resolved capability (not the JWT); CORS/X-Cacheare applied after the cache (noVaryfragmentation). History is servedimmutable; massive live fan-out is served by frame-polling with a negatively-cached gap, which decouples DO load from watcher count (O(colos / pollInterval)).What the adversarial review changed (recorded in the doc)
!upToDatecache predicate, a DO-persistedepoch, project-qualified cache keys, andcaphygiene.ctx.propssharding,Authorization→BYPASS, per-subscriber key fragmentation, unverified cross-colo tiering) are documented; Stage 0 go/no-go is "two JWTs on the samecap→ shared HIT on staging."Status
PROPOSED — gated on Stage 0 staging verification and two sign-off decisions (security boundary; how far to go in one pass). Supersedes Chapters 4–7 if adopted. No code is changed by this PR.
🤖 Generated with Claude Code
https://claude.ai/code/session_015zpKb8VddYgqXP5xygVj5r
Generated by Claude Code