vinext 1.0.0-beta.8 → 1.0.0

package/dist/server/app-route-handler-dispatch.js

@@ -1,20 +1,25 @@
 import { closeAfterResponse, createRequestContext, runWithRequestContext } from "../shims/unified-request-context.js";
+import "../utils/protocol-headers.js";
 import { getRequestExecutionContext } from "../shims/request-context.js";
 import { reportRequestError } from "./instrumentation.js";
+import { beginRouteCacheability, getRouteCacheabilityDynamicReason } from "../shims/cacheability-classification.js";
+import { applyCdnResponseBuildIdentityHeaders } from "./cache-control.js";
+import { isOnDemandRevalidateRequest } from "./revalidation-request.js";
 import { consumeDynamicUsage, getActiveDraftModeState, getAndClearPendingCookies, getDraftModeCookieHeader, isDraftModeRequest, markDynamicUsage, setHeadersAccessPhase } from "../shims/headers.js";
 import { _drainPendingRevalidations } from "../shims/cache-request-state.js";
 import { ensureFetchPatch, getCollectedFetchTags, setCurrentFetchCacheMode, setCurrentFetchRevalidate, setCurrentFetchSoftTags, setCurrentForceDynamicFetchDefault } from "../shims/fetch-cache.js";
 import { setNavigationContext } from "../shims/navigation-context-state.js";
 import { makeThenableParams } from "../shims/thenable-params.js";
+import { traceResponseStart } from "./response-start-tracing.js";
 import { buildPageCacheTags } from "./implicit-tags.js";
 import { applyRouteHandlerMiddlewareContext, finalizeRouteHandlerResponse } from "./app-route-handler-response.js";
+import { resolveAppRouteHandlerFetchCacheMode } from "./app-segment-config.js";
 import "../shims/navigation.js";
 import { isKnownDynamicAppRoute, isValidHTTPMethod } from "./app-route-handler-runtime.js";
+import { getAppRouteHandlerRevalidateSeconds, hasAppRouteHandlerDefaultExport, hasNonStaticAppRouteHandlerMethods, resolveAppRouteHandlerMethod, shouldReadAppRouteHandlerCache } from "./app-route-handler-policy.js";
 import { createStaticGenerationHeadersContext } from "./app-static-generation.js";
-import { getAppRouteHandlerRevalidateSeconds, hasAppRouteHandlerDefaultExport, resolveAppRouteHandlerMethod, shouldReadAppRouteHandlerCache } from "./app-route-handler-policy.js";
 import { applyDraftModeCachePolicy, executeAppRouteHandler } from "./app-route-handler-execution.js";
 import { readAppRouteHandlerCacheResponse } from "./app-route-handler-cache.js";
-import { resolveAppRouteHandlerFetchCacheMode } from "./app-segment-config.js";
 //#region src/server/app-route-handler-dispatch.ts
 function isAppRouteHandlerFunction(value) {
 	return typeof value === "function";
@@ -23,14 +28,15 @@ function buildRouteHandlerPageCacheTags(pathname, extraTags, routeSegments) {
 	return buildPageCacheTags(pathname, extraTags, routeSegments, "route");
 }
 async function runInRouteHandlerRevalidationContext(options, renderFn) {
+	const headersContext = createStaticGenerationHeadersContext({
+		draftModeEnabled: false,
+		draftModeSecret: options.draftModeSecret,
+		dynamicConfig: options.dynamicConfig,
+		routeKind: "route",
+		routePattern: options.routePattern
+	});
 	const requestContext = createRequestContext({
-		headersContext: createStaticGenerationHeadersContext({
-			draftModeEnabled: false,
-			draftModeSecret: options.draftModeSecret,
-			dynamicConfig: options.dynamicConfig,
-			routeKind: "route",
-			routePattern: options.routePattern
-		}),
+		headersContext,
 		executionContext: getRequestExecutionContext(),
 		unstableCacheRevalidation: "foreground"
 	});
@@ -53,10 +59,15 @@ async function runInRouteHandlerRevalidationContext(options, renderFn) {
 	}
 }
 async function dispatchAppRouteHandler(options) {
+	return traceResponseStart(await dispatchAppRouteHandlerImpl(options));
+}
+async function dispatchAppRouteHandlerImpl(options) {
 	const { route } = options;
 	const handler = route.routeHandler;
 	const method = options.request.method.toUpperCase();
-	const revalidateSeconds = getAppRouteHandlerRevalidateSeconds(handler);
+	if (method === "GET" || method === "HEAD") beginRouteCacheability("app-route", route.pattern);
+	const configuredRevalidateSeconds = getAppRouteHandlerRevalidateSeconds(handler);
+	const revalidateSeconds = hasNonStaticAppRouteHandlerMethods(handler) ? null : configuredRevalidateSeconds;
 	const isDevelopment = options.isDevelopment ?? process.env.NODE_ENV === "development";
 	const isProduction = options.isProduction ?? process.env.NODE_ENV === "production";
 	const appendResponseLink = handler.runtime === "edge" || handler.runtime === "experimental-edge";
@@ -70,7 +81,7 @@ async function dispatchAppRouteHandler(options) {
 			isHead
 		});
 		options.clearRequestContext();
-		return applyDraftModeCachePolicy(applyRouteHandlerMiddlewareContext(finalized, options.middlewareContext, { appendResponseLink }), isDraftMode || hasDraftModeTransition);
+		return applyCdnResponseBuildIdentityHeaders(applyDraftModeCachePolicy(applyRouteHandlerMiddlewareContext(finalized, options.middlewareContext, { appendResponseLink }), isDraftMode || hasDraftModeTransition));
 	};
 	if (hasAppRouteHandlerDefaultExport(handler) && isDevelopment) console.error("[vinext] Detected default export in route handler " + route.pattern + ". Export a named export for each HTTP method instead.");
 	if (!isValidHTTPMethod(method)) return finalizeFrameworkResponse(new Response(null, { status: 400 }));
