Unverified Commit 6d67f46a authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

[backport] Keep the dev validation worker alive across HMR updates (#97315)

Backports #96988 ("Keep the dev validation worker alive across HMR
updates") to `next-16-3`.

Cache Components dev validation reported stack frames that pointed at
build output whenever a module had been updated while the dev server
ran. The overlay showed a raw `file:` URL, the terminal named the chunk
rather than the page, and because the frame never resolved to a source
position there was no code frame either, so nothing indicated which line
caused the error. This affected both the static shell validation and the
instant-navigation validation, since both run on the same worker.

Turbopack's server HMR evaluates an updated module as a script of its
own, carrying its source map inline rather than on disk, so only the
isolate that ran that `eval` can resolve a frame in it. The validation
worker never ran it. The worker now replays the applied updates, the
cleared manifest cache entries, and the evicted paths that the dev
server reports, in the same order the dev server applied them, which
leaves each updated module's inline source map in the worker's own
Node.js cache.

Not dropping the worker on every edit also removes a worker respawn and
a `loadComponents` call from each validation that follows an edit, which
is paid at exactly the moment the user is waiting for the insight. The
case in the test suite that covers this went from around 870ms to around
240ms.

This affects Turbopack dev with Cache Components, which is on by default
unless `experimental.devValidationWorker` is set to `false`.

### Verification on this branch

Cherry-picked from `f70564f7` with no conflicts. All source files are
byte-identical to canary. Behavioral verification is left to CI on this
branch; the change carries the `dev-validation-worker-source-maps`
suite, whose snapshots turn from a frame naming the chunk into resolved
frames.

<!-- NEXT_JS_LLM -->
parent 2dd7f528
...@@ -28,6 +28,17 @@ prints the speedup. Options: ...@@ -28,6 +28,17 @@ prints the speedup. Options:
- `--port=<n>`, `--headless=false`, `--settle-ms=<n>`. - `--port=<n>`, `--headless=false`, `--settle-ms=<n>`.
- `--json-out=<path>` — write the raw stats as JSON. - `--json-out=<path>` — write the raw stats as JSON.
Set `BENCH_DEV_VALIDATION_INSIGHTS=1` to give every family's leaf page an
uncached data access, so validation reports one insight per navigation. Without
it the run only covers the validation renders; with it, it also covers what
follows an insight — encoding the errors and printing them with a source-mapped
stack and code frame — which is the part that moves when that printing changes
threads. The access sits below the family's heavy subtree, so validation still
does that work before it reaches it: a page that suspends before it returns
leaves the subtree unrendered in the validation pass. The routes become
dynamic, so the absolute numbers are not comparable with a run without the
flag; the worker-versus-in-process comparison within a run is.
This depends on `experimental.devValidationWorker` existing, so it stacks on the This depends on `experimental.devValidationWorker` existing, so it stacks on the
PR that adds the flag. Until the worker implementation lands, both PR that adds the flag. Until the worker implementation lands, both
configurations run in-process and the A/B shows no delta; once it lands, the configurations run in-process and the A/B shows no delta; once it lands, the
......
...@@ -25,7 +25,15 @@ import { fileURLToPath } from 'node:url' ...@@ -25,7 +25,15 @@ import { fileURLToPath } from 'node:url'
// Bump VERSION whenever the generation logic or shape changes; the marker file // Bump VERSION whenever the generation logic or shape changes; the marker file
// short-circuits regeneration when nothing changed. // short-circuits regeneration when nothing changed.
const VERSION = 'v6-3families-nested4-noinstant-48leaves-d4-b3-400symbols' // Set BENCH_DEV_VALIDATION_INSIGHTS=1 to give every family's leaf page an
// uncached data access. Validation then reports one insight per navigation, so
// the run also exercises the error path (encoding the errors, and printing them
// with a source-mapped stack and code frame) rather than only the validation
// render. Off by default, so the numbers the README describes stay comparable.
const WITH_INSIGHTS = process.env.BENCH_DEV_VALIDATION_INSIGHTS === '1'
const VERSION =
'v6-3families-nested4-noinstant-48leaves-d4-b3-400symbols' +
(WITH_INSIGHTS ? '-insights-below-tree' : '')
const LEAF_COMPONENTS = 48 const LEAF_COMPONENTS = 48
const TREE_DEPTH = 4 const TREE_DEPTH = 4
const TREE_BRANCH = 3 const TREE_BRANCH = 3
...@@ -221,27 +229,56 @@ export default function Layout({ children }: { children: React.ReactNode }) { ...@@ -221,27 +229,56 @@ export default function Layout({ children }: { children: React.ReactNode }) {
` `
} }
// The uncached access that makes validation report an insight. It renders last,
// below the family's heavy subtree, so validation does that work before it
// reaches the access. It is not wrapped in a `<Suspense>`, which is what makes
// validation report the route as blocking.
const insightImport = WITH_INSIGHTS
? "import { connection } from 'next/server'\n"
: ''
const insightComponent = WITH_INSIGHTS
? `
async function Insight() {
await connection()
return null
}
`
: ''
function leafPageSource(family, depthFromApp) { function leafPageSource(family, depthFromApp) {
if (family === 'sprite') { if (family === 'sprite') {
return `// Generated. See scripts/generate.mjs. The sprite renders in the if (!WITH_INSIGHTS) {
return `// Generated. See scripts/generate.mjs. The sprite renders in the
// shared layout above, so the leaf page only carries the route marker. // shared layout above, so the leaf page only carries the route marker.
export default function Page() { export default function Page() {
return <h1 id="route">sprite</h1> return <h1 id="route">sprite</h1>
} }
` `
}
return `${insightImport}// Generated. See scripts/generate.mjs. The sprite renders in the
// shared layout above, so the leaf page only carries the route marker.
export default function Page() {
return (
<>
<h1 id="route">sprite</h1>
<Insight />
</>
)
}
${insightComponent}`
} }
return `import { HeavyTree } from '${up(depthFromApp)}_generated/${family}-tree' return `${insightImport}import { HeavyTree } from '${up(depthFromApp)}_generated/${family}-tree'
// Generated. See scripts/generate.mjs. // Generated. See scripts/generate.mjs.
export default function Page() { export default function Page() {
return ( return (
<section> <section>
<h1 id="route">${family}</h1> <h1 id="route">${family}</h1>
<HeavyTree seed={7} /> <HeavyTree seed={7} />${WITH_INSIGHTS ? '\n <Insight />' : ''}
</section> </section>
) )
} }
` ${insightComponent}`
} }
for (const family of FAMILIES) { for (const family of FAMILIES) {
......
import type { NextConfigComplete } from '../config-shared' import type { NextConfigComplete } from '../config-shared'
import type { runDevValidation } from './dev-validation-worker' import type { NodeJsPartialHmrUpdate } from '../../build/swc/types'
import type {
applyHmrUpdate,
invalidateCaches,
runDevValidation,
} from './dev-validation-worker'
import type { import type {
DevValidationSnapshot, DevValidationSnapshot,
DevValidationWorkerMessage, DevValidationWorkerMessage,
...@@ -21,6 +26,52 @@ interface InstallOptions { ...@@ -21,6 +26,52 @@ interface InstallOptions {
type ValidationPool = { [key: string]: any } & { type ValidationPool = { [key: string]: any } & {
runDevValidation: typeof runDevValidation runDevValidation: typeof runDevValidation
applyHmrUpdate: typeof applyHmrUpdate
invalidateCaches: typeof invalidateCaches
}
/**
* One change the dev server made to its own module state — the modules it has
* loaded, and the manifest caches that describe them.
*
* The worker holds the same state, seeded from the same build output, and
* replays every change the dev server reports, so its state is the dev server's
* state by construction.
*/
type DevModuleStateChange =
| { type: 'apply'; update: NodeJsPartialHmrUpdate }
| { type: 'invalidate'; filePaths: string[]; evictModules: boolean }
/**
* Replays a change the dev server made to its own module state in the
* validation worker. Installed alongside the worker, so it is absent when no
* worker runs (`experimental.devValidationWorker: false`, or Webpack).
*/
let mirrorModuleState: ((change: DevModuleStateChange) => void) | undefined
/**
* Drops the validation worker. Called when the dev server cannot repair its own
* module state in place and re-evaluates every module from disk, which the
* worker matches by starting over: the next validation spawns a worker that
* loads the current build output.
*
* A worker dropped on its own, by a failed replay or a crash, is the one case
* where the two can diverge. The dev server keeps the modules it evaluated from
* earlier updates, and a worker spawned afterwards has no way to obtain those
* scripts, so frames naming them stay unresolved until those modules change
* again. The validation itself is unaffected, because the worker loads the
* current code from disk.
*/
let dropWorker: (() => void) | undefined
export function mirrorModuleStateToDevValidationWorker(
change: DevModuleStateChange
): void {
mirrorModuleState?.(change)
}
export function dropDevValidationWorker(): void {
dropWorker?.()
} }
/** /**
...@@ -43,9 +94,46 @@ export function installDevValidationWorker(options: InstallOptions): void { ...@@ -43,9 +94,46 @@ export function installDevValidationWorker(options: InstallOptions): void {
// //
// TODO(dev-validation-worker): raise `numWorkers` if concurrent navigations // TODO(dev-validation-worker): raise `numWorkers` if concurrent navigations
// across independent requests (e.g. multiple tabs) show a validation-latency // across independent requests (e.g. multiple tabs) show a validation-latency
// tail. // tail. Raising it means `mirrorChange` has to reach every worker instead of
// whichever one the pool hands the call to, and the ordering it relies on
// holds per worker rather than across them.
let pool: ValidationPool | undefined let pool: ValidationPool | undefined
const mirrorChange = (change: DevModuleStateChange): void => {
const current = pool
if (!current) {
// No worker to keep current, and nothing to replay into a later one: the
// compilation that produced this change also wrote the updated chunk to
// disk, so a worker spawning after it reads the current code through
// `loadComponents`. Evaluating the update is what an isolate that is
// already running needs, not what a new one does.
return
}
// The worker runs one call at a time, in the order the calls were made
// (see `numWorkers` below), so this is replayed before any validation
// requested after it, and never in the middle of one. That ordering is by
// call time, which is why the call is made here, as the change arrives,
// rather than deferred onto a queue of our own. A validation already
// queued runs first, which is what its render needs: it was produced
// before this change. The dev server does not hold its own updates back
// for a validation running in process either.
const replayed =
change.type === 'invalidate'
? current.invalidateCaches(change.filePaths, change.evictModules)
: current.applyHmrUpdate(change.update).then(async (outcome) => {
if (outcome === 'failed') {
await tearDownPool()
}
})
void replayed.catch(async () => {
// A replay that failed leaves the worker's state unknown, so it is
// dropped rather than trusted.
await tearDownPool()
})
}
const getPool = (): ValidationPool => { const getPool = (): ValidationPool => {
if (pool) { if (pool) {
return pool return pool
...@@ -84,7 +172,11 @@ export function installDevValidationWorker(options: InstallOptions): void { ...@@ -84,7 +172,11 @@ export function installDevValidationWorker(options: InstallOptions): void {
// the module's exports. This worker's top-level imports (`require-hook`, // the module's exports. This worker's top-level imports (`require-hook`,
// `node-environment`) run runtime setup meant only for the isolated // `node-environment`) run runtime setup meant only for the isolated
// worker thread, so they must not be evaluated in the parent. // worker thread, so they must not be evaluated in the parent.
exposedMethods: ['runDevValidation'], exposedMethods: [
'runDevValidation',
'applyHmrUpdate',
'invalidateCaches',
],
forkOptions: { forkOptions: {
env: { env: {
...process.env, ...process.env,
...@@ -169,13 +261,20 @@ export function installDevValidationWorker(options: InstallOptions): void { ...@@ -169,13 +261,20 @@ export function installDevValidationWorker(options: InstallOptions): void {
} }
} }
// The dev server can't reach into the worker to clear its `require.cache` or // The dev server just cleared these paths from its own `require.cache` and
// manifest caches, so we drop the worker whenever the parent's caches are // manifest caches. The worker clears them from its copies.
// invalidated (HMR, route recompile). The next validation lazy-spawns a fresh onCacheInvalidation((filePaths) => {
// worker with empty caches. mirrorChange({
onCacheInvalidation(() => { type: 'invalidate',
void tearDownPool() filePaths,
evictModules: true,
})
}) })
mirrorModuleState = mirrorChange
dropWorker = () => {
void tearDownPool()
}
setDevValidationWorker(runValidation) setDevValidationWorker(runValidation)
} }
...@@ -3,6 +3,7 @@ import type { ...@@ -3,6 +3,7 @@ import type {
DevValidationWorkerMessage, DevValidationWorkerMessage,
DevValidationWorkerResult, DevValidationWorkerResult,
} from '../app-render/dev-validation-worker-globals' } from '../app-render/dev-validation-worker-globals'
import type { NodeJsPartialHmrUpdate } from '../../build/swc/types'
import '../require-hook' import '../require-hook'
import '../node-environment' import '../node-environment'
...@@ -19,6 +20,8 @@ import { ...@@ -19,6 +20,8 @@ import {
import { setHttpClientAndAgentOptions } from '../setup-http-agent-env' import { setHttpClientAndAgentOptions } from '../setup-http-agent-env'
import { serializeValidationErrorsToFlight } from '../app-render/dev-validation-error-delivery' import { serializeValidationErrorsToFlight } from '../app-render/dev-validation-error-delivery'
import { formatValidationEvent } from '../app-render/dev-validation-events' import { formatValidationEvent } from '../app-render/dev-validation-events'
import { clearManifestCache } from '../load-manifest.external'
import { deleteCache } from './require-cache'
import { import {
getServerActionsManifest, getServerActionsManifest,
setManifestsSingleton, setManifestsSingleton,
...@@ -38,11 +41,12 @@ import type { ModernSourceMapPayload } from '../lib/source-maps' ...@@ -38,11 +41,12 @@ import type { ModernSourceMapPayload } from '../lib/source-maps'
* `loadComponents` pulled in. Frames arriving in the transported payload can * `loadComponents` pulled in. Frames arriving in the transported payload can
* point at any chunk the main render touched. * point at any chunk the main render touched.
* *
* This only helps Turbopack, which writes a `.map` beside every chunk. Webpack * Reading from disk covers the chunks, because the worker only runs under
* keeps its dev source maps in the compiler rather than on disk, so its frames * Turbopack (see `next-dev-server.ts`), which writes a `.map` beside every one
* from chunks this thread never evaluated stay unresolved, and its module URLs * of them. A module the server updated in place has no chunk of its own and is
* (`webpack-internal://…`) are declined below for the same reason. Frames from * covered instead by this thread applying the same update (see
* dependencies that are not bundled never reach this point, because * `applyHmrUpdate`), which leaves its inline map in Node.js' cache here. Frames
* from dependencies that are not bundled never reach this point, because
* `filterStackFrameDEV` drops `node_modules` and `node:` frames; bundled * `filterStackFrameDEV` drops `node_modules` and `node:` frames; bundled
* dependencies appear as chunks inside `distDir` like any other code. * dependencies appear as chunks inside `distDir` like any other code.
*/ */
...@@ -71,7 +75,7 @@ function createDiskSourceMapLookup( ...@@ -71,7 +75,7 @@ function createDiskSourceMapLookup(
} }
if (!isAbsolute(chunkPath)) { if (!isAbsolute(chunkPath)) {
// Not an emitted chunk, e.g. `webpack-internal://` or `<anonymous>`. // Not an emitted chunk, e.g. `<anonymous>`.
return undefined return undefined
} }
...@@ -228,6 +232,70 @@ async function registerAdditionalClientReferenceManifests( ...@@ -228,6 +232,70 @@ async function registerAdditionalClientReferenceManifests(
) )
} }
declare const __turbopack_server_hmr_apply__:
| ((update: NodeJsPartialHmrUpdate) => void)
| undefined
/**
* What this thread did with a forwarded HMR update.
*
* `no-runtime` is not a failure: no runtime the update routes to had been
* loaded here, so there was nothing to patch, and whatever loads that route
* later reads the updated chunk from disk.
*/
export type HmrApplyOutcome = 'applied' | 'no-runtime' | 'failed'
/**
* Applies a server HMR update to this thread's module registry, mirroring the
* apply the dev server performed on its own.
*
* Turbopack's Node.js runtime registers the apply machinery per isolate (see
* `dev-nodejs.ts`), and `loadComponents` evaluates that runtime here, so this
* thread patches the same modules the dev server does. The apply also leaves
* the updated module's inline source map in this thread's Node.js cache, which
* is what makes a stack frame in that module source-mappable here.
*/
export async function applyHmrUpdate(
update: NodeJsPartialHmrUpdate
): Promise<HmrApplyOutcome> {
if (typeof __turbopack_server_hmr_apply__ !== 'function') {
return 'no-runtime'
}
try {
__turbopack_server_hmr_apply__(update)
} catch {
// The dev server responds to the same failure by re-evaluating every
// module from disk. This thread cannot be repaired in place either, so the
// caller drops it.
return 'failed'
}
return 'applied'
}
/**
* Clears the same caches the dev server cleared, for the same paths.
*
* `evictModules` follows the dev server's own split: an applied update patches
* modules in place and clears only the manifest cache for the updated chunks,
* while a recompile evicts `require.cache` as well. This thread follows both,
* so its module state stays the dev server's module state.
*/
export async function invalidateCaches(
filePaths: string[],
evictModules: boolean
): Promise<void> {
if (evictModules) {
deleteCache(filePaths)
return
}
for (const filePath of filePaths) {
clearManifestCache(filePath)
}
}
/** /**
* Runs the dev instant/static-shell validation passes off the main thread. * Runs the dev instant/static-shell validation passes off the main thread.
* Reloads the route's compiled module, then delegates the whole validation to * Reloads the route's compiled module, then delegates the whole validation to
......
...@@ -40,6 +40,10 @@ import { PageNotFoundError } from '../../shared/lib/utils' ...@@ -40,6 +40,10 @@ import { PageNotFoundError } from '../../shared/lib/utils'
import { debounce } from '../utils' import { debounce } from '../utils'
import { clearManifestCache } from '../load-manifest.external' import { clearManifestCache } from '../load-manifest.external'
import { deleteCache } from './require-cache' import { deleteCache } from './require-cache'
import {
dropDevValidationWorker,
mirrorModuleStateToDevValidationWorker,
} from './dev-validation-worker-pool'
import { import {
clearAllModuleContexts, clearAllModuleContexts,
clearModuleContext, clearModuleContext,
...@@ -261,6 +265,9 @@ function setupServerHmr( ...@@ -261,6 +265,9 @@ function setupServerHmr(
if (typeof __turbopack_server_hmr_apply__ === 'function') { if (typeof __turbopack_server_hmr_apply__ === 'function') {
try { try {
__turbopack_server_hmr_apply__(update) __turbopack_server_hmr_apply__(update)
// The validation worker keeps its own copy of the module graph, and
// applies the same update to it.
mirrorModuleStateToDevValidationWorker({ type: 'apply', update })
} catch { } catch {
// A matching runtime tried the apply and threw. Evict require.cache // A matching runtime tried the apply and threw. Evict require.cache
// so the next request loads fresh, then skip onApplied. (A no-match // so the next request loads fresh, then skip onApplied. (A no-match
...@@ -2142,6 +2149,11 @@ export async function createHotReloaderTurbopack( ...@@ -2142,6 +2149,11 @@ export async function createHotReloaderTurbopack(
resetFetch() resetFetch()
// This thread gave up on repairing its module graph in place. The
// validation worker cannot repair its own either, so it is dropped and
// the next validation loads the build output afresh.
dropDevValidationWorker()
notifyServerComponentChanges() notifyServerComponentChanges()
}, },
onApplied: (chunkPaths: string[]) => { onApplied: (chunkPaths: string[]) => {
...@@ -2149,10 +2161,23 @@ export async function createHotReloaderTurbopack( ...@@ -2149,10 +2161,23 @@ export async function createHotReloaderTurbopack(
// next RSC render picks up the HMR-applied module changes. Unlike // next RSC render picks up the HMR-applied module changes. Unlike
// a full restart, this does NOT clear require.cache — the HMR-applied // a full restart, this does NOT clear require.cache — the HMR-applied
// modules in devModuleCache must persist for dep preservation. // modules in devModuleCache must persist for dep preservation.
for (const chunkPath of chunkPaths) { const manifestPaths = chunkPaths.map((chunkPath) =>
clearManifestCache(join(distDir, chunkPath)) join(distDir, chunkPath)
)
for (const manifestPath of manifestPaths) {
clearManifestCache(manifestPath)
} }
// This path clears the manifest cache without going through
// `deleteCache`, so `onCacheInvalidation` does not report it to the
// validation worker. Report it here instead.
mirrorModuleStateToDevValidationWorker({
type: 'invalidate',
filePaths: manifestPaths,
evictModules: false,
})
notifyServerComponentChanges() notifyServerComponentChanges()
}, },
}) })
......
export default function NeighborPage() {
return <p>neighbor</p>
}
import { readValue } from './read-value'
export default async function SharedPage() {
return <p>{await readValue()}</p>
}
// import { connection } from 'next/server'
export async function readValue(): Promise<string> {
// The test uncomments the line below, and the import above, while the dev
// server runs, so the update lands in a module the page imports.
// await connection()
return 'shared'
}
export default async function UpdatedPage() {
// The test uncomments the line below while the dev server is running, so the
// module is updated in place after the route has already been loaded.
// await new Promise((resolve) => setTimeout(resolve, 0))
return <p>updated</p>
}
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