Repository: vercel/next.js
Pull request: [Cache Components] Atomic setTimeouts

This PR exploits some Node internals to make sure that, if we schedule some timeouts back to back to perform staged rendering, they'll actually run in the same iteration of the event loop.

If we cannot patch the timeouts correctly (due to runtime differences in e.g. Bun, or changes in future node versions), we'll warn that Cache Components may not function correctly, and run the timers normally. timer/immediate interleaving is rare in practice, and we'll usually be fine even without this patch, so it's better to warn and try to carry on rather than to error out.

(h/t to @sokra for finding this trick)

Changed files:
filename: packages/next/errors.json
patch: @@ -930,5 +930,8 @@
   "929": "No pages or app directory found.",
   "930": "Expected a dynamic route, but got a static route: %s",
   "931": "Unexpected empty path segments match for a route \"%s\" with param \"%s\" of type \"%s\"",
-  "932": "Could not resolve param value for segment: %s"
+  "932": "Could not resolve param value for segment: %s",
+  "933": "An unexpected error occurred while adjusting `_idleStart` on an atomic timer",
+  "934": "createAtomicTimerGroup cannot be called in the edge runtime",
+  "935": "Cannot schedule more timers into a group that already executed"
 }

filename: packages/next/src/server/app-render/app-render-prerender-utils.ts
patch: @@ -1,4 +1,5 @@
 import { InvariantError } from '../../shared/lib/invariant-error'