@@ -80,11 +91,7 @@ async function dispatchAppRouteHandler(options) {
 		headers: { Allow: allowHeaderForOptions }
 	}));
 	const resolvedHandlerFn = isAppRouteHandlerFunction(handlerFn) ? handlerFn : void 0;
-	const fetchCacheMode = resolveAppRouteHandlerFetchCacheMode(handler);
-	setCurrentFetchCacheMode(fetchCacheMode);
-	setCurrentFetchRevalidate(revalidateSeconds);
-	setCurrentForceDynamicFetchDefault(handler.dynamic === "force-dynamic");
-	if (revalidateSeconds !== null && shouldReadAppRouteHandlerCache({
+	const shouldReadRouteCache = options.bypassSharedCache !== true && revalidateSeconds !== null && !getRouteCacheabilityDynamicReason() && shouldReadAppRouteHandlerCache({
 		dynamicConfig: handler.dynamic,
 		handlerFn: resolvedHandlerFn,
 		isAutoHead,
@@ -93,7 +100,13 @@ async function dispatchAppRouteHandler(options) {
 		isProduction,
 		method,
 		revalidateSeconds
-	}) && resolvedHandlerFn) {
+	});
+	const revalidateReason = isOnDemandRevalidateRequest(options.request.headers.get("x-prerender-revalidate")) ? "on-demand" : shouldReadRouteCache ? "stale" : void 0;
+	const fetchCacheMode = resolveAppRouteHandlerFetchCacheMode(handler);
+	setCurrentFetchCacheMode(fetchCacheMode);
+	setCurrentFetchRevalidate(configuredRevalidateSeconds);
+	setCurrentForceDynamicFetchDefault(handler.dynamic === "force-dynamic");
+	if (shouldReadRouteCache && resolvedHandlerFn) {
 		const cachedRouteResponse = await readAppRouteHandlerCacheResponse({
 			basePath: options.basePath,
 			buildPageCacheTags(pathname, extraTags) {
@@ -142,47 +155,52 @@ async function dispatchAppRouteHandler(options) {
 			setHeadersAccessPhase,
 			setNavigationContext
 		});
-		if (cachedRouteResponse) return cachedRouteResponse;
+		if (cachedRouteResponse) return applyCdnResponseBuildIdentityHeaders(cachedRouteResponse);
+	}
+	if (resolvedHandlerFn) {
+		const response = await executeAppRouteHandler({
+			basePath: options.basePath,
+			bypassSharedCache: options.bypassSharedCache,
+			buildPageCacheTags(pathname, extraTags) {
+				return buildRouteHandlerPageCacheTags(pathname, extraTags, route.routeSegments);
+			},
+			cleanPathname: options.cleanPathname,
+			clearRequestContext: options.clearRequestContext,
+			consumeDynamicUsage,
+			draftModeSecret: options.draftModeSecret,
+			executionContext: getRequestExecutionContext(),
+			getAndClearPendingCookies,
+			getCollectedFetchTags,
+			getActiveDraftModeState,
+			getDraftModeCookieHeader,
+			handler,
+			handlerFn: resolvedHandlerFn,
+			i18n: options.i18n,
+			trailingSlash: options.trailingSlash,
+			isAutoHead,
+			initialDraftModeCookie,
+			isDraftMode,
+			isProduction,
+			isrDebug: options.isrDebug,
+			isrRouteKey: options.isrRouteKey,
+			isrSet: options.isrSet,
+			markDynamicUsage,
+			method,
+			middlewareContext: options.middlewareContext,
+			middlewareRequestHeaders: options.middlewareRequestHeaders,
+			params: options.params === null ? null : makeThenableParams(options.params),
+			reportRequestError(error, request, context) {
+				return reportRequestError(error, request, context);
+			},
+			request: options.request,
+			expireSeconds: options.expireSeconds,
+			revalidateSeconds,
+			revalidateReason,
+			routePattern: route.pattern,
+			setHeadersAccessPhase
+		});
+		return applyCdnResponseBuildIdentityHeaders(response);
 	}
-	if (resolvedHandlerFn) return executeAppRouteHandler({
-		basePath: options.basePath,
-		buildPageCacheTags(pathname, extraTags) {
-			return buildRouteHandlerPageCacheTags(pathname, extraTags, route.routeSegments);
-		},
-		cleanPathname: options.cleanPathname,
-		clearRequestContext: options.clearRequestContext,
-		consumeDynamicUsage,
-		draftModeSecret: options.draftModeSecret,
-		executionContext: getRequestExecutionContext(),
-		getAndClearPendingCookies,
-		getCollectedFetchTags,
-		getActiveDraftModeState,
-		getDraftModeCookieHeader,
-		handler,
-		handlerFn: resolvedHandlerFn,
-		i18n: options.i18n,
-		trailingSlash: options.trailingSlash,
-		isAutoHead,
-		initialDraftModeCookie,
-		isDraftMode,
-		isProduction,
-		isrDebug: options.isrDebug,
-		isrRouteKey: options.isrRouteKey,
-		isrSet: options.isrSet,
-		markDynamicUsage,
-		method,
-		middlewareContext: options.middlewareContext,
-		middlewareRequestHeaders: options.middlewareRequestHeaders,
-		params: options.params === null ? null : makeThenableParams(options.params),
-		reportRequestError(error, request, context) {
-			reportRequestError(error, request, context);
-		},
-		request: options.request,
-		expireSeconds: options.expireSeconds,
-		revalidateSeconds,
-		routePattern: route.pattern,
-		setHeadersAccessPhase
-	});
 	return finalizeFrameworkResponse(new Response(null, { status: 405 }));
 }
 //#endregion

package/dist/server/app-route-handler-execution.d.ts

@@ -1,15 +1,16 @@
 import { NextI18nConfig } from "../config/next-config.js";
 import { ExecutionContextLike } from "../shims/request-context.js";
 import { NextRequest } from "../shims/server.js";
+import { FrameworkSpan } from "./framework-tracer.js";
 import { CachedRouteValue } from "../shims/cache-handler.js";
 import { IsrWritePolicy } from "./isr-cache.js";
 import { HeadersAccessPhase } from "../shims/headers.js";
 import { RouteHandlerMiddlewareContext } from "./app-route-handler-response.js";
 import { AppRouteHandlerModule } from "./app-route-handler-policy.js";
 //#region src/server/app-route-handler-execution.d.ts
-type AppRouteParams = Record<string, string | string[]>;
-type AppRouteDynamicUsageFn = () => boolean;
-type MarkAppRouteDynamicUsageFn = () => void;
+export type AppRouteParams = Record<string, string | string[]>;
+export type AppRouteDynamicUsageFn = () => boolean;
+export type MarkAppRouteDynamicUsageFn = () => void;
 /**
  * Route handler context.
  *
@@ -21,11 +22,11 @@ type MarkAppRouteDynamicUsageFn = () => void;
  * See: test/e2e/app-dir/app-routes/app-custom-routes.test.ts in Next.js for
  * the authoritative assertion (`expect(meta.params).toEqual(null)`).
  */
-type AppRouteHandlerFunction = (request: NextRequest, context: {
+export type AppRouteHandlerFunction = (request: NextRequest, context: {
   params: AppRouteParams | null;
 }) => Response | Promise<Response>;
-type RouteHandlerCacheSetter = (key: string, data: CachedRouteValue, policy: IsrWritePolicy) => Promise<void>;
-type AppRouteErrorReporter = (error: Error, request: {
+export type RouteHandlerCacheSetter = (key: string, data: CachedRouteValue, policy: IsrWritePolicy) => Promise<void>;
+type AppRouteErrorReporter = (error: unknown, request: {
   path: string;
   method: string;
   headers: Record<string, string>;
@@ -33,8 +34,9 @@ type AppRouteErrorReporter = (error: Error, request: {
   routerKind: "App Router";
   routePath: string;
   routeType: "route";
-}) => void;
-type AppRouteDebugLogger = (event: string, detail: string) => void;
+  revalidateReason: "on-demand" | "stale" | undefined;
+}) => void | Promise<void>;
+export type AppRouteDebugLogger = (event: string, detail: string) => void;
 type RunAppRouteHandlerOptions = {
   basePath?: string;
   consumeDynamicUsage: AppRouteDynamicUsageFn;
@@ -56,12 +58,14 @@ type RunAppRouteHandlerOptions = {
   setHeadersAccessPhase?: (phase: HeadersAccessPhase) => HeadersAccessPhase;
 };
 type RunAppRouteHandlerResult = {
+  didAccessDynamicRequest: () => boolean;
   dynamicUsedInHandler: boolean;
   response: Response;
 };
-declare function applyDraftModeCachePolicy(response: Response, isDraftMode: boolean): Response;
+export declare function applyDraftModeCachePolicy(response: Response, isDraftMode: boolean): Response;
 type ExecuteAppRouteHandlerOptions = {
   buildPageCacheTags: (pathname: string, extraTags: string[]) => string[];
+  bypassSharedCache?: boolean;
   clearRequestContext: () => void;
   cleanPathname: string;
   executionContext: ExecutionContextLike | null;
@@ -82,10 +86,11 @@ type ExecuteAppRouteHandlerOptions = {
   reportRequestError: AppRouteErrorReporter;
   expireSeconds?: number;
   revalidateSeconds: number | null;
+  revalidateReason?: "on-demand" | "stale";
   routePattern: string;
   setHeadersAccessPhase: (phase: HeadersAccessPhase) => HeadersAccessPhase;
 } & RunAppRouteHandlerOptions;
-declare function runAppRouteHandler(options: RunAppRouteHandlerOptions): Promise<RunAppRouteHandlerResult>;
-declare function executeAppRouteHandler(options: ExecuteAppRouteHandlerOptions): Promise<Response>;
-//#endregion
-export { AppRouteDebugLogger, AppRouteDynamicUsageFn, AppRouteHandlerFunction, AppRouteParams, MarkAppRouteDynamicUsageFn, RouteHandlerCacheSetter, applyDraftModeCachePolicy, executeAppRouteHandler, runAppRouteHandler };
+export declare function runAppRouteHandler(options: RunAppRouteHandlerOptions): Promise<RunAppRouteHandlerResult>;
+export declare function executeAppRouteHandler(options: ExecuteAppRouteHandlerOptions): Promise<Response>;
+export declare function traceAppRouteHandlerExecution<T>(routePattern: string, callback: (span: FrameworkSpan) => T): T;
+//#endregion

package/dist/server/app-route-handler-execution.js

@@ -1,15 +1,79 @@
-import { NEVER_CACHE_CONTROL, applyCdnResponseHeaders } from "./cache-control.js";
+import { patternToNextFormat } from "../routing/route-validation.js";
+import { frameworkTracer } from "./tracer.js";
+import { getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityResponseBodyComplete } from "../shims/cacheability-classification.js";
+import { NEVER_CACHE_CONTROL, applyCdnResponseHeaders, hasCdnResponsePolicy, hasExplicitNonCacheableResponsePolicy } from "./cache-control.js";
 import { isrCacheControl } from "./isr-cache.js";
 import { isDraftModeRequest, setHeadersContext } from "../shims/headers.js";
 import { _drainPendingRevalidations } from "../shims/cache-request-state.js";
 import { copyLinkHeaderProvenance } from "./app-response-header-provenance.js";
 import { applyRouteHandlerMiddlewareContext, applyRouteHandlerRevalidateHeader, assertSupportedAppRouteHandlerResponse, buildAppRouteCacheValue, finalizeRouteHandlerResponse, markRouteHandlerCacheMiss } from "./app-route-handler-response.js";
-import { runWithRootParamsUsage } from "../shims/root-params.js";
 import { isPossibleAppRouteActionRequest } from "./app-action-request.js";
+import { runWithRootParamsUsage } from "../shims/root-params.js";
 import { createTrackedAppRouteRequest, markKnownDynamicAppRoute } from "./app-route-handler-runtime.js";
+import { resolveAppRouteHandlerSpecialError, shouldApplyAppRouteHandlerRevalidateHeader, shouldCompleteAppRouteHandlerResponse, shouldWriteAppRouteHandlerCache } from "./app-route-handler-policy.js";
 import { createStaticGenerationHeadersContext, getAppRouteStaticGenerationErrorMessage } from "./app-static-generation.js";
-import { resolveAppRouteHandlerSpecialError, shouldApplyAppRouteHandlerRevalidateHeader, shouldWriteAppRouteHandlerCache } from "./app-route-handler-policy.js";
+import { CACHEABILITY_ADMISSION_RESPONSE_BODY_LIMIT } from "./cacheability-limits.js";
 //#region src/server/app-route-handler-execution.ts
+function hasExplicitCacheableResponsePolicy(headers) {
+	return !hasExplicitNonCacheableResponsePolicy(headers) && hasCdnResponsePolicy(headers);
+}
+async function completeAppRouteHandlerResponse(response) {
+	const { captureCacheabilityAdmissionBody } = await import("./cacheability-request.js");
+	const captureOptions = getRouteCacheabilityCaptureOptions();
+	const captured = await captureCacheabilityAdmissionBody(response.body, captureOptions?.captureDeadlineAt ?? Date.now() + 2e4, CACHEABILITY_ADMISSION_RESPONSE_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, cleanup) {
+	if (!response.body) {
+		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({
+		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;
+}
 function applyDraftModeCachePolicy(response, isDraftMode) {
 	if (!isDraftMode) return response;
 	const headers = new Headers(response.headers);
@@ -24,8 +88,9 @@ function applyDraftModeCachePolicy(response, isDraftMode) {
 }
 function configureAppRouteStaticGenerationContext(options) {
 	if (options.dynamicConfig === "force-static" || options.dynamicConfig === "error") {
+		const isDraftMode = options.isDraftMode ?? (options.draftModeSecret !== void 0 && isDraftModeRequest(options.request, options.draftModeSecret));
 		setHeadersContext(createStaticGenerationHeadersContext({
-			draftModeEnabled: options.isDraftMode ?? (options.draftModeSecret !== void 0 && isDraftModeRequest(options.request, options.draftModeSecret)),
+			draftModeEnabled: isDraftMode,
 			draftModeSecret: options.draftModeSecret,
 			dynamicConfig: options.dynamicConfig,
 			routeKind: "route",
@@ -50,41 +115,116 @@ async function runAppRouteHandler(options) {
 			return getAppRouteStaticGenerationErrorMessage(options.routePattern, expression);
 		}
 	});
+	const routePattern = options.routePattern ?? new URL(options.request.url).pathname;
 	const response = await runWithRootParamsUsage({
 		kind: "route-handler",
-		routePattern: options.routePattern ?? new URL(options.request.url).pathname
+		routePattern
 	}, () => options.handlerFn(trackedRequest.request, { params: options.params }));
+	const dynamicUsedInContext = options.consumeDynamicUsage();
 	return {
-		dynamicUsedInHandler: options.consumeDynamicUsage(),
+		didAccessDynamicRequest: () => trackedRequest.didAccessDynamicRequest(),
+		dynamicUsedInHandler: trackedRequest.didAccessDynamicRequest() || dynamicUsedInContext,
 		response
 	};
 }
 async function executeAppRouteHandler(options) {
+	return executeAppRouteHandlerImpl(options);
+}
+function traceAppRouteHandlerExecution(routePattern, callback) {
+	const route = patternToNextFormat(routePattern);
+	return frameworkTracer.trace({
+		attributes: { "next.route": route },
+		name: `executing api route (app) ${route}`,
+		type: "AppRouteRouteHandlers.runHandler"
+	}, callback);
+}
+async function executeAppRouteHandlerImpl(options) {
 	const previousHeadersPhase = options.setHeadersAccessPhase("route-handler");
+	let cleanupDeferredToBody = false;
 	const middlewareMergeOptions = { appendResponseLink: options.handler.runtime === "edge" || options.handler.runtime === "experimental-edge" };
 	try {
-		let handlerResult;
+		let tracedResult;
+		let traceError;
+		let traceFailed = false;
+		let pendingRevalidations = Promise.resolve();
 		try {
-			handlerResult = await runAppRouteHandler({
-				...options,
-				dynamicConfig: options.handler.dynamic
+			tracedResult = await traceAppRouteHandlerExecution(options.routePattern, async () => {
+				try {
+					try {
+						return {
+							kind: "handler",
+							handlerResult: await runAppRouteHandler({
+								...options,
+								dynamicConfig: options.handler.dynamic
+							})
+						};
+					} catch (error) {
+						if (resolveAppRouteHandlerSpecialError(error, options.request.url, { isAction: isPossibleAppRouteActionRequest(options.request) })) return {
+							kind: "special",
+							error
+						};
+						throw error;
+					}
+				} finally {
+					pendingRevalidations = _drainPendingRevalidations();
+					pendingRevalidations.catch(() => {});
+				}
 			});
-		} finally {
-			await _drainPendingRevalidations();
+		} catch (error) {
+			traceFailed = true;
+			traceError = error;
+		}
+		let revalidationError;
+		let revalidationFailed = false;
+		try {
+			await pendingRevalidations;
+		} catch (error) {
+			revalidationFailed = true;
+			revalidationError = error;
 		}
-		const { dynamicUsedInHandler, response } = handlerResult;
+		if (traceFailed) throw traceError;
+		if (revalidationFailed) throw revalidationError;
+		if (!tracedResult) throw new Error("App Route Handler tracing completed without a result");
+		if (tracedResult.kind === "special") throw tracedResult.error;
+		const handlerResult = tracedResult.handlerResult;
+		let { dynamicUsedInHandler, response } = handlerResult;
 		assertSupportedAppRouteHandlerResponse(response);
-		const handlerSetCacheControl = response.headers.has("cache-control");
+		const handlerSetCachePolicy = hasCdnResponsePolicy(response.headers);
+		const hasExplicitCacheablePolicy = hasExplicitCacheableResponsePolicy(response.headers);
+		if (hasExplicitCacheablePolicy) markRouteCacheabilityExplicitResponsePolicy();
+		const draftModeBeforeCompletion = options.getActiveDraftModeState?.() ?? options.isDraftMode === true;
+		const handlerDraftCookieBeforeCompletion = options.getDraftModeCookieHeader() ?? options.initialDraftModeCookie;
+		if (shouldCompleteAppRouteHandlerResponse({
+			dynamicConfig: options.handler.dynamic,
+			dynamicUsedInHandler,
+			hasExplicitCacheablePolicy,
+			handlerSetCachePolicy,
+			isAutoHead: options.isAutoHead,
+			isDraftMode: draftModeBeforeCompletion || handlerDraftCookieBeforeCompletion != null,
+			isProduction: options.isProduction,
+			method: options.method,
+			revalidateSeconds: options.revalidateSeconds,
+			requiresCompletedResponseAdmission: isRouteCacheabilityEvaluation()
+		})) {
+			const completed = await completeAppRouteHandlerResponse(response);
+			response = completed.response;
+			cleanupDeferredToBody = !completed.completed;
+			if (completed.completed) markRouteCacheabilityResponseBodyComplete();
+			const dynamicUsedDuringCompletion = options.consumeDynamicUsage();
+			dynamicUsedInHandler = handlerResult.didAccessDynamicRequest() || dynamicUsedDuringCompletion || dynamicUsedInHandler;
+		}
+		const requestCacheabilityVeto = getRouteCacheabilityDynamicReason();
+		const responseMustStayPrivate = Boolean(options.bypassSharedCache === true || options.handler.dynamic === "force-dynamic" || 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 shouldApplyDraftPolicy = (options.getActiveDraftModeState?.() ?? options.isDraftMode === true) || draftCookie != null;
 		if (handlerDraftCookie != null) markKnownDynamicAppRoute(options.routePattern);
 		const routeTags = options.buildPageCacheTags(options.cleanPathname, options.getCollectedFetchTags());
 		if (shouldApplyAppRouteHandlerRevalidateHeader({
-			dynamicUsedInHandler,
-			handlerSetCacheControl,
+			dynamicUsedInHandler: responseMustStayPrivate,
+			handlerSetCachePolicy,
 			isAutoHead: options.isAutoHead,
 			isDraftMode: shouldApplyDraftPolicy,
 			method: options.method,
@@ -96,8 +236,8 @@ async function executeAppRouteHandler(options) {
 		}
 		if (shouldWriteAppRouteHandlerCache({
 			dynamicConfig: options.handler.dynamic,
-			dynamicUsedInHandler,
-			handlerSetCacheControl,
+			dynamicUsedInHandler: responseMustStayPrivate,
+			handlerSetCachePolicy,
 			isAutoHead: options.isAutoHead,
 			isDraftMode: shouldApplyDraftPolicy,
 			isProduction: options.isProduction,
@@ -123,12 +263,35 @@ async function executeAppRouteHandler(options) {
 			})();
 			options.executionContext?.waitUntil(routeWritePromise);
 		}
-		options.clearRequestContext();
-		return applyDraftModeCachePolicy(applyRouteHandlerMiddlewareContext(finalizeRouteHandlerResponse(response, {
+		let finalized = applyDraftModeCachePolicy(applyRouteHandlerMiddlewareContext(finalizeRouteHandlerResponse(response, {
 			pendingCookies,
 			draftCookie,
 			isHead: options.isAutoHead
 		}), options.middlewareContext, middlewareMergeOptions), shouldApplyDraftPolicy);
+		const preserveHandlerPolicy = isRouteCacheabilityEvaluation() ? hasExplicitCacheablePolicy : handlerSetCachePolicy;
+		if (options.bypassSharedCache === true || responseMustStayPrivate && !preserveHandlerPolicy) {
+			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();
@@ -149,19 +312,20 @@ async function executeAppRouteHandler(options) {
 			return applyDraftModeCachePolicy(applyRouteHandlerMiddlewareContext(new Response(null, { status: specialError.statusCode }), options.middlewareContext, middlewareMergeOptions), shouldApplyDraftPolicy);
 		}
 		console.error("[vinext] Route handler error:", error);
-		options.reportRequestError(error instanceof Error ? error : new Error(String(error)), {
+		await options.reportRequestError(error, {
 			path: options.cleanPathname,
 			method: options.request.method,
 			headers: Object.fromEntries(options.request.headers.entries())
 		}, {
 			routerKind: "App Router",
 			routePath: options.routePattern,
-			routeType: "route"
+			routeType: "route",
+			revalidateReason: options.revalidateReason
 		});
 		return applyDraftModeCachePolicy(applyRouteHandlerMiddlewareContext(new Response(null, { status: 500 }), options.middlewareContext, middlewareMergeOptions), shouldApplyDraftPolicy);
 	} finally {
-		options.setHeadersAccessPhase(previousHeadersPhase);
+		if (!cleanupDeferredToBody) options.setHeadersAccessPhase(previousHeadersPhase);
 	}
 }
 //#endregion
-export { applyDraftModeCachePolicy, executeAppRouteHandler, runAppRouteHandler };
+export { applyDraftModeCachePolicy, executeAppRouteHandler, runAppRouteHandler, traceAppRouteHandlerExecution };

package/dist/server/app-route-handler-middleware-context.d.ts

@@ -0,0 +1,8 @@
+//#region src/server/app-route-handler-middleware-context.d.ts
+export type RouteHandlerMiddlewareContext = {
+  headers: Headers | null;
+  status: number | null;
+};
+/** Apply request-stage middleware response metadata to a route-handler response. */
+export declare function applyRouteHandlerMiddlewareContext(response: Response, middlewareContext: RouteHandlerMiddlewareContext): Response;
+//#endregion

package/dist/server/app-route-handler-middleware-context.js

@@ -0,0 +1,15 @@
+import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
+//#region src/server/app-route-handler-middleware-context.ts
+/** Apply request-stage middleware response metadata to a route-handler response. */
+function applyRouteHandlerMiddlewareContext(response, middlewareContext) {
+	if (!middlewareContext.headers && middlewareContext.status == null) return response;
+	const responseHeaders = new Headers(response.headers);
+	mergeMiddlewareResponseHeaders(responseHeaders, middlewareContext.headers);
+	return new Response(response.body, {
+		status: middlewareContext.status ?? response.status,
+		statusText: response.statusText,
+		headers: responseHeaders
+	});
+}
+//#endregion
+export { applyRouteHandlerMiddlewareContext };

package/dist/server/app-route-handler-policy.d.ts

@@ -1,9 +1,10 @@
 import { isPossibleAppRouteActionRequest } from "./app-action-request.js";
 import { RouteHandlerHttpMethod, RouteHandlerModule } from "./app-route-handler-runtime.js";
 //#region src/server/app-route-handler-policy.d.ts
-type AppRouteHandlerModule = {
+export type AppRouteHandlerModule = {
   dynamic?: string;
   fetchCache?: unknown;
+  generateStaticParams?: unknown;
   revalidate?: unknown;
   runtime?: string;
 } & RouteHandlerModule;
@@ -28,12 +29,14 @@ type AppRouteHandlerCacheReadOptions = {
 type AppRouteHandlerResponseCacheOptions = {
   dynamicConfig?: string;
   dynamicUsedInHandler: boolean;
-  handlerSetCacheControl: boolean;
+  hasExplicitCacheablePolicy?: boolean;
+  handlerSetCachePolicy: boolean;
   isAutoHead: boolean;
   isDraftMode?: boolean;
   isProduction: boolean;
   method: string;
   revalidateSeconds: number | null;
+  requiresCompletedResponseAdmission?: boolean;
 };
 type AppRouteHandlerSpecialError = {
   kind: "redirect";
@@ -46,12 +49,21 @@ type AppRouteHandlerSpecialError = {
 type AppRouteHandlerSpecialErrorOptions = {
   isAction: boolean;
 };
-declare function getAppRouteHandlerRevalidateSeconds(handler: Pick<AppRouteHandlerModule, "revalidate">): number | null;
-declare function hasAppRouteHandlerDefaultExport(handler: RouteHandlerModule): boolean;
-declare function resolveAppRouteHandlerMethod(handler: AppRouteHandlerModule, method: string): ResolvedAppRouteHandlerMethod;
-declare function shouldReadAppRouteHandlerCache(options: AppRouteHandlerCacheReadOptions): boolean;
-declare function shouldApplyAppRouteHandlerRevalidateHeader(options: Omit<AppRouteHandlerResponseCacheOptions, "dynamicConfig" | "isProduction">): boolean;
-declare function shouldWriteAppRouteHandlerCache(options: AppRouteHandlerResponseCacheOptions): boolean;
-declare function resolveAppRouteHandlerSpecialError(error: unknown, requestUrl: string, options?: AppRouteHandlerSpecialErrorOptions): AppRouteHandlerSpecialError | null;
+export declare function getAppRouteHandlerRevalidateSeconds(handler: Pick<AppRouteHandlerModule, "dynamic" | "generateStaticParams" | "revalidate">): number | null;
+export declare function hasAppRouteHandlerDefaultExport(handler: RouteHandlerModule): boolean;
+/** Match Next.js methods that force an App Route out of static generation. */
+export declare function hasNonStaticAppRouteHandlerMethods(handler: RouteHandlerModule): boolean;
+export declare function resolveAppRouteHandlerMethod(handler: AppRouteHandlerModule, method: string): ResolvedAppRouteHandlerMethod;
+export declare function shouldReadAppRouteHandlerCache(options: AppRouteHandlerCacheReadOptions): boolean;
+export declare function shouldApplyAppRouteHandlerRevalidateHeader(options: Omit<AppRouteHandlerResponseCacheOptions, "dynamicConfig" | "isProduction">): boolean;
+/**
+ * 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 declare function shouldCompleteAppRouteHandlerResponse(options: AppRouteHandlerResponseCacheOptions): boolean;
+export declare function shouldWriteAppRouteHandlerCache(options: AppRouteHandlerResponseCacheOptions): boolean;
+export declare function resolveAppRouteHandlerSpecialError(error: unknown, requestUrl: string, options?: AppRouteHandlerSpecialErrorOptions): AppRouteHandlerSpecialError | null;
 //#endregion
-export { AppRouteHandlerModule, getAppRouteHandlerRevalidateSeconds, hasAppRouteHandlerDefaultExport, isPossibleAppRouteActionRequest, resolveAppRouteHandlerMethod, resolveAppRouteHandlerSpecialError, shouldApplyAppRouteHandlerRevalidateHeader, shouldReadAppRouteHandlerCache, shouldWriteAppRouteHandlerCache };
+export { isPossibleAppRouteActionRequest };