vinext 1.0.0-beta.9 → 1.0.1

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

@@ -1,15 +1,17 @@
 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 { HeadersAccessPhase } from "../shims/internal/headers-state.js";
+import "../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 +23,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 +35,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;
@@ -60,9 +63,15 @@ type RunAppRouteHandlerResult = {
   dynamicUsedInHandler: boolean;
   response: Response;
 };
-declare function applyDraftModeCachePolicy(response: Response, isDraftMode: boolean): Response;
+type CompletedAppRouteHandlerResponse = {
+  completed: boolean;
+  response: Response;
+};
+export declare function completeAppRouteHandlerResponse(response: Response): Promise<CompletedAppRouteHandlerResponse>;
+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;
@@ -75,6 +84,8 @@ type ExecuteAppRouteHandlerOptions = {
   initialDraftModeCookie?: string | null;
   isDraftMode?: boolean;
   isProduction: boolean;
+  /** An existing entry may require foreground regeneration after hard expiry. */
+  isRevalidation?: boolean;
   isrDebug?: AppRouteDebugLogger;
   isrRouteKey: (pathname: string) => string;
   isrSet: RouteHandlerCacheSetter;
@@ -83,10 +94,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,21 +1,29 @@
-import { NEVER_CACHE_CONTROL, applyCdnResponseHeaders, hasExplicitNonCacheableResponsePolicy } from "./cache-control.js";
-import { isrCacheControl } from "./isr-cache.js";
+import { isFullyBufferedBody } from "./fully-buffered-response.js";
+import { patternToNextFormat } from "../routing/route-validation.js";
+import { frameworkTracer } from "./tracer.js";
+import { getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityResponseBodyComplete, recordRouteCacheability } from "../shims/cacheability-classification.js";
+import { NEVER_CACHE_CONTROL, applyCdnResponseHeaders, hasCdnResponsePolicy, hasExplicitNonCacheableResponsePolicy } from "./cache-control.js";
+import { buildAppRouteMissIsrCacheControl } from "./isr-decision.js";
+import { isrCacheControl, resolveRouteExpireSeconds } 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 { CACHEABILITY_POLICY_HEADERS, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityResponseBodyComplete } from "../shims/cacheability-classification.js";
 import { applyRouteHandlerMiddlewareContext, applyRouteHandlerRevalidateHeader, assertSupportedAppRouteHandlerResponse, buildAppRouteCacheValue, finalizeRouteHandlerResponse, markRouteHandlerCacheMiss } from "./app-route-handler-response.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 { createStaticGenerationHeadersContext, getAppRouteStaticGenerationErrorMessage } from "./app-static-generation.js";
 import { resolveAppRouteHandlerSpecialError, shouldApplyAppRouteHandlerRevalidateHeader, shouldCompleteAppRouteHandlerResponse, shouldWriteAppRouteHandlerCache } from "./app-route-handler-policy.js";
+import { createStaticGenerationHeadersContext, getAppRouteStaticGenerationErrorMessage } from "./app-static-generation.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) && CACHEABILITY_POLICY_HEADERS.some((name) => headers.has(name));
+	return !hasExplicitNonCacheableResponsePolicy(headers) && hasCdnResponsePolicy(headers);
 }
 async function completeAppRouteHandlerResponse(response) {
+	if (isFullyBufferedBody(response)) return {
+		completed: true,
+		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);
@@ -86,8 +94,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",
@@ -112,9 +121,10 @@ 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 {
@@ -124,31 +134,74 @@ async function runAppRouteHandler(options) {
 	};
 }
 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;
 		}
+		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 handlerSetCachePolicy = CACHEABILITY_POLICY_HEADERS.some((name) => response.headers.has(name));
-		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,
+			hasExplicitCacheablePolicy: hasExplicitCacheableResponsePolicy(response.headers),
+			handlerSetCachePolicy: hasCdnResponsePolicy(response.headers),
 			isAutoHead: options.isAutoHead,
 			isDraftMode: draftModeBeforeCompletion || handlerDraftCookieBeforeCompletion != null,
 			isProduction: options.isProduction,
@@ -163,8 +216,11 @@ async function executeAppRouteHandler(options) {
 			const dynamicUsedDuringCompletion = options.consumeDynamicUsage();
 			dynamicUsedInHandler = handlerResult.didAccessDynamicRequest() || dynamicUsedDuringCompletion || dynamicUsedInHandler;
 		}
+		const browserCacheControl = response.headers.get("Cache-Control") ?? void 0;
+		const handlerSetCachePolicy = hasCdnResponsePolicy(response.headers);
+		if (handlerSetCachePolicy) markRouteCacheabilityExplicitResponsePolicy();
 		const requestCacheabilityVeto = getRouteCacheabilityDynamicReason();
-		const responseMustStayPrivate = Boolean(options.handler.dynamic === "force-dynamic" || dynamicUsedInHandler || requestCacheabilityVeto || cleanupDeferredToBody);
+		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() ?? handlerDraftCookieBeforeCompletion;
@@ -172,6 +228,15 @@ async function executeAppRouteHandler(options) {
 		const shouldApplyDraftPolicy = (options.getActiveDraftModeState?.() ?? options.isDraftMode === true) || draftCookie != null;
 		if (handlerDraftCookie != null) markKnownDynamicAppRoute(options.routePattern);
 		const routeTags = options.buildPageCacheTags(options.cleanPathname, options.getCollectedFetchTags());
+		const frameworkCacheable = (options.isRevalidation === true || response.status < 400 || response.status === 404) && options.revalidateSeconds !== null && options.revalidateSeconds > 0 && !responseMustStayPrivate && !shouldApplyDraftPolicy && pendingCookies.length === 0 && !response.headers.has("set-cookie") && (options.method === "GET" || options.isAutoHead);
+		recordRouteCacheability(frameworkCacheable ? {
+			cacheable: true,
+			cacheControl: buildAppRouteMissIsrCacheControl(options.revalidateSeconds, options.expireSeconds),
+			tags: routeTags
+		} : {
+			cacheable: false,
+			dynamicUsage: responseMustStayPrivate || shouldApplyDraftPolicy || options.revalidateSeconds === 0
+		});
 		if (shouldApplyAppRouteHandlerRevalidateHeader({
 			dynamicUsedInHandler: responseMustStayPrivate,
 			handlerSetCachePolicy,
@@ -184,9 +249,9 @@ async function executeAppRouteHandler(options) {
 			if (revalidateSeconds == null) throw new Error("Expected route handler revalidate seconds");
 			applyRouteHandlerRevalidateHeader(response, revalidateSeconds, options.expireSeconds, routeTags);
 		}
-		if (shouldWriteAppRouteHandlerCache({
+		if (frameworkCacheable && shouldWriteAppRouteHandlerCache({
 			dynamicConfig: options.handler.dynamic,
-			dynamicUsedInHandler: responseMustStayPrivate,
+			dynamicUsedInHandler: responseMustStayPrivate || pendingCookies.length > 0 || response.headers.has("set-cookie"),
 			handlerSetCachePolicy,
 			isAutoHead: options.isAutoHead,
 			isDraftMode: shouldApplyDraftPolicy,
@@ -201,9 +266,9 @@ async function executeAppRouteHandler(options) {
 			if (revalidateSeconds == null) throw new Error("Expected route handler cache revalidate seconds");
 			const routeWritePromise = (async () => {
 				try {
-					const routeCacheValue = await buildAppRouteCacheValue(routeClone);
+					const routeCacheValue = await buildAppRouteCacheValue(routeClone, browserCacheControl);
 					await options.isrSet(routeKey, routeCacheValue, {
-						cacheControl: isrCacheControl(revalidateSeconds, { expireSeconds: options.expireSeconds }),
+						cacheControl: isrCacheControl(revalidateSeconds === Infinity ? false : revalidateSeconds, { expireSeconds: resolveRouteExpireSeconds(options.revalidateSeconds, options.expireSeconds) }),
 						tags: routeTags
 					});
 					options.isrDebug?.("route cache written", routeKey);
@@ -218,8 +283,8 @@ async function executeAppRouteHandler(options) {
 			draftCookie,
 			isHead: options.isAutoHead
 		}), options.middlewareContext, middlewareMergeOptions), shouldApplyDraftPolicy);
-		const preserveHandlerPolicy = isRouteCacheabilityEvaluation() ? hasExplicitCacheablePolicy : handlerSetCachePolicy;
-		if (responseMustStayPrivate && !preserveHandlerPolicy) {
+		const preserveHandlerPolicy = handlerSetCachePolicy;
+		if (options.bypassSharedCache === true || responseMustStayPrivate && !preserveHandlerPolicy) {
 			const headers = new Headers(finalized.headers);
 			applyCdnResponseHeaders(headers, { cacheControl: NEVER_CACHE_CONTROL });
 			finalized = new Response(finalized.body, {
@@ -262,14 +327,15 @@ 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 {
@@ -277,4 +343,4 @@ async function executeAppRouteHandler(options) {
 	}
 }
 //#endregion
-export { applyDraftModeCachePolicy, executeAppRouteHandler, runAppRouteHandler };
+export { applyDraftModeCachePolicy, completeAppRouteHandlerResponse, 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,7 +1,7 @@
 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;
@@ -49,21 +49,21 @@ type AppRouteHandlerSpecialError = {
 type AppRouteHandlerSpecialErrorOptions = {
   isAction: boolean;
 };
-declare function getAppRouteHandlerRevalidateSeconds(handler: Pick<AppRouteHandlerModule, "dynamic" | "generateStaticParams" | "revalidate">): number | null;
-declare function hasAppRouteHandlerDefaultExport(handler: RouteHandlerModule): boolean;
+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. */
-declare function hasNonStaticAppRouteHandlerMethods(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;
+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).
  */
-declare function shouldCompleteAppRouteHandlerResponse(options: AppRouteHandlerResponseCacheOptions): boolean;
-declare function shouldWriteAppRouteHandlerCache(options: AppRouteHandlerResponseCacheOptions): boolean;
-declare function resolveAppRouteHandlerSpecialError(error: unknown, requestUrl: string, options?: AppRouteHandlerSpecialErrorOptions): AppRouteHandlerSpecialError | null;
+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, hasNonStaticAppRouteHandlerMethods, isPossibleAppRouteActionRequest, resolveAppRouteHandlerMethod, resolveAppRouteHandlerSpecialError, shouldApplyAppRouteHandlerRevalidateHeader, shouldCompleteAppRouteHandlerResponse, shouldReadAppRouteHandlerCache, shouldWriteAppRouteHandlerCache };
+export { isPossibleAppRouteActionRequest };

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

@@ -36,7 +36,7 @@ function resolveAppRouteHandlerMethod(handler, method) {
 	};
 }
 function shouldReadAppRouteHandlerCache(options) {
-	return options.isProduction && options.revalidateSeconds !== null && options.revalidateSeconds > 0 && options.revalidateSeconds !== Infinity && options.dynamicConfig !== "force-dynamic" && !options.isDraftMode && !options.isKnownDynamic && (options.method === "GET" || options.isAutoHead) && typeof options.handlerFn === "function";
+	return options.isProduction && options.revalidateSeconds !== null && options.revalidateSeconds > 0 && options.dynamicConfig !== "force-dynamic" && !options.isDraftMode && !options.isKnownDynamic && (options.method === "GET" || options.isAutoHead) && typeof options.handlerFn === "function";
 }
 function shouldApplyAppRouteHandlerRevalidateHeader(options) {
 	return options.revalidateSeconds !== null && !options.isDraftMode && !options.dynamicUsedInHandler && (options.method === "GET" || options.isAutoHead) && !options.handlerSetCachePolicy;
@@ -51,7 +51,7 @@ function shouldCompleteAppRouteHandlerResponse(options) {
 	return options.isProduction && (options.revalidateSeconds !== null && options.revalidateSeconds > 0 || options.requiresCompletedResponseAdmission === true || options.hasExplicitCacheablePolicy === true) && options.dynamicConfig !== "force-dynamic" && !options.isDraftMode && !options.dynamicUsedInHandler && (options.method === "GET" || options.isAutoHead);
 }
 function shouldWriteAppRouteHandlerCache(options) {
-	return options.isProduction && options.revalidateSeconds !== null && options.revalidateSeconds > 0 && options.revalidateSeconds !== Infinity && options.dynamicConfig !== "force-dynamic" && !options.isDraftMode && shouldApplyAppRouteHandlerRevalidateHeader(options);
+	return options.isProduction && options.revalidateSeconds !== null && options.revalidateSeconds > 0 && options.dynamicConfig !== "force-dynamic" && !options.isDraftMode && !options.dynamicUsedInHandler && (options.method === "GET" || options.isAutoHead);
 }
 function resolveAppRouteHandlerSpecialError(error, requestUrl, options) {
 	if (!(error && typeof error === "object" && "digest" in error)) return null;

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

@@ -1,6 +1,6 @@
 import { CacheControlMetadata, CachedRouteValue } from "../shims/cache-handler.js";
 //#region src/server/app-route-handler-response.d.ts
-type RouteHandlerMiddlewareContext = {
+export type RouteHandlerMiddlewareContext = {
   headers: Headers | null;
   status: number | null;
 };
@@ -16,14 +16,13 @@ type FinalizeRouteHandlerResponseOptions = {
   draftCookie?: string | null;
   isHead: boolean;
 };
-declare function applyRouteHandlerMiddlewareContext(response: Response, middlewareContext: RouteHandlerMiddlewareContext, options?: {
+export declare function applyRouteHandlerMiddlewareContext(response: Response, middlewareContext: RouteHandlerMiddlewareContext, options?: {
   appendResponseLink?: boolean;
 }): Response;
-declare function assertSupportedAppRouteHandlerResponse(response: Response): void;
-declare function buildRouteHandlerCachedResponse(cachedValue: CachedRouteValue, options: BuildRouteHandlerCachedResponseOptions): Response;
-declare function applyRouteHandlerRevalidateHeader(response: Response, revalidateSeconds: number, expireSeconds?: number, tags?: readonly string[]): void;
-declare function markRouteHandlerCacheMiss(response: Response): void;
-declare function buildAppRouteCacheValue(response: Response): Promise<CachedRouteValue>;
-declare function finalizeRouteHandlerResponse(response: Response, options: FinalizeRouteHandlerResponseOptions): Response;
-//#endregion
-export { RouteHandlerMiddlewareContext, applyRouteHandlerMiddlewareContext, applyRouteHandlerRevalidateHeader, assertSupportedAppRouteHandlerResponse, buildAppRouteCacheValue, buildRouteHandlerCachedResponse, finalizeRouteHandlerResponse, markRouteHandlerCacheMiss };
+export declare function assertSupportedAppRouteHandlerResponse(response: Response): void;
+export declare function buildRouteHandlerCachedResponse(cachedValue: CachedRouteValue, options: BuildRouteHandlerCachedResponseOptions): Response;
+export declare function applyRouteHandlerRevalidateHeader(response: Response, revalidateSeconds: number, expireSeconds?: number, tags?: readonly string[]): void;
+export declare function markRouteHandlerCacheMiss(response: Response): void;
+export declare function buildAppRouteCacheValue(response: Response, browserCacheControl?: string): Promise<CachedRouteValue>;
+export declare function finalizeRouteHandlerResponse(response: Response, options: FinalizeRouteHandlerResponseOptions): Response;
+//#endregion

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

@@ -1,6 +1,7 @@
 import "../utils/protocol-headers.js";
 import { NEXT_CACHE_TAGS_HEADER, VINEXT_METADATA_ROUTE_CACHE_HEADER } from "./headers.js";
 import { processMiddlewareHeaders } from "./request-pipeline.js";
+import { markRouteCacheabilityExplicitResponsePolicy, recordRouteCacheability } from "../shims/cacheability-classification.js";
 import { applyCdnResponseHeaders } from "./cache-control.js";
 import { buildAppRouteMissIsrCacheControl, decideIsr } from "./isr-decision.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
@@ -49,8 +50,17 @@ function buildRouteHandlerCachedResponse(cachedValue, options) {
 		expireSeconds: options.expireSeconds,
 		cacheControlMeta: options.cacheControl
 	});
-	applyCdnResponseHeaders(headers, { cacheControl });
-	return new Response(options.isHead ? null : cachedValue.body, {
+	recordRouteCacheability({
+		cacheable: true,
+		cacheControl
+	});
+	if (headers.has("Cache-Control")) markRouteCacheabilityExplicitResponsePolicy();
+	applyCdnResponseHeaders(headers, {
+		cacheControl,
+		browserCacheControl: headers.get("Cache-Control") ?? void 0
+	});
+	const hasNoBody = options.isHead || cachedValue.status === 204 || cachedValue.status === 205 || cachedValue.status === 304;
+	return new Response(hasNoBody ? null : cachedValue.body, {
 		status: cachedValue.status,
 		headers
 	});
@@ -123,13 +133,14 @@ function applyMutableCookieFallbacks(headers, pendingCookies) {
 	for (const cookie of fallbackCookies.values()) headers.append("Set-Cookie", cookie);
 	for (const cookie of returnedCookies) headers.append("Set-Cookie", normalizeReturnedCookie(cookie));
 }
-async function buildAppRouteCacheValue(response) {
+async function buildAppRouteCacheValue(response, browserCacheControl) {
 	const body = await response.arrayBuffer();
 	const headers = {};
 	response.headers.forEach((value, key) => {
 		if (key === "set-cookie" || key === "connection" || key === "content-length" || key === "date" || key === "keep-alive" || key === "transfer-encoding" || key === "x-next-cache-tags" || key === "x-vinext-metadata-route-cache" || key === "x-vinext-prerender-cache-life" || key === "X-Vinext-Cache".toLowerCase() || key === "x-nextjs-cache".toLowerCase() || key === "cache-control" || key.startsWith("x-middleware-")) return;
 		headers[key] = value;
 	});
+	if (browserCacheControl !== void 0) headers["cache-control"] = browserCacheControl;
 	const setCookies = response.headers.getSetCookie?.() ?? [];
 	if (setCookies.length > 0) headers["set-cookie"] = setCookies;
 	return {

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

@@ -2,8 +2,8 @@ import { NextI18nConfig } from "../config/next-config.js";
 import { NextRequest } from "../shims/server.js";
 //#region src/server/app-route-handler-runtime.d.ts
 declare const ROUTE_HANDLER_HTTP_METHODS: readonly ["GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"];
-type RouteHandlerHttpMethod = (typeof ROUTE_HANDLER_HTTP_METHODS)[number];
-type RouteHandlerModule = Partial<Record<RouteHandlerHttpMethod | "default", unknown>>;
+export type RouteHandlerHttpMethod = (typeof ROUTE_HANDLER_HTTP_METHODS)[number];
+export type RouteHandlerModule = Partial<Record<RouteHandlerHttpMethod | "default", unknown>>;
 /**
  * Checks whether a string is a recognized HTTP method for App Router route
  * handlers. Invalid methods must be rejected with 400 before any auto-OPTIONS
@@ -11,11 +11,11 @@ type RouteHandlerModule = Partial<Record<RouteHandlerHttpMethod | "default", unk
  *
  * @see https://github.com/vercel/next.js/blob/canary/packages/next/src/server/web/http.ts
  */
-declare function isValidHTTPMethod(maybeMethod: string): maybeMethod is RouteHandlerHttpMethod;
-declare function collectRouteHandlerMethods(handler: RouteHandlerModule): RouteHandlerHttpMethod[];
-declare function buildRouteHandlerAllowHeader(exportedMethods: readonly string[]): string;
-declare function isKnownDynamicAppRoute(pattern: string): boolean;
-declare function markKnownDynamicAppRoute(pattern: string): void;
+export declare function isValidHTTPMethod(maybeMethod: string): maybeMethod is RouteHandlerHttpMethod;
+export declare function collectRouteHandlerMethods(handler: RouteHandlerModule): RouteHandlerHttpMethod[];
+export declare function buildRouteHandlerAllowHeader(exportedMethods: readonly string[]): string;
+export declare function isKnownDynamicAppRoute(pattern: string): boolean;
+export declare function markKnownDynamicAppRoute(pattern: string): void;
 type RequestDynamicAccess = "request.headers" | "request.cookies" | "request.cf" | "request.ip" | "request.geo" | "request.url" | "request.body" | "request.blob" | "request.bytes" | "request.json" | "request.text" | "request.arrayBuffer" | "request.formData";
 type NextUrlDynamicAccess = "nextUrl.search" | "nextUrl.searchParams" | "nextUrl.url" | "nextUrl.href" | "nextUrl.toJSON" | "nextUrl.toString" | "nextUrl.origin";
 type AppRouteDynamicRequestAccess = RequestDynamicAccess | NextUrlDynamicAccess;
@@ -33,6 +33,5 @@ type TrackedAppRouteRequest = {
   request: NextRequest;
   didAccessDynamicRequest(): boolean;
 };
-declare function createTrackedAppRouteRequest(request: Request, options?: TrackedAppRouteRequestOptions): TrackedAppRouteRequest;
-//#endregion
-export { RouteHandlerHttpMethod, RouteHandlerModule, buildRouteHandlerAllowHeader, collectRouteHandlerMethods, createTrackedAppRouteRequest, isKnownDynamicAppRoute, isValidHTTPMethod, markKnownDynamicAppRoute };
+export declare function createTrackedAppRouteRequest(request: Request, options?: TrackedAppRouteRequestOptions): TrackedAppRouteRequest;
+//#endregion

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

@@ -1,5 +1,5 @@
-import { addBasePathToPathname } from "../utils/base-path.js";
 import { buildRequestHeadersFromMiddlewareResponse } from "../utils/middleware-request-headers.js";
+import { addBasePathToPathname } from "../utils/base-path.js";
 import { NextRequest, RequestCookies, sealRequestCookies, sealRequestHeaders } from "../shims/server.js";
 import { cloneRequestWithHeaders, cloneRequestWithUrl } from "./request-pipeline.js";
 import { BUILT_IN_REQUEST_PROPERTIES } from "./app-route-request-built-ins.js";
@@ -191,10 +191,12 @@ function createTrackedAppRouteRequest(request, options = {}) {
 		}
 		const requestHeaders = options.middlewareHeaders ? buildRequestHeadersFromMiddlewareResponse(input.headers, options.middlewareHeaders) : null;
 		const requestWithOverrides = requestHeaders ? cloneRequestWithHeaders(input, requestHeaders) : input;
-		const sourceCfMetadata = Reflect.get(requestWithOverrides, "cf", requestWithOverrides);
 		const sourceCfDescriptor = Reflect.getOwnPropertyDescriptor(requestWithOverrides, "cf");
+		const sourceCfAccessor = sourceCfDescriptor?.get;
+		const sourceCfMetadata = sourceCfAccessor ? void 0 : Reflect.get(requestWithOverrides, "cf", requestWithOverrides);
 		const nextRequest = requestMode === "force-static" ? createForceStaticNextRequest(requestWithOverrides, nextConfig) : requestWithOverrides instanceof NextRequest && sourceCfDescriptor?.configurable !== false ? requestWithOverrides : new NextRequest(requestWithOverrides, { nextConfig: nextConfig ?? void 0 });
-		const rawCfMetadata = sourceCfMetadata === void 0 ? Reflect.get(nextRequest, "cf", nextRequest) : sourceCfMetadata;
+		const rawCfMetadata = sourceCfAccessor ? void 0 : sourceCfMetadata === void 0 ? Reflect.get(nextRequest, "cf", nextRequest) : sourceCfMetadata;
+		const hasCfMetadata = sourceCfAccessor !== void 0 || rawCfMetadata !== void 0;
 		const originalCfDescriptor = sourceCfDescriptor ?? Reflect.getOwnPropertyDescriptor(nextRequest, "cf");
 		const accessCf = (read, forceStaticValue) => {
 			if (requestMode === "force-static") return forceStaticValue;
@@ -202,8 +204,8 @@ function createTrackedAppRouteRequest(request, options = {}) {
 			markDynamicAccess("request.cf");
 			return read();
 		};
-		const controlledCfGetter = () => accessCf(() => rawCfMetadata, void 0);
-		if (rawCfMetadata !== void 0) {
+		const controlledCfGetter = () => accessCf(sourceCfAccessor ? () => Reflect.apply(sourceCfAccessor, requestWithOverrides, []) : () => rawCfMetadata, void 0);
+		if (hasCfMetadata) {
 			if (requestMode === "force-static") Object.defineProperty(nextRequest, "cf", {
 				configurable: true,
 				enumerable: originalCfDescriptor?.enumerable ?? false,
@@ -217,7 +219,7 @@ function createTrackedAppRouteRequest(request, options = {}) {
 		}
 		const cloneTrackedRequest = () => {
 			const cloned = nextRequest.clone();
-			if (rawCfMetadata !== void 0) Object.defineProperty(cloned, "cf", {
+			if (hasCfMetadata) Object.defineProperty(cloned, "cf", sourceCfDescriptor ?? {
 				value: rawCfMetadata,
 				enumerable: originalCfDescriptor?.enumerable ?? false,
 				configurable: true
@@ -356,16 +358,18 @@ function createTrackedAppRouteRequest(request, options = {}) {
 			},
 			preventExtensions(target) {
 				const descriptor = Reflect.getOwnPropertyDescriptor(target, "cf");
-				if (descriptor?.get === controlledCfGetter) if (requestMode === "force-static") {
-					if (!Reflect.deleteProperty(target, "cf")) return false;
-				} else {
-					accessCf(() => void 0, void 0);
-					Object.defineProperty(target, "cf", {
-						configurable: true,
-						enumerable: descriptor.enumerable,
-						value: rawCfMetadata,
-						writable: false
-					});
+				if (descriptor?.get === controlledCfGetter) {
+					if (requestMode === "force-static") {
+						if (!Reflect.deleteProperty(target, "cf")) return false;
+					} else {
+						accessCf(() => void 0, void 0);
+						Object.defineProperty(target, "cf", {
+							configurable: true,
+							enumerable: descriptor.enumerable,
+							value: rawCfMetadata,
+							writable: false
+						});
+					}
 				}
 				return Reflect.preventExtensions(target);
 			}

package/dist/server/app-route-module-loader.d.ts

@@ -71,7 +71,7 @@ type LazyLoadableSlot = {
   /** Hydrated only after an intercept matches, not with the slot's base modules. */
   intercepts?: LazyLoadableIntercept[];
 };
-type LazyLoadableRoute = {
+export type LazyLoadableRoute = {
   page?: unknown;
   routeHandler?: unknown;
   layouts?: unknown[];
@@ -112,16 +112,15 @@ type LazyLoadableRoute = {
   __loading?: Promise<unknown> | null;
 };
 /** Hydrate an intercepting route's page module onto `intercept.page`. */
-declare function loadAppInterceptPage(intercept: LazyLoadableIntercept): Promise<void>;
+export declare function loadAppInterceptPage(intercept: LazyLoadableIntercept): Promise<void>;
 /** Hydrate an intercepting route's not-found boundary onto `intercept.notFound`. */
-declare function loadAppInterceptNotFound(intercept: LazyLoadableIntercept): Promise<void>;
-declare function loadAppInterceptLayouts(intercept: LazyLoadableIntercept): Promise<readonly unknown[]>;
+export declare function loadAppInterceptNotFound(intercept: LazyLoadableIntercept): Promise<void>;
+export declare function loadAppInterceptLayouts(intercept: LazyLoadableIntercept): Promise<readonly unknown[]>;
 /**
  * Resolve a route's lazy modules and assign them onto the route's synchronous
  * module fields. Returns the same route reference (synchronously when already
  * loaded, otherwise after the in-flight import resolves). Safe to call on
  * `null`/`undefined` routes and on eager routes that have no lazy thunks.
  */
-declare function ensureAppRouteModulesLoaded<TRoute extends LazyLoadableRoute>(route: TRoute | null | undefined): TRoute | Promise<TRoute>;
-//#endregion
-export { LazyLoadableRoute, ensureAppRouteModulesLoaded, loadAppInterceptLayouts, loadAppInterceptNotFound, loadAppInterceptPage };
+export declare function ensureAppRouteModulesLoaded<TRoute extends LazyLoadableRoute>(route: TRoute | null | undefined): TRoute | Promise<TRoute>;
+//#endregion