+import { createAtomicTimerGroup } from './app-render-scheduling'
 
 /**
  * This is a utility function to make scheduling sequential tasks that run back to back easier.
@@ -14,19 +15,22 @@ export function prerenderAndAbortInSequentialTasks<R>(
     )
   } else {
     return new Promise((resolve, reject) => {
+      const scheduleTimeout = createAtomicTimerGroup()
+
       let pendingResult: Promise<R>
-      setTimeout(() => {
+      scheduleTimeout(() => {
         try {
           pendingResult = prerender()
           pendingResult.catch(() => {})
         } catch (err) {
           reject(err)
         }
-      }, 0)
-      setTimeout(() => {
+      })
+
+      scheduleTimeout(() => {
         abort()
         resolve(pendingResult)
-      }, 0)
+      })
     })
   }
 }
@@ -46,22 +50,26 @@ export function prerenderAndAbortInSequentialTasksWithStages<R>(
     )
   } else {
     return new Promise((resolve, reject) => {
+      const scheduleTimeout = createAtomicTimerGroup()
+
       let pendingResult: Promise<R>
-      setTimeout(() => {
+      scheduleTimeout(() => {
         try {
           pendingResult = prerender()
           pendingResult.catch(() => {})
         } catch (err) {
           reject(err)
         }
-      }, 0)
-      setTimeout(() => {
+      })
+
+      scheduleTimeout(() => {
         advanceStage()
-      }, 0)
-      setTimeout(() => {
+      })
+
+      scheduleTimeout(() => {
         abort()
         resolve(pendingResult)
-      }, 0)
+      })
     })
   }
 }

filename: packages/next/src/server/app-render/app-render-render-utils.ts
patch: @@ -1,4 +1,5 @@
 import { InvariantError } from '../../shared/lib/invariant-error'
+import { createAtomicTimerGroup } from './app-render-scheduling'
 
 /**
  * This is a utility function to make scheduling sequential tasks that run back to back easier.
@@ -14,18 +15,21 @@ export function scheduleInSequentialTasks<R>(
     )
   } else {
     return new Promise((resolve, reject) => {
+      const scheduleTimeout = createAtomicTimerGroup()
+
       let pendingResult: R | Promise<R>
-      setTimeout(() => {
+      scheduleTimeout(() => {
         try {
           pendingResult = render()
         } catch (err) {
           reject(err)
         }
-      }, 0)
-      setTimeout(() => {
+      })
+
+      scheduleTimeout(() => {
         followup()
         resolve(pendingResult)
-      }, 0)
+      })
     })
   }
 }
@@ -46,19 +50,21 @@ export function pipelineInSequentialTasks<A, B, C>(
     )
   } else {
     return new Promise((resolve, reject) => {
+      const scheduleTimeout = createAtomicTimerGroup()
+
       let oneResult: A | undefined = undefined
-      setTimeout(() => {
+      scheduleTimeout(() => {
         try {
           oneResult = one()
         } catch (err) {
           clearTimeout(twoId)
           clearTimeout(threeId)
           reject(err)
         }
-      }, 0)
+      })
 
       let twoResult: B | undefined = undefined
-      const twoId = setTimeout(() => {
+      const twoId = scheduleTimeout(() => {
         // if `one` threw, then this timeout would've been cleared,
         // so if we got here, we're guaranteed to have a value.
         try {
@@ -67,17 +73,17 @@ export function pipelineInSequentialTasks<A, B, C>(
           clearTimeout(threeId)
           reject(err)
         }
-      }, 0)
+      })
 
-      const threeId = setTimeout(() => {
+      const threeId = scheduleTimeout(() => {
         // if `two` threw, then this timeout would've been cleared,
         // so if we got here, we're guaranteed to have a value.
         try {
           resolve(three(twoResult!))
         } catch (err) {
           reject(err)
         }
-      }, 0)
+      })
     })
   }
 }

filename: packages/next/src/server/app-render/app-render-scheduling.ts
patch: @@ -0,0 +1,192 @@
+import { InvariantError } from '../../shared/lib/invariant-error'
+
+/*
+==========================
+| Background             |
+==========================
+
+Node.js does not guarantee that two timers scheduled back to back will run
+on the same iteration of the event loop:
+
+```ts
+setTimeout(one, 0)
+setTimeout(two, 0)
+```
+
+Internally, each timer is assigned a `_idleStart` property that holds
+an internal libuv timestamp in millisecond resolution.
+This will be used to determine if the timer is already "expired" and should be executed.
+However, even in sync code, it's possible for two timers to get different `_idleStart` values.
+This can cause one of the timers to be executed, and the other to be delayed until the next timer phase.
+
+The delaying happens [here](https://github.com/nodejs/node/blob/c208ffc66bb9418ff026c4e3fa82e5b4387bd147/lib/internal/timers.js#L556-L564).
+and can be debugged by running node with `NODE_DEBUG=timer`.
+
+The easiest way to observe it is to run this program in a loop until it exits with status 1:
+
+```
+// test.js
+
+let immediateRan = false
+const t1 = setTimeout(() => {
+  console.log('timeout 1')
+  setImmediate(() => {
+    console.log('immediate 1')
+    immediateRan = true
+  })
+})
+
+const t2 = setTimeout(() => {
+  console.log('timeout 2')
+  if (immediateRan) {
+    console.log('immediate ran before the second timeout!')
+    console.log(
+      `t1._idleStart: ${t1._idleStart}, t2_idleStart: ${t2._idleStart}`
+    );
+    process.exit(1)
+  }
+})
+```
+
+```bash
+#!/usr/bin/env bash
+
+i=1;
+while true; do
+  output="$(NODE_DEBUG=timer node test.js 2>&1)";
+  if [ "$?" -eq 1 ]; then
+    echo "failed after $i iterations";
+    echo "$output";
+    break;
+  fi;
+  i=$((i+1));
+done
+```
+
+If `t2` is deferred to the next iteration of the event loop,
+then the immediate scheduled from inside `t1` will run first.
+When this occurs, `_idleStart` is reliably different between `t1` and `t2`.
+
+==========================
+| Solution               |
+==========================
+
+We can guarantee that multiple timers (with the same delay, usually `0`)
+run together without any delays by making sure that their `_idleStart`s are the same,
+because that's what's used to determine if a timer should be deferred or not.
+Luckily, this property is currently exposed to userland and mutable,
+so we can patch it.
+
+Another related trick we could potentially apply is making
+a timer immediately be considered expired by doing  `timer._idleStart -= 2`.
+(the value must be more than `1`, the delay that actually gets set for `setTimeout(cb, 0)`).
+This makes node view this timer as "a 1ms timer scheduled 2ms ago",
+meaning that it should definitely run in the next timer phase.
+However, I'm not confident we know all the side effects of doing this,
+so for now, simply ensuring coordination is enough.
+*/
+
+let shouldAttemptPatching = true
+
+function warnAboutTimers() {
+  console.warn(
+    "Next.js cannot guarantee that Cache Components will run as expected due to the current runtime's implementation of `setTimeout()`.\nPlease report a github issue here: https://github.com/vercel/next.js/issues/new/"
+  )
+}
+
+/**
+ * Allows scheduling multiple timers (equivalent to `setTimeout(cb, delayMs)`)
+ * that are guaranteed to run in the same iteration of the event loop.
+ *
+ * @param delayMs - the delay to pass to `setTimeout`. (default: 0)
+ *
+ * */
+export function createAtomicTimerGroup(delayMs = 0) {
+  if (process.env.NEXT_RUNTIME === 'edge') {
+    throw new InvariantError(
+      'createAtomicTimerGroup cannot be called in the edge runtime'
+    )
+  } else {
+    let isFirstCallback = true
+    let firstTimerIdleStart: number | null = null
+    let didFirstTimerRun = false
+
+    // As a sanity check, we schedule an immediate from the first timeout
+    // to check if the execution was interrupted.
+    let didImmediateRun = false
+    function runFirstCallback(callback: () => void) {
+      didFirstTimerRun = true
+      if (shouldAttemptPatching) {
+        setImmediate(() => {
+          didImmediateRun = true
+        })
+      }
+      return callback()
+    }
+
+    function runSubsequentCallback(callback: () => void) {
+      if (shouldAttemptPatching) {
+        if (didImmediateRun) {
+          // If the immediate managed to run between the timers, then we're not
+          // able to provide the guarantees that we're supposed to
+          shouldAttemptPatching = false
+          warnAboutTimers()
+        }
+      }
+      return callback()
+    }
+
+    return function scheduleTimeout(callback: () => void) {
+      if (didFirstTimerRun) {
+        throw new InvariantError(
+          'Cannot schedule more timers into a group that already executed'
+        )
+      }
+
+      const timer = setTimeout(
+        isFirstCallback ? runFirstCallback : runSubsequentCallback,
+        delayMs,
+        callback
+      )
+      isFirstCallback = false
+
+      if (!shouldAttemptPatching) {
+        // We already tried patching some timers, and it didn't work.
+        // No point trying again.
+        return timer
+      }
+
+      // NodeJS timers have a `_idleStart` property, but it doesn't exist e.g. in Bun.
+      // If it's not present, we'll warn and try to continue.
+      try {
+        if ('_idleStart' in timer && typeof timer._idleStart === 'number') {
+          // If this is the first timer that was scheduled, save its `_idleStart`.
+          // We'll copy it onto subsequent timers to guarantee that they'll all be
+          // considered expired in the same iteration of the event loop
+          // and thus will all be executed in the same timer phase.
+          if (firstTimerIdleStart === null) {
+            firstTimerIdleStart = timer._idleStart
+          } else {
+            timer._idleStart = firstTimerIdleStart
+          }
+        } else {
+          shouldAttemptPatching = false
+          warnAboutTimers()
+        }
+      } catch (err) {
+        // This should never fail in current Node, but it might start failing in the future.
+        // We might be okay even without tweaking the timers, so warn and try to continue.
+        console.error(
+          new InvariantError(
+            'An unexpected error occurred while adjusting `_idleStart` on an atomic timer',
+            { cause: err }
+          )
+        )
+        shouldAttemptPatching = false
+        warnAboutTimers()
+      }
+
+      return timer
+    }
+  }
+}