vinext 1.0.0-beta.8 → 1.0.0

package/dist/server/app-page-cache-finalizer.js

@@ -1,21 +1,26 @@
 import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER } from "./headers.js";
+import { getCdnCacheAdapter } from "../shims/cdn-cache.js";
+import { captureRouteCacheabilityResponsePolicy, deferRouteCacheability, isRouteCacheabilityEvaluation } from "../shims/cacheability-classification.js";
+import { NO_STORE_CACHE_CONTROL, STATIC_CACHE_CONTROL, applyCdnResponseHeaders, buildRevalidateCacheControl, captureCdnResponsePolicyHeaders, hasExplicitNonCacheableResponsePolicy } from "./cache-control.js";
+import { buildAppPageCacheValue, isrCacheControl, resolveRouteExpireSeconds } from "./isr-cache.js";
 import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
-import { NO_STORE_CACHE_CONTROL, applyCdnResponseHeaders } from "./cache-control.js";
-import { buildAppPageCacheValue, isrCacheControl } from "./isr-cache.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
 import { readStreamAsText } from "../utils/text-stream.js";
+import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
 import { markFrameworkLinkHeaders } from "./app-response-header-provenance.js";
+import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { createEmptyAppPageRenderObservationState } from "./app-page-render-observation.js";
 //#region src/server/app-page-cache-finalizer.ts
 function applyPendingDynamicCdnHeaders(headers, tags, options = {}) {
+	const cacheable = headers.get("Cache-Control") ?? "";
 	applyCdnResponseHeaders(headers, {
-		cacheControl: headers.get("Cache-Control") ?? "",
+		cacheControl: cacheable,
 		pendingDynamicCheck: true,
 		tags
 	});
 	finalizePendingCacheStateHeaders(headers, options);
 }
-function applyUncacheableRscVariantNoStoreHeaders(headers, options = {}) {
+function applyUncacheableVariantNoStoreHeaders(headers, options = {}) {
 	applyCdnResponseHeaders(headers, { cacheControl: NO_STORE_CACHE_CONTROL });
 	finalizePendingCacheStateHeaders(headers, {
 		...options,
@@ -33,17 +38,99 @@ function finalizePendingCacheStateHeaders(headers, options = {}) {
 }
 function resolveAppPageCacheControl(options) {
 	let revalidateSeconds = options.revalidateSeconds;
-	let expireSeconds = options.expireSeconds;
 	const requestCacheLife = options.requestCacheLife;
 	if (requestCacheLife?.revalidate !== void 0) revalidateSeconds = revalidateSeconds === null ? requestCacheLife.revalidate : Math.min(revalidateSeconds, requestCacheLife.revalidate);
-	if (requestCacheLife?.expire !== void 0) expireSeconds = requestCacheLife.expire;
+	const expireSeconds = requestCacheLife?.expire ?? resolveRouteExpireSeconds(revalidateSeconds, options.expireSeconds);
 	if (revalidateSeconds === null || Number.isNaN(revalidateSeconds) || revalidateSeconds <= 0) return null;
 	return isrCacheControl(revalidateSeconds, {
 		expireSeconds,
 		staleSeconds: resolveClientStaleTimeSeconds(requestCacheLife)
 	});
 }
+function appPageCacheControlHeader(cacheControl) {
+	return cacheControl.revalidate === Infinity ? STATIC_CACHE_CONTROL : buildRevalidateCacheControl(cacheControl.revalidate, cacheControl.expire);
+}
+function finalizeEvaluatedAppPageResponse(response, options) {
+	if (!isRouteCacheabilityEvaluation()) return null;
+	const complete = deferRouteCacheability();
+	if (!complete) return response;
+	captureRouteCacheabilityResponsePolicy(captureCdnResponsePolicyHeaders(response.headers));
+	let completed = false;
+	const finish = () => {
+		if (completed) return;
+		completed = true;
+		const observationState = options.consumeRenderObservationState?.();
+		let outcome;
+		if (options.capturedDynamicUsageBeforeContextCleanup?.() === true || options.consumeDynamicUsage()) outcome = {
+			cacheable: false,
+			dynamicUsage: true,
+			reason: "dynamic API used during render"
+		};
+		else if (options.isStaticEligible === false) outcome = {
+			cacheable: false,
+			reason: "route is not statically generated"
+		};
+		else if (response.headers.has("set-cookie") || hasExplicitNonCacheableResponsePolicy(response.headers)) outcome = {
+			cacheable: false,
+			reason: "response explicitly opts out of shared caching"
+		};
+		else {
+			const cacheControl = resolveAppPageCacheControl({
+				expireSeconds: options.expireSeconds,
+				requestCacheLife: options.getRequestCacheLife?.(),
+				revalidateSeconds: options.revalidateSeconds
+			});
+			outcome = cacheControl ? {
+				cacheable: true,
+				cacheControl: appPageCacheControlHeader(cacheControl),
+				...observationState && !observationState.requestApis.includes("searchParams") ? { searchParamsUnread: true } : {},
+				tags: options.getPageTags()
+			} : {
+				cacheable: false,
+				reason: "render did not produce a cache policy"
+			};
+		}
+		complete(outcome);
+	};
+	if (!response.body) {
+		finish();
+		return response;
+	}
+	return new Response(deferUntilStreamConsumed(response.body, finish), {
+		headers: response.headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+/**
+* Complete probe/admission classification for an App Page response that does
+* not enter the ISR cache-write path. Ordinary requests pass through unchanged.
+*/
+function finalizeAppPageCacheabilityEvaluationResponse(response, options) {
+	return finalizeEvaluatedAppPageResponse(response, options) ?? response;
+}
 function finalizeAppPageHtmlCacheResponse(response, options) {
+	const probeResponse = finalizeEvaluatedAppPageResponse(response, options);
+	if (probeResponse) {
+		if (options.capturedRscDataPromise) {
+			const adapter = getCdnCacheAdapter();
+			if (adapter.captureAppPageRscData) adapter.captureAppPageRscData(options.capturedRscDataPromise);
+			else options.capturedRscDataPromise.catch(() => {});
+		}
+		return probeResponse;
+	}
+	if (options.bypassInterceptionContextCache === true) {
+		options.capturedRscDataPromise?.catch(() => {});
+		const headers = new Headers(response.headers);
+		applyUncacheableVariantNoStoreHeaders(headers, { omitCacheState: options.omitPendingDynamicCacheState === true });
+		const clientResponse = new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers
+		});
+		markFrameworkLinkHeaders(clientResponse.headers, options.linkHeader);
+		return clientResponse;
+	}
 	if (!response.body) return response;
 	const [streamForClient, streamForCache] = response.body.tee();
 	const htmlKey = options.isrHtmlKey(options.cleanPathname);
@@ -52,7 +139,7 @@ function finalizeAppPageHtmlCacheResponse(response, options) {
 	if (options.preserveClientResponseHeaders !== true) applyPendingDynamicCdnHeaders(clientHeaders, options.getPageTags(), { omitCacheState: options.omitPendingDynamicCacheState === true });
 	const cachePromise = (async () => {
 		try {
-			const cachedHtml = await readStreamAsText(streamForCache);
+			let cachedHtml = await readStreamAsText(streamForCache);
 			if (options.capturedDynamicUsageBeforeContextCleanup?.() === true || options.consumeDynamicUsage()) {
 				options.isrDebug?.("HTML cache write skipped (dynamic usage during render)", htmlKey);
 				return;
@@ -66,17 +153,25 @@ function finalizeAppPageHtmlCacheResponse(response, options) {
 				options.isrDebug?.("HTML cache write skipped (no cache policy)", htmlKey);
 				return;
 			}
+			if (options.clientTraceMetadataMarker) {
+				const { stripClientTraceMetadataBlock } = await import("./client-trace-metadata.js");
+				cachedHtml = stripClientTraceMetadataBlock(cachedHtml, options.clientTraceMetadataMarker);
+			}
 			const pageTags = options.getPageTags();
 			const observationState = options.consumeRenderObservationState?.() ?? createEmptyAppPageRenderObservationState();
-			const htmlRenderObservation = options.createHtmlRenderObservation?.({
+			const htmlRenderObservation = options.createHtmlRenderObservation({
 				cacheTags: pageTags,
 				state: observationState
 			});
-			const rscRenderObservation = options.createRscRenderObservation?.({
+			const rscRenderObservation = options.createRscRenderObservation({
 				cacheTags: pageTags,
 				state: observationState
 			});
 			const linkHeader = options.linkHeader;
+			if (!hasQueryInvariantRenderProof(htmlRenderObservation) || !hasQueryInvariantRenderProof(rscRenderObservation)) {
+				options.isrDebug?.("HTML cache write skipped (searchParams not proven unread)", htmlKey);
+				return;
+			}
 			const writes = [options.isrSet(htmlKey, buildAppPageCacheValue(cachedHtml, void 0, 200, htmlRenderObservation, linkHeader ? { link: linkHeader } : void 0), {
 				cacheControl,
 				tags: pageTags
@@ -101,11 +196,16 @@ function finalizeAppPageHtmlCacheResponse(response, options) {
 	return clientResponse;
 }
 function finalizeAppPageRscCacheResponse(response, options) {
+	const probeResponse = finalizeEvaluatedAppPageResponse(response, options);
+	if (probeResponse) {
+		options.capturedRscDataPromise?.catch(() => {});
+		return probeResponse;
+	}
 	scheduleAppPageRscCacheWrite(options);
-	const isUncacheableVariant = Boolean(options.mountedSlotsHeader);
+	const isUncacheableVariant = Boolean(options.mountedSlotsHeader) || options.bypassInterceptionContextCache === true;
 	if (options.preserveClientResponseHeaders === true && !isUncacheableVariant) return response;
 	const clientHeaders = new Headers(response.headers);
-	if (isUncacheableVariant) applyUncacheableRscVariantNoStoreHeaders(clientHeaders, { omitCacheState: options.omitPendingDynamicCacheState === true });
+	if (isUncacheableVariant) applyUncacheableVariantNoStoreHeaders(clientHeaders, { omitCacheState: options.omitPendingDynamicCacheState === true });
 	else applyPendingDynamicCdnHeaders(clientHeaders, options.getPageTags(), { omitCacheState: options.omitPendingDynamicCacheState === true });
 	return new Response(response.body, {
 		status: response.status,
@@ -115,7 +215,7 @@ function finalizeAppPageRscCacheResponse(response, options) {
 }
 function scheduleAppPageRscCacheWrite(options) {
 	const capturedRscDataPromise = options.capturedRscDataPromise;
-	if (!capturedRscDataPromise || options.dynamicUsedDuringBuild || options.mountedSlotsHeader) return false;
+	if (!capturedRscDataPromise || options.dynamicUsedDuringBuild || options.mountedSlotsHeader || options.bypassInterceptionContextCache === true) return false;
 	const rscKey = options.isrRscKey(options.cleanPathname, null, options.renderMode, options.interceptionContext, options.interceptionId);
 	const cachePromise = (async () => {
 		try {
@@ -135,10 +235,14 @@ function scheduleAppPageRscCacheWrite(options) {
 			}
 			const pageTags = options.getPageTags();
 			const observationState = options.consumeRenderObservationState?.() ?? createEmptyAppPageRenderObservationState();
-			const rscRenderObservation = options.createRscRenderObservation?.({
+			const rscRenderObservation = options.createRscRenderObservation({
 				cacheTags: pageTags,
 				state: observationState
 			});
+			if (!hasQueryInvariantRenderProof(rscRenderObservation)) {
+				options.isrDebug?.("RSC cache write skipped (searchParams not proven unread)", rscKey);
+				return;
+			}
 			await options.isrSet(rscKey, buildAppPageCacheValue("", rscData, 200, rscRenderObservation), {
 				cacheControl,
 				tags: pageTags
@@ -152,4 +256,4 @@ function scheduleAppPageRscCacheWrite(options) {
 	return true;
 }
 //#endregion
-export { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite };
+export { finalizeAppPageCacheabilityEvaluationResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite };

package/dist/server/app-page-cache-render.d.ts

@@ -12,7 +12,7 @@ type AppPageCacheRoute = {
   pattern: string;
   routeSegments: readonly string[];
 };
-type RenderAppPageCacheArtifactsOptions = {
+export type RenderAppPageCacheArtifactsOptions = {
   basePath?: string;
   captureRscData: boolean;
   cleanPathname: string;
@@ -25,7 +25,9 @@ type RenderAppPageCacheArtifactsOptions = {
   loadSsrHandler: () => Promise<AppPageSsrHandler>;
   mountedSlotsHeader?: string | null;
   navigationParams: Record<string, unknown>;
+  isCapturedRscError?: (error: unknown) => boolean;
   onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
+  onSsrError?: (error: unknown) => unknown;
   reactMaxHeadersLength?: number;
   renderToReadableStream: (element: AppPageRenderableElement, options: {
     onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
@@ -35,7 +37,7 @@ type RenderAppPageCacheArtifactsOptions = {
   waitForAllReady?: boolean;
   isForceStatic?: boolean;
 };
-type RenderAppPageCacheArtifactsResult = {
+export type RenderAppPageCacheArtifactsResult = {
   cacheControl?: CacheControlMetadata;
   html: string;
   htmlRenderObservation: ReturnType<typeof createAppPageRenderObservation>;
@@ -43,6 +45,8 @@ type RenderAppPageCacheArtifactsResult = {
   rscData?: ArrayBuffer;
   rscRenderObservation?: ReturnType<typeof createAppPageRenderObservation>;
   tags: string[];
+  /** The render used a dynamic API, so its output must not be stored. */
+  usedDynamicApi: boolean;
 };
 /**
  * Render an App page element to HTML (and optionally its RSC payload) for cache
@@ -50,6 +54,5 @@ type RenderAppPageCacheArtifactsResult = {
  * cache-tag construction used by both normal ISR revalidation and PPR fallback
  * shell regeneration.
  */
-declare function renderAppPageCacheArtifacts(options: RenderAppPageCacheArtifactsOptions): Promise<RenderAppPageCacheArtifactsResult>;
-//#endregion
-export { RenderAppPageCacheArtifactsOptions, RenderAppPageCacheArtifactsResult, renderAppPageCacheArtifacts };
+export declare function renderAppPageCacheArtifacts(options: RenderAppPageCacheArtifactsOptions): Promise<RenderAppPageCacheArtifactsResult>;
+//#endregion

package/dist/server/app-page-cache-render.js

@@ -1,11 +1,12 @@
-import { consumeDynamicUsage, consumeInvalidDynamicUsageError } from "../shims/headers.js";
+import { consumeDynamicUsage, consumeInvalidDynamicUsageError, isRenderDynamicLatched } from "../shims/headers.js";
 import { _consumeRequestScopedCacheLife } from "../shims/cache-request-state.js";
 import { getCollectedFetchTags } from "../shims/fetch-cache.js";
 import { readStreamAsText } from "../utils/text-stream.js";
 import { buildAppPageFontLinkHeader, teeAppPageRscStreamForCapture } from "./app-page-execution.js";
+import { recordAppPageRenderError, traceAppPageRender } from "./app-page-tracing.js";
 import { buildAppPageTags } from "./implicit-tags.js";
 import { consumeAppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope } from "./app-page-render-observation.js";
-import { buildAppPageLinkHeader, isAppSsrRenderResult } from "./app-page-stream.js";
+import { buildAppPageLinkHeader, createAppPageSsrErrorHandler, isAppSsrRenderResult } from "./app-page-stream.js";
 //#region src/server/app-page-cache-render.ts
 /**
 * Render an App page element to HTML (and optionally its RSC payload) for cache
@@ -14,7 +15,14 @@ import { buildAppPageLinkHeader, isAppSsrRenderResult } from "./app-page-stream.
 * shell regeneration.
 */
 async function renderAppPageCacheArtifacts(options) {
-	const rscCapture = teeAppPageRscStreamForCapture(options.renderToReadableStream(options.element, { onError: options.onError }), options.captureRscData);
+	return traceAppPageRender(options.route.pattern, "prerender", (renderSpan) => renderAppPageCacheArtifactsImpl(options, renderSpan));
+}
+async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
+	const rscStream = options.renderToReadableStream(options.element, { onError(error, requestInfo, errorContext) {
+		recordAppPageRenderError(renderSpan, error);
+		return options.onError(error, requestInfo, errorContext);
+	} });
+	const rscCapture = teeAppPageRscStreamForCapture(rscStream, options.captureRscData);
 	const capturedRscDataRef = { value: null };
 	const fontPreloads = options.getFontPreloads();
 	const htmlResult = await (await options.loadSsrHandler()).handleSsr(rscCapture.ssrStream, options.getNavigationContext(), {
@@ -29,13 +37,21 @@ async function renderAppPageCacheArtifacts(options) {
 		waitForAllReady: options.waitForAllReady,
 		isStaticGeneration: true,
 		isForceStatic: options.isForceStatic,
+		onSsrError: options.onSsrError && options.isCapturedRscError ? createAppPageSsrErrorHandler((error) => {
+			recordAppPageRenderError(renderSpan, error);
+			return options.onSsrError?.(error);
+		}, options.isCapturedRscError) : options.onSsrError ? (error) => {
+			recordAppPageRenderError(renderSpan, error);
+			return options.onSsrError?.(error);
+		} : void 0,
 		...rscCapture.sideStream ? {
 			sideStream: rscCapture.sideStream,
 			capturedRscDataRef
 		} : {}
 	});
 	const htmlStream = isAppSsrRenderResult(htmlResult) ? htmlResult.htmlStream : htmlResult;
-	const linkHeader = buildAppPageLinkHeader(isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
+	const reactLinkHeader = isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0;
+	const linkHeader = buildAppPageLinkHeader(reactLinkHeader, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
 	const html = await readStreamAsText(htmlStream);
 	let rscData;
 	if (options.captureRscData) {
@@ -47,7 +63,7 @@ async function renderAppPageCacheArtifacts(options) {
 	const tags = buildAppPageTags(options.cleanPathname, getCollectedFetchTags(), options.route.routeSegments);
 	const observationState = consumeAppPageRenderObservationState();
 	consumeInvalidDynamicUsageError();
-	consumeDynamicUsage();
+	const usedDynamicApi = consumeDynamicUsage() || isRenderDynamicLatched();
 	const result = {
 		html,
 		htmlRenderObservation: createAppPageRenderObservation({
@@ -67,6 +83,7 @@ async function renderAppPageCacheArtifacts(options) {
 		}),
 		...linkHeader ? { linkHeader } : {},
 		tags,
+		usedDynamicApi,
 		cacheControl: typeof cacheLife?.revalidate === "number" ? {
 			revalidate: cacheLife.revalidate,
 			expire: cacheLife.expire,

package/dist/server/app-page-cache.d.ts

@@ -8,7 +8,7 @@ type AppPageDebugLogger = (event: string, detail: string) => void;
 type AppPageCacheGetter = (key: string) => Promise<ISRCacheEntry | null>;
 type AppPageBackgroundRegenerator = (key: string, renderFn: () => Promise<void>) => void;
 type AppPageRscCacheKeyBuilder = (pathname: string, mountedSlotsHeader?: string | null, renderMode?: AppRscRenderMode, interceptionContext?: string | null, interceptionId?: string | null) => string;
-type AppPageCacheOutcomeMetric = Readonly<{
+export type AppPageCacheOutcomeMetric = Readonly<{
   artifact: "html" | "rsc";
   /**
    * Internal cache lookup key for debugging and tests. Runtime telemetry sinks should hash or
@@ -22,11 +22,18 @@ type AppPageCacheOutcomeRecorder = (metric: AppPageCacheOutcomeMetric) => void;
 type AppPageCacheRenderResult = {
   cacheControl?: CacheControlMetadata;
   html: string;
-  htmlRenderObservation?: RenderObservation;
+  htmlRenderObservation: RenderObservation;
   linkHeader?: string;
   rscData: ArrayBuffer;
-  rscRenderObservation?: RenderObservation;
+  rscRenderObservation: RenderObservation;
+  /**
+   * The route-level revalidate of the route this render regenerated, or null
+   * when it has none and the render's cacheLife sets it. Undefined keeps the
+   * matched route's read seed, as when the render regenerated that route.
+   */
+  revalidateSeconds?: number | null;
   tags: string[];
+  usedDynamicApi: boolean;
 };
 type BuildAppPageCachedResponseOptions = {
   cacheControl?: CacheControlMetadata;
@@ -37,12 +44,17 @@ type BuildAppPageCachedResponseOptions = {
   middlewareHeaders?: Headers | null;
   middlewareStatus?: number | null;
   mountedSlotsHeader?: string | null;
+  /** The current request's route params, which the client reads on RSC responses. */
+  params?: Record<string, string | string[]>;
+  /** The current request's path and query, which the client reads on RSC responses. */
+  renderedPathAndSearch?: string | null;
   revalidateSeconds: number;
 };
 type ReadAppPageCacheResponseOptions = {
   cleanPathname: string;
   clearRequestContext: () => void;
   isEdgeRuntime?: boolean;
+  isRoutePPREnabled?: boolean;
   isRscRequest: boolean;
   isrDebug?: AppPageDebugLogger;
   isrGet: AppPageCacheGetter;
@@ -55,7 +67,14 @@ type ReadAppPageCacheResponseOptions = {
   middlewareHeaders?: Headers | null;
   middlewareStatus?: number | null;
   mountedSlotsHeader?: string | null;
+  /**
+   * Resolves the current request's route params for a cached RSC response.
+   * Called only once an entry can answer the request, since resolving them
+   * may load route modules.
+   */
+  resolveParams?: () => Promise<Record<string, string | string[]>>;
   recordCacheOutcome?: AppPageCacheOutcomeRecorder;
+  renderedPathAndSearch?: string | null;
   renderMode?: AppRscRenderMode;
   expireSeconds?: number;
   revalidateSeconds: number;
@@ -75,10 +94,10 @@ type ReadAppPageFallbackShellCacheResponseOptions = {
   revalidateSeconds: number;
   rewriteHtml: (html: string) => string;
 };
-declare function buildAppPageCacheTags(pathname: string, extraTags: readonly string[]): string[];
-declare function buildAppRouteCacheTags(pathname: string, extraTags: readonly string[], routeSegments: readonly string[]): string[];
-declare function buildAppPageCachedResponse(cachedValue: CachedAppPageValue, options: BuildAppPageCachedResponseOptions): Response | null;
-declare function readAppPageCacheResponse(options: ReadAppPageCacheResponseOptions): Promise<Response | null>;
-declare function readAppPageFallbackShellCacheResponse(options: ReadAppPageFallbackShellCacheResponseOptions): Promise<Response | null>;
+export declare function buildAppPageCacheTags(pathname: string, extraTags: readonly string[]): string[];
+export declare function buildAppRouteCacheTags(pathname: string, extraTags: readonly string[], routeSegments: readonly string[]): string[];
+export declare function buildAppPageCachedResponse(cachedValue: CachedAppPageValue, options: BuildAppPageCachedResponseOptions): Response | null;
+export declare function readAppPageCacheResponse(options: ReadAppPageCacheResponseOptions): Promise<Response | null>;
+export declare function readAppPageFallbackShellCacheResponse(options: ReadAppPageFallbackShellCacheResponseOptions): Promise<Response | null>;
 //#endregion
-export { AppPageCacheOutcomeMetric, buildAppPageCacheTags, buildAppPageCachedResponse, buildAppRouteCacheTags, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, readAppPageCacheResponse, readAppPageFallbackShellCacheResponse, scheduleAppPageRscCacheWrite };
+export { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite };

package/dist/server/app-page-cache.js

@@ -1,15 +1,16 @@
-import { VINEXT_MOUNTED_SLOTS_HEADER } from "./headers.js";
-import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
+import { VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_RSC_VARY_HEADER } from "./app-rsc-vary.js";
+import { VINEXT_PARAMS_HEADER, VINEXT_RENDERED_PATH_AND_SEARCH_HEADER } from "./headers.js";
 import { applyCdnResponseHeaders } from "./cache-control.js";
 import { decideIsr } from "./isr-decision.js";
-import { buildAppPageCacheValue, isrCacheControl } from "./isr-cache.js";
+import { buildAppPageCacheValue, isrCacheControl, resolveRouteExpireSeconds } from "./isr-cache.js";
+import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
 import { encodeCacheTag } from "../utils/encode-cache-tag.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
-import { VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader } from "./app-rsc-cache-busting.js";
+import { VINEXT_RSC_CONTENT_TYPE, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader } from "./app-rsc-cache-busting.js";
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
 import { markFrameworkLinkHeaders } from "./app-response-header-provenance.js";
 import { applyClientStaleTimeHeader, applyEdgeRuntimeHeader } from "./app-page-response.js";
-import { hasCompleteNegativeRequestApiProof } from "./cache-proof.js";
+import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { isAppPprDynamicFallbackShellHtml } from "./app-ppr-fallback-shell.js";
 import { buildPageCacheTags } from "./implicit-tags.js";
 import { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite } from "./app-page-cache-finalizer.js";
@@ -49,28 +50,44 @@ function buildAppPageCachedHeaders(options) {
 	applyCdnResponseHeaders(headers, { cacheControl: options.cacheControl });
 	setCacheStateHeaders(headers, options.cacheState);
 	applyEdgeRuntimeHeader(headers, options.isEdgeRuntime);
+	if (options.params && Object.keys(options.params).length > 0) headers.set(VINEXT_PARAMS_HEADER, encodeURIComponent(JSON.stringify(options.params)));
 	if (options.mountedSlotsHeader) headers.set(VINEXT_MOUNTED_SLOTS_HEADER, options.mountedSlotsHeader);
 	applyClientStaleTimeHeader(headers, options.staleTimeSeconds);
 	mergeMiddlewareResponseHeaders(headers, options.middlewareHeaders ?? null);
-	if (options.linkHeader) if (Array.isArray(options.linkHeader)) for (const value of options.linkHeader) headers.append("Link", value);
-	else headers.append("Link", options.linkHeader);
+	if (options.linkHeader) {
+		if (Array.isArray(options.linkHeader)) for (const value of options.linkHeader) headers.append("Link", value);
+		else headers.append("Link", options.linkHeader);
+	}
 	return headers;
 }
 function getCachedAppPageValue(entry) {
 	return entry?.value.value && entry.value.value.kind === "APP_PAGE" ? entry.value.value : null;
 }
-function hasQueryInvariantAppPageProof(cachedValue) {
-	return cachedValue.renderObservation !== void 0 && hasCompleteNegativeRequestApiProof(cachedValue.renderObservation, ["searchParams"]);
-}
 function resolveRegeneratedAppPageCacheControl(options) {
-	let revalidateSeconds = options.routeRevalidateSeconds;
 	const renderRevalidateSeconds = options.renderCacheControl?.revalidate;
-	if (typeof renderRevalidateSeconds === "number") revalidateSeconds = revalidateSeconds > 0 ? Math.min(revalidateSeconds, renderRevalidateSeconds) : renderRevalidateSeconds;
+	let revalidateSeconds;
+	if (typeof renderRevalidateSeconds === "number") revalidateSeconds = options.routeRevalidateSeconds === null ? renderRevalidateSeconds : Math.min(options.routeRevalidateSeconds, renderRevalidateSeconds);
+	else revalidateSeconds = options.routeRevalidateSeconds ?? 0;
 	return isrCacheControl(revalidateSeconds, {
-		expireSeconds: options.renderCacheControl?.expire ?? options.expireSeconds,
+		expireSeconds: options.renderCacheControl?.expire ?? resolveRouteExpireSeconds(revalidateSeconds, options.expireSeconds),
 		staleSeconds: resolveClientStaleTimeSeconds(options.renderCacheControl)
 	});
 }
+/**
+* When a regeneration fails, Next.js re-stores the previous entry with a short
+* revalidate so it isn't retried on every request
+* (`server/response-cache/index.ts`). `revalidate = false`, which vinext holds
+* as Infinity, retries after 3 s like Next.js's `revalidate || 3`.
+*/
+function resolveRegenerationFailureCacheControl(previous) {
+	const previousRevalidate = typeof previous.revalidate === "number" && Number.isFinite(previous.revalidate) ? previous.revalidate : 0;
+	const revalidate = Math.min(Math.max(previousRevalidate || 3, 3), 30);
+	return {
+		revalidate,
+		...previous.expire === void 0 ? {} : { expire: Math.max(revalidate + 3, previous.expire) },
+		...previous.stale === void 0 ? {} : { stale: previous.stale }
+	};
+}
 function buildAppPageCachedResponse(cachedValue, options) {
 	const status = options.middlewareStatus ?? (cachedValue.status || 200);
 	const { cacheControl } = decideIsr({
@@ -90,8 +107,10 @@ function buildAppPageCachedResponse(cachedValue, options) {
 			isEdgeRuntime: options.isEdgeRuntime,
 			middlewareHeaders: options.middlewareHeaders,
 			mountedSlotsHeader: options.mountedSlotsHeader,
+			params: options.params,
 			staleTimeSeconds
 		});
+		if (options.renderedPathAndSearch) rscHeaders.set(VINEXT_RENDERED_PATH_AND_SEARCH_HEADER, encodeURIComponent(options.renderedPathAndSearch));
 		applyRscCompatibilityIdHeader(rscHeaders);
 		applyRscDeploymentIdHeader(rscHeaders);
 		return new Response(cachedValue.rscData, {
@@ -150,6 +169,16 @@ async function readAppPageCacheResponse(options) {
 	}
 	const isrKey = options.isRscRequest ? options.isrRscKey(options.cleanPathname, null, options.renderMode, options.interceptionContext, options.interceptionId) : options.isrHtmlKey(options.cleanPathname);
 	const artifact = options.isRscRequest ? "rsc" : "html";
+	let paramsFailure;
+	const resolveCachedResponseParams = async (cachedValue) => {
+		if (!options.isRscRequest || !cachedValue.rscData) return void 0;
+		try {
+			return await options.resolveParams?.();
+		} catch (error) {
+			paramsFailure = { error };
+			throw error;
+		}
+	};
 	try {
 		const cached = await options.isrGet(isrKey);
 		const cachedValue = getCachedAppPageValue(cached);
@@ -173,7 +202,7 @@ async function readAppPageCacheResponse(options) {
 			options.isrDebug?.("MISS (non app-page cache entry)", options.cleanPathname);
 			return null;
 		}
-		if (cachedValue && options.hasRequestSearchParams === true && !hasQueryInvariantAppPageProof(cachedValue)) {
+		if (cachedValue && options.hasRequestSearchParams === true && cachedValue.prerendered !== true && !hasQueryInvariantRenderProof(cachedValue.renderObservation)) {
 			recordAppPageCacheOutcome(options.recordCacheOutcome, {
 				artifact,
 				cacheKey: isrKey,
@@ -193,6 +222,8 @@ async function readAppPageCacheResponse(options) {
 				middlewareHeaders: options.middlewareHeaders,
 				middlewareStatus: options.middlewareStatus,
 				mountedSlotsHeader: options.mountedSlotsHeader,
+				params: await resolveCachedResponseParams(cachedValue),
+				renderedPathAndSearch: options.renderedPathAndSearch,
 				revalidateSeconds: options.revalidateSeconds
 			});
 			if (hitResponse) {
@@ -215,23 +246,60 @@ async function readAppPageCacheResponse(options) {
 			options.isrDebug?.("MISS (empty cached entry)", options.cleanPathname);
 		}
 		if (cached?.isStale && cachedValue) {
-			options.scheduleBackgroundRegeneration(isrKey, async () => {
+			const keepPreviousEntry = async (key, previous) => {
+				const previousValue = getCachedAppPageValue(previous);
+				const previousCacheControl = previous.value.cacheControl;
+				const previousTags = previousValue?.renderObservation?.cacheTags;
+				if (!previousValue || !previousCacheControl || !previousTags || previous.isExpired) return;
+				try {
+					const current = await options.isrGet(key);
+					if (!current || current.value.lastModified === previous.value.lastModified) await options.isrSet(key, previousValue, {
+						cacheControl: resolveRegenerationFailureCacheControl(previousCacheControl),
+						tags: [...previousTags]
+					});
+				} catch (storeError) {
+					console.error(`[vinext] Failed to keep the previous entry for ${key}:`, storeError);
+				}
+			};
+			const regenerate = async () => {
 				const revalidatedPage = await options.renderFreshPageForCache();
 				const cacheControl = resolveRegeneratedAppPageCacheControl({
 					expireSeconds: options.expireSeconds,
 					renderCacheControl: revalidatedPage.cacheControl,
-					routeRevalidateSeconds: options.revalidateSeconds
+					routeRevalidateSeconds: revalidatedPage.revalidateSeconds === void 0 ? options.revalidateSeconds || null : revalidatedPage.revalidateSeconds
 				});
-				const writes = [options.isrSet(options.isRscRequest ? isrKey : options.isrRscKey(options.cleanPathname, null, options.renderMode, options.interceptionContext, options.interceptionId), buildAppPageCacheValue("", revalidatedPage.rscData, 200, revalidatedPage.rscRenderObservation), {
-					cacheControl,
-					tags: revalidatedPage.tags
-				})];
-				if (!options.isRscRequest) writes.push(options.isrSet(isrKey, buildAppPageCacheValue(revalidatedPage.html, void 0, 200, revalidatedPage.htmlRenderObservation, revalidatedPage.linkHeader ? { link: revalidatedPage.linkHeader } : void 0), {
-					cacheControl,
-					tags: revalidatedPage.tags
-				}));
-				await Promise.all(writes);
+				if (options.isRoutePPREnabled !== true && (revalidatedPage.usedDynamicApi || cacheControl.revalidate === 0)) throw new Error(`Page changed from static to dynamic at runtime ${options.cleanPathname}
+see more here https://nextjs.org/docs/messages/app-static-to-dynamic-error`);
+				if (!hasQueryInvariantRenderProof(revalidatedPage.rscRenderObservation) || !options.isRscRequest && !hasQueryInvariantRenderProof(revalidatedPage.htmlRenderObservation)) {
+					options.isrDebug?.("regen write skipped (searchParams not proven unread)", isrKey);
+					return;
+				}
+				const rscKey = options.isRscRequest ? isrKey : options.isrRscKey(options.cleanPathname, null, options.renderMode, options.interceptionContext, options.interceptionId);
+				const store = async (key, value) => {
+					try {
+						await options.isrSet(key, value, {
+							cacheControl,
+							tags: revalidatedPage.tags
+						});
+						return true;
+					} catch (storeError) {
+						console.warn(`[vinext] Failed to update prerender cache for ${key}:`, storeError);
+						return false;
+					}
+				};
+				if (!await store(rscKey, buildAppPageCacheValue("", revalidatedPage.rscData, 200, revalidatedPage.rscRenderObservation))) return;
+				if (!options.isRscRequest) {
+					if (!await store(isrKey, buildAppPageCacheValue(revalidatedPage.html, void 0, 200, revalidatedPage.htmlRenderObservation, revalidatedPage.linkHeader ? { link: revalidatedPage.linkHeader } : void 0))) return;
+				}
 				options.isrDebug?.("regen complete", options.cleanPathname);
+			};
+			options.scheduleBackgroundRegeneration(isrKey, async () => {
+				try {
+					await regenerate();
+				} catch (error) {
+					await keepPreviousEntry(isrKey, cached);
+					throw error;
+				}
 			});
 			const staleResponse = buildAppPageCachedResponse(cachedValue, {
 				cacheState: "STALE",
@@ -242,6 +310,8 @@ async function readAppPageCacheResponse(options) {
 				middlewareHeaders: options.middlewareHeaders,
 				middlewareStatus: options.middlewareStatus,
 				mountedSlotsHeader: options.mountedSlotsHeader,
+				params: await resolveCachedResponseParams(cachedValue),
+				renderedPathAndSearch: options.renderedPathAndSearch,
 				revalidateSeconds: options.revalidateSeconds
 			});
 			if (staleResponse) {
@@ -273,6 +343,7 @@ async function readAppPageCacheResponse(options) {
 			options.isrDebug?.("MISS (no cache entry)", options.cleanPathname);
 		}
 	} catch (isrReadError) {
+		if (paramsFailure) throw paramsFailure.error;
 		recordAppPageCacheOutcome(options.recordCacheOutcome, {
 			artifact,
 			cacheKey: isrKey,