Unverified Commit 3c4afc1a authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Run Cache Components dev validation on a worker thread (#96153)

This moves the dev-mode Cache Components validation renders off the dev
server's main thread onto a worker thread, so rapid navigation no longer
starves the event loop. The worker crosses into the app-page bundle
exactly once, calling a new
`ComponentMod.routeModule.runValidationInDev` entry that rebuilds the
render context, work store, and request store from a serializable
snapshot and runs the whole validation there, so the client prerender
and the user's client components resolve the single app-page React
instance rather than a second copy.

A thin worker shell (`dev-validation-worker.ts`) plus a single-worker
pool (`dev-validation-worker-pool.ts`) load the user bundle via
`loadComponents`, install code-frame support for CLI output, and forward
the validation errors back as Flight bytes; the main thread only
delivers them to the overlay through `sendErrorsToBrowser`. The
snapshot, the globalThis-symbol handoff, and the shared error-delivery
helpers live in their own modules. The dev server installs the worker
when `experimental.devValidationWorker` is not `false`, and
`runDevValidationInBackground` uses it when present, falling back to the
in-process path otherwise. A one-slot `SharedArrayBuffer` propagates a
supersede abort into the worker so a newer navigation cancels an
in-flight validation.

The runtime bundle gains an `app-worker` entry for the worker with the
`build/swc` boundary externalized for the code-frame native binding, and
`patch-error-inspect.ts` now backs its code-frame renderer with a
globalThis symbol so all copies of the module share it across the
thread.

The synthetic `bench/dev-validation` benchmark navigates back-to-back,
so every click lands inside the validation window — the worst case for
main-thread contention. Browser-observed navigation TTFB in that window,
worker vs in-process:

| Route  | Worker (p50/p95/max) | In-process (p50/p95/max) |
| ------ | -------------------- | ------------------------ |
| client | 19 / 24 / 27 ms      | 40 / 66 / 7762 ms        |
| server | 42 / 45 / 46 ms      | 122 / 158 / 252 ms       |
| sprite | 109 / 117 / 169 ms   | 196 / 208 / 299 ms       |

The steady-state difference is only tens of milliseconds; the effect
that matters is the tail. In-process, a navigation that collides with an
in-flight validation render can stall for seconds (this run peaked at
~7.8s on the client route, and the peak varies run to run) because a
staged render does not yield until it finishes; off-thread the main
thread stays free and that stall disappears.

Read these as an upper bound, not a speedup that generalizes. The work
moved off-thread is the validation render's CPU — bounded,
route-dependent, and free of IO — so it does not grow with the main
render's cost. In an app whose main render is dominated by IO the same
absolute saving is a small fraction of the request, and it only appears
when a navigation lands in the brief validation window; at ordinary
click speed it is largely invisible. This is a dev-only responsiveness
improvement whose benefit varies widely with the app and the navigation
pattern.

As a follow-up, the validation work that still runs on the main thread
could move to the worker as well. When the main render can't be reused
for validation (for example after a cache miss), the validation
re-renders on the main thread to produce its inputs, resuming from the
Resume Data Cache (RDC) the main render already filled, and only then
hands the resulting Flight chunks to the worker. A later iteration could
run those renders inside the worker too, transporting the (serializable)
RDC so the worker can resume from the filled caches rather than reading
them back on the main thread.

closes NAR-895
parent 59cc6420
......@@ -116,6 +116,10 @@ const bundleTypes = {
__dirname,
'dist/esm/server/dev/use-cache-probe-worker.js'
),
'dev-validation-worker': path.join(
__dirname,
'dist/esm/server/dev/dev-validation-worker.js'
),
},
}
......@@ -145,6 +149,28 @@ module.exports = ({ dev, turbo, bundleType, experimental, ...rest }) => {
return
}
// The dev validation worker calls `installBindings()` /
// `installCodeFrameSupport()` so its logged errors render source-mapped
// code frames. Those pull in the native SWC binding graph (`build/swc` →
// `trace` → `telemetry`), which isn't present under `dist/esm`. Resolve
// it from the installed `next/dist` tree at runtime instead of bundling
// it into the worker, exactly as the unbundled build worker loads it.
// Scoped to the `app-worker` bundle; the probe worker in the same group
// doesn't import it.
if (
bundleType === 'app-worker' &&
request.match(/[\\/]build[\\/]swc(?:[\\/]install-bindings)?(?:\.js)?$/)
) {
const resolve = getResolve()
const resolved = await resolve(context, request)
const relative = path.relative(
path.join(__dirname, '..'),
resolved.replace('esm' + path.sep, '')
)
callback(null, `commonjs ${relative}`)
return
}
if (request.match(/\.external(\.js)?$/)) {
const resolve = getResolve()
const resolved = await resolve(context, request)
......
import type { AppPageModule } from '../route-modules/app-page/module'
import { renderToNodeFlightStream } from './stream-ops'
import { getClientReferenceManifest } from './manifests-singleton'
import { extractNextErrorCode } from '../../lib/error-telemetry-utils'
const filterStackFrame =
process.env.NODE_ENV !== 'production'
? (require('../lib/source-maps') as typeof import('../lib/source-maps'))
.filterStackFrameDEV
: undefined
/**
* Encodes dev-validation errors into the RSC Flight bytes the dev overlay
* revives. Must run in the runtime that produced the errors (the in-process
* render or the validation worker) so the encode uses the matching
* client-reference manifest and captures the live `Error` objects with their
* stacks and digests. The error codes ride along in a side-channel `Map`
* because React doesn't revive `__NEXT_ERROR_CODE` during RSC deserialization;
* RSC preserves object identity, so the revived map keys reference the same
* errors.
*/
export async function serializeValidationErrorsToFlight(
componentMod: AppPageModule,
errors: Error[]
): Promise<Uint8Array[]> {
const errorCodes = new Map<Error, string>()
for (const err of errors) {
const code = extractNextErrorCode(err)
if (code !== undefined) {
errorCodes.set(err, code)
}
}
const { clientModules } = getClientReferenceManifest()
const stream = renderToNodeFlightStream(
componentMod,
{ errors, errorCodes },
clientModules,
{ filterStackFrame }
)
const chunks: Uint8Array[] = []
for await (const chunk of stream) {
chunks.push(chunk)
}
return chunks
}
import type { Params } from '../request/params'
import type { OpaqueFallbackRouteParamEntries } from '../request/fallback-params'
import type { NextParsedUrlQuery } from '../request-meta'
import type { PrefetchingMode } from './app-render'
import type { NextConfigComplete, ValidationLevel } from '../config-shared'
import type { ImageConfigComplete } from '../../shared/lib/image-config'
/**
* Cross-module handoff for the dev validation worker (client-module warmup,
* static-shell validation, and instant-config validation all run on it). A
* symbol on `globalThis` decouples the dev-server entry point (which installs
* the jest-worker pool) from the read site in `runDevValidationInBackground`
* inside `app-render.tsx`, avoiding a direct import of dev-only pool code from
* the render module. When the symbol is not set (e.g. because the feature flag
* is disabled), `getDevValidationWorker()` returns undefined and the caller
* runs validation in process instead.
*/
const SYMBOL: unique symbol = Symbol.for('next.dev.validationWorker')
/**
* Per-stage RSC chunks, the serializable form of `AccumulatedStreamChunks` that
* the worker replays. No live streams cross the boundary.
*/
export interface SerializedAccumulatedChunks {
shellStaticChunks: Uint8Array[]
staticChunks: Uint8Array[]
shellRuntimeChunks: Uint8Array[]
runtimeChunks: Uint8Array[]
dynamicChunks: Uint8Array[]
}
/**
* Serializable view of one validation input (the shape `DevValidationInputs`
* carries), with the live streams already drained to chunks. The stage-end
* timings are replayed into the per-depth Flight re-encodes so the worker
* reconstructs the same partial-stage boundaries the main render observed.
*/
export interface SerializedValidationInputs {
accumulatedChunks: SerializedAccumulatedChunks
debugChunks: Uint8Array[] | null
startTime: number
staticStageEndTime: number
runtimeStageEndTime: number
}
/**
* Serializable view of the request, rebuilt into a `RequestStore` on the worker
* so `cookies()` / `headers()` / `draftMode()` behave as in the real render.
*/
export interface DevValidationRequestSnapshot {
headers: [string, string][]
urlPathname: string
urlSearch: string
rootParams: Params
isDraftMode: boolean
isHmrRefresh: boolean
hmrRefreshHash: string | undefined
}
/**
* Everything the worker needs to rebuild the render context and inputs and run
* `runValidationInDev`. Built on the main thread from the settled render; the
* pool augments it with install-time fields (`distDir`, `buildId`, …).
*/
export interface DevValidationSnapshot {
page: string
route: string
requestId: string
responseFinished: boolean
prefetchMode: PrefetchingMode
devRenderDidError: boolean
nonce: string | undefined
query: NextParsedUrlQuery
request: DevValidationRequestSnapshot
// The interpolated route params, the routing seed the worker rebuilds
// `getDynamicParamFromSegment` from (together with the fallback params
// below).
interpolatedParams: Params
// The request's fallback params, the set `ctx.getDynamicParamFromSegment`
// closed over. The worker rebuilds `getDynamicParamFromSegment` from these
// (with `interpolatedParams` and `optimisticRouting`), so the depth-loop
// segment keys match the seed render's Flight. It is null for a request whose
// params all resolve to concrete values. Carried as map entries (like
// `fallbackRouteParams`) so both survive structured-clone transport.
requestFallbackRouteParams: OpaqueFallbackRouteParamEntries | null
// The validation fallback params, passed to `runValidationInDev` and its
// prerender stores. They mark params unknown so that accessing one during the
// simulated prefetch is treated as dynamic. This set may include params that
// `requestFallbackRouteParams` does not.
fallbackRouteParams: OpaqueFallbackRouteParamEntries | null
optimisticRouting: boolean
forceStatic: boolean | undefined
validationLevel: ValidationLevel
implicitTags: string[]
/**
* Pages whose client reference manifests supplied client references to the
* render being validated, beyond the validated route's own manifest (see
* `WorkStore.additionalClientReferenceManifestPages`). The worker registers
* these so the same references resolve in its thread. Empty for all but the
* rare renders that React's I/O tracking carries a reference into.
*/
additionalClientReferenceManifestPages: string[]
isDebugChannelEnabled: boolean
renderOpts: {
images: ImageConfigComplete
allowEmptyStaticShell: boolean | undefined
}
instantInputs: SerializedValidationInputs | null
staticInputs: SerializedValidationInputs
}
/**
* Install-time fields the dev server's worker pool augments the snapshot with
* so the worker can reload the route (`distDir`; `page` comes from the
* snapshot) and rebuild the work store (`buildId`, `deploymentId`, the config
* slice).
*/
export interface DevValidationInstallFields {
distDir: string
buildId: string
deploymentId: string
nextConfigSerializable: {
httpAgentOptions: NextConfigComplete['httpAgentOptions']
cacheLifeProfiles: NextConfigComplete['cacheLife']
useCacheTimeout: number
staticPageGenerationTimeout: number
}
}
/**
* The full message the worker receives and forwards into the in-bundle entry:
* the main-thread snapshot plus the pool's install-time fields.
*/
export type DevValidationWorkerMessage = DevValidationSnapshot &
DevValidationInstallFields
/**
* The RSC-encoded `{ errors, errorCodes }` Flight chunks for the dev overlay,
* or null when validation produced no errors or was aborted. The worker also
* logs the errors to its own stderr (piped to the parent) with code frames.
*/
export type DevValidationWorkerResult = Uint8Array[] | null
/**
* Worker hook installed by the dev server. Given the render snapshot and the
* validation abort signal, runs validation on a worker thread and resolves to
* the validation error Flight chunks to deliver on the main thread. On an abort
* the pool relays the aborted signal to the worker thread through a shared
* flag, so the in-flight run aborts mid-run; validation always runs as a thread
* (never a child process), which is what makes that cross-thread abort
* possible.
*/
export type DevValidationWorker = (
snapshot: DevValidationSnapshot,
validationAbortSignal: AbortSignal
) => Promise<DevValidationWorkerResult>
interface WorkerHolder {
[SYMBOL]?: DevValidationWorker
}
export function setDevValidationWorker(
fn: DevValidationWorker | undefined
): void {
;(globalThis as WorkerHolder)[SYMBOL] = fn
}
export function getDevValidationWorker(): DevValidationWorker | undefined {
return (globalThis as WorkerHolder)[SYMBOL]
}
import type { AppRenderContext, ResolvedValidationInputs } from './app-render'
import type { PrefetchingMode } from './app-render'
import type { OpaqueFallbackRouteParams } from '../request/fallback-params'
import type { AnyStream } from './stream-ops'
import type {
DevValidationSnapshot,
SerializedValidationInputs,
} from './dev-validation-worker-globals'
import { isNodeNextResponse } from '../base-http/helpers'
/**
* Builds the serializable snapshot the dev validation worker needs to rebuild
* the render context and inputs and run `runValidationInDev` on the worker
* thread. Reads only serializable data from the settled render; the live
* objects (`componentMod`, the async-storage stores,
* `getDynamicParamFromSegment`) are reconstructed on the worker from this seed.
* Draining the debug channels is async, so this returns a promise.
*/
export async function buildDevValidationSnapshot(
ctx: AppRenderContext,
instantInputs: ResolvedValidationInputs | null,
staticInputs: ResolvedValidationInputs,
prefetchMode: PrefetchingMode,
fallbackRouteParams: OpaqueFallbackRouteParams | null,
devRenderDidError: boolean
): Promise<DevValidationSnapshot> {
const requestStore = staticInputs.requestStore
const responseFinished =
!isNodeNextResponse(ctx.res) || ctx.res.originalResponse.writableFinished
// The instant and static inputs may share one debug channel, so drain each
// channel only once.
const chunksByChannel = new WeakMap<AnyStream, Uint8Array[]>()
const getDebugChunksOnce = async (
channel: AnyStream | undefined
): Promise<Uint8Array[] | null> => {
if (!channel) {
return null
}
let chunks = chunksByChannel.get(channel)
if (!chunks) {
chunks = []
for await (const chunk of channel) {
chunks.push(chunk)
}
chunksByChannel.set(channel, chunks)
}
return chunks
}
const toSerializedInputs = async (
inputs: ResolvedValidationInputs
): Promise<SerializedValidationInputs> => ({
accumulatedChunks: inputs.accumulatedChunks,
debugChunks: await getDebugChunksOnce(inputs.debugChannelClient),
startTime: inputs.startTime,
staticStageEndTime: inputs.staticStageEndTime,
runtimeStageEndTime: inputs.runtimeStageEndTime,
})
return {
page: ctx.workStore.page,
route: ctx.workStore.route,
requestId: ctx.requestId,
responseFinished,
prefetchMode,
devRenderDidError,
nonce: ctx.nonce,
query: ctx.query,
request: {
headers: [...requestStore.headers.entries()],
urlPathname: requestStore.url.pathname,
urlSearch: requestStore.url.search,
rootParams: requestStore.rootParams,
isDraftMode: requestStore.draftMode.isEnabled,
isHmrRefresh: requestStore.isHmrRefresh ?? false,
hmrRefreshHash: requestStore.hmrRefreshHash,
},
interpolatedParams: ctx.interpolatedParams,
requestFallbackRouteParams: ctx.fallbackRouteParams
? [...ctx.fallbackRouteParams.entries()]
: null,
fallbackRouteParams: fallbackRouteParams
? [...fallbackRouteParams.entries()]
: null,
optimisticRouting: ctx.renderOpts.experimental.optimisticRouting,
forceStatic: ctx.workStore.forceStatic,
validationLevel: ctx.workStore.validationLevel,
implicitTags: ctx.implicitTags.tags,
additionalClientReferenceManifestPages: ctx.workStore
.additionalClientReferenceManifestPages
? [...ctx.workStore.additionalClientReferenceManifestPages]
: [],
isDebugChannelEnabled: !!ctx.renderOpts.setReactDebugChannel,
renderOpts: {
images: ctx.renderOpts.images,
allowEmptyStaticShell: ctx.renderOpts.allowEmptyStaticShell,
},
instantInputs: instantInputs
? await toSerializedInputs(instantInputs)
: null,
staticInputs: await toSerializedInputs(staticInputs),
}
}
......@@ -54,10 +54,21 @@ const TRUNCATED_SERVER_REFERENCE_ID_LENGTH = 90
// AsyncLocalStorage as it might happen at the module level.
const MANIFESTS_SINGLETON = Symbol.for('next.server.manifests')
interface RegisteredClientReferenceManifest {
/**
* The page the manifest was registered with. Routes are normalized app paths,
* which is lossy (route groups, parallel slots and the trailing `/page` are
* stripped), so this is kept alongside for consumers that need to address the
* manifest on disk again rather than reversing the normalization.
*/
readonly page: string
readonly clientReferenceManifest: DeepReadonly<ClientReferenceManifest>
}
interface ManifestsSingleton {
readonly clientReferenceManifestsPerRoute: Map<
string,
DeepReadonly<ClientReferenceManifest>
RegisteredClientReferenceManifest
>
readonly proxiedClientReferenceManifest: DeepReadonly<ClientReferenceManifest>
serverActionsManifest: DeepReadonly<ActionManifest>
......@@ -80,7 +91,7 @@ const globalThisWithManifests = globalThis as GlobalThisWithManifests
function createProxiedClientReferenceManifest(
clientReferenceManifestsPerRoute: Map<
string,
DeepReadonly<ClientReferenceManifest>
RegisteredClientReferenceManifest
>
): DeepReadonly<ClientReferenceManifest> {
const createMappingProxy = (prop: ClientReferenceManifestMappingProp) => {
......@@ -93,7 +104,7 @@ function createProxiedClientReferenceManifest(
if (workStore) {
const currentManifest = clientReferenceManifestsPerRoute.get(
workStore.route
)
)?.clientReferenceManifest
if (currentManifest?.[prop][id]) {
return currentManifest[prop][id]
......@@ -112,15 +123,24 @@ function createProxiedClientReferenceManifest(
if (process.env.NODE_ENV !== 'production') {
for (const [
route,
manifest,
{ page, clientReferenceManifest },
] of clientReferenceManifestsPerRoute) {
if (route === workStore.route) {
continue
}
const entry = manifest[prop][id]
const entry = clientReferenceManifest[prop][id]
if (entry !== undefined) {
if (process.env.__NEXT_DEV_SERVER) {
// The dev validation worker rebuilds this registry in its
// own thread, seeded with only the route it validates, so
// it has to be told which other manifests it needs.
workStore.additionalClientReferenceManifestPages ??=
new Set()
workStore.additionalClientReferenceManifestPages.add(page)
}
return entry
}
}
......@@ -132,8 +152,10 @@ function createProxiedClientReferenceManifest(
// might also use client components which need to be serialized by
// Flight, and therefore client references need to be resolvable. In
// that case we search all page manifests to find the module.
for (const manifest of clientReferenceManifestsPerRoute.values()) {
const entry = manifest[prop][id]
for (const {
clientReferenceManifest,
} of clientReferenceManifestsPerRoute.values()) {
const entry = clientReferenceManifest[prop][id]
if (entry !== undefined) {
return entry
......@@ -168,17 +190,17 @@ function createProxiedClientReferenceManifest(
)
}
const currentManifest = clientReferenceManifestsPerRoute.get(
const registeredManifest = clientReferenceManifestsPerRoute.get(
workStore.route
)
if (!currentManifest) {
if (!registeredManifest) {
throw new InvariantError(
`The client reference manifest for route "${workStore.route}" does not exist.`
)
}
return currentManifest[prop]
return registeredManifest.clientReferenceManifest[prop]
}
case 'clientModules':
case 'rscModuleMapping':
......@@ -323,6 +345,7 @@ export function setManifestsSingleton({
serverActionsManifest: DeepReadonly<ActionManifest>
}) {
const existingSingleton = globalThisWithManifests[MANIFESTS_SINGLETON]
const route = normalizeAppPath(page)
const serverActionsManifest: DeepReadonly<ActionManifest> = {
encryptionKey: rawServerActionsManifest.encryptionKey,
......@@ -333,17 +356,17 @@ export function setManifestsSingleton({
}
if (existingSingleton) {
existingSingleton.clientReferenceManifestsPerRoute.set(
normalizeAppPath(page),
clientReferenceManifest
)
existingSingleton.clientReferenceManifestsPerRoute.set(route, {
page,
clientReferenceManifest,
})
existingSingleton.serverActionsManifest = serverActionsManifest
} else {
const clientReferenceManifestsPerRoute = new Map<
string,
DeepReadonly<ClientReferenceManifest>
>([[normalizeAppPath(page), clientReferenceManifest]])
RegisteredClientReferenceManifest
>([[route, { page, clientReferenceManifest }]])
const proxiedClientReferenceManifest = createProxiedClientReferenceManifest(
clientReferenceManifestsPerRoute
......
......@@ -143,6 +143,17 @@ export interface WorkStore {
cacheComponentsEnabled: boolean
validationLevel: ValidationLevel
/**
* Pages, other than the one being rendered, whose client reference manifest
* supplied a client reference for this render. Only populated by the dev
* server, where React's I/O tracking can carry a reference from another page
* into this render, which `createProxiedClientReferenceManifest` resolves by
* searching the other pages' manifests. The dev validation worker rebuilds
* that registry in its own thread from the route it validates, so it relies
* on this to know which other manifests to register.
*/
additionalClientReferenceManifestPages?: Set<string>
/**
* Run the given function inside a clean AsyncLocalStorage snapshot. This is
* useful when generating cache entries, to ensure that the cache generation
......
import type { NextConfigComplete } from '../config-shared'
import type { runDevValidation } from './dev-validation-worker'
import type {
DevValidationSnapshot,
DevValidationWorkerMessage,
DevValidationWorkerResult,
} from '../app-render/dev-validation-worker-globals'
import { Worker } from 'next/dist/compiled/jest-worker'
import { setDevValidationWorker } from '../app-render/dev-validation-worker-globals'
import { onCacheInvalidation } from './require-cache'
import { getFormattedNodeOptionsWithoutInspect } from '../lib/utils'
import { needsExperimentalReact } from '../../lib/needs-experimental-react'
interface InstallOptions {
distDir: string
buildId: string
deploymentId: string
nextConfig: NextConfigComplete
}
type ValidationPool = { [key: string]: any } & {
runDevValidation: typeof runDevValidation
}
/**
* Wire up the dev-server's validation worker: register the HMR teardown
* listener and install the hook that `runDevValidationInBackground` calls once
* a render has settled. The worker thread is spawned lazily, so nothing is
* created until the first navigation actually validates.
*/
export function installDevValidationWorker(options: InstallOptions): void {
const { distDir, buildId, deploymentId, nextConfig } = options
// A single worker, not a pool. Validation for one navigation runs its depth
// loop sequentially, and a newer navigation supersedes the previous one
// (aborting it mid-run) rather than running concurrently, so there's no
// per-request fan-out to parallelize (unlike the `'use cache'` probe, where
// one request fans out into concurrent probes). One worker already frees the
// main thread, which is the whole point; it also keeps each request's CLI
// marker block contiguous in the piped output. Torn down on HMR (stale user
// modules) and on crash.
//
// TODO(dev-validation-worker): raise `numWorkers` if concurrent navigations
// across independent requests (e.g. multiple tabs) show a validation-latency
// tail.
let pool: ValidationPool | undefined
const getPool = (): ValidationPool => {
if (pool) {
return pool
}
// Strip `--inspect` from any inherited `NODE_OPTIONS` so the worker doesn't
// fight the parent for the same debug port.
const workerNodeOptions = getFormattedNodeOptionsWithoutInspect()
// The worker is shipped as four pre-bundled dev-only artifacts
// ({webpack,turbopack} × {stable,experimental}), one per combination of the
// user's bundler and vendored React channel. Pick the matching artifact
// from runtime env so the worker stays in lockstep with the user's app
// bundle. `needsExperimentalReact` is the same predicate `define-env.ts`
// uses to wire `__NEXT_EXPERIMENTAL_REACT`.
const turbo = process.env.TURBOPACK ? '-turbo' : ''
const channel = needsExperimentalReact(nextConfig) ? '-experimental' : ''
const workerPath = require.resolve(
`next/dist/compiled/next-server/dev-validation-worker${turbo}${channel}.runtime.dev.js`
)
const worker = new Worker(workerPath, {
maxRetries: 0,
numWorkers: 1,
// Always worker-threads, regardless of `experimental.workerThreads`.
// Unlike the `'use cache'` probe (which follows the flag), validation has
// no reason to prefer a child process: it doesn't need process-level
// isolation (a worker thread already has its own V8 heap and module
// registry, so the reloaded route is isolated from the main thread), and
// threads let a superseded validation be aborted mid-run through a shared
// `SharedArrayBuffer`, which a separate process can't receive. Threads
// also carry the transported Flight bytes as typed arrays via structured
// clone, with no JSON round-trip to corrupt them.
enableWorkerThreads: true,
// Listing the method explicitly tells jest-worker to skip the discovery
// `require()` it would otherwise do in the parent process to enumerate
// the module's exports. This worker's top-level imports (`require-hook`,
// `node-environment`) run runtime setup meant only for the isolated
// worker thread, so they must not be evaluated in the parent.
exposedMethods: ['runDevValidation'],
forkOptions: {
env: {
...process.env,
NODE_OPTIONS: workerNodeOptions,
},
},
}) as Worker & ValidationPool
worker.getStdout().pipe(process.stdout)
worker.getStderr().pipe(process.stderr)
pool = worker
return worker
}
const tearDownPool = async (): Promise<void> => {
const current = pool
if (!current) {
return
}
pool = undefined
await current.end().catch(() => {
// The worker thread exits on its own once its work settles; a failed
// `.end()` here just means we couldn't wait for it cleanly.
})
}
const runValidation = async (
snapshot: DevValidationSnapshot,
validationAbortSignal: AbortSignal
): Promise<DevValidationWorkerResult> => {
let activePool: ValidationPool
try {
activePool = getPool()
} catch {
return null
}
const message: DevValidationWorkerMessage = {
...snapshot,
distDir,
buildId,
deploymentId,
nextConfigSerializable: {
httpAgentOptions: nextConfig.httpAgentOptions,
cacheLifeProfiles: nextConfig.cacheLife,
useCacheTimeout: nextConfig.experimental.useCacheTimeout,
staticPageGenerationTimeout: nextConfig.staticPageGenerationTimeout,
},
}
// The worker runs as a thread (see `enableWorkerThreads` above), so an
// abort reaches it through a one-slot shared flag rather than the abort
// signal directly (a signal can't cross the thread boundary). Mirror an
// abort of `validationAbortSignal` into the buffer and wake the worker's
// `Atomics.waitAsync` on it, so it aborts the in-flight run at its next
// depth boundary.
const abortBuffer = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT)
const abortFlag = new Int32Array(abortBuffer)
const propagateAbort = () => {
Atomics.store(abortFlag, 0, 1)
Atomics.notify(abortFlag, 0)
}
if (validationAbortSignal.aborted) {
propagateAbort()
} else {
validationAbortSignal.addEventListener('abort', propagateAbort, {
once: true,
})
}
try {
return await activePool.runDevValidation(message, abortBuffer)
} catch {
// Worker crash or IPC error: tear down so the next validation starts
// fresh. The main thread treats a missing result as "nothing to deliver."
await tearDownPool()
return null
} finally {
// `once` only auto-removes the listener if it fired, so remove it
// explicitly to bound its lifetime to this run when validation completed
// without being superseded.
validationAbortSignal.removeEventListener('abort', propagateAbort)
}
}
// The dev server can't reach into the worker to clear its `require.cache` or
// manifest caches, so we drop the worker whenever the parent's caches are
// invalidated (HMR, route recompile). The next validation lazy-spawns a fresh
// worker with empty caches.
onCacheInvalidation(() => {
void tearDownPool()
})
setDevValidationWorker(runValidation)
}
import type { AppPageModule } from '../route-modules/app-page/module'
import type {
DevValidationWorkerMessage,
DevValidationWorkerResult,
} from '../app-render/dev-validation-worker-globals'
import '../require-hook'
import '../node-environment'
import { installBindings } from '../../build/swc/install-bindings'
import { installCodeFrameSupport } from '../lib/install-code-frame'
import {
loadClientReferenceManifestForPage,
loadComponents,
} from '../load-components'
import { setHttpClientAndAgentOptions } from '../setup-http-agent-env'
import { serializeValidationErrorsToFlight } from '../app-render/dev-validation-error-delivery'
import { formatValidationEvent } from '../app-render/dev-validation-events'
import {
getServerActionsManifest,
setManifestsSingleton,
} from '../app-render/manifests-singleton'
// Match the main dev server (`next-dev-server.ts`), which raises this so the
// server captures deeper stacks. React's owner-stack capture during the
// validation prerenders depends on it, so without it the worker's errors lose
// their owner-stack source attribution.
try {
Error.stackTraceLimit = 50
} catch {}
// The lifecycle markers E2E tests read from the CLI. Emitted on the worker's
// stdout (piped to the parent) so they interleave with the parent's captured
// output the same way the in-process `runWithDevValidationLogging` markers do.
// Gated on the same test env that path checks.
const isTestLoggingEnabled = !!(
process.env.__NEXT_TEST_MODE && process.env.NEXT_TEST_LOG_VALIDATION
)
/**
* Adapts the pool's supersede flag into an `AbortSignal` the validation passes
* check at their depth/yield boundaries. The pool shares an `Int32Array`-backed
* `SharedArrayBuffer` whose first slot the main thread flips to non-zero (with
* `Atomics.store` + `Atomics.notify`) when a newer navigation supersedes this
* one. We wait for that notification with `Atomics.waitAsync`, which is
* event-driven rather than polled. A validation that finishes without being
* superseded calls `cleanup()`, which wakes our own still-pending wait so it
* leaves no waiter (and no retained buffer) behind.
*/
function createSupersedeSignal(abortBuffer: SharedArrayBuffer): {
signal: AbortSignal
cleanup: () => void
} {
const controller = new AbortController()
const flag = new Int32Array(abortBuffer)
if (Atomics.load(flag, 0) !== 0) {
controller.abort()
return { signal: controller.signal, cleanup: () => {} }
}
let settled = false
const wait = Atomics.waitAsync(flag, 0, 0)
if (wait.async) {
wait.value.then(() => {
if (settled) {
return
}
settled = true
// Woken either by a real supersede or by `cleanup()`; only the former
// leaves the flag set.
if (Atomics.load(flag, 0) !== 0) {
controller.abort()
}
})
} else if (Atomics.load(flag, 0) !== 0) {
// The flag flipped between the load above and the wait.
controller.abort()
}
return {
signal: controller.signal,
cleanup: () => {
if (!settled) {
Atomics.notify(flag, 0)
}
},
}
}
/**
* Waits out the test-only validation delay, resolving early if the render is
* superseded. Mirrors the delay in `runWithDevValidationLogging` so scheduler
* tests observe the same in-flight window on the worker path.
*/
async function applyTestValidationDelay(signal: AbortSignal): Promise<void> {
const delayMs = Number(process.env.NEXT_TEST_DEV_VALIDATION_DELAY_MS)
if (!Number.isFinite(delayMs) || delayMs <= 0 || signal.aborted) {
return
}
await new Promise<void>((resolve) => {
const finishDelay = () => {
clearTimeout(timeout)
signal.removeEventListener('abort', finishDelay)
resolve()
}
const timeout = setTimeout(finishDelay, delayMs)
signal.addEventListener('abort', finishDelay, { once: true })
})
}
/**
* Registers the client reference manifests of the pages that supplied client
* references to the render being validated, beyond the validated route's own
* manifest. This thread has its own manifests singleton, which `loadComponents`
* seeds with only the validated route, so without these the dev-only cross-page
* lookup in `createProxiedClientReferenceManifest` has no other manifest to
* search and decoding the transported payload fails. Usually a no-op, since the
* main thread only records a page when React's I/O tracking actually carried a
* reference across pages.
*/
async function registerAdditionalClientReferenceManifests(
distDir: string,
pages: string[]
): Promise<void> {
if (pages.length === 0) {
return
}
// Set by `loadComponents`. One server actions manifest covers the whole app,
// so the pages registered here share the validated route's.
const serverActionsManifest = getServerActionsManifest()
await Promise.all(
pages.map(async (page) => {
const clientReferenceManifest = await loadClientReferenceManifestForPage(
distDir,
page
)
if (clientReferenceManifest) {
setManifestsSingleton({
page,
clientReferenceManifest,
serverActionsManifest,
})
}
})
)
}
/**
* Runs the dev instant/static-shell validation passes off the main thread.
* Reloads the route's compiled module, then delegates the whole validation to
* that module via `ComponentMod.routeModule.runValidationInDev`, so every
* render (flight re-encodes and client prerenders) runs inside the app-page
* bundle's single React instance. Logs any returned errors to the worker's
* stderr with source-mapped code frames, then encodes them as RSC Flight bytes
* for the main thread to forward to the dev overlay. Returns `null` when
* validation was superseded or produced no errors.
*/
export async function runDevValidation(
message: DevValidationWorkerMessage,
abortBuffer: SharedArrayBuffer
): Promise<DevValidationWorkerResult> {
// Load the native SWC bindings and wire the code-frame renderer so the errors
// logged below render with a source-mapped code frame, matching the
// in-process dev output (the E2E tests snapshot the CLI text between the
// validation markers). The `build/swc` graph these pull in is bundled as a
// runtime external (see `next-runtime.webpack-config.js`), so it resolves
// from the installed `next/dist` tree rather than being compiled into this
// worker bundle, the same way the unbundled build worker loads it.
await installBindings()
installCodeFrameSupport()
setHttpClientAndAgentOptions({
httpAgentOptions: message.nextConfigSerializable.httpAgentOptions,
})
// Populates the manifests singleton for the route via `setManifestsSingleton`
// inside `loadComponents`, exactly as a real request does. The pool tears the
// worker down on HMR / route recompile so the next validation reloads from a
// clean require cache.
const { ComponentMod } = await loadComponents<AppPageModule>({
distDir: message.distDir,
page: message.page,
isAppPath: true,
isDev: true,
sriEnabled: false,
needsManifestsForLegacyReasons: true,
})
await registerAdditionalClientReferenceManifests(
message.distDir,
message.additionalClientReferenceManifestPages
)
const { signal, cleanup } = createSupersedeSignal(abortBuffer)
if (isTestLoggingEnabled) {
console.log(
formatValidationEvent({
type: 'validation_start',
requestId: message.requestId,
url: message.request.urlPathname + message.request.urlSearch,
responseFinished: message.responseFinished,
})
)
}
try {
if (isTestLoggingEnabled) {
await applyTestValidationDelay(signal)
}
if (signal.aborted) {
return null
}
// Crossing into the app-page bundle: the entire validation runs there, so
// the client prerenders use the same React the user's client components
// resolve through `ComponentMod`.
const validationErrors = await ComponentMod.routeModule.runValidationInDev(
ComponentMod,
message,
signal
)
if (validationErrors === undefined || signal.aborted) {
return null
}
const errors: Error[] = []
for (const validationError of validationErrors) {
// Log to the worker's stderr; `node-environment` +
// `installCodeFrameSupport` render the source-mapped stack and code frame
// there, matching the in-process CLI output.
console.error(validationError)
if (validationError instanceof Error) {
errors.push(validationError)
}
}
if (errors.length === 0) {
return null
}
return await serializeValidationErrorsToFlight(ComponentMod, errors)
} finally {
cleanup()
if (isTestLoggingEnabled) {
console.log(
formatValidationEvent({
type: signal.aborted ? 'validation_aborted' : 'validation_end',
requestId: message.requestId,
url: message.request.urlPathname + message.request.urlSearch,
})
)
}
}
}
......@@ -26,6 +26,7 @@ import * as React from 'react'
import fs from 'fs'
import { Worker } from 'next/dist/compiled/jest-worker'
import { installUseCacheProbe } from './use-cache-probe-pool'
import { installDevValidationWorker } from './dev-validation-worker-pool'
import { join as pathJoin } from 'path'
import { PUBLIC_DIR_MIDDLEWARE_CONFLICT } from '../../lib/constants'
import { findPagesDir } from '../../lib/find-pages-dir'
......@@ -225,6 +226,20 @@ export default class DevServer extends Server {
deploymentId: this.deploymentId,
nextConfig: this.nextConfig,
})
// Runs Cache Components dev validation on a worker thread, off the main
// thread, so validation renders don't block the event loop during rapid
// navigation. Gated by `experimental.devValidationWorker`. The worker is
// spawned lazily on the first navigation that validates, so this install is
// free when a project doesn't use Cache Components.
if (this.nextConfig.experimental.devValidationWorker !== false) {
installDevValidationWorker({
distDir: this.distDir,
buildId: this.buildId,
deploymentId: this.deploymentId,
nextConfig: this.nextConfig,
})
}
}
protected override getServerComponentsHmrCache() {
......
......@@ -142,11 +142,26 @@ export async function evalManifestWithRetries<T extends object>(
}
}
async function tryLoadClientReferenceManifest(
manifestPath: string,
entryName: string,
/**
* Loads the client reference manifest that the bundler emitted for an app page,
* or returns undefined if there is none. Both the manifest file and the entry
* inside it are addressed by the page with `%5F` decoded back to `_`, so
* callers pass the page as-is and this resolves both.
*/
export async function loadClientReferenceManifestForPage(
distDir: string,
page: string,
attempts?: number
): Promise<DeepReadonly<ClientReferenceManifest> | undefined> {
const entryName = page.replace(/%5F/g, '_')
const manifestPath = join(
/* turbopackIgnore: true */ distDir,
'server',
'app',
entryName + '_' + CLIENT_REFERENCE_MANIFEST + '.js'
)
try {
const context = await evalManifestWithRetries<{
__RSC_MANIFEST: { [key: string]: ClientReferenceManifest }
......@@ -252,17 +267,9 @@ async function loadComponentsImpl<
manifestLoadAttempts
).catch(() => undefined),
isAppPath && hasClientManifest
? tryLoadClientReferenceManifest(
join(
/* turbopackIgnore: true */ distDir,
'server',
'app',
page.replace(/%5F/g, '_') +
'_' +
CLIENT_REFERENCE_MANIFEST +
'.js'
),
page.replace(/%5F/g, '_'),
? loadClientReferenceManifestForPage(
distDir,
page,
manifestLoadAttempts
)
: undefined,
......
......@@ -37,10 +37,20 @@ type CodeFrameRenderer = (
colors: boolean
) => string | null
let codeFrameRenderer: CodeFrameRenderer | undefined
// The code-frame renderer is stored on `globalThis` rather than in a module
// variable because this module is bundled into several runtimes (the dev
// server, the app-page runtime bundle, and the dev worker bundles) that each
// get their own copy. `Error.prepareStackTrace` is a single process-global, so
// whichever copy patched it last is the one that renders errors, which may not
// be the copy `setCodeFrameRenderer` was called on. Sharing the renderer
// through a `globalThis` symbol lets any copy install it and any copy read it.
const CODE_FRAME_RENDERER = Symbol.for('next.dev.codeFrameRenderer')
type GlobalWithCodeFrameRenderer = typeof globalThis & {
[CODE_FRAME_RENDERER]?: CodeFrameRenderer
}
export function setCodeFrameRenderer(renderer: CodeFrameRenderer): void {
codeFrameRenderer = renderer
;(globalThis as GlobalWithCodeFrameRenderer)[CODE_FRAME_RENDERER] = renderer
}
function getOriginalCodeFrame(
......@@ -48,6 +58,9 @@ function getOriginalCodeFrame(
source: string | null,
colors: boolean = process.stdout.isTTY
): string | null {
const codeFrameRenderer = (globalThis as GlobalWithCodeFrameRenderer)[
CODE_FRAME_RENDERER
]
if (!codeFrameRenderer) {
// No renderer available - gracefully degrade
return null
......
......@@ -7,8 +7,10 @@ import type { PrerenderManifest } from '../../../build'
import {
renderToHTMLOrFlight,
runValidationInDevFromSnapshot,
type AppSharedContext,
} from '../../app-render/app-render'
import type { DevValidationWorkerMessage } from '../../app-render/dev-validation-worker-globals'
import {
RouteModule,
type RouteModuleOptions,
......@@ -169,6 +171,24 @@ export class AppPageRouteModule extends RouteModule<
)
}
/**
* Worker entry point for dev Cache Components dev validation. The dev
* validation worker reloads this route's module and calls this so the whole
* validation runs inside the app-page bundle's React instance (the same one
* the user's client components resolve through `componentMod`), rebuilding
* the render context from the transported `message`. `componentMod` is the
* reloaded module the worker holds; it's passed in because the route module
* has no back-reference to it. Returns the validation errors for the worker
* to serialize and the main thread to deliver to the dev overlay.
*/
public runValidationInDev(
componentMod: AppPageModule,
message: DevValidationWorkerMessage,
abortSignal: AbortSignal
): Promise<Array<unknown> | undefined> {
return runValidationInDevFromSnapshot(message, componentMod, abortSignal)
}
private pathCouldBeIntercepted(
resolvedPathname: string,
interceptionRoutePatterns: RegExp[]
......
......@@ -3030,10 +3030,10 @@ export async function next_bundle_server(task, opts) {
})
}
// The `app-worker` bundle currently has only one entry, the use-cache probe
// worker, which is dev-only. We therefore build just the four dev variants
// (turbo × experimental). If a future worker entry needs to run in prod,
// add the matching prod tasks then.
// The `app-worker` bundle holds the dev-only worker entries (the use-cache
// probe worker and the dev validation worker). We therefore build just the four
// dev variants (turbo × experimental). If a future worker entry needs to run in
// prod, add the matching prod tasks then.
export async function next_bundle_app_worker_dev(task, opts) {
await task.source('dist').webpack({
watch: opts.dev,
......
import { nextTestSetup } from 'e2e-utils'
import { retry, assertNoConsoleErrors } from 'next-test-utils'
import { parseValidationMessages } from 'e2e-utils/instant-validation'
import {
parseValidationMessages,
waitForValidation,
} from 'e2e-utils/instant-validation'
import type { Playwright } from 'next-webdriver'
const cacheComponentsEnabled = process.env.__NEXT_CACHE_COMPONENTS === 'true'
......@@ -258,6 +261,14 @@ describe('hmr-rsc-cancellation', () => {
await retry(async () => {
expect(await browser.elementById('dynamic').text()).toBe('initial')
})
if (cacheComponentsEnabled) {
// Loading the page triggers a validation, which is detached from the
// response and can write its markers long after the page has rendered.
// Wait for it to finish before recording the CLI position below,
// otherwise those markers can land in the window the assertions read and
// the expected sequence of refresh events no longer matches.
await waitForValidation(await browser.url(), () => next.cliOutput)
}
await instrumentBrowser(browser)
const cliStart = next.cliOutput.length
......
......@@ -474,6 +474,14 @@ export function registerClientTests(ctx: InstantValidationCaseContext) {
'/suspense-in-root/static/invalid-client-error-in-parent-sibling'
)
// Wait for validation to finish before snapshotting. Unlike the other
// client-error cases, this page also throws a client error during the
// render itself, which opens the redbox before validation reports its
// own errors. Without waiting, the snapshot can race the
// (asynchronously delivered) validation errors and capture only the
// render error.
await waitForValidation(await browser.url(), getCliOutputSinceMark)
if (isClientNav) {
// In a client navigation, the redbox will be collapsed.
await openRedbox(browser)
......
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