[Cache Components] Schedule work on timeouts (#84344)

Previously we used the immediate queue to schedule the consecutive tasks
that would prerender and abort and page prerender. This works fine but
since React does not consider immediates as IO for async work tracking
it means we can't use it for scheduling more advanced cases like
static->runtime->dynamic where the IO that unblocks in runtime phase can
be picked up.

While React could change to include immediates as IO the argument here
is that it isn't really IO since it is immediate work while timeouts
generally have to schedule something to fire later with timeout zero
being a sort of special case where later === now.

So instead we are going to move to scheduling our consecutive tasks
using timeout as well that way we can align the Next.js and React
heuristic for identifying IO and make certain kinds of debugging easier
to implement.

Author: gnoff

packages/next/src/server/app-render/app-render-prerender-utils.ts

@@ -2,7 +2,7 @@ import { InvariantError } from '../../shared/lib/invariant-error'
 
 /**
  * This is a utility function to make scheduling sequential tasks that run back to back easier.
- * We schedule on the same queue (setImmediate) at the same time to ensure no other events can sneak in between.
+ * We schedule on the same queue (setTimeout) at the same time to ensure no other events can sneak in between.
  */
 export function prerenderAndAbortInSequentialTasks<R>(
   prerender: () => Promise<R>,
@@ -15,18 +15,18 @@ export function prerenderAndAbortInSequentialTasks<R>(
   } else {
     return new Promise((resolve, reject) => {
       let pendingResult: Promise<R>
-      setImmediate(() => {
+      setTimeout(() => {
         try {
           pendingResult = prerender()
           pendingResult.catch(() => {})
         } catch (err) {
           reject(err)
         }
-      })
-      setImmediate(() => {
+      }, 0)
+      setTimeout(() => {
         abort()
         resolve(pendingResult)
-      })
+      }, 0)
     })
   }
 }
@@ -47,21 +47,21 @@ export function prerenderAndAbortInSequentialTasksWithStages<R>(
   } else {
     return new Promise((resolve, reject) => {
       let pendingResult: Promise<R>
-      setImmediate(() => {
+      setTimeout(() => {
         try {
           pendingResult = prerender()
           pendingResult.catch(() => {})
         } catch (err) {
           reject(err)
         }
-      })
-      setImmediate(() => {
+      }, 0)
+      setTimeout(() => {
         advanceStage()
-      })
-      setImmediate(() => {
+      }, 0)
+      setTimeout(() => {
         abort()
         resolve(pendingResult)
-      })
+      }, 0)
     })
   }
 }

packages/next/src/server/app-render/app-render-render-utils.ts

@@ -2,7 +2,7 @@ import { InvariantError } from '../../shared/lib/invariant-error'
 
 /**
  * This is a utility function to make scheduling sequential tasks that run back to back easier.
- * We schedule on the same queue (setImmediate) at the same time to ensure no other events can sneak in between.
+ * We schedule on the same queue (setTimeout) at the same time to ensure no other events can sneak in between.
  */
 export function scheduleInSequentialTasks<R>(
   render: () => R | Promise<R>,
@@ -15,17 +15,17 @@ export function scheduleInSequentialTasks<R>(
   } else {
     return new Promise((resolve, reject) => {
       let pendingResult: R | Promise<R>
-      setImmediate(() => {
+      setTimeout(() => {
         try {
           pendingResult = render()
         } catch (err) {
           reject(err)
         }
-      })
-      setImmediate(() => {
+      }, 0)
+      setTimeout(() => {
         followup()
         resolve(pendingResult)
-      })
+      }, 0)
     })
   }
 }

packages/next/src/server/lib/patch-fetch.ts

@@ -27,7 +27,6 @@ import {
   type ServerComponentsHmrCache,
   type SetIncrementalFetchCacheContext,
 } from '../response-cache'
-import { waitAtLeastOneReactRenderTask } from '../../lib/scheduler'
 import { cloneResponse } from './clone-response'
 import type { IncrementalCache } from './incremental-cache'
 
@@ -911,7 +910,7 @@ export function createPatchedFetcher(
                   // make sure we still exclude them from prerenders if
                   // cacheComponents is on so we introduce an artificial task boundary
                   // here.
-                  await waitAtLeastOneReactRenderTask()
+                  await getTimeoutBoundary()
                   break
                 case 'prerender-ppr':
                 case 'prerender-legacy':
@@ -1191,3 +1190,16 @@ export function patchFetch(options: PatchableModule) {
   // Set the global fetch to the patched fetch.
   globalThis.fetch = createPatchedFetcher(original, options)
 }
+
+let currentTimeoutBoundary: null | Promise<void> = null
+function getTimeoutBoundary() {
+  if (!currentTimeoutBoundary) {
+    currentTimeoutBoundary = new Promise((r) => {
+      setTimeout(() => {
+        currentTimeoutBoundary = null
+        r()
+      }, 0)
+    })
+  }
+  return currentTimeoutBoundary
+}