[PR #450] [MERGED] refactor: phase 1/2 unify per-request ALS into a shared request context #580

New issue

Closed

opened 2026-05-06 13:08:52 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:08:52 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/450
Author: @Divkix
Created: 3/11/2026
Status: ✅ Merged
Merged: 3/13/2026
Merged by: @james-elicx

Base: main ← Head: worktree-refactor/unified-als-request-context

📝 Commits (10+)

31f0065 refactor: consolidate 5 nested ALS scopes into unified request context
3d81a10 test: update entry-templates snapshots for unified ALS context
bd5a8c0 test: update app router waitUntil assertion
d708201 refactor: unify request ALS across router flows
68ff3ed fix: address unified request context review feedback
9408a13 fix: address unified ALS review feedback
cef7e65 fix: address remaining unified ALS review feedback
b8c2c12 fix: wrap Pages Router ISR regeneration in unified context
266d177 Fix dev ISR unified context parity
e5dd085 Merge remote-tracking branch 'origin/main' into worktree-refactor/unified-als-request-context

📊 Changes

26 files changed (+3007 additions, -1787 deletions)

View changed files

📝 packages/vinext/src/entries/app-rsc-entry.ts (+103 -116)
📝 packages/vinext/src/entries/pages-server-entry.ts (+114 -76)
📝 packages/vinext/src/index.ts (+1 -0)
📝 packages/vinext/src/server/app-router-entry.ts (+1 -1)
📝 packages/vinext/src/server/dev-server.ts (+677 -692)
📝 packages/vinext/src/shims/cache-runtime.ts (+28 -7)
📝 packages/vinext/src/shims/cache.ts (+15 -7)
📝 packages/vinext/src/shims/fetch-cache.ts (+26 -1)
📝 packages/vinext/src/shims/head-state.ts (+16 -7)
📝 packages/vinext/src/shims/headers.ts (+28 -31)
📝 packages/vinext/src/shims/i18n-state.ts (+20 -12)
📝 packages/vinext/src/shims/navigation-state.ts (+40 -14)
📝 packages/vinext/src/shims/request-context.ts (+13 -0)
➕ packages/vinext/src/shims/request-state-types.ts (+10 -0)
📝 packages/vinext/src/shims/router-state.ts (+17 -9)
➕ packages/vinext/src/shims/unified-request-context.ts (+170 -0)
📝 tests/__snapshots__/entry-templates.test.ts.snap (+773 -810)
📝 tests/app-router.test.ts (+7 -2)
📝 tests/entry-templates.test.ts (+64 -0)
📝 tests/fetch-cache.test.ts (+32 -0)

...and 6 more files

📄 Description

Summary

Introduces a single UnifiedRequestContext backed by one AsyncLocalStorage instance
Replaces the 5-6 nested ALS scopes used by App Router requests with one unified per-request scope
Lands the initial Pages Router rollout needed for parity: dev SSR, generated Pages server entry, unified-aware router/head shims, and Pages ISR background regeneration

Depends on: #432, #433, #434, #435, #436, #442

Closes #451
Follow-up tracked in #478

Included In This PR

File / area	Change
`shims/unified-request-context.ts`	NEW unified ALS module
`shims/headers.ts`	Dual-path `_getState()`, unified-aware wrapper semantics
`shims/navigation-state.ts`	Dual-path `_getState()`, unified-aware wrapper semantics
`shims/cache.ts`	Unified-aware request-scoped cache state
`shims/cache-runtime.ts`	Unified-aware private cache state
`shims/fetch-cache.ts`	Unified-aware tag collection + `ensureFetchPatch()`
`shims/request-context.ts`	Unified-aware execution context access
`shims/router-state.ts`	Pages Router SSR state reads from unified scope when present
`shims/head-state.ts`	Pages Router head state reads from unified scope when present
`server/dev-server.ts`	Pages Router dev SSR wrapped in unified scope
`entries/pages-server-entry.ts`	Generated Pages Router server entry wrapped in unified scope
`entries/app-rsc-entry.ts`	App Router handler + ISR regen wrapped in unified scope
`tests/unified-request-context.test.ts`	New unit coverage for unified ALS behavior

Deferred To #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
Validation of the production Pages Router path, which currently delegates through unified renderPage()
Documentation of the per-call ALS decision for cacheContextStorage and _unstableCacheAls
ALS architecture documentation

Fallback cleanup remains conditional and should only happen if those tests/validation show the standalone paths are truly unnecessary.

What Is Intentionally Still Separate

cacheContextStorage in cache-runtime.ts: per-cache-call ALS, not per-request
_unstableCacheAls in cache.ts: per-call scope for unstable_cache()
Standalone fallback ALS paths in shims: kept for compatibility and staged rollout safety until the phase-2 validation work is complete

Test Plan

Unified request-context unit tests
Existing shim/request-context coverage
App Router + ISR + fetch-cache + features coverage
Routing + nextjs-compat coverage
Typecheck, lint, format
CI full suite + Playwright E2E

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/450 **Author:** [@Divkix](https://github.com/Divkix) **Created:** 3/11/2026 **Status:** ✅ Merged **Merged:** 3/13/2026 **Merged by:** [@james-elicx](https://github.com/james-elicx) **Base:** `main` ← **Head:** `worktree-refactor/unified-als-request-context` --- ### 📝 Commits (10+) - [`31f0065`](https://github.com/cloudflare/vinext/commit/31f0065908c7a3e7f7fb5247195b8efa29c0ebe9) refactor: consolidate 5 nested ALS scopes into unified request context - [`3d81a10`](https://github.com/cloudflare/vinext/commit/3d81a101d79d3395e31098f3d1ce40a1feb5bd99) test: update entry-templates snapshots for unified ALS context - [`bd5a8c0`](https://github.com/cloudflare/vinext/commit/bd5a8c0952fafb066436e8aa01ad4afdd0378e65) test: update app router waitUntil assertion - [`d708201`](https://github.com/cloudflare/vinext/commit/d708201c27ddf8f23f198a17bff4b7dc580e80d3) refactor: unify request ALS across router flows - [`68ff3ed`](https://github.com/cloudflare/vinext/commit/68ff3edc82b4274935a07c00f46defd1b587dd7e) fix: address unified request context review feedback - [`9408a13`](https://github.com/cloudflare/vinext/commit/9408a13d2f55444c64fca506dd11627870a5a9d7) fix: address unified ALS review feedback - [`cef7e65`](https://github.com/cloudflare/vinext/commit/cef7e659b64ff1a1c63007509adbf87be3bcd977) fix: address remaining unified ALS review feedback - [`b8c2c12`](https://github.com/cloudflare/vinext/commit/b8c2c1257d642912131fb9a193a0c0a5fa29a9ec) fix: wrap Pages Router ISR regeneration in unified context - [`266d177`](https://github.com/cloudflare/vinext/commit/266d1772fa56d47e9cf6a4876147ee337ef4814c) Fix dev ISR unified context parity - [`e5dd085`](https://github.com/cloudflare/vinext/commit/e5dd085809c60a0441f110cbc686ed77b75076ee) Merge remote-tracking branch 'origin/main' into worktree-refactor/unified-als-request-context ### 📊 Changes **26 files changed** (+3007 additions, -1787 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/entries/app-rsc-entry.ts` (+103 -116) 📝 `packages/vinext/src/entries/pages-server-entry.ts` (+114 -76) 📝 `packages/vinext/src/index.ts` (+1 -0) 📝 `packages/vinext/src/server/app-router-entry.ts` (+1 -1) 📝 `packages/vinext/src/server/dev-server.ts` (+677 -692) 📝 `packages/vinext/src/shims/cache-runtime.ts` (+28 -7) 📝 `packages/vinext/src/shims/cache.ts` (+15 -7) 📝 `packages/vinext/src/shims/fetch-cache.ts` (+26 -1) 📝 `packages/vinext/src/shims/head-state.ts` (+16 -7) 📝 `packages/vinext/src/shims/headers.ts` (+28 -31) 📝 `packages/vinext/src/shims/i18n-state.ts` (+20 -12) 📝 `packages/vinext/src/shims/navigation-state.ts` (+40 -14) 📝 `packages/vinext/src/shims/request-context.ts` (+13 -0) ➕ `packages/vinext/src/shims/request-state-types.ts` (+10 -0) 📝 `packages/vinext/src/shims/router-state.ts` (+17 -9) ➕ `packages/vinext/src/shims/unified-request-context.ts` (+170 -0) 📝 `tests/__snapshots__/entry-templates.test.ts.snap` (+773 -810) 📝 `tests/app-router.test.ts` (+7 -2) 📝 `tests/entry-templates.test.ts` (+64 -0) 📝 `tests/fetch-cache.test.ts` (+32 -0) _...and 6 more files_ </details> ### 📄 Description ## Summary - Introduces a single `UnifiedRequestContext` backed by one `AsyncLocalStorage` instance - Replaces the 5-6 nested ALS scopes used by App Router requests with one unified per-request scope - Lands the initial Pages Router rollout needed for parity: dev SSR, generated Pages server entry, unified-aware router/head shims, and Pages ISR background regeneration **Depends on:** #432, #433, #434, #435, #436, #442 Closes #451 Follow-up tracked in #478 ## Included In This PR | File / area | Change | |------|--------| | `shims/unified-request-context.ts` | **NEW** unified ALS module | | `shims/headers.ts` | Dual-path `_getState()`, unified-aware wrapper semantics | | `shims/navigation-state.ts` | Dual-path `_getState()`, unified-aware wrapper semantics | | `shims/cache.ts` | Unified-aware request-scoped cache state | | `shims/cache-runtime.ts` | Unified-aware private cache state | | `shims/fetch-cache.ts` | Unified-aware tag collection + `ensureFetchPatch()` | | `shims/request-context.ts` | Unified-aware execution context access | | `shims/router-state.ts` | Pages Router SSR state reads from unified scope when present | | `shims/head-state.ts` | Pages Router head state reads from unified scope when present | | `server/dev-server.ts` | Pages Router dev SSR wrapped in unified scope | | `entries/pages-server-entry.ts` | Generated Pages Router server entry wrapped in unified scope | | `entries/app-rsc-entry.ts` | App Router handler + ISR regen wrapped in unified scope | | `tests/unified-request-context.test.ts` | New unit coverage for unified ALS behavior | ## Deferred To #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 - Validation of the production Pages Router path, which currently delegates through unified `renderPage()` - Documentation of the per-call ALS decision for `cacheContextStorage` and `_unstableCacheAls` - ALS architecture documentation Fallback cleanup remains conditional and should only happen if those tests/validation show the standalone paths are truly unnecessary. ## What Is Intentionally Still Separate - `cacheContextStorage` in `cache-runtime.ts`: per-cache-call ALS, not per-request - `_unstableCacheAls` in `cache.ts`: per-call scope for `unstable_cache()` - Standalone fallback ALS paths in shims: kept for compatibility and staged rollout safety until the phase-2 validation work is complete ## Test Plan - [x] Unified request-context unit tests - [x] Existing shim/request-context coverage - [x] App Router + ISR + fetch-cache + features coverage - [x] Routing + nextjs-compat coverage - [x] Typecheck, lint, format - [x] CI full suite + Playwright E2E --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>