[GH-ISSUE #451] Phase 1/2: Consolidate per-request ALS scopes and land initial Pages Router parity #101

New issue

Closed

opened 2026-05-06 12:37:13 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 12:37:13 +02:00

Owner

Originally created by @Divkix on GitHub (Mar 11, 2026).
Original GitHub issue: https://github.com/cloudflare/vinext/issues/451

Problem

Every vinext request path historically relied on multiple nested AsyncLocalStorage.run() calls from different shim modules. That adds measurable overhead on Workers and makes request-scoped state harder to reason about.

Solution

Consolidate request-scoped state into a single UnifiedRequestContext backed by one ALS instance. Individual shims read from the unified store when inside the unified scope and fall back to their standalone ALS outside it for compatibility.

Scope

Phase 1 (this issue / PR #450)

App Router request handling + ISR background regeneration
Shared unified context infrastructure across headers, navigation-state, cache, cache-runtime, fetch-cache, and request-context
Pages Router dev SSR now runs inside the unified scope
Generated Pages Router server entry now runs inside the unified scope
router-state.ts and head-state.ts read from unified context when inside the scope
Pages Router ISR background regeneration is wrapped in unified context for parity
Dual-path fallbacks remain in place for compatibility and staged rollout safety

Deferred to Phase 2 (#478)

#478 is an umbrella follow-up issue and may span more than one PR.

The first follow-up PR should focus on:

Pages Router integration/parity tests for concurrent router/head isolation in dev and prod
Final validation of the Pages Router production path, which currently delegates through the unified renderPage() entry
Documenting the decision for per-call ALS scopes: cacheContextStorage and _unstableCacheAls
ALS architecture documentation

Fallback cleanup is conditional after that validation work. Standalone fallback ALS code should only be removed where it is clearly unnecessary; otherwise it should be kept with rationale.

PR: #450
Phase 2/2 umbrella follow-up: #478

Originally created by @Divkix on GitHub (Mar 11, 2026). Original GitHub issue: https://github.com/cloudflare/vinext/issues/451 ## Problem Every vinext request path historically relied on multiple nested `AsyncLocalStorage.run()` calls from different shim modules. That adds measurable overhead on Workers and makes request-scoped state harder to reason about. ## Solution Consolidate request-scoped state into a single `UnifiedRequestContext` backed by one ALS instance. Individual shims read from the unified store when inside the unified scope and fall back to their standalone ALS outside it for compatibility. ## Scope ### Phase 1 (this issue / PR #450) - App Router request handling + ISR background regeneration - Shared unified context infrastructure across `headers`, `navigation-state`, `cache`, `cache-runtime`, `fetch-cache`, and `request-context` - Pages Router dev SSR now runs inside the unified scope - Generated Pages Router server entry now runs inside the unified scope - `router-state.ts` and `head-state.ts` read from unified context when inside the scope - Pages Router ISR background regeneration is wrapped in unified context for parity - Dual-path fallbacks remain in place for compatibility and staged rollout safety ### Deferred to Phase 2 (#478) `#478` is an umbrella follow-up issue and may span more than one PR. The first follow-up PR should focus on: - Pages Router integration/parity tests for concurrent router/head isolation in dev and prod - Final validation of the Pages Router production path, which currently delegates through the unified `renderPage()` entry - Documenting the decision for per-call ALS scopes: `cacheContextStorage` and `_unstableCacheAls` - ALS architecture documentation Fallback cleanup is conditional after that validation work. Standalone fallback ALS code should only be removed where it is clearly unnecessary; otherwise it should be kept with rationale. ## Related - PR: #450 - Phase 2/2 umbrella follow-up: #478