chore: clarify awaiting backgroundWorkPromise

Author: pieh

src/run/handlers/request-context.cts

@@ -22,11 +22,15 @@ export type RequestContext = {
   serverTiming?: string
   routeHandlerRevalidate?: NetlifyCachedRouteValue['revalidate']
   /**
-   * Track promise running in the background and need to be waited for
+   * Track promise running in the background and need to be waited for.
+   * Uses `context.waitUntil` if available, otherwise stores promises to
+   * await on.
    */
   trackBackgroundWork: (promise: Promise<unknown>) => void
   /**
-   * Promise that need to be executed even if response was already sent
+   * Promise that need to be executed even if response was already sent.
+   * If `context.waitUntil` is available this promise will be always resolved
+   * because background work tracking was offloaded to `context.waitUntil`.
    */
   backgroundWorkPromise: Promise<unknown>
   logger: SystemLogger

src/run/handlers/server.ts

@@ -134,8 +134,9 @@ export default async (request: Request) => {
         // otherwise Next would never run the callback variant of `next/after`
         res.emit('close')
 
-        // if waitUntil is not available, we have to keep response stream open until background promises are resolved
-        // to ensure that all background work executes
+        // We have to keep response stream open until tracked background promises that are don't use `context.waitUntil`
+        // are resolved. If `context.waitUntil` is available, `requestContext.backgroundWorkPromise` will be empty
+        // resolved promised and so awaiting it is no-op
         await requestContext.backgroundWorkPromise
       },
     })