[build-sourcemaps] Allow inspecting prerender worker (#79098)

If `--inspect` or `--inspect-brk` is specified, prerender will no longer time out since that's most likely not wanted (e.g. you'd always get timeouts if you set breakpoints).

Inspecting prerender workers is best done with `experimental.cpus: 1`.
Only the first prerender worker can be inspected since we can't set `NODE_OPTIONS` based off of the worker index.

This PR also sets up infra for inspecting arbitrary workers. Their debug port would need to be coordinated within `getNextBuildDebuggerPortOffset`. This doesn't work if worker creation is shared between `next build` and `next dev` which I haven't checked if that's the case.

Author: eps1lon

packages/next/src/build/index.ts

@@ -194,10 +194,6 @@ import {
 import { FallbackMode, fallbackModeToFallbackField } from '../lib/fallback'
 import { RenderingMode } from './rendering-mode'
 import { getParamKeys } from '../server/request/fallback-params'
-import {
-  formatNodeOptions,
-  getParsedNodeOptionsWithoutInspect,
-} from '../server/lib/utils'
 import { InvariantError } from '../shared/lib/invariant-error'
 import { HTML_LIMITED_BOT_UA_RE_STRING } from '../shared/lib/router/utils/is-bot'
 import type { UseCacheTrackerKey } from './webpack/plugins/telemetry-plugin/use-cache-tracker-utils'
@@ -743,17 +739,15 @@ const staticWorkerExposedMethods = [
 type StaticWorker = typeof import('./worker') & Worker
 export function createStaticWorker(
   config: NextConfigComplete,
-  progress?: {
-    run: () => void
-    clear: () => void
+  options: {
+    debuggerPortOffset: number
+    progress?: {
+      run: () => void
+      clear: () => void
+    }
   }
 ): StaticWorker {
-  // Get the node options without inspect and also remove the
-  // --max-old-space-size flag as it can cause memory issues.
-  const nodeOptions = getParsedNodeOptionsWithoutInspect()
-  delete nodeOptions['max-old-space-size']
-  delete nodeOptions['max_old_space_size']
-
+  const { debuggerPortOffset, progress } = options
   return new Worker(staticWorkerPath, {
     logger: Log,
     numWorkers: getNumberOfWorkers(config),
@@ -763,11 +757,9 @@ export function createStaticWorker(
     onActivityAbort: () => {
       progress?.clear()
     },
-    forkOptions: {
-      env: {
-        NODE_OPTIONS: formatNodeOptions(nodeOptions),
-      },
-    },
+    debuggerPortOffset,
+    // remove --max-old-space-size flag as it can cause memory issues.
+    isolatedMemory: true,
     enableWorkerThreads: config.experimental.workerThreads,
     exposedMethods: staticWorkerExposedMethods,
   }) as StaticWorker
@@ -1496,6 +1488,8 @@ export default async function build(
                 const buildTraceWorker = new Worker(
                   require.resolve('./collect-build-traces'),
                   {
+                    debuggerPortOffset: -1,
+                    isolatedMemory: false,
                     numWorkers: 1,
                     exposedMethods: ['collectBuildTraces'],
                   }
@@ -1652,7 +1646,7 @@ export default async function build(
 
       process.env.NEXT_PHASE = PHASE_PRODUCTION_BUILD
 
-      const worker = createStaticWorker(config)
+      const worker = createStaticWorker(config, { debuggerPortOffset: -1 })
 
       const analysisBegin = process.hrtime()
       const staticCheckSpan = nextBuildSpan.traceChild('static-check')

packages/next/src/build/turbopack-build/index.ts

@@ -1,23 +1,19 @@
 import path from 'path'
-import {
-  formatNodeOptions,
-  getParsedNodeOptionsWithoutInspect,
-} from '../../server/lib/utils'
+
 import { Worker } from '../../lib/worker'
 import { NextBuildContext } from '../build-context'
 
 async function turbopackBuildWithWorker() {
-  const nodeOptions = getParsedNodeOptionsWithoutInspect()
-
   try {
     const worker = new Worker(path.join(__dirname, 'impl.js'), {
       exposedMethods: ['workerMain', 'waitForShutdown'],
+      debuggerPortOffset: -1,
+      isolatedMemory: false,
       numWorkers: 1,
       maxRetries: 0,
       forkOptions: {
         env: {
           NEXT_PRIVATE_BUILD_WORKER: '1',
-          NODE_OPTIONS: formatNodeOptions(nodeOptions),
         },
       },
     }) as Worker & typeof import('./impl')

packages/next/src/build/type-check.ts

@@ -34,6 +34,8 @@ function verifyTypeScriptSetup(
     require.resolve('../lib/verify-typescript-setup'),
     {
       exposedMethods: ['verifyTypeScriptSetup'],
+      debuggerPortOffset: -1,
+      isolatedMemory: false,
       numWorkers: 1,
       enableWorkerThreads,
       maxRetries: 0,

packages/next/src/build/webpack-build/index.ts

@@ -6,10 +6,6 @@ import { Worker } from '../../lib/worker'
 import origDebug from 'next/dist/compiled/debug'
 import path from 'path'
 import { exportTraceState, recordTraceEvents } from '../../trace'
-import {
-  formatNodeOptions,
-  getParsedNodeOptionsWithoutInspect,
-} from '../../server/lib/utils'
 import { mergeUseCacheTrackers } from '../webpack/plugins/telemetry-plugin/use-cache-tracker-utils'
 import { durationToString } from '../duration-to-string'
 
@@ -48,17 +44,16 @@ async function webpackBuildWithWorker(
     buildTraceContext: {} as BuildTraceContext,
   }
 
-  const nodeOptions = getParsedNodeOptionsWithoutInspect()
-
   for (const compilerName of compilerNames) {
     const worker = new Worker(path.join(__dirname, 'impl.js'), {
       exposedMethods: ['workerMain'],
+      debuggerPortOffset: -1,
+      isolatedMemory: false,
       numWorkers: 1,
       maxRetries: 0,
       forkOptions: {
         env: {
           NEXT_PRIVATE_BUILD_WORKER: '1',
-          NODE_OPTIONS: formatNodeOptions(nodeOptions),
         },
       },
     }) as Worker & typeof import('./impl')

packages/next/src/export/index.ts

@@ -63,6 +63,7 @@ import { isInterceptionRouteRewrite } from '../lib/generate-interception-routes-
 import type { ActionManifest } from '../build/webpack/plugins/flight-client-entry-plugin'
 import { extractInfoFromServerReferenceId } from '../shared/lib/server-reference-info'
 import { convertSegmentPathToStaticExportFilename } from '../shared/lib/segment-cache/segment-value-encoding'
+import { getNextBuildDebuggerPortOffset } from '../lib/worker'
 
 export class ExportError extends Error {
   code = 'NEXT_EXPORT_ERROR'
@@ -581,7 +582,10 @@ async function exportAppImpl(
     options.statusMessage || 'Exporting'
   )
 
-  const worker = createStaticWorker(nextConfig, progress)
+  const worker = createStaticWorker(nextConfig, {
+    debuggerPortOffset: getNextBuildDebuggerPortOffset({ kind: 'export-page' }),
+    progress,
+  })
 
   const results = (
     await Promise.all(

packages/next/src/export/worker.ts

@@ -401,6 +401,10 @@ export async function exportPages(
     let attempt = 0
     let result
 
+    const hasDebuggerAttached =
+      // Also tests for `inspect-brk`
+      process.env.NODE_OPTIONS?.includes('--inspect')
+
     while (attempt < maxAttempts) {
       try {
         result = await Promise.race<ExportPageResult | undefined>([
@@ -427,12 +431,15 @@ export async function exportPages(
             sriEnabled: Boolean(nextConfig.experimental.sri?.algorithm),
             buildId: input.buildId,
           }),
-          // If exporting the page takes longer than the timeout, reject the promise.
-          new Promise((_, reject) => {
-            setTimeout(() => {
-              reject(new TimeoutError())
-            }, nextConfig.staticPageGenerationTimeout * 1000)
-          }),
+          hasDebuggerAttached
+            ? // With a debugger attached, exporting can take infinitely if we paused script execution.
+              new Promise(() => {})
+            : // If exporting the page takes longer than the timeout, reject the promise.
+              new Promise((_, reject) => {
+                setTimeout(() => {
+                  reject(new TimeoutError())
+                }, nextConfig.staticPageGenerationTimeout * 1000)
+              }),
         ])
 
         // If there was an error in the export, throw it immediately. In the catch block, we might retry the export,

packages/next/src/lib/verifyAndLint.ts

@@ -24,6 +24,8 @@ export async function verifyAndLint(
   try {
     lintWorkers = new Worker(require.resolve('./eslint/runLintCheck'), {
       exposedMethods: ['runLintCheck'],
+      debuggerPortOffset: -1,
+      isolatedMemory: false,
       numWorkers: 1,
       enableWorkerThreads,
       maxRetries: 0,

packages/next/src/lib/worker.ts

@@ -1,6 +1,13 @@
 import type { ChildProcess } from 'child_process'
 import { Worker as JestWorker } from 'next/dist/compiled/jest-worker'
 import { Transform } from 'stream'
+import {
+  formatDebugAddress,
+  formatNodeOptions,
+  getNodeDebugType,
+  getParsedDebugAddress,
+  getParsedNodeOptionsWithoutInspect,
+} from '../server/lib/utils'
 
 type FarmOptions = NonNullable<ConstructorParameters<typeof JestWorker>[1]>
 
@@ -14,6 +21,13 @@ const cleanupWorkers = (worker: JestWorker) => {
   }
 }
 
+export function getNextBuildDebuggerPortOffset(_: {
+  kind: 'export-page'
+}): number {
+  // 0: export worker
+  return 0
+}
+
 export class Worker {
   private _worker: JestWorker | undefined
 
@@ -25,6 +39,14 @@ export class Worker {
             env?: Partial<NodeJS.ProcessEnv> | undefined
           })
         | undefined
+      /**
+       * `-1` if not inspectable
+       */
+      debuggerPortOffset: number
+      /**
+       * True if `--max-old-space-size` should not be forwarded to the worker.
+       */
+      isolatedMemory: boolean
       timeout?: number
       onActivity?: () => void
       onActivityAbort?: () => void
@@ -34,7 +56,14 @@ export class Worker {
       enableWorkerThreads?: boolean
     }
   ) {
-    let { timeout, onRestart, logger = console, ...farmOptions } = options
+    let {
+      timeout,
+      onRestart,
+      logger = console,
+      debuggerPortOffset,
+      isolatedMemory,
+      ...farmOptions
+    } = options
 
     let restartPromise: Promise<typeof RESTARTED>
     let resolveRestartPromise: (arg: typeof RESTARTED) => void
@@ -47,6 +76,26 @@ export class Worker {
       this.close()
     })
 
+    const nodeOptions = getParsedNodeOptionsWithoutInspect()
+
+    if (debuggerPortOffset !== -1) {
+      const nodeDebugType = getNodeDebugType()
+      if (nodeDebugType) {
+        const address = getParsedDebugAddress()
+        address.port =
+          address.port +
+          // current process runs on `address.port`
+          1 +
+          debuggerPortOffset
+        nodeOptions[nodeDebugType] = formatDebugAddress(address)
+      }
+    }
+
+    if (isolatedMemory) {
+      delete nodeOptions['max-old-space-size']
+      delete nodeOptions['max_old_space_size']
+    }
+
     const createWorker = () => {
       this._worker = new JestWorker(workerPath, {
         ...farmOptions,
@@ -56,6 +105,7 @@ export class Worker {
             ...process.env,
             ...((farmOptions.forkOptions?.env || {}) as any),
             IS_NEXT_WORKER: 'true',
+            NODE_OPTIONS: formatNodeOptions(nodeOptions),
           } as any,
         },
         maxRetries: 0,

test/e2e/app-dir/server-source-maps/fixtures/default/next.config.js

@@ -3,6 +3,7 @@
  */
 const nextConfig = {
   experimental: {
+    cpus: 1,
     dynamicIO: true,
     serverSourceMaps: true,
   },