PR #86018: [Cache Components] Fast setImmediate

• Repository: vercel/next.js
• Author: lubieowoce
• State: closed | merged: True
• Link: https://github.com/vercel/next.js/pull/86018

Description (problem / solution / changelog)

This place is not a place of honor... no highly esteemed deed is commemorated here... nothing valued is here. What is here was dangerous and repulsive to us. This message is a warning about danger.

you think you know when setImmediate is supposed to run? no you don't

This PR introduces a patch to the Node setImmediate builtin. The patch is enabled by calling DANGEROUSLY_runPendingImmediatesAfterCurrentTask(). All immediates scheduled after that point (until the end of the task) will be captured and executed right after that task (after process.nextTick and microtasks). This applies to immediates scheduled from immediates as well.

This is relevant when scheduling back-to-back timeouts for staged rendering in Cache Components:

setTimeout(() => {
  // runs first
  
  DANGEROUSLY_runPendingImmediatesAfterCurrentTask() // enable the patch
  setImmediate(() => {
    // runs second (normally, it'd run last!)
  })
})

setTimeout(() => {
  // runs third
})

the immediate scheduled from inside the first timeout will always run before the second timeout.

A side-effect of this is that setImmediate will no longer be considered IO in the Cache Components rendering model, because immediates will always run before we advance the stage (or abort a prerender), and thus can't result in a dynamic hole. This brings the runtime behavior in line with React Devtools, which does not show setImmediate as IO.

This patch also has some observable differences in behavior from native setImmediate, mostly to do with uncaught errors:

1. sync errors in process.nextTick no longer interrupt processTicksAndRejections (which would make us move onto the next event loop step, and run the rest of the nextTick queue after the next task, breaking our scheduling). They're rethrown in a microtask, which changes the timing of uncaughtException a bit.
2. unhandled rejections will trigger unhandledRejection after all fast immediates are done executing, not after each immediate. This happens because our userspace immediate scheduling relies on nextTick, and rejections are only processed after everything else in processTicksAndRejections is done.

We hope that these divergences in behavior are niche enough to not affect any real world code. Both are potentially fixable by managing our own nextTick queue, more, but we'll try to avoid that complexity for now.

Changed files

• packages/next/errors.json (modified, +14/-1)
• packages/next/src/server/app-render/app-render-prerender-utils.ts (modified, +26/-8)
• packages/next/src/server/app-render/app-render-render-utils.ts (modified, +15/-2)
• packages/next/src/server/app-render/app-render-scheduling.ts (modified, +6/-2)
• packages/next/src/server/node-environment-extensions/fast-set-immediate.external.test.ts (added, +1445/-0)
• packages/next/src/server/node-environment-extensions/fast-set-immediate.external.ts (added, +797/-0)
• packages/next/src/server/node-environment.ts (modified, +1/-0)
• test/development/app-dir/cache-components-tasks/cache-components-tasks.test.ts (added, +190/-0)
• test/development/app-dir/cache-components-tasks/fixtures/with-prefetch-config/app/layout.tsx (added, +7/-0)
• test/development/app-dir/cache-components-tasks/fixtures/with-prefetch-config/app/page.tsx (added, +14/-0)
• test/development/app-dir/cache-components-tasks/fixtures/with-prefetch-config/app/revalidate/route.ts (added, +8/-0)
• test/development/app-dir/cache-components-tasks/fixtures/with-prefetch-config/app/shared.tsx (added, +31/-0)
• test/development/app-dir/cache-components-tasks/fixtures/with-prefetch-config/app/simple/layout.tsx (added, +22/-0)
• test/development/app-dir/cache-components-tasks/fixtures/with-prefetch-config/app/simple/page.tsx (added, +16/-0)
• test/development/app-dir/cache-components-tasks/fixtures/with-prefetch-config/next.config.ts (added, +7/-0)
• test/development/app-dir/cache-components-tasks/fixtures/without-prefetch-config/app/layout.tsx (added, +7/-0)
• test/development/app-dir/cache-components-tasks/fixtures/without-prefetch-config/app/page.tsx (added, +14/-0)
• test/development/app-dir/cache-components-tasks/fixtures/without-prefetch-config/app/revalidate/route.ts (added, +8/-0)
• test/development/app-dir/cache-components-tasks/fixtures/without-prefetch-config/app/shared.tsx (added, +31/-0)
• test/development/app-dir/cache-components-tasks/fixtures/without-prefetch-config/app/simple/layout.tsx (added, +20/-0)
• test/development/app-dir/cache-components-tasks/fixtures/without-prefetch-config/app/simple/page.tsx (added, +16/-0)
• test/development/app-dir/cache-components-tasks/fixtures/without-prefetch-config/next.config.ts (added, +7/-0)