[PR #279] [MERGED] fix: throw when dynamic request APIs are called inside cache scopes #438

New issue

Closed

opened 2026-05-06 12:39:48 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

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

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/279
Author: @southpolesteve
Created: 3/6/2026
Status: ✅ Merged
Merged: 3/6/2026
Merged by: @southpolesteve

Base: main ← Head: fix/cache-scope-dynamic-api-guards

📝 Commits (2)

bce3620 fix: throw when headers()/cookies()/connection() called inside cache scope
b5d1920 fix: add draftMode() cache scope guard, remove dead code, add nested scope test

📊 Changes

5 files changed (+373 additions, -4 deletions)

View changed files

📝 packages/vinext/src/shims/cache-runtime.ts (+7 -1)
📝 packages/vinext/src/shims/cache.ts (+23 -2)
📝 packages/vinext/src/shims/headers.ts (+53 -0)
📝 packages/vinext/src/shims/server.ts (+2 -1)
📝 tests/shims.test.ts (+288 -0)

📄 Description

Summary

Throw errors when headers(), cookies(), or connection() are called inside "use cache" functions or unstable_cache() callbacks, matching Next.js behavior
Cached results are shared across requests. Without this guard, calling these APIs inside a cache scope would freeze one caller's request-specific data (auth tokens, session cookies, etc.) into the cached result and serve it to all subsequent callers
The unstable_cache() callback is now wrapped in an AsyncLocalStorage scope so the guard can detect it
The "use cache" runtime's cacheContextStorage ALS is stored on globalThis via a well-known Symbol so headers.ts can read it without introducing circular imports

Changes

File	What changed
`shims/headers.ts`	Added `throwIfInsideCacheScope()` guard called by `headers()` and `cookies()`. Reads cache scope ALS instances from globalThis via Symbols to avoid circular imports.
`shims/server.ts`	`connection()` now calls `throwIfInsideCacheScope()` before `markDynamicUsage()`
`shims/cache.ts`	`unstable_cache()` wraps its callback in an ALS scope (`_unstableCacheAls`) stored on globalThis
`shims/cache-runtime.ts`	`cacheContextStorage` now stored on globalThis via Symbol (was a bare module-level variable). Added `isInsideCacheScope()` export.
`tests/shims.test.ts`	9 new tests covering all API + scope combinations, plus regression test for normal cache behavior

Testing

9 new tests for the cache scope guards (all 3 APIs x both scope types, plus 2 "works outside scope" tests, plus 1 regression test)
All existing tests pass (546/546 in shims.test.ts, 2141/2141 across full suite excluding pre-existing failures in ecosystem/static-export)
Typecheck clean, lint clean

_{🔄 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/279 **Author:** [@southpolesteve](https://github.com/southpolesteve) **Created:** 3/6/2026 **Status:** ✅ Merged **Merged:** 3/6/2026 **Merged by:** [@southpolesteve](https://github.com/southpolesteve) **Base:** `main` ← **Head:** `fix/cache-scope-dynamic-api-guards` --- ### 📝 Commits (2) - [`bce3620`](https://github.com/cloudflare/vinext/commit/bce362014b20248616ef4ddc2de8bf3b047f0c5d) fix: throw when headers()/cookies()/connection() called inside cache scope - [`b5d1920`](https://github.com/cloudflare/vinext/commit/b5d1920d1fb56c601e3bd0672c467e058d548bf3) fix: add draftMode() cache scope guard, remove dead code, add nested scope test ### 📊 Changes **5 files changed** (+373 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/shims/cache-runtime.ts` (+7 -1) 📝 `packages/vinext/src/shims/cache.ts` (+23 -2) 📝 `packages/vinext/src/shims/headers.ts` (+53 -0) 📝 `packages/vinext/src/shims/server.ts` (+2 -1) 📝 `tests/shims.test.ts` (+288 -0) </details> ### 📄 Description ## Summary - **Throw errors** when `headers()`, `cookies()`, or `connection()` are called inside `"use cache"` functions or `unstable_cache()` callbacks, matching Next.js behavior - Cached results are shared across requests. Without this guard, calling these APIs inside a cache scope would freeze one caller's request-specific data (auth tokens, session cookies, etc.) into the cached result and serve it to all subsequent callers - The `unstable_cache()` callback is now wrapped in an AsyncLocalStorage scope so the guard can detect it - The `"use cache"` runtime's `cacheContextStorage` ALS is stored on `globalThis` via a well-known Symbol so `headers.ts` can read it without introducing circular imports ## Changes | File | What changed | |------|-------------| | `shims/headers.ts` | Added `throwIfInsideCacheScope()` guard called by `headers()` and `cookies()`. Reads cache scope ALS instances from globalThis via Symbols to avoid circular imports. | | `shims/server.ts` | `connection()` now calls `throwIfInsideCacheScope()` before `markDynamicUsage()` | | `shims/cache.ts` | `unstable_cache()` wraps its callback in an ALS scope (`_unstableCacheAls`) stored on globalThis | | `shims/cache-runtime.ts` | `cacheContextStorage` now stored on globalThis via Symbol (was a bare module-level variable). Added `isInsideCacheScope()` export. | | `tests/shims.test.ts` | 9 new tests covering all API + scope combinations, plus regression test for normal cache behavior | ## Testing - 9 new tests for the cache scope guards (all 3 APIs x both scope types, plus 2 "works outside scope" tests, plus 1 regression test) - All existing tests pass (546/546 in shims.test.ts, 2141/2141 across full suite excluding pre-existing failures in ecosystem/static-export) - Typecheck clean, lint clean --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>