starred/vinext

Fork 0

mirror of https://github.com/cloudflare/vinext.git synced 2026-05-09 08:25:34 +02:00

[GH-ISSUE #478] Phase 2/2: Finalize ALS rollout with parity tests, cleanup, and docs #108

New issue

Closed

opened 2026-05-06 12:37:15 +02:00 by BreizhHardware · 3 comments

BreizhHardware commented

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

Owner

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

Originally assigned to: @aidantrabs on GitHub.

Why This Issue Exists

Phase 1 (#451 / PR #450) already landed the core unified request-context rollout, including the main Pages Router entry points. The remaining work is follow-up validation, cleanup, and documentation rather than another large implementation pass.

This issue is an umbrella follow-up for the ALS rollout and may span more than one PR.

Recommended Execution Order

First follow-up PR (required)

Focus on correctness, parity validation, and documentation:

Add Pages Router integration tests for concurrent SSR isolation in dev and prod
Verify <Head> elements do not leak between concurrent requests
Verify router SSR context does not leak between concurrent requests
Validate the production Pages Router path, which currently reaches the unified scope through renderPage() rather than a separate wrapper in prod-server.ts
Document the decision for per-call ALS scopes:
- cacheContextStorage in cache-runtime.ts
- _unstableCacheAls in cache.ts
Add ALS architecture documentation

Later cleanup PR (optional / conditional)

Only remove standalone fallback ALS paths if the parity tests and production validation show they are truly unnecessary. If they still serve SSR, entry-wrapper, or test compatibility needs, defer deletion and record the rationale here.

Scope

1. Pages Router parity and coverage

Add Pages Router integration tests for concurrent SSR isolation in dev and prod
Verify <Head> elements do not leak between concurrent requests
Verify router SSR context does not leak between concurrent requests
Validate the production Pages Router path, which currently reaches the unified scope through renderPage() rather than a separate wrapper in prod-server.ts

2. Per-call ALS evaluation

Evaluate and document whether these should remain separate from the unified request scope:

cacheContextStorage in cache-runtime.ts
_unstableCacheAls in cache.ts

Expected default: keep them separate unless benchmarking or correctness findings show otherwise, since they are semantically per-call rather than per-request.

3. Dual-path fallback cleanup

Once parity tests are in place and the rollout has had time to bake, remove standalone fallback ALS code only where it is clearly unnecessary:

headers.ts
navigation-state.ts
cache.ts
cache-runtime.ts (fallback/private-cache path only)
fetch-cache.ts
request-context.ts only if validation proves the standalone behavior is no longer needed for outer entry-wrapper flows
router-state.ts
head-state.ts

If some fallback paths still serve SSR, test, or entry-wrapper compatibility, keep them and document that decision instead of forcing deletion.

4. Documentation

Add an ALS architecture document explaining the final split between unified request scope and per-call cache scopes
Document contributor guidance for adding new request-scoped state

Acceptance Criteria

Pages Router dev concurrency tests added
Pages Router prod concurrency tests added
Head and router SSR isolation verified under concurrent requests
Production Pages Router unified path validated
Decision documented for cacheContextStorage and _unstableCacheAls
ALS architecture documented
Fallback cleanup completed, or explicitly deferred with rationale
Typecheck, lint, format, and targeted tests are clean

Phase 1/2: #451
PR: #450
Supersedes: #479

Originally created by @Divkix on GitHub (Mar 11, 2026). Original GitHub issue: https://github.com/cloudflare/vinext/issues/478 Originally assigned to: @aidantrabs on GitHub. ## Why This Issue Exists Phase 1 (`#451` / PR `#450`) already landed the core unified request-context rollout, including the main Pages Router entry points. The remaining work is follow-up validation, cleanup, and documentation rather than another large implementation pass. This issue is an umbrella follow-up for the ALS rollout and may span more than one PR. ## Recommended Execution Order ### First follow-up PR (required) Focus on correctness, parity validation, and documentation: - Add Pages Router integration tests for concurrent SSR isolation in dev and prod - Verify `<Head>` elements do not leak between concurrent requests - Verify router SSR context does not leak between concurrent requests - Validate the production Pages Router path, which currently reaches the unified scope through `renderPage()` rather than a separate wrapper in `prod-server.ts` - Document the decision for per-call ALS scopes: - `cacheContextStorage` in `cache-runtime.ts` - `_unstableCacheAls` in `cache.ts` - Add ALS architecture documentation ### Later cleanup PR (optional / conditional) Only remove standalone fallback ALS paths if the parity tests and production validation show they are truly unnecessary. If they still serve SSR, entry-wrapper, or test compatibility needs, defer deletion and record the rationale here. ## Scope ### 1. Pages Router parity and coverage - Add Pages Router integration tests for concurrent SSR isolation in dev and prod - Verify `<Head>` elements do not leak between concurrent requests - Verify router SSR context does not leak between concurrent requests - Validate the production Pages Router path, which currently reaches the unified scope through `renderPage()` rather than a separate wrapper in `prod-server.ts` ### 2. Per-call ALS evaluation Evaluate and document whether these should remain separate from the unified request scope: - `cacheContextStorage` in `cache-runtime.ts` - `_unstableCacheAls` in `cache.ts` Expected default: keep them separate unless benchmarking or correctness findings show otherwise, since they are semantically per-call rather than per-request. ### 3. Dual-path fallback cleanup Once parity tests are in place and the rollout has had time to bake, remove standalone fallback ALS code only where it is clearly unnecessary: - `headers.ts` - `navigation-state.ts` - `cache.ts` - `cache-runtime.ts` (fallback/private-cache path only) - `fetch-cache.ts` - `request-context.ts` only if validation proves the standalone behavior is no longer needed for outer entry-wrapper flows - `router-state.ts` - `head-state.ts` If some fallback paths still serve SSR, test, or entry-wrapper compatibility, keep them and document that decision instead of forcing deletion. ### 4. Documentation - Add an ALS architecture document explaining the final split between unified request scope and per-call cache scopes - Document contributor guidance for adding new request-scoped state ## Acceptance Criteria - [ ] Pages Router dev concurrency tests added - [ ] Pages Router prod concurrency tests added - [ ] Head and router SSR isolation verified under concurrent requests - [ ] Production Pages Router unified path validated - [ ] Decision documented for `cacheContextStorage` and `_unstableCacheAls` - [ ] ALS architecture documented - [ ] Fallback cleanup completed, or explicitly deferred with rationale - [ ] Typecheck, lint, format, and targeted tests are clean ## Related - Phase 1/2: #451 - PR: #450 - Supersedes: #479

BreizhHardware closed this issue

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

BreizhHardware commented

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

Author

Owner

@aidantrabs commented on GitHub (Mar 12, 2026):

hi, i would like to work on this, if possible

@aidantrabs commented on GitHub (Mar 12, 2026): hi, i would like to work on this, if possible

BreizhHardware commented

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

Author

Owner

@Divkix commented on GitHub (Mar 12, 2026):

hi, i would like to work on this, if possible

Sure, you can work after #450 is merged

@Divkix commented on GitHub (Mar 12, 2026): > hi, i would like to work on this, if possible Sure, you can work after #450 is merged

BreizhHardware commented

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

Author

Owner

@aidantrabs commented on GitHub (Mar 13, 2026):

hi, i would like to work on this, if possible

Sure, you can work after #450 is merged

saw it was merged, will start working on it today ; you can assign me to the issue

@aidantrabs commented on GitHub (Mar 13, 2026): > > hi, i would like to work on this, if possible > > Sure, you can work after [#450](https://github.com/cloudflare/vinext/pull/450) is merged saw it was merged, will start working on it today ; you can assign me to the issue

BreizhHardware referenced this issue

2026-05-06 12:39:10 +02:00

[PR #108] [MERGED] fix: dev sanitizeDestination now normalizes leading backslashes #317