Unverified Commit 90305124 authored by Orkhan Rzazade's avatar Orkhan Rzazade Committed by GitHub

fix(incremental-cache): keep an ISR entry's cache lifetime across instances and restarts (#99289)

### What?

An on-demand ISR page (dynamic route with `revalidate`, not prerendered
at build) loses its `Cache-Control` header when the process serving it
from the cache is not the one that rendered it. That happens with
several instances sharing a cache handler, and with a single instance
after a restart, including the default file-system cache.

After a restart it is also served `STALE` on every request, because
`calculateRevalidate` falls back to its 1-second default.

A running instance can also retain an outdated lifetime after another
instance replaces the shared entry with a shorter-lived result.

### Why?

`IncrementalCache.get()` takes an entry's lifetime only from
`SharedCacheControls`: an in-memory map that `IncrementalCache.set()`
fills in the same process, with the prerender manifest as fallback. An
on-demand page of a dynamic route is not in the manifest. So any other
process has no lifetime for the entry, sends no header, and treats the
entry as stale after one second.

### How?

- `CacheHandlerValue` gets an optional `cacheControl`. Handlers already
receive it as `ctx.cacheControl` in `set()`; now they can return it from
`get()`.
- In `IncrementalCache.get()`, the lifetime returned with the entry
takes precedence over the in-memory map and is remembered for the route,
so both the response header and revalidation use the entry's current
lifetime.
- The default `FileSystemCache` stores `cacheControl` in the `.meta`
file of App Router pages and routes, and returns it.

Pages Router ISR is not covered: the file-system cache writes no `.meta`
for it. I kept that out of this PR.

### Tests

`test/production/app-dir/isr-cache-control-restart` contains three
separate on-disk fixture apps:

- `default`: the built-in file-system cache, with `cacheComponents:
false`.
- `custom`: a persistent custom cache handler that stores
`ctx.cacheControl`, with `cacheComponents: false`.
- `cache-components`: `cacheLife` with a persistent custom route-cache
handler, covering the same on-demand route-cache path with Cache
Components enabled.

The three restart cases render an on-demand page, age the entry beyond
two seconds, and restart the server without rebuilding. The first
response after restart must retain the original `Cache-Control` and
report `HIT`; a repeat request must also report `HIT`. Aging past the
broken one-second fallback makes the freshness assertion meaningful.

A fourth test keeps servers A and B running from the same build with one
shared cache handler and a controllable service. A first caches a
success with a one-hour lifetime. After direct eviction from the shared
store, B caches an error result with a two-second lifetime. A must use
the replacement entry's shorter `Cache-Control` and report `STALE` after
two seconds. Direct eviction avoids relying on the fixture handler's
no-op tag invalidation.

All four tests pass locally with Webpack and with Turbopack under
`__NEXT_CACHE_COMPONENTS=true`. The new two-server test catches the
previous implementation retaining A's one-hour lifetime. The three
restart cases were also verified to fail on the original PR base
(`1cc0f661`) with `STALE` instead of `HIT`. Prettier, ESLint, the root
and Next.js type checks, and the full repository build pass.

The local validation above ran on `7adcd57b`, before the subsequent
merge of `canary` (`d093eb45`). That merge preserved the changed
incremental-cache files and fixtures.

Fixes #99288

---------
Co-authored-by: 's avatarorzazade <orzazade@users.noreply.github.com>
parent a5cf7ef1
import type { OutgoingHttpHeaders } from 'node:http' import type { OutgoingHttpHeaders } from 'node:http'
import type { PrefetchHints } from '../../shared/lib/app-router-types' import type { PrefetchHints } from '../../shared/lib/app-router-types'
import type { CacheControl } from '../../server/lib/cache-control'
export type RouteMetadata = { export type RouteMetadata = {
status: number | undefined status: number | undefined
...@@ -7,4 +8,9 @@ export type RouteMetadata = { ...@@ -7,4 +8,9 @@ export type RouteMetadata = {
postponed: string | undefined postponed: string | undefined
segmentPaths: Array<string> | undefined segmentPaths: Array<string> | undefined
prefetchHints: PrefetchHints | undefined prefetchHints: PrefetchHints | undefined
/**
* The lifetime of an entry written by the incremental cache at runtime, so an
* instance that did not render it can serve it with the same Cache-Control.
*/
cacheControl?: CacheControl
} }
...@@ -142,6 +142,7 @@ export default class FileSystemCache implements CacheHandler { ...@@ -142,6 +142,7 @@ export default class FileSystemCache implements CacheHandler {
headers: meta.headers, headers: meta.headers,
status: meta.status, status: meta.status,
}, },
cacheControl: meta.cacheControl,
} }
} else { } else {
const filePath = this.getFilePath( const filePath = this.getFilePath(
...@@ -253,6 +254,7 @@ export default class FileSystemCache implements CacheHandler { ...@@ -253,6 +254,7 @@ export default class FileSystemCache implements CacheHandler {
status: meta?.status, status: meta?.status,
segmentData: maybeSegmentData, segmentData: maybeSegmentData,
}, },
cacheControl: meta?.cacheControl,
} }
} else if (kind === IncrementalCacheKind.PAGES) { } else if (kind === IncrementalCacheKind.PAGES) {
let meta: RouteMetadata | undefined let meta: RouteMetadata | undefined
...@@ -351,9 +353,12 @@ export default class FileSystemCache implements CacheHandler { ...@@ -351,9 +353,12 @@ export default class FileSystemCache implements CacheHandler {
data: IncrementalCacheValue | null, data: IncrementalCacheValue | null,
ctx: SetIncrementalFetchCacheContext | SetIncrementalResponseCacheContext ctx: SetIncrementalFetchCacheContext | SetIncrementalResponseCacheContext
) { ) {
const cacheControl = ctx.fetchCache ? undefined : ctx.cacheControl
FileSystemCache.memoryCache?.set(key, { FileSystemCache.memoryCache?.set(key, {
value: data, value: data,
lastModified: Date.now(), lastModified: Date.now(),
cacheControl,
}) })
if (FileSystemCache.debug) { if (FileSystemCache.debug) {
...@@ -380,6 +385,7 @@ export default class FileSystemCache implements CacheHandler { ...@@ -380,6 +385,7 @@ export default class FileSystemCache implements CacheHandler {
postponed: undefined, postponed: undefined,
segmentPaths: undefined, segmentPaths: undefined,
prefetchHints: undefined, prefetchHints: undefined,
cacheControl,
} }
writer.append( writer.append(
...@@ -434,6 +440,7 @@ export default class FileSystemCache implements CacheHandler { ...@@ -434,6 +440,7 @@ export default class FileSystemCache implements CacheHandler {
postponed: data.postponed, postponed: data.postponed,
segmentPaths, segmentPaths,
prefetchHints: undefined, prefetchHints: undefined,
cacheControl,
} }
writer.append( writer.append(
......
...@@ -30,7 +30,7 @@ import { ...@@ -30,7 +30,7 @@ import {
workUnitAsyncStorage, workUnitAsyncStorage,
} from '../../app-render/work-unit-async-storage.external' } from '../../app-render/work-unit-async-storage.external'
import { InvariantError } from '../../../shared/lib/invariant-error' import { InvariantError } from '../../../shared/lib/invariant-error'
import type { Revalidate } from '../cache-control' import type { CacheControl, Revalidate } from '../cache-control'
import { getPreviouslyRevalidatedTags } from '../../server-utils' import { getPreviouslyRevalidatedTags } from '../../server-utils'
import { workAsyncStorage } from '../../app-render/work-async-storage.external' import { workAsyncStorage } from '../../app-render/work-async-storage.external'
import { createPromiseWithResolvers } from '../../../shared/lib/promise-with-resolvers' import { createPromiseWithResolvers } from '../../../shared/lib/promise-with-resolvers'
...@@ -54,6 +54,13 @@ export interface CacheHandlerValue { ...@@ -54,6 +54,13 @@ export interface CacheHandlerValue {
age?: number age?: number
cacheState?: string cacheState?: string
value: IncrementalCacheValue | null value: IncrementalCacheValue | null
/**
* The entry's cache lifetime, as passed to `set()` in `ctx.cacheControl`.
* A cache handler that stores it and returns it here lets any instance serve
* the entry with its lifetime, including one that did not render it (another
* server sharing the cache, or the same server after a restart).
*/
cacheControl?: CacheControl
} }
function toHex(buffer: ArrayBufferView | ArrayBuffer): string { function toHex(buffer: ArrayBufferView | ArrayBuffer): string {
...@@ -632,7 +639,15 @@ export class IncrementalCache implements IncrementalCacheType { ...@@ -632,7 +639,15 @@ export class IncrementalCache implements IncrementalCacheType {
let entry: IncrementalResponseCacheEntry | null = null let entry: IncrementalResponseCacheEntry | null = null
const { isFallback } = ctx const { isFallback } = ctx
const cacheControl = this.cacheControls.get(toRoute(cacheKey)) let cacheControl = this.cacheControls.get(toRoute(cacheKey))
// The stored lifetime belongs to this entry, which another instance may
// have replaced with a different lifetime. Prefer it over this process's
// remembered lifetime, and update the route so revalidation uses it too.
if (cacheData?.cacheControl) {
cacheControl = cacheData.cacheControl
this.cacheControls.set(toRoute(cacheKey), cacheControl)
}
let isStale: boolean | -1 | undefined let isStale: boolean | -1 | undefined
let revalidateAfter: Revalidate let revalidateAfter: Revalidate
......
import { cacheLife } from 'next/cache'
// Cache Components requires a build-time sample. /1 is not among the samples,
// so its full route entry is still generated on demand.
export function generateStaticParams() {
return [{ id: 'prerendered' }]
}
async function CachedPage({ id }: { id: string }) {
'use cache'
const serviceUrl = process.env.CACHE_LIFE_SERVICE_URL
const result: { message: string; revalidate: number } =
serviceUrl && id !== 'prerendered'
? await (await fetch(serviceUrl)).json()
: { message: 'success', revalidate: 3600 }
cacheLife({ stale: 300, revalidate: result.revalidate, expire: 7200 })
return (
<>
<p id="page">page {id}</p>
<p id="result">{result.message}</p>
</>
)
}
export default async function Page({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
return <CachedPage id={id} />
}
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>{children}</body>
</html>
)
}
// Persist complete route entries across restarts. For this PPR fixture, the
// default handler omits the RSC payload needed to reload the entry from disk.
const fs = require('fs')
const path = require('path')
const file = path.join(process.cwd(), '.next', 'shared-cache.json')
const replacer = (_key, value) => {
if (value instanceof Map) return { __map: [...value.entries()] }
if (value && value.type === 'Buffer' && Array.isArray(value.data)) {
return { __buffer: Buffer.from(value.data).toString('base64') }
}
return value
}
const reviver = (_key, value) => {
if (value && typeof value === 'object' && '__map' in value) {
return new Map(value.__map)
}
if (value && typeof value === 'object' && '__buffer' in value) {
return Buffer.from(value.__buffer, 'base64')
}
return value
}
const read = () => {
try {
return JSON.parse(fs.readFileSync(file, 'utf8'), reviver)
} catch {
return {}
}
}
module.exports = class CacheHandler {
async get(key) {
return read()[key] ?? null
}
async set(key, data, ctx) {
const entries = read()
entries[key] = {
value: data,
lastModified: Date.now(),
cacheControl: ctx.cacheControl,
}
fs.writeFileSync(file, JSON.stringify(entries, replacer))
}
async revalidateTag() {}
resetRequestCache() {}
}
module.exports = {
cacheComponents: true,
cacheHandler: require.resolve('./cache-handler.js'),
cacheMaxMemorySize: 0,
}
// Rendered on demand (nothing is prerendered) and cached for an hour.
export const revalidate = 3600
export function generateStaticParams() {
return []
}
export default async function Page({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
return <p id="page">page {id}</p>
}
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>{children}</body>
</html>
)
}
// A cache handler that keeps entries in a JSON file, like a cache shared by
// several instances would. It stores the lifetime Next.js passes to `set()` and
// returns it from `get()`.
const fs = require('fs')
const path = require('path')
const file = path.join(process.cwd(), '.next', 'shared-cache.json')
const replacer = (_key, value) => {
if (value instanceof Map) return { __map: [...value.entries()] }
if (value && value.type === 'Buffer' && Array.isArray(value.data)) {
return { __buffer: Buffer.from(value.data).toString('base64') }
}
return value
}
const reviver = (_key, value) => {
if (value && typeof value === 'object' && '__map' in value) {
return new Map(value.__map)
}
if (value && typeof value === 'object' && '__buffer' in value) {
return Buffer.from(value.__buffer, 'base64')
}
return value
}
const read = () => {
try {
return JSON.parse(fs.readFileSync(file, 'utf8'), reviver)
} catch {
return {}
}
}
module.exports = class CacheHandler {
async get(key) {
return read()[key] ?? null
}
async set(key, data, ctx) {
const entries = read()
entries[key] = {
value: data,
lastModified: Date.now(),
cacheControl: ctx.cacheControl,
}
fs.writeFileSync(file, JSON.stringify(entries, replacer))
}
async revalidateTag() {}
resetRequestCache() {}
}
module.exports = {
cacheComponents: false,
experimental: {
cachedNavigations: false,
},
cacheHandler: require.resolve('./cache-handler.js'),
cacheMaxMemorySize: 0,
}
// Rendered on demand (nothing is prerendered) and cached for an hour.
export const revalidate = 3600
export function generateStaticParams() {
return []
}
export default async function Page({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
return <p id="page">page {id}</p>
}
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>{children}</body>
</html>
)
}
module.exports = {
cacheComponents: false,
experimental: {
cachedNavigations: false,
},
}
import { nextTestSetup } from 'e2e-utils'
import { load } from 'cheerio'
import {
fetchViaHTTP,
findPort,
killApp,
nextStart,
retry,
} from 'next-test-utils'
import { createServer } from 'http'
import type { AddressInfo } from 'net'
import { join } from 'path'
// An on-demand entry must retain its lifetime when read by a new process.
describe('isr-cache-control-restart', () => {
describe.each(['default', 'custom', 'cache-components'])(
'%s cache',
(fixture) => {
const { next } = nextTestSetup({
files: join(__dirname, fixture),
})
it('keeps the Cache-Control and freshness of an on-demand page after a restart', async () => {
const rendered = await next.fetch('/1')
expect(rendered.status).toBe(200)
expect(rendered.headers.get('x-nextjs-cache')).toBe('MISS')
const cacheControl = rendered.headers.get('cache-control')
expect(cacheControl).toContain('s-maxage=3600')
expect(load(await rendered.text())('#page').text()).toBe('page 1')
const renderedAt = performance.now()
await next.stop()
// The broken fallback lifetime is one second. Age the entry beyond it,
// but keep it well within the intended one-hour lifetime.
await retry(() => {
expect(performance.now() - renderedAt).toBeGreaterThan(2000)
}, 5000)
await next.start({ skipBuild: true })
const cached = await next.fetch('/1')
expect(cached.status).toBe(200)
expect(cached.headers.get('x-nextjs-cache')).toBe('HIT')
expect(cached.headers.get('cache-control')).toBe(cacheControl)
expect(load(await cached.text())('#page').text()).toBe('page 1')
const repeated = await next.fetch('/1')
expect(repeated.headers.get('x-nextjs-cache')).toBe('HIT')
expect(repeated.headers.get('cache-control')).toBe(cacheControl)
})
}
)
describe('replacement entries shared by running instances', () => {
const { next } = nextTestSetup({
files: join(__dirname, 'cache-components'),
skipStart: true,
})
let result = 'success'
const service = createServer((_req, res) => {
res.setHeader('Content-Type', 'application/json')
res.end(
JSON.stringify({
message: result,
revalidate: result === 'success' ? 3600 : 2,
})
)
})
let serverB: Awaited<ReturnType<typeof nextStart>>
let portB: number
beforeAll(async () => {
await new Promise<void>((resolve) => {
service.listen(0, '127.0.0.1', resolve)
})
const { port } = service.address() as AddressInfo
next.env.CACHE_LIFE_SERVICE_URL = `http://127.0.0.1:${port}`
await next.start()
// Both processes use the same build and on-disk route-cache handler.
portB = await findPort()
serverB = await nextStart(next.testDir, portB, {
cwd: next.testDir,
nextBin: join(next.testDir, 'node_modules/next/dist/bin/next'),
env: next.env,
})
if (!serverB) throw new Error('Server B failed to start')
})
afterAll(async () => {
await killApp(serverB)
await new Promise<void>((resolve, reject) => {
service.close((err) => (err ? reject(err) : resolve()))
})
})
it("uses the replacement entry lifetime instead of the first instance's remembered lifetime", async () => {
const initial = await next.fetch('/1')
expect(initial.headers.get('x-nextjs-cache')).toBe('MISS')
expect(initial.headers.get('cache-control')).toContain('s-maxage=3600')
expect(load(await initial.text())('#result').text()).toBe('success')
const cacheFile = '.next/shared-cache.json'
await retry(async () => {
const entries = JSON.parse(await next.readFile(cacheFile))
expect(entries['/1'].cacheControl.revalidate).toBe(3600)
})
// Evict the route directly. No revalidatePath() is used, so this does
// not rely on the fixture handler's no-op revalidateTag(). Keep A alive.
result = 'error'
const entries = JSON.parse(await next.readFile(cacheFile))
delete entries['/1']
await next.patchFile(cacheFile, JSON.stringify(entries))
const replacement = await fetchViaHTTP(portB, '/1')
expect(replacement.headers.get('x-nextjs-cache')).toBe('MISS')
const cacheControl = replacement.headers.get('cache-control')
expect(cacheControl).toContain('s-maxage=2,')
expect(load(await replacement.text())('#result').text()).toBe('error')
const lastModified = await retry(async () => {
const shared = JSON.parse(await next.readFile(cacheFile))['/1']
expect(shared.cacheControl.revalidate).toBe(2)
return shared.lastModified as number
})
const cached = await next.fetch('/1')
expect(cached.headers.get('x-nextjs-cache')).toBe('HIT')
expect(cached.headers.get('cache-control')).toBe(cacheControl)
expect(load(await cached.text())('#result').text()).toBe('error')
await retry(() => {
expect(Date.now() - lastModified).toBeGreaterThan(2100)
}, 5000)
const stale = await next.fetch('/1')
expect(stale.headers.get('x-nextjs-cache')).toBe('STALE')
expect(stale.headers.get('cache-control')).toBe(cacheControl)
await stale.text()
})
})
})
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