feat(cloudflare): probe route cacheability before CDN warming

[james-elicx]

Summary

• add an opt-in two-stage CDN warm deployment that uploads a probe Worker at 0 percent, discovers concrete routes with real bindings, and probes completed-response cacheability
• embed the resulting route cacheability manifest into a second final Worker version before promotion
• warm and certify active CDN entries only after the manifest-bearing Worker is promoted
• preserve Next.js cache eligibility and response-header precedence across App pages, Route Handlers, Pages Router, middleware, and next.config headers
• fail closed for dynamic usage, unprobed paths, unsupported response types, capacity pressure, deadline expiry, and deployment races

Runtime bounds

• 4 MiB maximum captured response body
• 32 MiB aggregate capture budget
• 2 guaranteed-progress probe or warm requests per isolate
• one absolute 20 second classification deadline shared by HTML and raw RSC capture

Validation

• 529 focused unit and integration tests pass locally
• vp check passes
• vinext package build passes
• @vinext/cloudflare package build passes
• workers-cache example build passes
• five independent cumulative reviews are clean on exact SHA 25ce787
• exact-head review runs covered up to 764 focused tests with format, lint, type, and diff checks clean

Live two-stage proof

URL: https://vinext-cache-probe-mvp-d7aa.vinext.workers.dev

Final Worker version: 023d0969-e6e4-4676-88d9-3b3488b663f5 at 100 percent

• 26 route-pattern probes completed
• 31 manifest routes embedded in the final Worker
• 30 warm requests attempted
• 22 eligible entries warmed and 8 explicit opt-outs safely skipped
• 22 of 22 warmed entries certified reusable
• 0 warm or certification failures
• live Cloudflare Playwright RSC prewarm test passed, including repeated HITs for hashed loading-shell and canonical full-RSC keys

Draft status

Implementation, exact-head review, current-head deployment, and live E2E validation are complete. This remains a draft for design review.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@vinext/cloudflare@3089

npm i https://pkg.pr.new/create-vinext-app@3089

npm i https://pkg.pr.new/@vinext/types@3089

npm i https://pkg.pr.new/vinext@3089

commit: 92ea6c4

[github-actions]

Example	Preview	Production	Original
app-router-cloudflare	preview	production
pages-router-cloudflare	preview	production
app-router-playground	preview	production	original
realworld-api-rest	preview	production
nextra-docs-template	preview	production
benchmarks	preview	production
hackernews	preview	production	original
workers-cache	preview	production
web	preview	production

[github-actions]

Performance benchmarks

Compared 92ea6c4 against base c812639 using alternating same-runner rounds. Next.js was unchanged and skipped.

0 improved · 3 regressed · 3 within ±1.5%

Scenario	Framework	Baseline	Current	Change
Client bundle size (gzip)	vinext	142.2 KB	142.3 KB	⚫ +0.1%
Client entry size (gzip)	vinext	129.5 KB	129.6 KB	⚫ +0.1%
Dev server cold start	vinext	3.19 s	3.16 s	⚫ -0.8%
Production build time	vinext	3.60 s	3.66 s	🔴 +1.9%
RSC entry closure size (gzip)	vinext	116.6 KB	130.0 KB	🔴 +11.5%
Server bundle size (gzip)	vinext	198.1 KB	218.4 KB	🔴 +10.2%

View detailed results and traces

_{🟢 improvement · 🔴 regression · ⚫ change below 1.5% · paired base/head}