Unverified Commit 286862e3 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Fix stale dev `'use cache'` for cookieless requests and route handlers (#96022)

In development, editing a file does not evict existing `'use cache'`
entries; an entry is invalidated only by re-keying, and the key includes
an HMR refresh hash. That hash was delivered through the
`__next_hmr_refresh_hash__` cookie, which the browser HMR client set
from each server-components change and sent back on later requests. Two
cases were therefore broken. First, any request that does not carry the
cookie (a `curl`, a plain `fetch`, a fresh browser profile, a second
device) served stale cached content after an edit, for both pages and
route handlers. Second, on Turbopack a route handler served stale
content even when fetched from a page whose HMR client had the cookie,
because a route-handler edit never advanced the hash there and so never
updated the cookie; on webpack that case happens to work, leaving only
cookieless route handlers broken.

The hash is server-authored to begin with (webpack's `stats.hash`,
Turbopack's `hmrHash` counter), so this change sources it directly on
the server and removes the cookie entirely. The hot-reloader exposes it,
and `base-server` attaches it to each request with `addRequestMeta`,
next to `serverComponentsHmrCache`, so it reaches every render,
including the internal Cache Components validation and warmup renders.
It is threaded onto the request store the same way
`serverComponentsHmrCache` is, so `'use cache'` is invalidated for every
client regardless of whether it ran the HMR client. Route handlers,
whose `NextRequest` does not carry request meta, receive it through the
app-route template's `renderOpts`.

Editing a route handler also has to advance the hash in the first place.
On webpack it already did, but on Turbopack the `app-route` entry wired
no change subscription, so a route edit recompiled the module without
advancing `hmrHash`; it now subscribes to the route endpoint so an edit
advances the hash without broadcasting a page refresh. That subscription
is also made the only thing that advances `hmrHash`: the
config-invalidation and server Fast Refresh reset paths previously
bumped it even without a content change, for example on a route's first
load, and with the hash now read synchronously instead of bounced back
through a cookie, such a bump would land between a route's cold write
and warm read and evict a still-valid entry. The getter returns the
counter unconditionally so the key is present and stable for every
request, matching webpack's always-present `stats.hash`.

With the cookie gone, the `hash` field on the `SERVER_COMPONENT_CHANGES`
HMR message has no remaining consumer, so it is dropped from the message
type and both bundlers.

This is a short-term stopgap until the granular implementation hash
(`codeHash` plus `runtimeEnvVars` plus the Next.js version) is used in
`next dev`, which invalidates server-authoritatively by construction and
will let this mechanism be removed.

> [!TIP]
> Best reviewed with hidden whitespace changes. 

closes NAR-894

---

<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 70f8b678
......@@ -1445,5 +1445,6 @@
"1444": "Invalid target hostname \"%s\" for proxy request, expected \"%s\"",
"1445": "Invariant: Missing `__NEXT_PRIVATE_ORIGIN` environment variable.",
"1446": "Missing initURL",
"1447": "Could not determine origin for forwarded Server Actions request. This can happen if port or hostname are not configured for this server."
"1447": "Could not determine origin for forwarded Server Actions request. This can happen if port or hostname are not configured for this server.",
"1448": "Error in the \"%s\" app-route HMR subscription"
}
......@@ -253,6 +253,7 @@ export async function handler(
validationLevel: nextConfig.experimental.instantInsights.validationLevel,
supportsDynamicResponse,
incrementalCache,
hmrRefreshHash: getRequestMeta(req, 'hmrRefreshHash'),
cacheLifeProfiles: nextConfig.cacheLife,
staticPageGenerationTimeout: nextConfig.staticPageGenerationTimeout,
waitUntil: ctx.waitUntil,
......
......@@ -12,7 +12,6 @@ export const NEXT_ROUTER_PREFETCH_HEADER = 'next-router-prefetch' as const
export const NEXT_ROUTER_SEGMENT_PREFETCH_HEADER =
'next-router-segment-prefetch' as const
export const NEXT_HMR_REFRESH_HEADER = 'next-hmr-refresh' as const
export const NEXT_HMR_REFRESH_HASH_COOKIE = '__next_hmr_refresh_hash__' as const
export const NEXT_URL = 'next-url' as const
export const RSC_CONTENT_TYPE_HEADER = 'text/x-component' as const
......
......@@ -31,7 +31,6 @@ import type { McpPageMetadataResponse } from '../../../../shared/lib/mcp-page-me
import { useUntrackedPathname } from '../../../components/navigation-untracked'
import reportHmrLatency from '../../report-hmr-latency'
import { TurbopackHmr } from '../turbopack-hot-reloader-common'
import { NEXT_HMR_REFRESH_HASH_COOKIE } from '../../../components/app-router-headers'
import {
publicAppRouterInstance,
type GlobalErrorState,
......@@ -412,14 +411,9 @@ export function processMessage(
JSON.stringify({
event: 'server-component-reload-page',
clientId: __nextDevClientId,
hash: message.hash,
})
)
// Store the latest hash in a session cookie so that it's sent back to the
// server with any subsequent requests.
document.cookie = `${NEXT_HMR_REFRESH_HASH_COOKIE}=${message.hash};path=/`
if (
RuntimeErrorHandler.hadRuntimeError ||
document.documentElement.id === '__next_error__'
......
......@@ -2856,6 +2856,7 @@ async function renderToHTMLOrFlightImpl(
const rootParams = getRootParams(loaderTree, ctx.getDynamicParamFromSegment)
const fallbackParams = getRequestMeta(req, 'fallbackParams') || null
const hmrRefreshHash = getRequestMeta(req, 'hmrRefreshHash')
const createRequestStore = createRequestStoreForRender.bind(
null,
......@@ -2869,7 +2870,8 @@ async function renderToHTMLOrFlightImpl(
isHmrRefresh,
serverComponentsHmrCache,
renderResumeDataCache,
fallbackParams
fallbackParams,
hmrRefreshHash
)
const requestStore = createRequestStore()
......
......@@ -18,7 +18,6 @@ import type {
import type { Params } from '../request/params'
import type { ImplicitTags } from '../lib/implicit-tags'
import type { WorkStore } from './work-async-storage.external'
import { NEXT_HMR_REFRESH_HASH_COOKIE } from '../../client/components/app-router-headers'
import { InvariantError } from '../../shared/lib/invariant-error'
import type { StagedRenderingController } from './staged-rendering'
import type { ValidationBoundaryTracking } from './instant-validation/boundary-tracking'
......@@ -61,6 +60,7 @@ export interface RequestStore extends CommonWorkUnitStore {
readonly draftMode: DraftModeProvider
readonly isHmrRefresh?: boolean
readonly serverComponentsHmrCache?: ServerComponentsHmrCache
readonly hmrRefreshHash?: string
readonly rootParams: Params
......@@ -438,9 +438,8 @@ export function getHmrRefreshHash(
case 'private-cache':
case 'prerender':
case 'prerender-runtime':
return workUnitStore.hmrRefreshHash
case 'request':
return workUnitStore.cookies.get(NEXT_HMR_REFRESH_HASH_COOKIE)?.value
return workUnitStore.hmrRefreshHash
case 'prerender-client':
case 'validation-client':
case 'prerender-ppr':
......
......@@ -126,6 +126,12 @@ export type RequestStoreInputs = {
previewProps: WrapperRenderOpts['previewProps']
isHmrRefresh: boolean | undefined
serverComponentsHmrCache: ServerComponentsHmrCache | undefined
/**
* The hash of the most recent server component change (dev only). Included in
* `"use cache"` cache keys so that cached entries are revalidated after an
* edit, for every client, regardless of whether it runs the HMR client.
*/
hmrRefreshHash: string | undefined
fallbackParams: OpaqueFallbackRouteParams | null | undefined
}
......@@ -173,7 +179,8 @@ export function createRequestStoreForRender(
isHmrRefresh: RequestContext['isHmrRefresh'],
serverComponentsHmrCache: RequestContext['serverComponentsHmrCache'],
resumeDataCache: ResumeDataCache | null,
fallbackParams: OpaqueFallbackRouteParams | null
fallbackParams: OpaqueFallbackRouteParams | null,
hmrRefreshHash: string | undefined
): RequestStore {
return createRequestStore({
// Pages start in render phase by default
......@@ -193,6 +200,7 @@ export function createRequestStoreForRender(
previewProps,
isHmrRefresh,
serverComponentsHmrCache,
hmrRefreshHash,
fallbackParams,
})
}
......@@ -202,7 +210,8 @@ export function createRequestStoreForAPI(
url: RequestContext['url'],
implicitTags: RequestContext['implicitTags'],
onUpdateCookies: RenderOpts['onUpdateCookies'],
previewProps: WrapperRenderOpts['previewProps']
previewProps: WrapperRenderOpts['previewProps'],
hmrRefreshHash: string | undefined
): RequestStore {
return createRequestStore({
// API routes start in action phase by default
......@@ -216,6 +225,7 @@ export function createRequestStoreForAPI(
previewProps,
isHmrRefresh: false,
serverComponentsHmrCache: undefined,
hmrRefreshHash,
fallbackParams: null,
})
}
......@@ -239,6 +249,7 @@ export function createRequestStore(inputs: RequestStoreInputs): RequestStore {
previewProps,
isHmrRefresh,
serverComponentsHmrCache,
hmrRefreshHash,
fallbackParams,
} = inputs
......@@ -321,6 +332,7 @@ export function createRequestStore(inputs: RequestStoreInputs): RequestStore {
serverComponentsHmrCache:
serverComponentsHmrCache ||
(globalThis as any).__serverComponentsHmrCache,
hmrRefreshHash,
fallbackParams,
}
}
......
......@@ -28,6 +28,12 @@ export type WorkStoreContext = {
cacheLifeProfiles: ResolvedCacheLifeProfiles
staticPageGenerationTimeout: number
incrementalCache?: IncrementalCache
/**
* The hash of the most recent server component change (dev only). Included
* in `"use cache"` cache keys so that cached entries are revalidated after
* an edit, for every client, regardless of whether it runs the HMR client.
*/
hmrRefreshHash?: string
isOnDemandRevalidate?: boolean
cacheComponents: boolean
validationLevel: ValidationLevel
......
......@@ -422,6 +422,15 @@ export default abstract class Server<
: undefined
}
/**
* The hash of the most recent server component change (dev only), used to
* revalidate `"use cache"` entries after an edit. Overridden by the dev
* server; returns `undefined` otherwise.
*/
protected getServerComponentsHmrRefreshHash(): string | undefined {
return undefined
}
protected abstract loadEnvConfig(params: {
dev: boolean
forceReload: boolean
......@@ -1547,6 +1556,20 @@ export default abstract class Server<
)
}
// Attach the server components HMR refresh hash here, alongside the HMR
// cache, so it reaches every render that passes through this request
// handling, including internal renders (e.g. dev validation/warmup) that
// don't re-enter the top-level request handler. It's included in `"use
// cache"` keys so cached entries revalidate after an edit, for every
// client.
if (!getRequestMeta(req, 'hmrRefreshHash')) {
addRequestMeta(
req,
'hmrRefreshHash',
this.getServerComponentsHmrRefreshHash()
)
}
// when invokePath is specified we can short short circuit resolving
// we only honor this header if we are inside of a render worker to
// prevent external users coercing the routing path
......
......@@ -696,6 +696,14 @@ export async function createHotReloaderTurbopack(
let serverHmrSubscriptions: ServerHmrSubscriptions | undefined
let hmrEventHappened = false
// A counter identifying the current version of the compiled output, included
// by `"use cache"` in dev cache keys so that cached entries revalidate after
// an edit. It advances once per HMR change event (for App Router pages that
// is an RSC change, which is what a cached render depends on), independent of
// how many clients are connected. It deliberately does not advance on `BUILT`
// messages: those are sent per connected client on every compilation, so
// advancing there would both churn the hash without an edit and fail to
// advance it at all when no client is connected.
let hmrHash = 0
const clientsWithoutHtmlRequestId = new Set<ws>()
......@@ -1495,6 +1503,16 @@ export async function createHotReloaderTurbopack(
}
},
getServerComponentsHmrRefreshHash() {
// The current server-components generation. Only the change subscription
// (an actual recompile) advances `hmrHash`; reloads and config
// invalidations don't, so the value stays stable across requests until a
// real edit. Returned unconditionally (`"0"` before the first edit) so
// `"use cache"` keys are present and consistent for every request,
// mirroring webpack's always-present `stats.hash`.
return String(hmrHash)
},
sendToLegacyClients(action) {
const payload = JSON.stringify(action)
......@@ -1641,7 +1659,6 @@ export async function createHotReloaderTurbopack(
await clearAllModuleContexts()
this.send({
type: HMR_MESSAGE_SENT_TO_BROWSER.SERVER_COMPONENT_CHANGES,
hash: String(++hmrHash),
})
}
},
......@@ -1922,7 +1939,10 @@ export async function createHotReloaderTurbopack(
sendToClient(client, {
type: HMR_MESSAGE_SENT_TO_BROWSER.BUILT,
hash: String(++hmrHash),
// Report the current version without advancing it: a completed
// compilation is not itself an edit, and this hash is not
// consumed by the Turbopack client.
hash: String(hmrHash),
errors: [...clientErrors.values()],
warnings: [],
})
......@@ -1981,7 +2001,6 @@ export async function createHotReloaderTurbopack(
// Tell browsers to refetch RSC (soft refresh, not full page reload)
hotReloader.send({
type: HMR_MESSAGE_SENT_TO_BROWSER.SERVER_COMPONENT_CHANGES,
hash: String(++hmrHash),
})
},
})
......
......@@ -117,7 +117,6 @@ export interface ReloadPageMessage {
export interface ServerComponentChangesMessage {
type: HMR_MESSAGE_SENT_TO_BROWSER.SERVER_COMPONENT_CHANGES
hash: string
}
/**
......@@ -259,6 +258,13 @@ export interface NextJsHotReloaderInterface {
* and App Router clients that don't have Cache Components enabled.
*/
sendToLegacyClients(action: HmrMessageSentToBrowser): void
/**
* The hash of the most recent server component change, or `undefined` if no
* server component change has occurred yet. In dev, this is included in `"use
* cache"` cache keys so that cached entries are revalidated after an edit,
* for every client, regardless of whether it runs the HMR client.
*/
getServerComponentsHmrRefreshHash(): string | undefined
setCacheStatus(status: ServerCacheStatus, htmlRequestId: string): void
setReactDebugChannel(
debugChannel: ReactDebugChannelForBrowser,
......
......@@ -241,6 +241,7 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
private serverError: Error | null = null
private hmrServerError: Error | null = null
private serverPrevDocumentHash: string | null
private serverComponentsHmrRefreshHash: string | undefined
private serverChunkNames?: Set<string>
private prevChunkNames?: Set<any>
private onDemandEntries?: ReturnType<typeof onDemandEntryHandler>
......@@ -431,14 +432,18 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
}
protected async refreshServerComponents(hash: string): Promise<void> {
this.serverComponentsHmrRefreshHash = hash
this.send({
type: HMR_MESSAGE_SENT_TO_BROWSER.SERVER_COMPONENT_CHANGES,
hash,
// TODO: granular reloading of changes
// entrypoints: serverComponentChanges,
})
}
public getServerComponentsHmrRefreshHash(): string | undefined {
return this.serverComponentsHmrRefreshHash
}
public onHMR(
req: IncomingMessage,
_socket: Duplex,
......
......@@ -231,6 +231,10 @@ export default class DevServer extends Server {
return this.serverComponentsHmrCache
}
protected override getServerComponentsHmrRefreshHash(): string | undefined {
return this.bundlerService.getServerComponentsHmrRefreshHash()
}
protected getRouteMatchers(): RouteMatcherManager {
const { pagesDir, appDir } = findPagesDir(this.dir)
......
......@@ -408,6 +408,34 @@ export async function handleRouteType({
const writtenEndpoint = await route.endpoint.writeToDisk()
hooks?.handleWrittenEndpoint(key, writtenEndpoint, false)
if (dev) {
// Advance the hot-reloader's HMR refresh hash whenever this route
// handler is recompiled, so its `"use cache"` entries are invalidated
// after an edit. Subscribing runs `subscribeToClientChanges`, which
// bumps the `hmrHash` counter on each change; that counter is returned
// by `getServerComponentsHmrRefreshHash` and folded into cache keys by
// `getHmrRefreshHash`. Unlike app pages there is no RSC for a connected
// browser to refetch, so `createMessage` returns nothing; the
// subscription exists only to advance the hash.
hooks?.subscribeToChanges(
key,
/** includeIssues= */ true,
route.endpoint,
() => undefined,
(error) => {
// This subscription only advances the refresh hash, so there is
// nothing to send the browser when it fails. `subscribeToChanges`
// drops the subscription on error and re-creates it the next time
// this route is ensured, so just log it.
console.error(
new Error(`Error in the "${page}" app-route HMR subscription`, {
cause: error,
})
)
}
)
}
const type = writtenEndpoint.type
manifestLoader.loadAppPathsManifest(page)
......
......@@ -167,6 +167,7 @@ export async function probeUseCache(msg: ProbeMessage): Promise<boolean> {
previewProps: undefined,
isHmrRefresh: msg.request.isHmrRefresh,
serverComponentsHmrCache: undefined,
hmrRefreshHash: msg.request.hmrRefreshHash,
fallbackParams: null,
})
......
......@@ -64,6 +64,10 @@ export class DevBundlerService {
return await this.bundler.hotReloader.ensurePage(definition)
}
public getServerComponentsHmrRefreshHash(): string | undefined {
return this.bundler.hotReloader.getServerComponentsHmrRefreshHash()
}
public logErrorWithOriginalStack =
this.bundler.logErrorWithOriginalStack.bind(this.bundler)
......
......@@ -114,6 +114,14 @@ export interface RequestMeta {
*/
serverComponentsHmrCache?: ServerComponentsHmrCache
/**
* The hash of the most recent server component change (dev only), set by the
* router-server from the hot-reloader. Included in `"use cache"` cache keys
* so that cached entries are revalidated after an edit, for every client,
* regardless of whether it runs the HMR client.
*/
hmrRefreshHash?: string
/**
* Equals the segment path that was used for the prefetch RSC request.
*/
......
......@@ -805,7 +805,8 @@ export class AppRouteRouteModule extends RouteModule<
req.nextUrl,
implicitTags,
undefined,
context.previewProps
context.previewProps,
context.renderOpts.hmrRefreshHash
)
const workStore = createWorkStore(staticGenerationContext)
......
......@@ -24,6 +24,7 @@ export type UseCacheProbeRequestSnapshot = {
rootParams: Params
isDraftMode: boolean
isHmrRefresh: boolean
hmrRefreshHash: string | undefined
}
/**
......
......@@ -115,6 +115,7 @@ export function setupProbeScheduler(
rootParams: outerRequestStore.rootParams ?? {},
isDraftMode: workStore.isDraftMode ?? false,
isHmrRefresh: outerRequestStore.isHmrRefresh ?? false,
hmrRefreshHash: outerRequestStore.hmrRefreshHash,
},
timeoutMs: probeInternalTimeoutMs,
}).then(
......
......@@ -74,10 +74,7 @@ import {
} from './handlers'
import type { CacheReadWriteHandler } from './tiered-cache-handler'
import { cloneCacheEntry } from './clone-cache-entry'
import {
NEXT_HMR_REFRESH_HASH_COOKIE,
NEXT_INSTANT_TEST_COOKIE,
} from '../../client/components/app-router-headers'
import { NEXT_INSTANT_TEST_COOKIE } from '../../client/components/app-router-headers'
import type { ReadonlyRequestCookies } from '../web/spec-extension/adapters/request-cookies'
import type { ReadonlyHeaders } from '../web/spec-extension/adapters/headers'
import {
......@@ -366,10 +363,8 @@ function computeRootParamsCacheKeySuffix(
// Next-internal cookies that must not vary the private cache key, since they're
// not part of the application's own cookie state. The instant-navigation cookie
// toggles while a navigation lock is held, so including it would force spurious
// misses. The HMR refresh hash is already part of the cache key (see
// `cacheKeyParts`), so including its cookie too would just be redundant.
// misses.
const COOKIES_EXCLUDED_FROM_PRIVATE_CACHE_KEY = new Set<string>([
NEXT_HMR_REFRESH_HASH_COOKIE,
NEXT_INSTANT_TEST_COOKIE,
])
......
......@@ -313,7 +313,10 @@ export async function adapter(
request.nextUrl,
implicitTags,
onUpdateCookies,
previewProps
previewProps,
// Edge route handlers can't use `"use cache"`, so there's no HMR
// refresh hash to thread through here.
undefined
)
const workStore = createWorkStore({
......
......@@ -27,12 +27,15 @@ describe('use-cache-custom-handler', () => {
expect(cliOutput).toContain('ModernCustomCacheHandler::refreshTags')
// In development the cache key carries a trailing HMR refresh hash element
// (absent in production), so the args array may be followed by an optional
// quoted hash.
expect(next.cliOutput.slice(outputIndex)).toMatch(
/ModernCustomCacheHandler::get \["(development|[A-Za-z0-9_-]+)","([0-9a-f]{2})+",\[\]\] \[ '_N_T_\/layout', '_N_T_\/page', '_N_T_\/', '_N_T_\/index' \]/
/ModernCustomCacheHandler::get \["(development|[A-Za-z0-9_-]+)","([0-9a-f]{2})+",\[\](,"[^"]+")?\] \[ '_N_T_\/layout', '_N_T_\/page', '_N_T_\/', '_N_T_\/index' \]/
)
expect(next.cliOutput.slice(outputIndex)).toMatch(
/ModernCustomCacheHandler::set \["(development|[A-Za-z0-9_-]+)","([0-9a-f]{2})+",\[\]\]/
/ModernCustomCacheHandler::set \["(development|[A-Za-z0-9_-]+)","([0-9a-f]{2})+",\[\](,"[^"]+")?\]/
)
// Since no existing cache entry was retrieved, we don't need to call
......
......@@ -50,15 +50,16 @@ describe('use-cache-default-handler-expire-zero', () => {
// In development the default handler keeps `expire: 0` entries (its
// minimum retention serves them warm across reloads), so it stores rather
// than skips.
// than skips. The dev cache key always carries a trailing HMR refresh
// hash element after the args array.
await retry(async () => {
expect(next.cliOutput).toMatch(
/DefaultCacheHandler: set \["[A-Za-z0-9_-]+","([0-9a-f]{2})+",\[{"id":"expire-zero"}]\] done/
/DefaultCacheHandler: set \["[A-Za-z0-9_-]+","([0-9a-f]{2})+",\[{"id":"expire-zero"}],"[^"]+"\] done/
)
})
expect(next.cliOutput).not.toMatch(
/DefaultCacheHandler: set \["[A-Za-z0-9_-]+","([0-9a-f]{2})+",\[{"id":"expire-zero"}]\] skipped/
/DefaultCacheHandler: set \["[A-Za-z0-9_-]+","([0-9a-f]{2})+",\[{"id":"expire-zero"}],"[^"]+"\] skipped/
)
})
}
......
......@@ -457,7 +457,6 @@ async function readNormalizedNFT(next, name) {
expect(trace).toMatchInlineSnapshot(`
[
"/node_modules/client-only/index.js",
"/node_modules/next/dist/client/components/app-router-headers.js",
"/node_modules/next/dist/compiled/@opentelemetry/api/index.js",
"/node_modules/next/dist/compiled/next-server/server.runtime.prod.js",
"/node_modules/next/dist/compiled/source-map/source-map.js",
......@@ -627,7 +626,6 @@ async function readNormalizedNFT(next, name) {
"./.next/server/server-reference-manifest.json",
"/node_modules/@swc/helpers/cjs/_interop_require_default.cjs",
"/node_modules/next/dist/build/adapter/setup-node-env.external.js",
"/node_modules/next/dist/client/components/app-router-headers.js",
"/node_modules/next/dist/client/components/hooks-server-context.js",
"/node_modules/next/dist/client/components/static-generation-bailout.js",
"/node_modules/next/dist/client/lib/console.js",
......
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