Unverified Commit 8283b126 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Support accessing root params in `"use cache"` functions (#91191)

Root params (e.g. `import { lang } from 'next/root-params'`) can now be read inside `"use cache"` functions. The read root param values are automatically included in the cache key so that different root param combinations produce separate cache entries.

Since which root params a cache function reads is only known after execution, the cache key is reconciled post-generation. When root params are read, a two-key scheme is used: the full entry is stored under a specific key (coarse key + root param suffix), and a lightweight redirect entry is stored under the coarse key. The redirect entry's tags encode the root param names using the pattern `_N_RP_<rootParamName>` (e.g. `_N_RP_lang`), following the convention of existing internal tags like `_N_T_<pathname>` (e.g. `_N_T_/dashboard`) for implicit route tags. This allows a cold server to resolve the specific key on the first request after restart. An in-memory map (`knownRootParamsByFunctionId`) provides a fast path for subsequent invocations. When no root params are read, the full entry is stored directly under the coarse key with no redirect involved.

The in-memory map grows monotonically — if a function conditionally reads different root params across invocations, the set accumulates all observed param names. The redirect entry's tags are built from this combined set, ensuring cold servers always resolve the most complete specific key.

The two-key scheme only applies to the cache handler. The Resume Data Cache (RDC) always uses the coarse key because each page gets its own isolated RDC instance, so root params are fixed within a single RDC and no disambiguation is needed. When an RDC entry is found during resume, it seeds `knownRootParamsByFunctionId` so that subsequent cache handler lookups can use the specific key directly.

Reading root params inside `unstable_cache` still throws. Reading root params inside `"use cache"` nested within `unstable_cache` throws with a specific error message explaining the limitation.

Alternatives considered: extending the `CacheEntry` interface (would be a breaking change for custom cache handlers), encoding root param metadata in the stream via a wrapper object, or sentinel byte, or Flightception (runtime overhead of stream manipulation on every cache read), and deferring `cacheHandler.set` until after generation (breaks the cache handler's pending-set deduplication for concurrent requests).
parent 76d7dc1e
......@@ -1137,5 +1137,7 @@
"1136": "Page \"%s\" cannot use both \\`export const unstable_dynamicStaleTime\\` and \\`export const unstable_instant\\`.",
"1137": "\"%s\" cannot use \\`export const unstable_dynamicStaleTime\\`. This config is only supported in page files, not layouts.",
"1138": "`unstable_retry()` can only be used in the App Router. Use `reset()` in the Pages Router.",
"1139": "`unstable_catchError` can only be used in Client Components."
"1139": "`unstable_catchError` can only be used in Client Components.",
"1140": "Route %s used \\`import('next/root-params').%s()\\` inside \\`\"use cache\"\\` nested within \\`unstable_cache\\`. Root params are not available in this context.",
"1141": "Route %s used \\`import('next/root-params').%s()\\` inside \\`unstable_cache\\`. This is not supported. Use \\`\"use cache\"\\` instead."
}
......@@ -35,6 +35,7 @@ export const NEXT_CACHE_TAG_MAX_ITEMS = 128
export const NEXT_CACHE_TAG_MAX_LENGTH = 256
export const NEXT_CACHE_SOFT_TAG_MAX_LENGTH = 1024
export const NEXT_CACHE_IMPLICIT_TAG_ID = '_N_T_'
export const NEXT_CACHE_ROOT_PARAM_TAG_ID = '_N_RP_'
// in seconds
export const CACHE_ONE_YEAR_SECONDS = 31536000
......
......@@ -44,6 +44,7 @@ describe('getDynamicHTMLPostponedState', () => {
},
hasExplicitRevalidate: true,
hasExplicitExpire: true,
readRootParamNames: undefined,
})
)
......
......@@ -345,6 +345,19 @@ export interface CommonUseCacheStore extends CommonCacheStore, RevalidateStore {
export interface PublicUseCacheStore extends CommonUseCacheStore {
readonly type: 'cache'
/**
* The root params for the current route. `undefined` when nested inside
* `unstable_cache`, which doesn't carry root params. Currently, `"use cache"`
* inside `unstable_cache` is allowed, so this case must be handled. The error
* message in `getRootParam` assumes this is the only scenario where
* `rootParams` is `undefined`.
*/
readonly rootParams: Params | undefined
/**
* Tracks which root param names were read during this cache invocation.
*/
readonly readRootParamNames: Set<string>
}
export interface PrivateUseCacheStore extends CommonUseCacheStore {
......@@ -354,9 +367,8 @@ export interface PrivateUseCacheStore extends CommonUseCacheStore {
readonly cookies: ReadonlyRequestCookies
/**
* Private caches don't currently need to track root params in the cache key
* because they're not persisted anywhere, so we can allow root params access
* (unlike public caches)
* Private caches don't currently need to track read root params for the cache
* key because they're not persisted anywhere.
*/
readonly rootParams: Params
}
......@@ -365,6 +377,12 @@ export type UseCacheStore = PublicUseCacheStore | PrivateUseCacheStore
export interface UnstableCacheStore extends CommonCacheStore {
readonly type: 'unstable-cache'
/**
* Always `undefined` for `unstable_cache` — root params are not available in
* this context. If a `"use cache"` function nested inside `unstable_cache`
* tries to access root params, it will encounter `undefined` here and throw.
*/
readonly rootParams: undefined
}
/**
......
......@@ -58,12 +58,20 @@ export function getRootParam(paramName: string): Promise<ParamValue> {
}
switch (workUnitStore.type) {
case 'unstable-cache':
case 'cache': {
case 'unstable-cache': {
throw new Error(
`Route ${workStore.route} used ${apiName} inside \`"use cache"\` or \`unstable_cache\`. Support for this API inside cache scopes is planned for a future version of Next.js.`
`Route ${workStore.route} used ${apiName} inside \`unstable_cache\`. This is not supported. Use \`"use cache"\` instead.`
)
}
case 'cache': {
if (!workUnitStore.rootParams) {
throw new Error(
`Route ${workStore.route} used ${apiName} inside \`"use cache"\` nested within \`unstable_cache\`. Root params are not available in this context.`
)
}
workUnitStore.readRootParamNames.add(paramName)
return Promise.resolve(workUnitStore.rootParams[paramName])
}
case 'prerender':
case 'prerender-ppr':
case 'prerender-legacy': {
......
......@@ -44,6 +44,7 @@ export interface UseCacheCacheStoreSerialized {
}
hasExplicitRevalidate: boolean | undefined
hasExplicitExpire: boolean | undefined
readRootParamNames: string[] | undefined
}
/**
......@@ -64,7 +65,7 @@ export function parseUseCacheCacheStore(
for (const [
key,
{ entry, hasExplicitRevalidate, hasExplicitExpire },
{ entry, hasExplicitRevalidate, hasExplicitExpire, readRootParamNames },
] of entries) {
store.set(
key,
......@@ -88,6 +89,9 @@ export function parseUseCacheCacheStore(
},
hasExplicitRevalidate,
hasExplicitExpire,
readRootParamNames: readRootParamNames
? new Set(readRootParamNames)
: undefined,
})
)
}
......@@ -107,45 +111,55 @@ export async function serializeUseCacheCacheStore(
return Promise.all(
Array.from(entries).map(([key, value]) => {
return value
.then(async ({ entry, hasExplicitRevalidate, hasExplicitExpire }) => {
if (
isCacheComponentsEnabled &&
(entry.revalidate === 0 || entry.expire < DYNAMIC_EXPIRE)
) {
// The entry was omitted from the prerender result, and subsequently
// does not need to be included in the serialized RDC.
return null
}
.then(
async ({
entry,
hasExplicitRevalidate,
hasExplicitExpire,
readRootParamNames,
}) => {
if (
isCacheComponentsEnabled &&
(entry.revalidate === 0 || entry.expire < DYNAMIC_EXPIRE)
) {
// The entry was omitted from the prerender result, and subsequently
// does not need to be included in the serialized RDC.
return null
}
const [left, right] = entry.value.tee()
entry.value = right
const [left, right] = entry.value.tee()
entry.value = right
let binaryString: string = ''
let binaryString: string = ''
// We want to encode the value as a string, but we aren't sure if the
// value is a a stream of UTF-8 bytes or not, so let's just encode it
// as a string using base64.
for await (const chunk of left) {
binaryString += arrayBufferToString(chunk)
}
// We want to encode the value as a string, but we aren't sure if the
// value is a a stream of UTF-8 bytes or not, so let's just encode it
// as a string using base64.
for await (const chunk of left) {
binaryString += arrayBufferToString(chunk)
}
return [
key,
{
entry: {
// Encode the value as a base64 string.
value: btoa(binaryString),
tags: entry.tags,
stale: entry.stale,
timestamp: entry.timestamp,
expire: entry.expire,
revalidate: entry.revalidate,
return [
key,
{
entry: {
// Encode the value as a base64 string.
value: btoa(binaryString),
tags: entry.tags,
stale: entry.stale,
timestamp: entry.timestamp,
expire: entry.expire,
revalidate: entry.revalidate,
},
hasExplicitRevalidate,
hasExplicitExpire,
readRootParamNames: readRootParamNames
? [...readRootParamNames]
: undefined,
},
hasExplicitRevalidate,
hasExplicitExpire,
},
] satisfies [string, UseCacheCacheStoreSerialized]
})
] satisfies [string, UseCacheCacheStoreSerialized]
}
)
.catch(() => {
// Any failed cache writes should be ignored as to not discard the
// entire cache.
......
......@@ -25,6 +25,7 @@ function createMockedCache() {
},
hasExplicitRevalidate: true,
hasExplicitExpire: true,
readRootParamNames: undefined,
})
)
......@@ -42,6 +43,7 @@ function createMockedCache() {
},
hasExplicitRevalidate: true,
hasExplicitExpire: true,
readRootParamNames: undefined,
})
)
......@@ -59,6 +61,7 @@ function createMockedCache() {
},
hasExplicitRevalidate: true,
hasExplicitExpire: true,
readRootParamNames: undefined,
})
)
......
......@@ -148,6 +148,7 @@ export function unstable_cache<T extends Callback>(
workUnitStore &&
workStore &&
getDraftModeProviderForCacheScope(workStore, workUnitStore),
rootParams: undefined,
}
if (workStore) {
......
import { lang, locale } from 'next/root-params'
export default async function Page() {
const rootParams = await getCachedParams()
const data = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
const result = await getCachedData()
return (
<p>
<span id="param">
{rootParams.lang} {rootParams.locale}
{result.lang} {result.locale}
</span>{' '}
<span id="random">{data}</span>
<span id="random">{result.random}</span>
</p>
)
}
async function getCachedParams() {
async function getCachedData() {
'use cache'
return { lang: await lang(), locale: await locale() }
const random = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
return { lang: await lang(), locale: await locale(), random }
}
import { lang } from 'next/root-params'
import { cacheTag, updateTag } from 'next/cache'
import { connection } from 'next/server'
import { Suspense } from 'react'
let flagValue = false
async function getFlag() {
'use cache: remote'
cacheTag('flag-tag')
return flagValue
}
async function conditionalOnAnotherCache() {
'use cache: remote'
const random = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
const flag = await getFlag()
if (flag) {
return { lang: await lang(), random }
}
return { lang: null, random }
}
async function Runtime() {
await connection()
const result = await conditionalOnAnotherCache()
return (
<div>
<p id="lang-value">{String(result.lang)}</p>
<p id="random">{result.random}</p>
<form>
<button
id="enable-flag"
formAction={async () => {
'use server'
flagValue = true
updateTag('flag-tag')
}}
>
Enable flag
</button>
<button
id="disable-flag"
formAction={async () => {
'use server'
flagValue = false
updateTag('flag-tag')
}}
>
Disable flag
</button>
</form>
</div>
)
}
export default async function Page() {
return (
<Suspense fallback="Loading...">
<Runtime />
</Suspense>
)
}
import { lang, countryCode } from 'next/root-params'
import { connection } from 'next/server'
import { Suspense } from 'react'
async function conditionalOnRootParam() {
'use cache: remote'
const random = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
const currentLang = await lang()
if (currentLang === 'en') {
return { lang: currentLang, countryCode: await countryCode(), random }
}
return { lang: currentLang, countryCode: null, random }
}
async function Runtime() {
await connection()
const result = await conditionalOnRootParam()
return (
<div>
<p id="lang-value">{String(result.lang)}</p>
<p id="country-code-value">{String(result.countryCode)}</p>
<p id="random">{result.random}</p>
</div>
)
}
export default async function Page() {
return (
<Suspense fallback="Loading...">
<Runtime />
</Suspense>
)
}
......@@ -9,8 +9,9 @@ export default function Root({ children }: { children: ReactNode }) {
}
export function generateStaticParams() {
// the param values are not accessed in tests,
// we just need a value here to avoid errors in PPR/cacheComponents
// where we need to provide at least one set of values for root params
return [{ lang: 'foo', locale: 'bar' }]
return [
{ lang: 'en', countryCode: 'us' },
{ lang: 'en', countryCode: 'gb' },
{ lang: 'fr', countryCode: 'ca' },
]
}
import { lang } from 'next/root-params'
import { connection } from 'next/server'
import { Suspense } from 'react'
async function maybeReadsRootParam(readLang: boolean) {
'use cache: remote'
const random = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
if (readLang) {
return { lang: await lang(), random }
}
return { lang: null, random }
}
async function Runtime() {
await connection()
// The `true` call must come first so that `saveToCacheHandler` adds `lang`
// to `knownRootParamsByFunctionId` before the `false` call's lookup runs.
const withLang = await maybeReadsRootParam(true)
const withoutLang = await maybeReadsRootParam(false)
return (
<div>
<p id="with-lang-random">{withLang.random}</p>
<p id="with-lang-value">{String(withLang.lang)}</p>
<p id="without-lang-random">{withoutLang.random}</p>
<p id="without-lang-value">{String(withoutLang.lang)}</p>
</div>
)
}
export default async function Page() {
return (
<Suspense fallback="Loading...">
<Runtime />
</Suspense>
)
}
import { lang, countryCode } from 'next/root-params'
import { unstable_cache } from 'next/cache'
import { connection } from 'next/server'
import { Suspense } from 'react'
export default async function Page() {
return (
<Suspense fallback="Loading...">
<Runtime />
</Suspense>
)
}
async function Runtime() {
await connection()
const getParams = unstable_cache(getCachedParams)
const rootParams = await getParams()
return (
<p id="param">
{rootParams.lang} {rootParams.countryCode}
</p>
)
}
async function getCachedParams() {
'use cache'
return { lang: await lang(), countryCode: await countryCode() }
}
import { Suspense } from 'react'
import { lang, locale } from 'next/root-params'
import { lang, countryCode } from 'next/root-params'
import { connection } from 'next/server'
import { unstable_cache } from 'next/cache'
......@@ -22,7 +22,7 @@ async function Runtime() {
return (
<p>
<span id="param">
{rootParams.lang} {rootParams.locale}
{rootParams.lang} {rootParams.countryCode}
</span>{' '}
<span id="random">{data}</span>
</p>
......@@ -30,5 +30,5 @@ async function Runtime() {
}
const getCachedParams = unstable_cache(async function uncachedGetParams() {
return { lang: await lang(), locale: await locale() }
return { lang: await lang(), countryCode: await countryCode() }
})
import { lang, countryCode } from 'next/root-params'
import { connection } from 'next/server'
import { Suspense } from 'react'
async function getCachedData() {
'use cache'
const random = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
return { lang: await lang(), countryCode: await countryCode(), random }
}
export default async function Page() {
const result = await getCachedData()
return (
<>
<p>
<span id="param">
{result.lang} {result.countryCode}
</span>{' '}
<span id="random">{result.random}</span>
</p>
<Suspense fallback={<p id="fallback">Loading...</p>}>
<Dynamic />
</Suspense>
</>
)
}
async function Dynamic() {
await connection()
return <p id="dynamic">dynamic</p>
}
import { lang, locale } from 'next/root-params'
import { lang, countryCode } from 'next/root-params'
import { connection } from 'next/server'
import { Suspense } from 'react'
......@@ -13,22 +13,24 @@ export default async function Page() {
async function Runtime() {
await connection()
const rootParams = await getCachedParams()
const data = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
const result = await getCachedData()
return (
<p>
<span id="param">
{rootParams.lang} {rootParams.locale}
{result.lang} {result.countryCode}
</span>{' '}
<span id="random">{data}</span>
<span id="random">{result.random}</span>
</p>
)
}
async function getCachedParams() {
'use cache'
return { lang: await lang(), locale: await locale() }
async function getCachedData() {
'use cache: remote'
const random = await fetch(
'https://next-data-api-endpoint.vercel.app/api/random'
).then((res) => res.text())
return { lang: await lang(), countryCode: await countryCode(), random }
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment