vinext 1.0.0-beta.9 → 1.0.1

package/dist/server/app-request-stage-independent-entry.js

@@ -0,0 +1,112 @@
+import { VINEXT_PRERENDER_SECRET_HEADER, VINEXT_REVALIDATE_HOST_HEADER } from "../utils/protocol-headers.js";
+import { runWithExecutionContext } from "../shims/request-context.js";
+import "./server-globals.js";
+import "./app-rsc-vary.js";
+import { VINEXT_CACHEABILITY_PROBE_QUERY_PARAM, VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "./headers.js";
+import { badRequestResponse, notFoundResponse } from "./http-error-responses.js";
+import { isOpenRedirectShaped } from "./open-redirect.js";
+import { cloneRequestWithHeaders, filterInternalHeaders } from "./request-pipeline.js";
+import { getExplicitCdnCacheAdapter } from "../shims/cdn-cache-state.js";
+import { applyCdnResponseIdentityHeaders, validateCdnRequest } from "./cache-control.js";
+import { registerLazyDataCacheHandler } from "../shims/cache-handler.js";
+import { getImageOptimizer, handleConfiguredImageOptimization, isImageOptimizationPath } from "./image-optimization.js";
+import { consumeFrameworkRequestRoute, traceFrameworkRequest } from "./request-tracing.js";
+import { createStaticAssetRequest, resolveStaticAssetSignal } from "./worker-utils.js";
+import { readTrustedPrerenderStateFromHeaders } from "./prerender-route-params.js";
+import { createWorkerRevalidationContext } from "./worker-revalidation-context.js";
+import { createWorkerPrerenderDiscoveryContext, createWorkerPrerenderReadinessResponse } from "./worker-prerender-discovery.js";
+import requestRscHandler, { __ensureHybridPagesApplication, __ensureInstrumentation, __imageAllowedWidths, __imageConfig, __prerenderSecret } from "virtual:vinext-app-request-entry";
+import * as configuredCdnCacheAdapters from "virtual:vinext-cdn-cache-adapter";
+import { registerConfiguredImageOptimizer } from "virtual:vinext-image-adapters";
+//#region src/server/app-request-stage-independent-entry.ts
+function handleRequestStage(request, env, ctx, dispatchResponseStage) {
+	const originalRequest = request;
+	const handleStage = async () => {
+		await __ensureInstrumentation();
+		const url = new URL(request.url);
+		return traceFrameworkRequest({
+			callback: () => handleRequest(request, env, ctx, dispatchResponseStage, ctx?.assets).then((response) => applyCdnResponseIdentityHeaders(response, originalRequest)),
+			getStatus: (response) => response?.status,
+			headers: request.headers,
+			isRsc: url.pathname.endsWith(".rsc") || request.headers.get("RSC") === "1",
+			method: request.method,
+			target: url.pathname + url.search
+		});
+	};
+	return ctx ? runWithExecutionContext(ctx, handleStage) : handleStage();
+}
+async function handleRequest(request, env, platformCtx, dispatchResponseStage, assets) {
+	let ctx = platformCtx?.trustedRevalidateOrigin ? platformCtx : createWorkerRevalidationContext(platformCtx, (internalRequest, internalCtx) => handleRequest(internalRequest, env, internalCtx, dispatchResponseStage, assets), "node");
+	configuredCdnCacheAdapters.registerConfiguredCacheAdapters(env);
+	assets ??= getExplicitCdnCacheAdapter()?.assets;
+	if (configuredCdnCacheAdapters.hasConfiguredDataCache) registerLazyDataCacheHandler(async () => {
+		(await import("virtual:vinext-cache-adapters")).registerConfiguredCacheAdapters(env);
+	});
+	registerConfiguredImageOptimizer(env);
+	ctx = createWorkerPrerenderDiscoveryContext(ctx, request, __prerenderSecret);
+	const readinessResponse = createWorkerPrerenderReadinessResponse(ctx, request);
+	let didValidateCdnRequest = false;
+	if (readinessResponse) {
+		const validationResponse = await validateCdnRequest(request);
+		if (validationResponse) return validationResponse;
+		didValidateCdnRequest = true;
+		if (readinessResponse.status !== 204) return readinessResponse;
+		await __ensureHybridPagesApplication();
+	}
+	let probeMode = null;
+	let probeRoute = null;
+	if (request.headers.has("X-Vinext-Cacheability-Probe")) {
+		const { readWorkerCacheabilityProbeMode, readWorkerCacheabilityProbeRoute } = await import("./cacheability-request.js");
+		probeMode = readWorkerCacheabilityProbeMode(request, __prerenderSecret);
+		if (probeMode) {
+			probeRoute = readWorkerCacheabilityProbeRoute(request);
+			const probeUrl = new URL(request.url);
+			probeUrl.searchParams.delete(VINEXT_CACHEABILITY_PROBE_QUERY_PARAM);
+			request = new Request(probeUrl, request);
+		}
+	}
+	if (!didValidateCdnRequest) {
+		const cdnValidationResponse = await validateCdnRequest(request);
+		if (cdnValidationResponse) return cdnValidationResponse;
+	}
+	const url = new URL(request.url);
+	if (isImageOptimizationPath(url.pathname) && assets && getImageOptimizer()) return handleConfiguredImageOptimization(request, (assetPath) => Promise.resolve(assets.fetch(new Request(new URL(assetPath, request.url)))), __imageAllowedWidths, __imageConfig);
+	if (isOpenRedirectShaped(url.pathname)) return notFoundResponse();
+	try {
+		decodeURIComponent(url.pathname);
+	} catch {
+		return badRequestResponse();
+	}
+	const trustedPrerenderState = readTrustedPrerenderStateFromHeaders(request.headers, __prerenderSecret);
+	const filteredHeaders = ctx.isInternalPagesRevalidation ? new Headers(request.headers) : filterInternalHeaders(request.headers);
+	filteredHeaders.delete(VINEXT_PRERENDER_SECRET_HEADER);
+	filteredHeaders.delete(VINEXT_REVALIDATE_HOST_HEADER);
+	if (readinessResponse?.status === 204) {
+		const expectedWorkerVersion = request.headers.get(VINEXT_EXPECTED_WORKER_VERSION_HEADER);
+		if (expectedWorkerVersion) filteredHeaders.set(VINEXT_EXPECTED_WORKER_VERSION_HEADER, expectedWorkerVersion);
+	}
+	request = cloneRequestWithHeaders(request, filteredHeaders);
+	let responseStageDispatched = false;
+	const trackedDispatchResponseStage = (stageRequest, props, options) => {
+		responseStageDispatched = true;
+		const response = dispatchResponseStage(stageRequest, props, options);
+		return props.kind === "app-full-request" ? response.then(consumeFrameworkRequestRoute) : response;
+	};
+	const handle = () => requestRscHandler(request, ctx, trackedDispatchResponseStage, probeMode, ctx.isPrerenderPathDiscovery === true, trustedPrerenderState);
+	let response = await runWithExecutionContext(ctx, handle);
+	if (assets) {
+		const assetResponse = await resolveStaticAssetSignal(response, { fetchAsset: (path) => Promise.resolve(assets.fetch(createStaticAssetRequest(path, request))) });
+		if (assetResponse) response = assetResponse;
+	}
+	if (probeMode && probeRoute && !responseStageDispatched) {
+		const { finalizeRequestStageCacheabilityProbe } = await import("./cacheability-request.js");
+		response = finalizeRequestStageCacheabilityProbe(response, {
+			mode: probeMode,
+			responseStageDispatched,
+			route: probeRoute
+		});
+	}
+	return response;
+}
+//#endregion
+export { handleRequestStage };

package/dist/server/app-response-header-provenance.d.ts

@@ -1,13 +1,19 @@
 //#region src/server/app-response-header-provenance.d.ts
 /** Mark response headers whose Link value was emitted by the App page renderer. */
-declare function markFrameworkLinkHeaders(headers: Headers, linkHeader: string | string[] | null | undefined): void;
+export declare function markFrameworkLinkHeaders(headers: Headers, linkHeader: string | string[] | null | undefined): void;
 /** Whether the response carries renderer-owned Link values that config may prepend to. */
-declare function hasFrameworkLinkHeaders(headers: Headers): boolean;
+export declare function hasFrameworkLinkHeaders(headers: Headers): boolean;
 /** Mark Link values returned by an Edge route handler after config and middleware. */
-declare function markEdgeRouteHandlerLinkHeaders(headers: Headers, linkHeader: string | null | undefined): void;
+export declare function markEdgeRouteHandlerLinkHeaders(headers: Headers, linkHeader: string | null | undefined): void;
 /** Whether config must precede a later framework or Edge-handler Link value. */
-declare function hasPostConfigLinkHeaders(headers: Headers): boolean;
+export declare function hasPostConfigLinkHeaders(headers: Headers): boolean;
 /** Preserve Link provenance when a response wrapper reconstructs a Response. */
-declare function copyLinkHeaderProvenance(source: Headers, target: Headers): void;
-//#endregion
-export { copyLinkHeaderProvenance, hasFrameworkLinkHeaders, hasPostConfigLinkHeaders, markEdgeRouteHandlerLinkHeaders, markFrameworkLinkHeaders };
+export declare function copyLinkHeaderProvenance(source: Headers, target: Headers): void;
+/** Serialize otherwise process-local Link provenance across a response-stage transport. */
+export declare function serializeResponseStageLinkProvenance(response: Response): Response;
+/** Consume transported Link provenance before applying outer config and middleware. */
+export declare function consumeResponseStageLinkProvenance(response: Response): {
+  appendToPostConfigLink: boolean;
+  response: Response;
+};
+//#endregion

package/dist/server/app-response-header-provenance.js

@@ -1,6 +1,9 @@
+import { preserveFullyBufferedBodyMetadata } from "./fully-buffered-response.js";
+import "../shims/unified-request-context.js";
 //#region src/server/app-response-header-provenance.ts
 const frameworkLinkHeaders = /* @__PURE__ */ new WeakSet();
 const edgeRouteHandlerLinkHeaders = /* @__PURE__ */ new WeakSet();
+const APP_RESPONSE_STAGE_LINK_PROVENANCE_HEADER = "x-vinext-app-stage-post-config-link";
 /** Mark response headers whose Link value was emitted by the App page renderer. */
 function markFrameworkLinkHeaders(headers, linkHeader) {
 	if (linkHeader && (typeof linkHeader === "string" || linkHeader.length > 0)) frameworkLinkHeaders.add(headers);
@@ -22,5 +25,35 @@ function copyLinkHeaderProvenance(source, target) {
 	if (frameworkLinkHeaders.has(source)) frameworkLinkHeaders.add(target);
 	if (edgeRouteHandlerLinkHeaders.has(source)) edgeRouteHandlerLinkHeaders.add(target);
 }
+/** Serialize otherwise process-local Link provenance across a response-stage transport. */
+function serializeResponseStageLinkProvenance(response) {
+	if (!hasPostConfigLinkHeaders(response.headers)) return response;
+	const headers = new Headers(response.headers);
+	headers.set(APP_RESPONSE_STAGE_LINK_PROVENANCE_HEADER, "1");
+	return preserveFullyBufferedBodyMetadata(response, new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	}));
+}
+/** Consume transported Link provenance before applying outer config and middleware. */
+function consumeResponseStageLinkProvenance(response) {
+	if (response.headers.get(APP_RESPONSE_STAGE_LINK_PROVENANCE_HEADER) !== "1") return {
+		appendToPostConfigLink: false,
+		response
+	};
+	const headers = new Headers(response.headers);
+	headers.delete(APP_RESPONSE_STAGE_LINK_PROVENANCE_HEADER);
+	const transported = preserveFullyBufferedBodyMetadata(response, new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	}));
+	markFrameworkLinkHeaders(transported.headers, transported.headers.get("link"));
+	return {
+		appendToPostConfigLink: true,
+		response: transported
+	};
+}
 //#endregion
-export { copyLinkHeaderProvenance, hasFrameworkLinkHeaders, hasPostConfigLinkHeaders, markEdgeRouteHandlerLinkHeaders, markFrameworkLinkHeaders };
+export { consumeResponseStageLinkProvenance, copyLinkHeaderProvenance, hasFrameworkLinkHeaders, hasPostConfigLinkHeaders, markEdgeRouteHandlerLinkHeaders, markFrameworkLinkHeaders, serializeResponseStageLinkProvenance };

package/dist/server/app-response-stage-entry.d.ts

@@ -0,0 +1,9 @@
+import { VinextCacheFunctionInvocation, VinextRequestStageTransport, VinextResponseStageDispatchOptions } from "./multi-stage.js";
+import { ExecutionContextLike } from "../shims/request-context.js";
+import { AppWorkerResponseStageProps } from "./app-worker-stages.js";
+//#region src/server/app-response-stage-entry.d.ts
+type AppResponseStageEnv = Record<string, unknown>;
+/** Invoke one transformed public cache function without rendering its owning route. */
+export declare function invokeCacheFunction(invocation: VinextCacheFunctionInvocation, env: AppResponseStageEnv | undefined, platformCtx: ExecutionContextLike | undefined, dispatchRequestStage: VinextRequestStageTransport): Promise<void>;
+export declare function handleResponseStage(request: Request, env: AppResponseStageEnv | undefined, platformCtx: ExecutionContextLike | undefined, props: AppWorkerResponseStageProps, dispatchRequestStage: VinextRequestStageTransport, options?: VinextResponseStageDispatchOptions): Promise<Response>;
+//#endregion

package/dist/server/app-response-stage-entry.js

@@ -0,0 +1,87 @@
+import { createRequestContext, runWithRequestContext } from "../shims/unified-request-context.js";
+import { runWithExecutionContext } from "../shims/request-context.js";
+import { serializeStaticFileSignalForTransport } from "./static-file-signal.js";
+import { validateCdnRequest } from "./cache-control.js";
+import { ensureFetchPatch } from "../shims/fetch-cache.js";
+import { serializeResponseStageLinkProvenance } from "./app-response-header-provenance.js";
+import { attachFrameworkRequestError, attachFrameworkRequestRoute, captureFrameworkRequestRoute, clearFrameworkRequestError } from "./request-tracing.js";
+import { isAppWorkerResponseStageProps } from "./app-worker-stages.js";
+import { createWorkerRevalidationContext } from "./worker-revalidation-context.js";
+import { createWorkerPrerenderReadinessResponse } from "./worker-prerender-discovery.js";
+import { withResponseStageCacheability } from "./response-stage-cacheability.js";
+import { registerConfiguredImageOptimizer } from "virtual:vinext-image-adapters";
+import rscHandler, { __cacheabilityManifest, __ensureHybridPagesApplication, __ensureInstrumentation } from "virtual:vinext-app-response-entry";
+import { registerConfiguredCacheAdapters } from "virtual:vinext-cache-adapters";
+//#region src/server/app-response-stage-entry.ts
+/** Cacheable App response stage. This is the only multi-stage App entry that imports user routes. */
+/** Invoke one transformed public cache function without rendering its owning route. */
+async function invokeCacheFunction(invocation, env, platformCtx, dispatchRequestStage) {
+	await __ensureInstrumentation();
+	const [{ loadServerAction }, { invokeCacheFunction: invokeRegisteredCacheFunction }] = await Promise.all([import("@vitejs/plugin-rsc/core/rsc"), import("../shims/cache-callable-runtime.js")]);
+	registerConfiguredCacheAdapters(env);
+	ensureFetchPatch();
+	const executionContext = createWorkerRevalidationContext(platformCtx, (request) => dispatchRequestStage(request), "node");
+	const context = createRequestContext({
+		currentFetchSoftTags: invocation.softTags,
+		executionContext,
+		rootParams: invocation.rootParams
+	});
+	await runWithRequestContext(context, () => invokeRegisteredCacheFunction(invocation, loadServerAction));
+}
+async function handleResponseStage(request, env, platformCtx, props, dispatchRequestStage, options = { cache: "bypass" }) {
+	if (!isAppWorkerResponseStageProps(props)) return new Response("Invalid vinext App response stage", { status: 400 });
+	if (props.requestOrigin !== new URL(request.url).origin) return new Response("Invalid vinext App response stage", { status: 400 });
+	const currentBuildId = process.env.__VINEXT_BUILD_ID ?? null;
+	if (props.buildId !== currentBuildId) return new Response("Incompatible vinext App response stage", { status: 409 });
+	await __ensureInstrumentation();
+	if (props.kind === "app-full-request" && props.prerenderDiscovery) await __ensureHybridPagesApplication();
+	registerConfiguredImageOptimizer(env);
+	let ctx = createWorkerRevalidationContext(platformCtx, (internalRequest) => dispatchRequestStage(internalRequest), "node");
+	if (props.kind === "app-full-request" && props.prerenderDiscovery) ctx = {
+		...ctx,
+		isPrerenderPathDiscovery: true
+	};
+	return withResponseStageCacheability({
+		buildId: process.env.__VINEXT_BUILD_ID,
+		cache: options.cache,
+		context: ctx,
+		forceDynamic: (props.kind === "app-page" || props.kind === "app-route-handler") && props.forceDynamic === true,
+		policyHeaders: props.cacheability.policyHeaders,
+		probeMode: props.cacheability.probeMode,
+		rawManifest: __cacheabilityManifest,
+		recomposesRequestScopedHeaders: props.kind === "app-page" && props.isRscRequest,
+		registerCacheAdapters: () => registerConfiguredCacheAdapters(env),
+		request,
+		representation: props.cacheability.representation,
+		resolvedRoutePathname: props.cacheability.resolvedRoutePathname
+	}, async (cacheabilityContext) => {
+		if (props.kind === "app-full-request") {
+			if (props.prerenderDiscovery) {
+				const readinessResponse = createWorkerPrerenderReadinessResponse(cacheabilityContext, request);
+				if (readinessResponse) return await validateCdnRequest(request) ?? readinessResponse;
+			}
+			const fullEntry = await import("virtual:vinext-rsc-entry");
+			const render = () => fullEntry.default(request, cacheabilityContext, false, void 0, null, props.trustedPrerenderState);
+			let route;
+			let result;
+			let failure;
+			let failed = false;
+			try {
+				({result, route} = await captureFrameworkRequestRoute(() => runWithExecutionContext(cacheabilityContext, render), (matchedRoute) => {
+					route = matchedRoute;
+				}));
+			} catch (error) {
+				console.error("[vinext] App response stage error:", error);
+				failed = true;
+				failure = error;
+				result = new Response("Internal Server Error", { status: 500 });
+			}
+			const serialized = serializeStaticFileSignalForTransport(result, props.staticFileSignalToken);
+			return attachFrameworkRequestRoute(failed ? attachFrameworkRequestError(serialized, failure) : clearFrameworkRequestError(serialized), route);
+		}
+		const render = () => rscHandler.handleResponseStage(request, cacheabilityContext, props, options);
+		return serializeResponseStageLinkProvenance(await runWithExecutionContext(cacheabilityContext, render));
+	});
+}
+//#endregion
+export { handleResponseStage, invokeCacheFunction };

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

@@ -1,6 +1,7 @@
 import { NextI18nConfig } from "../config/next-config.js";
 import { ISRCacheEntry } 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 { AppRouteDebugLogger, AppRouteDynamicUsageFn, AppRouteHandlerFunction, AppRouteParams, MarkAppRouteDynamicUsageFn, RouteHandlerCacheSetter } from "./app-route-handler-execution.js";
 //#region src/server/app-route-handler-cache.d.ts
@@ -42,6 +43,5 @@ type ReadAppRouteHandlerCacheOptions = {
     params: AppRouteParams;
   } | null) => void;
 };
-declare function readAppRouteHandlerCacheResponse(options: ReadAppRouteHandlerCacheOptions): Promise<Response | null>;
-//#endregion
-export { readAppRouteHandlerCacheResponse };
+export declare function readAppRouteHandlerCacheResponse(options: ReadAppRouteHandlerCacheOptions): Promise<Response | null>;
+//#endregion

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

@@ -1,8 +1,9 @@
-import { isrCacheControl } from "./isr-cache.js";
+import { isrCacheControl, resolveRouteExpireSeconds } from "./isr-cache.js";
 import { makeThenableParams } from "../shims/thenable-params.js";
 import { applyRouteHandlerMiddlewareContext, assertSupportedAppRouteHandlerResponse, buildAppRouteCacheValue, buildRouteHandlerCachedResponse } from "./app-route-handler-response.js";
 import { markKnownDynamicAppRoute } from "./app-route-handler-runtime.js";
-import { runAppRouteHandler } from "./app-route-handler-execution.js";
+import { resolveAppRouteHandlerSpecialError } from "./app-route-handler-policy.js";
+import { completeAppRouteHandlerResponse, runAppRouteHandler, traceAppRouteHandlerExecution } from "./app-route-handler-execution.js";
 //#region src/server/app-route-handler-cache.ts
 const EMPTY_PARAMS = Object.freeze({});
 function getCachedAppRouteValue(entry) {
@@ -31,42 +32,57 @@ async function readAppRouteHandlerCacheResponse(options) {
 		if (cached?.isStale && cachedValue) {
 			const staleValue = cachedValue;
 			const revalidateSearchParams = new URLSearchParams(options.revalidateSearchParams);
-			options.scheduleBackgroundRegeneration(routeKey, async () => {
-				await options.runInRevalidationContext(async () => {
-					options.setNavigationContext({
-						pathname: options.cleanPathname,
-						searchParams: revalidateSearchParams,
-						params: options.params ?? EMPTY_PARAMS
-					});
-					const { dynamicUsedInHandler, response } = await runAppRouteHandler({
-						basePath: options.basePath,
-						consumeDynamicUsage: options.consumeDynamicUsage,
-						dynamicConfig: options.dynamicConfig,
-						handlerFn: options.handlerFn,
-						i18n: options.i18n,
-						trailingSlash: options.trailingSlash,
-						markDynamicUsage: options.markDynamicUsage,
-						params: options.params === null ? null : makeThenableParams(options.params),
-						request: new Request(options.requestUrl, { method: "GET" }),
-						routePattern: options.routePattern,
-						setHeadersAccessPhase: options.setHeadersAccessPhase
+			options.scheduleBackgroundRegeneration(routeKey, () => options.runInRevalidationContext(async () => {
+				options.setNavigationContext({
+					pathname: options.cleanPathname,
+					searchParams: revalidateSearchParams,
+					params: options.params ?? EMPTY_PARAMS
+				});
+				let tracedResult;
+				try {
+					tracedResult = await traceAppRouteHandlerExecution(options.routePattern, async () => {
+						try {
+							return { handlerResult: await runAppRouteHandler({
+								basePath: options.basePath,
+								consumeDynamicUsage: options.consumeDynamicUsage,
+								dynamicConfig: options.dynamicConfig,
+								handlerFn: options.handlerFn,
+								i18n: options.i18n,
+								trailingSlash: options.trailingSlash,
+								markDynamicUsage: options.markDynamicUsage,
+								params: options.params === null ? null : makeThenableParams(options.params),
+								request: new Request(options.requestUrl, { method: "GET" }),
+								routePattern: options.routePattern,
+								setHeadersAccessPhase: options.setHeadersAccessPhase
+							}) };
+						} catch (error) {
+							if (resolveAppRouteHandlerSpecialError(error, options.requestUrl)) return { specialError: error };
+							throw error;
+						}
 					});
+				} finally {
 					options.setNavigationContext(null);
-					assertSupportedAppRouteHandlerResponse(response);
-					if (dynamicUsedInHandler) {
-						markKnownDynamicAppRoute(options.routePattern);
-						options.isrDebug?.("route regen skipped (dynamic usage)", options.cleanPathname);
-						return;
-					}
-					const routeTags = options.buildPageCacheTags(options.cleanPathname, options.getCollectedFetchTags());
-					const routeCacheValue = await buildAppRouteCacheValue(response);
-					await options.isrSet(routeKey, routeCacheValue, {
-						cacheControl: isrCacheControl(options.revalidateSeconds, { expireSeconds: options.expireSeconds }),
-						tags: routeTags
-					});
-					options.isrDebug?.("route regen complete", routeKey);
+				}
+				if ("specialError" in tracedResult) return;
+				const { dynamicUsedInHandler, response, didAccessDynamicRequest } = tracedResult.handlerResult;
+				assertSupportedAppRouteHandlerResponse(response);
+				const completed = await completeAppRouteHandlerResponse(response);
+				const lateDynamicUsage = options.consumeDynamicUsage();
+				const becameDynamic = dynamicUsedInHandler || lateDynamicUsage || didAccessDynamicRequest();
+				if (!completed.completed || becameDynamic || response.headers.has("set-cookie")) {
+					completed.response.body?.cancel().catch(() => {});
+					if (becameDynamic) markKnownDynamicAppRoute(options.routePattern);
+					options.isrDebug?.("route regen skipped (dynamic usage)", options.cleanPathname);
+					return;
+				}
+				const routeTags = options.buildPageCacheTags(options.cleanPathname, options.getCollectedFetchTags());
+				const routeCacheValue = await buildAppRouteCacheValue(completed.response, response.headers.get("Cache-Control") ?? void 0);
+				await options.isrSet(routeKey, routeCacheValue, {
+					cacheControl: isrCacheControl(options.revalidateSeconds === Infinity ? false : options.revalidateSeconds, { expireSeconds: resolveRouteExpireSeconds(options.revalidateSeconds, options.expireSeconds) }),
+					tags: routeTags
 				});
-			});
+				options.isrDebug?.("route regen complete", routeKey);
+			}));
 			options.isrDebug?.("STALE (route)", options.cleanPathname);
 			options.clearRequestContext();
 			return applyRouteHandlerMiddlewareContext(buildRouteHandlerCachedResponse(staleValue, {

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

@@ -18,6 +18,7 @@ type RouteHandlerBackgroundRegenerationErrorContext = {
 type RouteHandlerBackgroundRegenerator = (key: string, renderFn: () => Promise<void>, errorContext?: RouteHandlerBackgroundRegenerationErrorContext) => void;
 type DispatchAppRouteHandlerOptions = {
   basePath?: string;
+  bypassSharedCache?: boolean;
   cleanPathname: string;
   clearRequestContext: () => void;
   draftModeSecret: string;
@@ -43,6 +44,5 @@ type DispatchAppRouteHandlerOptions = {
   scheduleBackgroundRegeneration: RouteHandlerBackgroundRegenerator;
   searchParams: URLSearchParams;
 };
-declare function dispatchAppRouteHandler(options: DispatchAppRouteHandlerOptions): Promise<Response>;
-//#endregion
-export { dispatchAppRouteHandler };
+export declare function dispatchAppRouteHandler(options: DispatchAppRouteHandlerOptions): Promise<Response>;
+//#endregion

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

@@ -1,20 +1,24 @@
 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 { consumeDynamicUsage, getActiveDraftModeState, getAndClearPendingCookies, getDraftModeCookieHeader, isDraftModeRequest, markDynamicUsage, setHeadersAccessPhase } from "../shims/headers.js";
+import { isOnDemandRevalidateRequest } from "./revalidation-request.js";
+import { markDynamicUsage } from "../shims/internal/headers-state.js";
+import { consumeDynamicUsage, getActiveDraftModeState, getAndClearPendingCookies, getDraftModeCookieHeader, isDraftModeRequest, 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 { beginRouteCacheability, getRouteCacheabilityDynamicReason } from "../shims/cacheability-classification.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 { createStaticGenerationHeadersContext } from "./app-static-generation.js";
 import { getAppRouteHandlerRevalidateSeconds, hasAppRouteHandlerDefaultExport, hasNonStaticAppRouteHandlerMethods, resolveAppRouteHandlerMethod, shouldReadAppRouteHandlerCache } from "./app-route-handler-policy.js";
+import { createStaticGenerationHeadersContext } from "./app-static-generation.js";
 import { applyDraftModeCachePolicy, executeAppRouteHandler } from "./app-route-handler-execution.js";
 import { readAppRouteHandlerCacheResponse } from "./app-route-handler-cache.js";
 //#region src/server/app-route-handler-dispatch.ts
@@ -25,14 +29,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"
 	});
@@ -55,6 +60,9 @@ 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();
@@ -84,11 +92,7 @@ async function dispatchAppRouteHandler(options) {
 		headers: { Allow: allowHeaderForOptions }
 	}));
 	const resolvedHandlerFn = isAppRouteHandlerFunction(handlerFn) ? handlerFn : void 0;
-	const fetchCacheMode = resolveAppRouteHandlerFetchCacheMode(handler);
-	setCurrentFetchCacheMode(fetchCacheMode);
-	setCurrentFetchRevalidate(configuredRevalidateSeconds);
-	setCurrentForceDynamicFetchDefault(handler.dynamic === "force-dynamic");
-	if (revalidateSeconds !== null && !getRouteCacheabilityDynamicReason() && shouldReadAppRouteHandlerCache({
+	const shouldReadRouteCache = options.bypassSharedCache !== true && revalidateSeconds !== null && !getRouteCacheabilityDynamicReason() && shouldReadAppRouteHandlerCache({
 		dynamicConfig: handler.dynamic,
 		handlerFn: resolvedHandlerFn,
 		isAutoHead,
@@ -97,7 +101,14 @@ async function dispatchAppRouteHandler(options) {
 		isProduction,
 		method,
 		revalidateSeconds
-	}) && resolvedHandlerFn) {
+	});
+	const revalidateReason = isOnDemandRevalidateRequest(options.request.headers.get("x-prerender-revalidate")) ? "on-demand" : shouldReadRouteCache && revalidateSeconds !== Infinity ? "stale" : void 0;
+	const fetchCacheMode = resolveAppRouteHandlerFetchCacheMode(handler);
+	setCurrentFetchCacheMode(fetchCacheMode);
+	setCurrentFetchRevalidate(configuredRevalidateSeconds);
+	setCurrentForceDynamicFetchDefault(handler.dynamic === "force-dynamic");
+	let isRevalidation = false;
+	if (shouldReadRouteCache && resolvedHandlerFn) {
 		const cachedRouteResponse = await readAppRouteHandlerCacheResponse({
 			basePath: options.basePath,
 			buildPageCacheTags(pathname, extraTags) {
@@ -114,7 +125,11 @@ async function dispatchAppRouteHandler(options) {
 			isAutoHead,
 			appendResponseLink,
 			isrDebug: options.isrDebug,
-			isrGet: options.isrGet,
+			async isrGet(key) {
+				const entry = await options.isrGet(key);
+				isRevalidation = entry?.value.value?.kind === "APP_ROUTE";
+				return entry;
+			},
 			isrRouteKey: options.isrRouteKey,
 			isrSet: options.isrSet,
 			markDynamicUsage,
@@ -148,45 +163,51 @@ async function dispatchAppRouteHandler(options) {
 		});
 		if (cachedRouteResponse) return applyCdnResponseBuildIdentityHeaders(cachedRouteResponse);
 	}
-	if (resolvedHandlerFn) return applyCdnResponseBuildIdentityHeaders(await 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
-	}));
+	if (resolvedHandlerFn) {
+		const response = await executeAppRouteHandler({
+			isRevalidation,
+			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);
+	}
 	return finalizeFrameworkResponse(new Response(null, { status: 405 }));
 }
 //#endregion