Unverified Commit 02a73c59 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Rename `DYNAMIC_EXPIRE` and `DYNAMIC_STALE` to describe what they gate (#95361)

The `DYNAMIC_EXPIRE` and `DYNAMIC_STALE` constants read as if the value
itself is a dynamic expire or stale time, but every comparison is
`expire < DYNAMIC_EXPIRE` / `stale < DYNAMIC_STALE`, so the value is the
exclusive upper bound of the dynamic range: it is the smallest value
that is *not* dynamic, not a dynamic value. The names are backwards at
the boundary, which is easy to misread.

The two thresholds also gate different things. `expire` gates whether a
cache entry is included in the static prerender: below the threshold it
becomes a dynamic hole, though a short-`expire` value is still served
during a runtime prefetch. `stale` gates whether an entry is included in
a runtime prefetch or app shell.

This renames them to name that consequence: `MIN_PRERENDERABLE_EXPIRE`
and `MIN_PREFETCHABLE_STALE`. It reads correctly both at the comparison
sites (`expire < MIN_PRERENDERABLE_EXPIRE` is "below the minimum
prerenderable expire", i.e. dynamic) and at the one site that uses the
value directly, where private caches force `expire:
MIN_PRERENDERABLE_EXPIRE` precisely because it is the shortest expire
that stays prerenderable (and so is retained without being reclassified
as a short-expire dynamic hole). This is a pure rename with no behavior
change.


---

<sub>Stack created with <a
href="https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a
href="https://gh.io/stacks-feedback">Give Feedback 💬</a></sub>
parent a25865f1
......@@ -366,8 +366,8 @@ export interface PublicUseCacheStore extends CommonUseCacheStore {
readonly readRootParamNames: Set<string>
/**
* The first nested public `'use cache'` invocation with a dynamic cache life
* (`revalidate === 0` or `expire < DYNAMIC_EXPIRE`) that propagated up to
* this store. Used as `cause` for the nested-dynamic cache error so the
* (`revalidate === 0` or `expire < MIN_PRERENDERABLE_EXPIRE`) that propagated
* up to this store. Used as `cause` for the nested-dynamic cache error so the
* redbox can point at the inner invocation site, not just the outer one.
*/
dynamicNestedCacheError: Error | undefined
......
......@@ -3,7 +3,7 @@ import {
stringToUint8Array,
} from '../app-render/encryption-utils'
import type { CachedFetchValue } from '../response-cache/types'
import { DYNAMIC_EXPIRE } from '../use-cache/constants'
import { MIN_PRERENDERABLE_EXPIRE } from '../use-cache/constants'
import type { CollectedCacheResult } from '../use-cache/use-cache-wrapper'
/**
......@@ -135,7 +135,8 @@ export async function serializeUseCacheCacheStore(
}) => {
if (
isCacheComponentsEnabled &&
(entry.revalidate === 0 || entry.expire < DYNAMIC_EXPIRE)
(entry.revalidate === 0 ||
entry.expire < MIN_PRERENDERABLE_EXPIRE)
) {
// The entry was omitted from the prerender result, and subsequently
// does not need to be included in the serialized RDC.
......
export const DYNAMIC_EXPIRE = 300 // 5 minutes
export const DYNAMIC_STALE = 30 // 30 seconds
export const MIN_PRERENDERABLE_EXPIRE = 300 // 5 minutes
export const MIN_PREFETCHABLE_STALE = 30 // 30 seconds
......@@ -59,7 +59,7 @@ import {
} from '../app-render/create-error-handler'
import { createDigestWithErrorCode } from '../../lib/error-telemetry-utils'
import stringHash from 'next/dist/compiled/string-hash'
import { DYNAMIC_EXPIRE, DYNAMIC_STALE } from './constants'
import { MIN_PRERENDERABLE_EXPIRE, MIN_PREFETCHABLE_STALE } from './constants'
import { NEXT_CACHE_ROOT_PARAM_TAG_ID } from '../../lib/constants'
import {
getCacheHandler,
......@@ -907,7 +907,8 @@ function propagateCacheEntryMetadata(
// cause points at the immediate dynamic child.
if (
cacheContext.dynamicNestedCacheError !== undefined &&
(metadata.revalidate === 0 || metadata.expire < DYNAMIC_EXPIRE)
(metadata.revalidate === 0 ||
metadata.expire < MIN_PRERENDERABLE_EXPIRE)
) {
cacheContext.outerWorkUnitStore.dynamicNestedCacheError ??=
cacheContext.dynamicNestedCacheError
......@@ -1085,18 +1086,18 @@ async function collectResult(
)
// In development, force a dynamic cache life (`revalidate: 0`, `expire:
// DYNAMIC_EXPIRE`) for private caches, which have no real backing handler.
// The zero revalidate makes every read serve stale-while-revalidate
// (regenerating a fresh entry in the background), and `DYNAMIC_EXPIRE` (5
// minutes) caps how long an entry lingers in the dedicated in-memory private
// handler. It is the shortest `expire` that isn't treated as dynamic; a
// smaller `expire` would exclude the entry from prerenders. The size-0 case
// (`cacheMaxMemorySize: 0`) deliberately does NOT force this: it keeps its
// resolved cache life so that the cache entry can be considered prerenderable
// instead of being misread as a dynamic hole, and a separate dev revalidation
// (see the cache-hit path below) keeps its reloads showing a fresh value.
// Custom kinds keep their real cache life too, since their backing handler
// owns it.
// MIN_PRERENDERABLE_EXPIRE`) for private caches, which have no real backing
// handler. The zero revalidate makes every read serve stale-while-revalidate
// (regenerating a fresh entry in the background), and
// `MIN_PRERENDERABLE_EXPIRE` (5 minutes) caps how long an entry lingers in
// the dedicated in-memory private handler. It is the shortest `expire` that
// isn't treated as dynamic; a smaller `expire` would exclude the entry from
// prerenders. The size-0 case (`cacheMaxMemorySize: 0`) deliberately does NOT
// force this: it keeps its resolved cache life so that the cache entry can be
// considered prerenderable instead of being misread as a dynamic hole, and a
// separate dev revalidation (see the cache-hit path below) keeps its reloads
// showing a fresh value. Custom kinds keep their real cache life too, since
// their backing handler owns it.
const forceDynamicCacheLifeInDev = isPrivateCacheInDev
// If cacheLife() was used to set an explicit revalidate/expire/stale time we
......@@ -1108,7 +1109,7 @@ async function collectResult(
? innerCacheStore.explicitRevalidate
: innerCacheStore.revalidate
const collectedExpire = forceDynamicCacheLifeInDev
? DYNAMIC_EXPIRE
? MIN_PRERENDERABLE_EXPIRE
: innerCacheStore.explicitExpire !== undefined
? innerCacheStore.explicitExpire
: innerCacheStore.expire
......@@ -2254,7 +2255,7 @@ export async function cache(
if (rdcResult !== undefined) {
if (
rdcResult.entry.revalidate === 0 ||
rdcResult.entry.expire < DYNAMIC_EXPIRE
rdcResult.entry.expire < MIN_PRERENDERABLE_EXPIRE
) {
switch (workUnitStore.type) {
case 'prerender':
......@@ -2320,8 +2321,8 @@ export async function cache(
// otherwise silently shorten. A dev private cache's
// `revalidate` is forced to 0 by us (not by a nested cache), so
// it's excluded from the first throw to avoid a false positive.
// Its forced `expire` is exactly DYNAMIC_EXPIRE, so it never
// trips the second throw and needs no exclusion there.
// Its forced `expire` is exactly MIN_PRERENDERABLE_EXPIRE, so
// it never trips the second throw and needs no exclusion there.
if (
cacheContext.kind !== 'private' &&
rdcResult.entry.revalidate === 0 &&
......@@ -2334,7 +2335,7 @@ export async function cache(
)
}
if (
rdcResult.entry.expire < DYNAMIC_EXPIRE &&
rdcResult.entry.expire < MIN_PRERENDERABLE_EXPIRE &&
rdcResult.hasExplicitExpire === false
) {
throw wrapAsInvalidDynamicUsageError(
......@@ -2378,7 +2379,7 @@ export async function cache(
}
}
if (rdcResult.entry.stale < DYNAMIC_STALE) {
if (rdcResult.entry.stale < MIN_PREFETCHABLE_STALE) {
switch (workUnitStore.type) {
case 'prerender':
case 'prerender-runtime':
......@@ -2826,7 +2827,7 @@ export async function cache(
const currentTime = performance.timeOrigin + performance.now()
if (
entry !== undefined &&
(entry.revalidate === 0 || entry.expire < DYNAMIC_EXPIRE)
(entry.revalidate === 0 || entry.expire < MIN_PRERENDERABLE_EXPIRE)
) {
switch (workUnitStore.type) {
case 'prerender':
......@@ -2903,7 +2904,7 @@ export async function cache(
}
}
if (entry !== undefined && entry.stale < DYNAMIC_STALE) {
if (entry !== undefined && entry.stale < MIN_PREFETCHABLE_STALE) {
switch (workUnitStore.type) {
case 'request': {
// A short stale time excludes the entry from prerenders.
......
......@@ -13,7 +13,7 @@ export default async function Page() {
This page uses a short-lived private cache (with cacheLife("seconds")),
which should not be included in a static prefetch, but should be
included in a runtime prefetch, because it has a long enough stale time
(&ge; DYNAMIC_STALE, 30s)
(&ge; MIN_PREFETCHABLE_STALE, 30s)
</p>
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
<ShortLivedCache />
......
......@@ -11,8 +11,8 @@ export default async function Page() {
<DebugRenderKind />
<p id="intro">
This page uses a short-lived private cache (staleTime &lt;
DYNAMIC_STALE, which is 30s), which should not be included in a runtime
prefetch
MIN_PREFETCHABLE_STALE, which is 30s), which should not be included in a
runtime prefetch
</p>
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
<CachedButShortLived />
......
......@@ -13,7 +13,7 @@ export default async function Page() {
This page uses a short-lived public cache (with cacheLife("seconds")),
which should not be included in a static prefetch, but should be
included in a runtime prefetch, because it has a long enough stale time
(&ge; DYNAMIC_STALE, 30s)
(&ge; MIN_PREFETCHABLE_STALE, 30s)
</p>
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
<ShortLivedCache />
......
......@@ -10,10 +10,10 @@ export default async function Page() {
<main>
<DebugRenderKind />
<p id="intro">
This page uses a short-lived public cache (expire &lt; DYNAMIC_EXPIRE,
5min), which should not be included in a static prefetch, but should be
included in a runtime prefetch, because it has a long enough stale time
(&ge; DYNAMIC_STALE, 30s)
This page uses a short-lived public cache (expire &lt;
MIN_PRERENDERABLE_EXPIRE, 5min), which should not be included in a
static prefetch, but should be included in a runtime prefetch, because
it has a long enough stale time (&ge; MIN_PREFETCHABLE_STALE, 30s)
</p>
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
<ShortLivedCache />
......@@ -25,9 +25,9 @@ export default async function Page() {
async function ShortLivedCache() {
'use cache'
cacheLife({
stale: 60, // > DYNAMIC_STALE
stale: 60, // >= MIN_PREFETCHABLE_STALE
revalidate: 2 * 60,
expire: 3 * 60, // < DYNAMIC_EXPIRE
expire: 3 * 60, // < MIN_PRERENDERABLE_EXPIRE
})
await cachedDelay([__filename])
......
......@@ -10,10 +10,11 @@ export default async function Page() {
<main>
<DebugRenderKind />
<p id="intro">
This page uses a short-lived public cache (expire &lt; DYNAMIC_EXPIRE,
5min), which should not be included in a static prefetch, and should
also not be included in a runtime prefetch, because it has a short
enough stale time (&lt; DYNAMIC_STALE, 30s)
This page uses a short-lived public cache (expire &lt;
MIN_PRERENDERABLE_EXPIRE, 5min), which should not be included in a
static prefetch, and should also not be included in a runtime prefetch,
because it has a short enough stale time (&lt; MIN_PREFETCHABLE_STALE,
30s)
</p>
<Suspense fallback={<div style={{ color: 'grey' }}>Loading...</div>}>
<ShortLivedCache />
......@@ -25,9 +26,9 @@ export default async function Page() {
async function ShortLivedCache() {
'use cache'
cacheLife({
stale: 20, // < DYNAMIC_STALE
stale: 20, // < MIN_PREFETCHABLE_STALE
revalidate: 2 * 60,
expire: 3 * 60, // < DYNAMIC_EXPIRE
expire: 3 * 60, // < MIN_PRERENDERABLE_EXPIRE
})
await cachedDelay([__filename])
......
......@@ -715,25 +715,32 @@ describe('runtime prefetching', () => {
describe('cache stale time handling', () => {
it.each([
{
// If a cache has an expiration time under 5min (DYNAMIC_EXPIRE), we omit it from static prerenders.
// However, it should still be included in a runtime prefetch if its stale time is >=30s. (DYNAMIC_STALE)
// If a cache has an expiration time under 5min
// (MIN_PRERENDERABLE_EXPIRE), we omit it from static prerenders.
// However, it should still be included in a runtime prefetch if its
// stale time is >=30s. (MIN_PREFETCHABLE_STALE)
description:
'includes short-lived public caches with a long enough staleTime',
staticContent: 'This page uses a short-lived public cache',
path: '/caches/public-short-expire-long-stale',
},
{
// If a cache has an expiration time under 5min (DYNAMIC_EXPIRE), we omit it from static prerenders.
// However, it should still be included in a runtime prefetch if its stale time is >=30s. (DYNAMIC_STALE)
// `cacheLife("seconds")` is deliberately set to have a stale time of 30s to stay above this treshold.
// If a cache has an expiration time under 5min
// (MIN_PRERENDERABLE_EXPIRE), we omit it from static prerenders.
// However, it should still be included in a runtime prefetch if its
// stale time is >=30s. (MIN_PREFETCHABLE_STALE) `cacheLife("seconds")`
// is deliberately set to have a stale time of 30s to stay above this
// treshold.
description: 'includes public caches with cacheLife("seconds")',
staticContent: 'This page uses a short-lived public cache',
path: '/caches/public-seconds',
},
{
// A Private cache will always be omitted from static prerenders.
// However, it should still be included in a runtime prefetch if its stale time is >=30s. (DYNAMIC_STALE)
// `cacheLife("seconds")` is deliberately set to have a stale time of 30s to stay above this treshold.
// However, it should still be included in a runtime prefetch if its
// stale time is >=30s. (MIN_PREFETCHABLE_STALE) `cacheLife("seconds")`
// is deliberately set to have a stale time of 30s to stay above this
// treshold.
description: 'includes private caches with cacheLife("seconds")',
staticContent: 'This page uses a short-lived private cache',
path: '/caches/private-seconds',
......@@ -777,7 +784,8 @@ describe('runtime prefetching', () => {
})
it('omits short-lived public caches with a short enough staleTime', async () => {
// If a cache has a stale time below 30s (DYNAMIC_STALE), we should omit it from runtime prefetches.
// If a cache has a stale time below 30s (MIN_PREFETCHABLE_STALE), we
// should omit it from runtime prefetches.
let page: Playwright.Page
const browser = await next.browser('/', {
......@@ -837,7 +845,8 @@ describe('runtime prefetching', () => {
})
it('omits private caches with a short enough staleTime', async () => {
// If a cache has a stale time below 30s (DYNAMIC_STALE), we should omit it from runtime prefetches.
// If a cache has a stale time below 30s (MIN_PREFETCHABLE_STALE), we
// should omit it from runtime prefetches.
let page: Playwright.Page
const browser = await next.browser('/', {
......
......@@ -3,18 +3,19 @@ import { Suspense } from 'react'
async function getCachedRandom() {
'use cache'
// Long-lived (stale >= DYNAMIC_STALE, expire >= DYNAMIC_EXPIRE): stays in the
// static shell.
// Long-lived (stale >= MIN_PREFETCHABLE_STALE, expire >=
// MIN_PRERENDERABLE_EXPIRE): stays in the static shell.
cacheLife({ stale: 60, revalidate: 100, expire: 1000 })
return Math.random()
}
async function ShortStaleCache() {
'use cache'
// Long expire (>= DYNAMIC_EXPIRE, 5min) and a non-zero revalidate, but a
// stale time below DYNAMIC_STALE (30s). This isolates the short-stale
// exclusion: the entry is omitted from the static shell purely because of its
// short stale time, not because of a short expire or revalidate: 0.
// Long expire (>= MIN_PRERENDERABLE_EXPIRE, 5min) and a non-zero revalidate,
// but a stale time below MIN_PREFETCHABLE_STALE (30s). This isolates the
// short-stale exclusion: the entry is omitted from the static shell purely
// because of its short stale time, not because of a short expire or
// revalidate: 0.
cacheLife({ stale: 18, revalidate: 100, expire: 1000 })
return <p id="y">{new Date().toISOString()}</p>
}
......
......@@ -13,8 +13,9 @@ const nextConfig = {
},
cacheLife: {
frequent: {
// >= DYNAMIC_STALE (30s) so the cache is still eligible for the static
// shell. A shorter stale time would exclude it from static prerenders.
// >= MIN_PREFETCHABLE_STALE (30s) so the cache is still eligible for the
// static shell. A shorter stale time would exclude it from static
// prerenders.
stale: 30,
revalidate: 100,
expire: 300,
......
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