fix(cache): complete cacheable route handler responses

Author: james-elicx

packages/vinext/src/server/app-route-handler-dispatch.ts

@@ -43,6 +43,10 @@ import {
   type RouteHandlerCacheSetter,
 } from "./app-route-handler-execution.js";
 import { isKnownDynamicAppRoute, isValidHTTPMethod } from "./app-route-handler-runtime.js";
+import {
+  beginRouteCacheability,
+  getRouteCacheabilityDynamicReason,
+} from "vinext/shims/cacheability-classification";
 import {
   applyRouteHandlerMiddlewareContext,
   finalizeRouteHandlerResponse,
@@ -169,6 +173,9 @@ export async function dispatchAppRouteHandler(
   const { route } = options;
   const handler = route.routeHandler;
   const method = options.request.method.toUpperCase();
+  if (method === "GET" || method === "HEAD") {
+    beginRouteCacheability("app-route", route.pattern);
+  }
   const revalidateSeconds = getAppRouteHandlerRevalidateSeconds(handler);
   const isDevelopment = options.isDevelopment ?? process.env.NODE_ENV === "development";
   const isProduction = options.isProduction ?? process.env.NODE_ENV === "production";
@@ -240,6 +247,7 @@ export async function dispatchAppRouteHandler(
 
   if (
     revalidateSeconds !== null &&
+    !getRouteCacheabilityDynamicReason() &&
     shouldReadAppRouteHandlerCache({
       dynamicConfig: handler.dynamic,
       handlerFn: resolvedHandlerFn,

packages/vinext/src/server/app-route-handler-execution.ts

@@ -19,6 +19,7 @@ import {
   isPossibleAppRouteActionRequest,
   resolveAppRouteHandlerSpecialError,
   shouldApplyAppRouteHandlerRevalidateHeader,
+  shouldCompleteAppRouteHandlerResponse,
   shouldWriteAppRouteHandlerCache,
   type AppRouteHandlerModule,
 } from "./app-route-handler-policy.js";
@@ -36,6 +37,14 @@ import {
   createTrackedAppRouteRequest,
   markKnownDynamicAppRoute,
 } from "./app-route-handler-runtime.js";
+import {
+  getRouteCacheabilityCaptureOptions,
+  getRouteCacheabilityDynamicReason,
+} from "vinext/shims/cacheability-classification";
+import {
+  CACHEABILITY_PROBE_BODY_LIMIT,
+  CACHEABILITY_PROBE_TIMEOUT_MS,
+} from "./cacheability-limits.js";
 
 export type AppRouteParams = Record<string, string | string[]>;
 export type AppRouteDynamicUsageFn = () => boolean;
@@ -89,10 +98,93 @@ type RunAppRouteHandlerOptions = {
 };
 
 type RunAppRouteHandlerResult = {
+  didAccessDynamicRequest: () => boolean;
   dynamicUsedInHandler: boolean;
   response: Response;
 };
 
+type CompletedAppRouteHandlerResponse = {
+  completed: boolean;
+  response: Response;
+};
+
+async function completeAppRouteHandlerResponse(
+  response: Response,
+): Promise<CompletedAppRouteHandlerResponse> {
+  // Match Next.js static App Route generation: resolve only after clean EOF,
+  // then rebuild the response from the completed body. Besides making the ISR
+  // artifact deterministic, this keeps request tracking active for stream
+  // pulls and turns a late body failure into the normal Route Handler error
+  // path before cacheable response headers are applied.
+  // Workers cannot safely buffer an unbounded or never-ending response. Reuse
+  // admission's isolate-wide bounded capture and fall back to private streaming
+  // when the response exceeds either the size or completion deadline.
+  const { captureCacheabilityAdmissionBody } = await import("./cacheability-request.js");
+  const captureOptions = getRouteCacheabilityCaptureOptions();
+  const captured = await captureCacheabilityAdmissionBody(
+    response.body,
+    captureOptions?.captureDeadlineAt ?? Date.now() + CACHEABILITY_PROBE_TIMEOUT_MS,
+    CACHEABILITY_PROBE_BODY_LIMIT,
+    captureOptions?.captureBudget,
+  );
+  const completed = new Response(captured.body, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+  copyLinkHeaderProvenance(response.headers, completed.headers);
+  return { completed: captured.kind === "captured", response: completed };
+}
+
+function deferAppRouteHandlerCleanup(response: Response, cleanup: () => Promise<void>): Response {
+  if (!response.body) {
+    void cleanup();
+    return response;
+  }
+
+  const reader = response.body.getReader();
+  let cleaned = false;
+  const cleanOnce = async () => {
+    if (cleaned) return;
+    cleaned = true;
+    reader.releaseLock();
+    await cleanup();
+  };
+  const body = new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        try {
+          const result = await reader.read();
+          if (result.done) {
+            await cleanOnce();
+            controller.close();
+          } else {
+            controller.enqueue(result.value);
+          }
+        } catch (error) {
+          await cleanOnce();
+          controller.error(error);
+        }
+      },
+      async cancel(reason) {
+        try {
+          await reader.cancel(reason);
+        } finally {
+          await cleanOnce();
+        }
+      },
+    },
+    { highWaterMark: 0 },
+  );
+  const deferred = new Response(body, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+  copyLinkHeaderProvenance(response.headers, deferred.headers);
+  return deferred;
+}
+
 export function applyDraftModeCachePolicy(response: Response, isDraftMode: boolean): Response {
   if (!isDraftMode) return response;
 
@@ -184,8 +276,10 @@ export async function runAppRouteHandler(
       }),
   );
 
+  const dynamicUsedInContext = options.consumeDynamicUsage();
   return {
-    dynamicUsedInHandler: options.consumeDynamicUsage(),
+    didAccessDynamicRequest: () => trackedRequest.didAccessDynamicRequest(),
+    dynamicUsedInHandler: trackedRequest.didAccessDynamicRequest() || dynamicUsedInContext,
     response,
   };
 }
@@ -194,6 +288,7 @@ export async function executeAppRouteHandler(
   options: ExecuteAppRouteHandlerOptions,
 ): Promise<Response> {
   const previousHeadersPhase = options.setHeadersAccessPhase("route-handler");
+  let cleanupDeferredToBody = false;
   const middlewareMergeOptions = {
     appendResponseLink:
       options.handler.runtime === "edge" || options.handler.runtime === "experimental-edge",
@@ -212,16 +307,48 @@ export async function executeAppRouteHandler(
       // finalization clears the request context.
       await _drainPendingRevalidations();
     }
-    const { dynamicUsedInHandler, response } = handlerResult;
+    let { dynamicUsedInHandler, response } = handlerResult;
     assertSupportedAppRouteHandlerResponse(response);
     const handlerSetCacheControl = response.headers.has("cache-control");
 
+    const draftModeBeforeCompletion =
+      options.getActiveDraftModeState?.() ?? options.isDraftMode === true;
+    const handlerDraftCookieBeforeCompletion =
+      options.getDraftModeCookieHeader() ?? options.initialDraftModeCookie;
+    if (
+      shouldCompleteAppRouteHandlerResponse({
+        dynamicConfig: options.handler.dynamic,
+        dynamicUsedInHandler,
+        handlerSetCacheControl,
+        isAutoHead: options.isAutoHead,
+        isDraftMode: draftModeBeforeCompletion || handlerDraftCookieBeforeCompletion != null,
+        isProduction: options.isProduction,
+        method: options.method,
+        revalidateSeconds: options.revalidateSeconds,
+      })
+    ) {
+      const completed = await completeAppRouteHandlerResponse(response);
+      response = completed.response;
+      cleanupDeferredToBody = !completed.completed;
+      const dynamicUsedDuringCompletion = options.consumeDynamicUsage();
+      dynamicUsedInHandler =
+        handlerResult.didAccessDynamicRequest() ||
+        dynamicUsedDuringCompletion ||
+        dynamicUsedInHandler;
+    }
+
+    const requestCacheabilityVeto = getRouteCacheabilityDynamicReason();
+    const responseMustStayPrivate = Boolean(
+      dynamicUsedInHandler || requestCacheabilityVeto || cleanupDeferredToBody,
+    );
+
     if (dynamicUsedInHandler) {
       markKnownDynamicAppRoute(options.routePattern);
     }
 
     const pendingCookies = options.getAndClearPendingCookies();
-    const handlerDraftCookie = options.getDraftModeCookieHeader();
+    const handlerDraftCookie =
+      options.getDraftModeCookieHeader() ?? handlerDraftCookieBeforeCompletion;
     const draftCookie = handlerDraftCookie ?? options.initialDraftModeCookie;
     const activeDraftMode = options.getActiveDraftModeState?.() ?? options.isDraftMode === true;
     const shouldApplyDraftPolicy = activeDraftMode || draftCookie != null;
@@ -242,7 +369,7 @@ export async function executeAppRouteHandler(
 
     if (
       shouldApplyAppRouteHandlerRevalidateHeader({
-        dynamicUsedInHandler,
+        dynamicUsedInHandler: responseMustStayPrivate,
         handlerSetCacheControl,
         isAutoHead: options.isAutoHead,
         isDraftMode: shouldApplyDraftPolicy,
@@ -265,7 +392,7 @@ export async function executeAppRouteHandler(
     if (
       shouldWriteAppRouteHandlerCache({
         dynamicConfig: options.handler.dynamic,
-        dynamicUsedInHandler,
+        dynamicUsedInHandler: responseMustStayPrivate,
         handlerSetCacheControl,
         isAutoHead: options.isAutoHead,
         isDraftMode: shouldApplyDraftPolicy,
@@ -298,9 +425,7 @@ export async function executeAppRouteHandler(
       options.executionContext?.waitUntil(routeWritePromise);
     }
 
-    options.clearRequestContext();
-
-    return applyDraftModeCachePolicy(
+    let finalized = applyDraftModeCachePolicy(
       applyRouteHandlerMiddlewareContext(
         finalizeRouteHandlerResponse(response, {
           pendingCookies,
@@ -312,6 +437,31 @@ export async function executeAppRouteHandler(
       ),
       shouldApplyDraftPolicy,
     );
+    if (responseMustStayPrivate) {
+      const headers = new Headers(finalized.headers);
+      applyCdnResponseHeaders(headers, { cacheControl: NEVER_CACHE_CONTROL });
+      finalized = new Response(finalized.body, {
+        headers,
+        status: finalized.status,
+        statusText: finalized.statusText,
+      });
+      copyLinkHeaderProvenance(response.headers, finalized.headers);
+    }
+
+    if (!cleanupDeferredToBody) {
+      options.clearRequestContext();
+      return finalized;
+    }
+
+    return deferAppRouteHandlerCleanup(finalized, async () => {
+      try {
+        await _drainPendingRevalidations();
+        options.consumeDynamicUsage();
+      } finally {
+        options.clearRequestContext();
+        options.setHeadersAccessPhase(previousHeadersPhase);
+      }
+    });
   } catch (error) {
     const pendingCookies = options.getAndClearPendingCookies();
     const handlerDraftCookie = options.getDraftModeCookieHeader();
@@ -382,6 +532,6 @@ export async function executeAppRouteHandler(
       shouldApplyDraftPolicy,
     );
   } finally {
-    options.setHeadersAccessPhase(previousHeadersPhase);
+    if (!cleanupDeferredToBody) options.setHeadersAccessPhase(previousHeadersPhase);
   }
 }

packages/vinext/src/server/app-route-handler-policy.ts

@@ -10,6 +10,7 @@ export { isPossibleAppRouteActionRequest } from "./app-action-request.js";
 export type AppRouteHandlerModule = {
   dynamic?: string;
   fetchCache?: unknown;
+  generateStaticParams?: unknown;
   revalidate?: unknown;
   runtime?: string;
 } & RouteHandlerModule;
@@ -62,18 +63,32 @@ type AppRouteHandlerSpecialErrorOptions = {
 };
 
 export function getAppRouteHandlerRevalidateSeconds(
-  handler: Pick<AppRouteHandlerModule, "revalidate">,
+  handler: Pick<AppRouteHandlerModule, "dynamic" | "generateStaticParams" | "revalidate">,
 ): number | null {
   // 0 is a meaningful value ("never cache") and must be preserved so the
   // header path can emit a no-store Cache-Control.
   // revalidate = false means "cache indefinitely" (Next.js segment config
   // parity) — return Infinity to signal the cache-later path.
   const { revalidate } = handler;
   if (revalidate === false) return Infinity;
-  if (typeof revalidate !== "number" || !Number.isFinite(revalidate) || revalidate < 0) {
+  if (typeof revalidate === "number" && Number.isFinite(revalidate) && revalidate >= 0) {
+    return revalidate;
+  }
+  if (revalidate !== undefined) {
     return null;
   }
-  return revalidate;
+
+  // Ported from Next.js static eligibility:
+  // packages/next/src/server/route-modules/app-route/helpers/is-static-gen-enabled.ts
+  if (
+    handler.dynamic === "force-static" ||
+    handler.dynamic === "error" ||
+    typeof handler.generateStaticParams === "function"
+  ) {
+    return Infinity;
+  }
+
+  return null;
 }
 
 export function hasAppRouteHandlerDefaultExport(handler: RouteHandlerModule): boolean {
@@ -144,6 +159,26 @@ export function shouldApplyAppRouteHandlerRevalidateHeader(
   );
 }
 
+/**
+ * Next.js consumes the full body before completing static generation for an
+ * App Route. Keep that completion boundary for every response that can still
+ * receive a public framework cache policy, including
+ * `revalidate = false` (represented by Infinity).
+ */
+export function shouldCompleteAppRouteHandlerResponse(
+  options: AppRouteHandlerResponseCacheOptions,
+): boolean {
+  return (
+    options.isProduction &&
+    options.revalidateSeconds !== null &&
+    options.revalidateSeconds > 0 &&
+    options.dynamicConfig !== "force-dynamic" &&
+    !options.isDraftMode &&
+    !options.dynamicUsedInHandler &&
+    (options.method === "GET" || options.isAutoHead)
+  );
+}
+
 export function shouldWriteAppRouteHandlerCache(
   options: AppRouteHandlerResponseCacheOptions,
 ): boolean {

packages/vinext/src/server/app-router-entry.ts

@@ -56,7 +56,6 @@ import {
 import {
   NEXT_ACTION_HEADER,
   RSC_ACTION_HEADER,
-  RSC_HEADER,
   VINEXT_CACHEABILITY_PROBE_HEADER,
   VINEXT_PRERENDER_ROUTE_PARAMS_HEADER,
   VINEXT_PRERENDER_SECRET_HEADER,
@@ -93,9 +92,7 @@ function isPotentialCompletedAdmissionRequest(request: Request): boolean {
   if (request.method !== "GET" && request.method !== "HEAD") return false;
   if (request.headers.has(NEXT_ACTION_HEADER) || request.headers.has(RSC_ACTION_HEADER))
     return false;
-  if (request.headers.get(RSC_HEADER) === "1") return true;
-  if (request.headers.get("Accept")?.toLowerCase().includes("text/html")) return true;
-  return new URL(request.url).pathname.endsWith(".rsc");
+  return true;
 }
 
 export default {