fix(app-router): schedule segment-cache prefetch phases

packages/vinext/src/build/prerender.ts

@@ -142,6 +142,7 @@ export type PrerenderRouteResult =
       outputFiles: string[];
       revalidate: number | false;
       expire?: number;
+      stale?: number;
       /**
        * The concrete prerendered URL path, e.g. `/blog/hello-world`.
        * Only present when the route is dynamic and `path` differs from `route`.
@@ -1567,6 +1568,9 @@ export async function prerenderApp({
           ...(typeof renderedRevalidate === "number"
             ? { expire: renderedCacheControl.expire }
             : {}),
+          ...(typeof renderedCacheControl.stale === "number"
+            ? { stale: renderedCacheControl.stale }
+            : {}),
           router: "app",
           ...(htmlRender.linkHeader ? { headers: { link: htmlRender.linkHeader } } : {}),
           ...(urlPath !== routePattern ? { path: urlPath } : {}),
@@ -1674,10 +1678,10 @@ export async function prerenderApp({
 }
 
 function resolveRenderedCacheControl(
-  requestCacheLife: { expire?: number; revalidate?: number },
+  requestCacheLife: { expire?: number; revalidate?: number; stale?: number },
   cacheControl: string,
   fallbackExpireSeconds: number,
-): { expire: number; revalidate?: number } {
+): { expire: number; revalidate?: number; stale?: number } {
   const sMaxage = parseCacheControlSeconds(cacheControl, "s-maxage");
   const staleWhileRevalidate = parseCacheControlSeconds(cacheControl, "stale-while-revalidate");
   const revalidate =
@@ -1690,26 +1694,34 @@ function resolveRenderedCacheControl(
         sMaxage,
         staleWhileRevalidate,
       }),
+    ...(requestCacheLife.stale === undefined ? {} : { stale: requestCacheLife.stale }),
     ...(revalidate === undefined ? {} : { revalidate }),
   };
 }
 
 function readPrerenderCacheLifeHeader(
   headers: Headers,
-): { expire?: number; revalidate?: number } | null {
+): { expire?: number; revalidate?: number; stale?: number } | null {
   const value = headers.get(VINEXT_PRERENDER_CACHE_LIFE_HEADER);
   if (!value) return null;
 
   try {
-    const parsed = JSON.parse(value) as { expire?: unknown; revalidate?: unknown };
-    const cacheLife: { expire?: number; revalidate?: number } = {};
+    const parsed = JSON.parse(value) as { expire?: unknown; revalidate?: unknown; stale?: unknown };
+    const cacheLife: { expire?: number; revalidate?: number; stale?: number } = {};
     if (typeof parsed.revalidate === "number" && Number.isFinite(parsed.revalidate)) {
       cacheLife.revalidate = parsed.revalidate;
     }
+    if (typeof parsed.stale === "number" && Number.isFinite(parsed.stale)) {
+      cacheLife.stale = parsed.stale;
+    }
     if (typeof parsed.expire === "number" && Number.isFinite(parsed.expire)) {
       cacheLife.expire = parsed.expire;
     }
-    return cacheLife.revalidate === undefined && cacheLife.expire === undefined ? null : cacheLife;
+    return cacheLife.revalidate === undefined &&
+      cacheLife.stale === undefined &&
+      cacheLife.expire === undefined
+      ? null
+      : cacheLife;
   } catch {
     return null;
   }

packages/vinext/src/server/app-page-cache-finalizer.ts

@@ -18,22 +18,39 @@ type AppPageCacheSetter = (
   revalidateSeconds: number,
   tags: string[],
   expireSeconds?: number,
+  staleSeconds?: number,
 ) => Promise<void>;
 type AppPageRscCacheKeyBuilder = (
   pathname: string,
   mountedSlotsHeader?: string | null,
   renderMode?: AppRscRenderMode,
   interceptionContext?: string | null,
+  segmentPrefetchPath?: string | null,
 ) => string;
 type AppPageRequestCacheLife = {
   revalidate?: number;
+  stale?: number;
   expire?: number;
 };
 type BuildAppPageCacheRenderObservation = (input: {
   cacheTags: readonly string[];
   state: AppPageRenderObservationState;
 }) => RenderObservation;
 
+function setAppPageCacheEntry(
+  setter: AppPageCacheSetter,
+  key: string,
+  data: CachedAppPageValue,
+  revalidateSeconds: number,
+  tags: string[],
+  expireSeconds: number | undefined,
+  staleSeconds: number | undefined,
+): Promise<void> {
+  return staleSeconds === undefined
+    ? setter(key, data, revalidateSeconds, tags, expireSeconds)
+    : setter(key, data, revalidateSeconds, tags, expireSeconds, staleSeconds);
+}
+
 type FinalizeAppPageHtmlCacheResponseOptions = {
   capturedDynamicUsageBeforeContextCleanup?: () => boolean;
   capturedRscDataPromise: Promise<ArrayBuffer> | null;
@@ -71,6 +88,7 @@ type ScheduleAppPageRscCacheWriteOptions = {
   interceptionContext?: string | null;
   mountedSlotsHeader?: string | null;
   renderMode?: AppRscRenderMode;
+  segmentPrefetchPath?: string | null;
   preserveClientResponseHeaders?: boolean;
   expireSeconds?: number;
   revalidateSeconds: number | null;
@@ -96,9 +114,10 @@ function resolveAppPageCacheWritePolicy(options: {
   expireSeconds?: number;
   requestCacheLife?: AppPageRequestCacheLife | null;
   revalidateSeconds: number | null;
-}): { expireSeconds?: number; revalidateSeconds: number } | null {
+}): { expireSeconds?: number; revalidateSeconds: number; staleSeconds?: number } | null {
   let revalidateSeconds = options.revalidateSeconds;
   let expireSeconds = options.expireSeconds;
+  let staleSeconds: number | undefined;
   const requestCacheLife = options.requestCacheLife;
 
   if (requestCacheLife?.revalidate !== undefined) {
@@ -110,12 +129,15 @@ function resolveAppPageCacheWritePolicy(options: {
   if (requestCacheLife?.expire !== undefined) {
     expireSeconds = requestCacheLife.expire;
   }
+  if (requestCacheLife?.stale !== undefined) {
+    staleSeconds = requestCacheLife.stale;
+  }
 
   if (revalidateSeconds === null || Number.isNaN(revalidateSeconds) || revalidateSeconds <= 0) {
     return null;
   }
 
-  return { expireSeconds, revalidateSeconds };
+  return { expireSeconds, revalidateSeconds, staleSeconds };
 }
 
 export function finalizeAppPageHtmlCacheResponse(
@@ -176,7 +198,8 @@ export function finalizeAppPageHtmlCacheResponse(
       });
       const linkHeader = response.headers.get("link");
       const writes = [
-        options.isrSet(
+        setAppPageCacheEntry(
+          options.isrSet,
           htmlKey,
           buildAppPageCacheValue(
             cachedHtml,
@@ -188,18 +211,21 @@ export function finalizeAppPageHtmlCacheResponse(
           cachePolicy.revalidateSeconds,
           pageTags,
           cachePolicy.expireSeconds,
+          cachePolicy.staleSeconds,
         ),
       ];
 
       if (options.capturedRscDataPromise) {
         writes.push(
           options.capturedRscDataPromise.then((rscData) =>
-            options.isrSet(
+            setAppPageCacheEntry(
+              options.isrSet,
               rscKey,
               buildAppPageCacheValue("", rscData, 200, rscRenderObservation),
               cachePolicy.revalidateSeconds,
               pageTags,
               cachePolicy.expireSeconds,
+              cachePolicy.staleSeconds,
             ),
           ),
         );
@@ -257,6 +283,7 @@ export function scheduleAppPageRscCacheWrite(
     options.mountedSlotsHeader,
     options.renderMode,
     options.interceptionContext,
+    options.segmentPrefetchPath,
   );
   const cachePromise = (async () => {
     try {
@@ -284,12 +311,14 @@ export function scheduleAppPageRscCacheWrite(
         cacheTags: pageTags,
         state: observationState,
       });
-      await options.isrSet(
+      await setAppPageCacheEntry(
+        options.isrSet,
         rscKey,
         buildAppPageCacheValue("", rscData, 200, rscRenderObservation),
         cachePolicy.revalidateSeconds,
         pageTags,
         cachePolicy.expireSeconds,
+        cachePolicy.staleSeconds,
       );
       options.isrDebug?.("RSC cache written", rscKey);
     } catch (cacheError) {

packages/vinext/src/server/app-page-cache-render.ts

@@ -155,7 +155,7 @@ export async function renderAppPageCacheArtifacts(
     tags,
     cacheControl:
       typeof cacheLife?.revalidate === "number"
-        ? { revalidate: cacheLife.revalidate, expire: cacheLife.expire }
+        ? { revalidate: cacheLife.revalidate, stale: cacheLife.stale, expire: cacheLife.expire }
         : undefined,
   };