@vinext/cloudflare 1.0.0-beta.7 → 1.0.0-beta.8

package/dist/cdn-warm.d.ts

@@ -1,7 +1,7 @@
-import { PrerenderRoutePattern } from "vinext/internal/build/prerender-paths";
+import { PrerenderPathManifest, PrerenderRoutePattern } from "vinext/internal/build/prerender-paths";
 import { PrerenderManifest, PrerenderedPathSelectionOptions } from "vinext/internal/server/prerender-manifest";
 //#region src/cdn-warm.d.ts
-type CdnWarmOptions = {
+export type CdnWarmOptions = {
   targetUrl: string;
   paths: readonly string[];
   /** Pages Router JSON data identities used by client navigation. */
@@ -27,23 +27,27 @@ type CdnWarmOptions = {
   phaseTimeoutMs?: number;
   /** Retry a newly staged version or preview alias until its routing has propagated. */
   propagatingTarget?: boolean;
+  /** @internal Matching skipped targets that may be transient while a staged version propagates. */
+  retrySkippedTargetKeys?: ReadonlySet<string>;
   /** Require the response to come from a reusable cache entry, not merely an eligible MISS. */
   requireCacheHit?: boolean;
   strict?: boolean;
+  /** Cache-admission signal exposed by the deployed adapter. */
+  statusSource?: "cloudflare" | "vinext";
   fetchImpl?: typeof fetch;
 };
-declare const DEFAULT_CDN_WARM_CONCURRENCY = 25;
-declare const DEFAULT_CDN_WARM_TIMEOUT_MS = 10000;
-declare const DEFAULT_STAGED_READINESS_RETRIES = 60;
-declare const DEFAULT_STAGED_READINESS_INTERVAL_MS = 1000;
-declare const DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS = 120000;
-type PrerenderCdnWarmOptions = Omit<CdnWarmOptions, "paths"> & {
+export declare const DEFAULT_CDN_WARM_CONCURRENCY = 25;
+export declare const DEFAULT_CDN_WARM_TIMEOUT_MS = 10000;
+export declare const DEFAULT_STAGED_READINESS_RETRIES = 60;
+export declare const DEFAULT_STAGED_READINESS_INTERVAL_MS = 1000;
+export declare const DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS = 120000;
+export type PrerenderCdnWarmOptions = Omit<CdnWarmOptions, "paths"> & {
   root: string;
   includeFallbackShells?: boolean;
   /** Use the manifest build identity unless the configured adapter cannot expose it. */
   validateBuildIdentity?: boolean;
 };
-type CdnWarmResult = {
+export type CdnWarmResult = {
   total: number;
   warmed: number;
   skipped: number;
@@ -56,7 +60,7 @@ type CdnWarmResult = {
   warmedPlan: CdnWarmRequestPlan;
   retryPlan: CdnWarmRequestPlan;
 };
-type CdnWarmRequestPlan = {
+export type CdnWarmRequestPlan = {
   loadingShellPaths: string[];
   pagesDataPaths: string[];
   paths: string[];
@@ -64,13 +68,13 @@ type CdnWarmRequestPlan = {
   routeHandlerPaths?: string[];
   routePatterns?: Record<string, PrerenderRoutePattern>;
 };
-type CdnWarmReadinessResult = {
+export type CdnWarmReadinessResult = {
   ready: true;
 } | {
   error: string;
   ready: false;
 };
-type PrerenderWarmPlan = {
+export type PrerenderWarmPlan = {
   appPaths?: string[];
   buildId?: string;
   buildIdentity?: string;
@@ -85,17 +89,20 @@ type PrerenderWarmPlan = {
   rscBuildId?: string;
   rscPaths: string[];
 };
-declare function readPrerenderWarmPlan(root: string, options?: {
+type PrerenderWarmPlanOptions = {
+  includeCanonicalRsc?: boolean;
   includeFallbackShells?: boolean;
   strict?: boolean;
-}): PrerenderWarmPlan;
-declare function readPrerenderWarmPaths(root: string, options?: {
+};
+export declare function createPrerenderWarmPlan(root: string, manifest: PrerenderPathManifest, options?: PrerenderWarmPlanOptions): PrerenderWarmPlan;
+export declare function readPrerenderWarmPlan(root: string, options?: PrerenderWarmPlanOptions): PrerenderWarmPlan;
+export declare function readPrerenderWarmPaths(root: string, options?: {
   includeFallbackShells?: boolean;
   strict?: boolean;
 }): string[];
-declare function getWarmPathsFromPrerenderManifest(manifest: PrerenderManifest, options?: PrerenderedPathSelectionOptions): string[];
-declare function buildWarmupUrl(targetUrl: string, pathname: string): URL;
-type CdnWarmTarget = {
+export declare function getWarmPathsFromPrerenderManifest(manifest: PrerenderManifest, options?: PrerenderedPathSelectionOptions): string[];
+export declare function buildWarmupUrl(targetUrl: string, pathname: string): URL;
+export type CdnWarmTarget = {
   headers?: HeadersInit;
   kind: "app-route" | "html" | "pages-data" | "rsc-full" | "rsc-loading-shell";
   label: string;
@@ -103,8 +110,8 @@ type CdnWarmTarget = {
   sourcePathname: string;
   route?: PrerenderRoutePattern;
 };
-declare function createCdnWarmTargets(options: Pick<CdnWarmOptions, "deploymentId" | "headers" | "loadingShellPaths" | "pagesDataPaths" | "paths" | "routeHandlerPaths" | "routePatterns" | "rscPaths">): Promise<CdnWarmTarget[]>;
-declare class CdnOperationProgress {
+export declare function createCdnWarmTargets(options: Pick<CdnWarmOptions, "deploymentId" | "headers" | "loadingShellPaths" | "pagesDataPaths" | "paths" | "routeHandlerPaths" | "routePatterns" | "rscPaths">): Promise<CdnWarmTarget[]>;
+export declare class CdnOperationProgress {
   private readonly isTTY;
   private lastLineLength;
   update(completed: number, total: number, label: string, phase?: string): void;
@@ -115,7 +122,7 @@ declare class CdnOperationProgress {
  * before any real cache key is filled. Every probe has a unique query key, so
  * an early response cannot make a later readiness attempt pass from cache.
  */
-declare function waitForCdnWarmTargetReadiness(options: Pick<CdnWarmOptions, "deploymentId" | "expectedBuildId" | "expectedRscBuildId" | "fetchImpl" | "headers" | "retries" | "targetUrl" | "timeoutMs"> & {
+export declare function waitForCdnWarmTargetReadiness(options: Pick<CdnWarmOptions, "deploymentId" | "expectedBuildId" | "expectedRscBuildId" | "fetchImpl" | "headers" | "retries" | "targetUrl" | "timeoutMs"> & {
   plan: CdnWarmRequestPlan;
   maxAttempts?: number;
   phaseTimeoutMs?: number;
@@ -123,7 +130,6 @@ declare function waitForCdnWarmTargetReadiness(options: Pick<CdnWarmOptions, "de
   probeIntervalMs?: number;
   requiredConsecutiveSuccesses?: number;
 }): Promise<CdnWarmReadinessResult>;
-declare function warmCdnCache(options: CdnWarmOptions): Promise<CdnWarmResult>;
-declare function warmCdnCacheFromPrerender(options: PrerenderCdnWarmOptions): Promise<CdnWarmResult>;
-//#endregion
-export { CdnOperationProgress, CdnWarmOptions, CdnWarmReadinessResult, CdnWarmRequestPlan, CdnWarmResult, CdnWarmTarget, DEFAULT_CDN_WARM_CONCURRENCY, DEFAULT_CDN_WARM_TIMEOUT_MS, DEFAULT_STAGED_READINESS_INTERVAL_MS, DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS, DEFAULT_STAGED_READINESS_RETRIES, PrerenderCdnWarmOptions, PrerenderWarmPlan, buildWarmupUrl, createCdnWarmTargets, getWarmPathsFromPrerenderManifest, readPrerenderWarmPaths, readPrerenderWarmPlan, waitForCdnWarmTargetReadiness, warmCdnCache, warmCdnCacheFromPrerender };
+export declare function warmCdnCache(options: CdnWarmOptions): Promise<CdnWarmResult>;
+export declare function warmCdnCacheFromPrerender(options: PrerenderCdnWarmOptions): Promise<CdnWarmResult>;
+//#endregion

package/dist/cdn-warm.js

@@ -1,12 +1,13 @@
 import { VINEXT_CDN_BUILD_ID_HEADER } from "./cache/cdn-build-id.js";
 import fs from "node:fs";
 import path from "node:path";
+import { cacheabilityRoutePathname } from "vinext/internal/server/cacheability-manifest";
 import { randomUUID } from "node:crypto";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { VINEXT_PRERENDER_READINESS_HEADER, VINEXT_PRERENDER_READINESS_PATH, VINEXT_PRERENDER_SECRET_HEADER } from "vinext/internal/server/headers";
+import { VINEXT_CACHE_HEADER, VINEXT_PRERENDER_READINESS_HEADER, VINEXT_PRERENDER_READINESS_PATH, VINEXT_PRERENDER_SECRET_HEADER } from "vinext/internal/server/headers";
 import { PRERENDER_PATHS_MANIFEST } from "vinext/internal/build/prerender-paths";
 import { getPrerenderedConcretePaths, readPrerenderManifest } from "vinext/internal/server/prerender-manifest";
-import { VINEXT_RSC_BUILD_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER, createCanonicalLoadingShellRscRequestHeaders, createCanonicalRscRequestHeaders, createCanonicalRscRequestUrl, createRscRequestUrl } from "vinext/internal/server/app-rsc-cache-busting";
+import { VINEXT_RSC_BUILD_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER as VINEXT_RSC_VARY_HEADER$1, createCanonicalLoadingShellRscRequestHeaders, createCanonicalRscRequestHeaders, createCanonicalRscRequestUrl, createRscRequestUrl } from "vinext/internal/server/app-rsc-cache-busting";
 import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
 import { normalizePathTrailingSlash } from "vinext/shims/url-utils";
 //#region src/cdn-warm.ts
@@ -18,7 +19,8 @@ const DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS = 12e4;
 const DEFAULT_STAGED_READINESS_SUCCESSES = 6;
 const STAGED_READINESS_QUERY_PARAM = "__vinext_cdn_warm_readiness";
 function applyWarmPathConfig(pathname, config) {
-	const normalized = normalizePathTrailingSlash(config.basePath ? pathname === "/" ? config.basePath : `${config.basePath}${pathname}` : pathname, config.trailingSlash === true);
+	const withBasePath = config.basePath ? pathname === "/" ? config.basePath : `${config.basePath}${pathname}` : pathname;
+	const normalized = normalizePathTrailingSlash(withBasePath, config.trailingSlash === true);
 	return new URL(normalized, "http://vinext.local").pathname;
 }
 function readBuiltBuildId(root) {
@@ -36,16 +38,14 @@ function readPrerenderPathManifest(manifestPath) {
 		const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
 		if (!parsed || typeof parsed !== "object") return null;
 		const manifest = parsed;
-		if (!Array.isArray(manifest.paths) || !manifest.paths.every((pathname) => typeof pathname === "string") || manifest.appPaths !== void 0 && (!Array.isArray(manifest.appPaths) || !manifest.appPaths.every((pathname) => typeof pathname === "string")) || manifest.pagesPaths !== void 0 && (!Array.isArray(manifest.pagesPaths) || !manifest.pagesPaths.every((pathname) => typeof pathname === "string")) || manifest.pagesDataPaths !== void 0 && (!Array.isArray(manifest.pagesDataPaths) || !manifest.pagesDataPaths.every((pathname) => typeof pathname === "string")) || manifest.excludedWarmPaths !== void 0 && (!Array.isArray(manifest.excludedWarmPaths) || !manifest.excludedWarmPaths.every((pathname) => typeof pathname === "string")) || manifest.fallbackRoutePatterns !== void 0 && (!Array.isArray(manifest.fallbackRoutePatterns) || !manifest.fallbackRoutePatterns.every((route) => route !== null && typeof route === "object" && !Array.isArray(route) && (route.kind === "app-page" || route.kind === "app-route" || route.kind === "pages-page") && typeof route.pattern === "string" && route.pattern.startsWith("/"))) || manifest.rscPaths !== void 0 && (!Array.isArray(manifest.rscPaths) || !manifest.rscPaths.every((pathname) => typeof pathname === "string")) || manifest.routeHandlerPaths !== void 0 && (!Array.isArray(manifest.routeHandlerPaths) || !manifest.routeHandlerPaths.every((pathname) => typeof pathname === "string")) || manifest.routePatterns !== void 0 && (!manifest.routePatterns || typeof manifest.routePatterns !== "object" || Array.isArray(manifest.routePatterns) || !Object.entries(manifest.routePatterns).every(([pathname, route]) => pathname.startsWith("/") && route !== null && typeof route === "object" && !Array.isArray(route) && (route.kind === "app-page" || route.kind === "app-route" || route.kind === "pages-page") && typeof route.pattern === "string" && route.pattern.startsWith("/") && (route.cacheabilityProbe === void 0 || route.cacheabilityProbe !== null && typeof route.cacheabilityProbe === "object" && !Array.isArray(route.cacheabilityProbe) && typeof route.cacheabilityProbe.canPrunePattern === "boolean" && (route.cacheabilityProbe.concretePathname === void 0 || typeof route.cacheabilityProbe.concretePathname === "string" && route.cacheabilityProbe.concretePathname.startsWith("/"))))) || manifest.loadingShellPaths !== void 0 && (!Array.isArray(manifest.loadingShellPaths) || !manifest.loadingShellPaths.every((pathname) => typeof pathname === "string")) || manifest.basePath !== void 0 && typeof manifest.basePath !== "string" || manifest.buildIdentity !== void 0 && typeof manifest.buildIdentity !== "string" || manifest.deploymentId !== void 0 && typeof manifest.deploymentId !== "string" || manifest.rscBuildId !== void 0 && typeof manifest.rscBuildId !== "string" || manifest.trailingSlash !== void 0 && typeof manifest.trailingSlash !== "boolean" || manifest.responseVary !== void 0 && manifest.responseVary !== "verbatim") return null;
+		if (!Array.isArray(manifest.paths) || !manifest.paths.every((pathname) => typeof pathname === "string") || manifest.appPaths !== void 0 && (!Array.isArray(manifest.appPaths) || !manifest.appPaths.every((pathname) => typeof pathname === "string")) || manifest.pagesPaths !== void 0 && (!Array.isArray(manifest.pagesPaths) || !manifest.pagesPaths.every((pathname) => typeof pathname === "string")) || manifest.pagesDataPaths !== void 0 && (!Array.isArray(manifest.pagesDataPaths) || !manifest.pagesDataPaths.every((pathname) => typeof pathname === "string")) || manifest.excludedWarmPaths !== void 0 && (!Array.isArray(manifest.excludedWarmPaths) || !manifest.excludedWarmPaths.every((pathname) => typeof pathname === "string")) || manifest.fallbackRoutePatterns !== void 0 && (!Array.isArray(manifest.fallbackRoutePatterns) || !manifest.fallbackRoutePatterns.every((route) => route !== null && typeof route === "object" && !Array.isArray(route) && (route.kind === "app-page" || route.kind === "app-route" || route.kind === "pages-page") && typeof route.pattern === "string" && route.pattern.startsWith("/"))) || manifest.rscPaths !== void 0 && (!Array.isArray(manifest.rscPaths) || !manifest.rscPaths.every((pathname) => typeof pathname === "string")) || manifest.routeHandlerPaths !== void 0 && (!Array.isArray(manifest.routeHandlerPaths) || !manifest.routeHandlerPaths.every((pathname) => typeof pathname === "string")) || manifest.routePatterns !== void 0 && (!manifest.routePatterns || typeof manifest.routePatterns !== "object" || Array.isArray(manifest.routePatterns) || !Object.entries(manifest.routePatterns).every(([pathname, route]) => pathname.startsWith("/") && route !== null && typeof route === "object" && !Array.isArray(route) && (route.kind === "app-page" || route.kind === "app-route" || route.kind === "pages-page") && typeof route.pattern === "string" && route.pattern.startsWith("/") && (route.cacheabilityProbe === void 0 || route.cacheabilityProbe !== null && typeof route.cacheabilityProbe === "object" && !Array.isArray(route.cacheabilityProbe) && typeof route.cacheabilityProbe.canPrunePattern === "boolean" && (route.cacheabilityProbe.concretePathname === void 0 || typeof route.cacheabilityProbe.concretePathname === "string" && route.cacheabilityProbe.concretePathname.startsWith("/")) && (route.cacheabilityProbe.routeMayResolve === void 0 || typeof route.cacheabilityProbe.routeMayResolve === "boolean") && (route.cacheabilityProbe.requestStageMayTerminate === void 0 || typeof route.cacheabilityProbe.requestStageMayTerminate === "boolean")))) || manifest.loadingShellPaths !== void 0 && (!Array.isArray(manifest.loadingShellPaths) || !manifest.loadingShellPaths.every((pathname) => typeof pathname === "string")) || manifest.basePath !== void 0 && typeof manifest.basePath !== "string" || manifest.buildIdentity !== void 0 && typeof manifest.buildIdentity !== "string" || manifest.deploymentId !== void 0 && typeof manifest.deploymentId !== "string" || manifest.rscBuildId !== void 0 && typeof manifest.rscBuildId !== "string" || manifest.trailingSlash !== void 0 && typeof manifest.trailingSlash !== "boolean" || manifest.responseVary !== void 0 && manifest.responseVary !== "verbatim") return null;
 		return manifest;
 	} catch (error) {
 		console.warn(`[vinext] Failed to read prerender path manifest at ${manifestPath}:`, error);
 		return null;
 	}
 }
-function readPrerenderPathWarmPaths(root, options) {
-	const manifest = readPrerenderPathManifest(path.join(root, "dist", "server", PRERENDER_PATHS_MANIFEST));
-	if (!manifest) return null;
+function createPrerenderPathWarmPaths(root, manifest, options) {
 	const builtBuildId = readBuiltBuildId(root);
 	if (!manifest.buildId || !builtBuildId || manifest.buildId !== builtBuildId) {
 		const message = "[vinext] CDN warmup skipped: prerender path manifest buildId does not match dist/server/BUILD_ID.";
@@ -59,10 +59,10 @@ function readPrerenderPathWarmPaths(root, options) {
 		paths: manifest.paths.filter((pathname) => pathname.startsWith("/")).filter((pathname) => !manifest.excludedWarmPaths?.includes(pathname)).map((pathname) => applyWarmPathConfig(pathname, manifest))
 	};
 }
-function readPrerenderWarmPlan(root, options) {
-	const pathPlan = readPrerenderPathWarmPaths(root, options);
+function createPrerenderWarmPlan(root, manifest, options) {
+	const pathPlan = createPrerenderPathWarmPaths(root, manifest, options);
 	if (!pathPlan) {
-		const message = "[vinext] CDN warmup skipped: prerender path manifest not found.";
+		const message = "[vinext] CDN warmup skipped: prerender path discovery is invalid.";
 		if (options?.strict) throw new Error(message);
 		return {
 			loadingShellPaths: [],
@@ -70,8 +70,7 @@ function readPrerenderWarmPlan(root, options) {
 			rscPaths: []
 		};
 	}
-	const { manifest } = pathPlan;
-	const supportsCanonicalRsc = manifest.responseVary === "verbatim" && manifest.rscPaths !== void 0 && manifest.rscBuildId !== void 0;
+	const supportsCanonicalRsc = (manifest.responseVary === "verbatim" || options?.includeCanonicalRsc === true) && manifest.rscPaths !== void 0 && manifest.rscBuildId !== void 0;
 	const applyConfig = (pathname) => applyWarmPathConfig(pathname, manifest);
 	const routePatterns = manifest.routePatterns ? Object.fromEntries(Object.entries(manifest.routePatterns).map(([pathname, route]) => [pathname.includes("/_next/data/") ? pathname : applyConfig(pathname), route])) : void 0;
 	let htmlPaths = pathPlan.paths;
@@ -101,6 +100,19 @@ function readPrerenderWarmPlan(root, options) {
 		...routePatterns ? { routePatterns } : {}
 	};
 }
+function readPrerenderWarmPlan(root, options) {
+	const manifest = readPrerenderPathManifest(path.join(root, "dist", "server", PRERENDER_PATHS_MANIFEST));
+	if (!manifest) {
+		const message = "[vinext] CDN warmup skipped: prerender path manifest not found.";
+		if (options?.strict) throw new Error(message);
+		return {
+			loadingShellPaths: [],
+			paths: [],
+			rscPaths: []
+		};
+	}
+	return createPrerenderWarmPlan(root, manifest, options);
+}
 function readPrerenderWarmPaths(root, options) {
 	return readPrerenderWarmPlan(root, options).paths;
 }
@@ -169,6 +181,89 @@ async function fetchHeadersWithTimeout(fetchImpl, url, timeoutMs, headers, metho
 		if (timer !== void 0) clearTimeout(timer);
 	}
 }
+const MAX_CDN_WARM_REPORT_ROUTES = 10;
+const MAX_CDN_WARM_REPORT_PATTERN_WIDTH = 48;
+const CDN_WARM_ROUTE_KIND_LABELS = {
+	"app-page": "App page",
+	"app-route": "Route Handler",
+	"pages-page": "Pages page"
+};
+function formatCount(count, singular, plural = `${singular}s`) {
+	return `${count.toLocaleString("en-US")} ${count === 1 ? singular : plural}`;
+}
+function formatNumber(count) {
+	return count.toLocaleString("en-US");
+}
+function truncateMiddle(value, maxLength) {
+	if (value.length <= maxLength) return value;
+	const remaining = maxLength - 1;
+	const startLength = Math.ceil(remaining / 2);
+	return `${value.slice(0, startLength)}…${value.slice(-(remaining - startLength))}`;
+}
+function printCdnWarmTable(headings, rows, rightAlignedFrom) {
+	const widths = headings.map((heading, index) => Math.max(heading.length, ...rows.map((row) => row[index]?.length ?? 0)));
+	for (const row of [headings, ...rows]) console.log(`    ${row.map((value, index) => index >= rightAlignedFrom ? value.padStart(widths[index]) : value.padEnd(widths[index])).join("  ")}`);
+}
+function createCdnWarmRouteReport(targets, outcomes) {
+	const routes = /* @__PURE__ */ new Map();
+	for (const [index, target] of targets.entries()) {
+		const key = target.route ? `${target.route.kind}\0${target.route.pattern}` : "unmatched";
+		const route = routes.get(key) ?? {
+			failed: 0,
+			kind: target.route ? CDN_WARM_ROUTE_KIND_LABELS[target.route.kind] : "Other",
+			key,
+			pattern: target.route?.pattern ?? "Other discovered requests",
+			paths: /* @__PURE__ */ new Set(),
+			skipped: 0,
+			total: 0,
+			warmed: 0
+		};
+		route.paths.add(target.route?.cacheabilityProbe?.concretePathname ?? cacheabilityRoutePathname(target.pathname, target.kind));
+		route.total++;
+		const outcome = outcomes?.[index];
+		if (outcome) route[outcome]++;
+		routes.set(key, route);
+	}
+	return [...routes.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
+}
+function printCdnWarmRouteReport(targets, outcomes) {
+	if (!targets.some((target) => target.route)) return;
+	const routes = createCdnWarmRouteReport(targets, outcomes);
+	if (routes.length === 0) return;
+	console.log(`  CDN warmup ${outcomes ? "result" : "plan"} by route:`);
+	const visible = routes.slice(0, MAX_CDN_WARM_REPORT_ROUTES);
+	const routeColumns = (route) => [truncateMiddle(route.pattern, MAX_CDN_WARM_REPORT_PATTERN_WIDTH), route.kind];
+	if (outcomes) printCdnWarmTable([
+		"Route pattern",
+		"Kind",
+		"Warmed",
+		"Skipped",
+		"Failed"
+	], visible.map((route) => [
+		...routeColumns(route),
+		`${formatNumber(route.warmed)}/${formatNumber(route.total)}`,
+		formatNumber(route.skipped),
+		formatNumber(route.failed)
+	]), 2);
+	else printCdnWarmTable([
+		"Route pattern",
+		"Kind",
+		"Paths",
+		"Entries"
+	], visible.map((route) => [
+		...routeColumns(route),
+		formatNumber(route.paths.size),
+		formatNumber(route.total)
+	]), 2);
+	const omitted = routes.slice(MAX_CDN_WARM_REPORT_ROUTES);
+	if (omitted.length > 0) {
+		const omittedEntries = omitted.reduce((total, route) => total + route.total, 0);
+		console.log(`    ... ${formatCount(omitted.length, "additional route pattern")} omitted (${formatCount(omittedEntries, "cache entry", "cache entries")})`);
+	}
+}
+function cdnWarmTargetKey(target) {
+	return `${target.kind}\0${target.sourcePathname}`;
+}
 async function createCdnWarmTargets(options) {
 	const requests = [];
 	const fullRscPaths = new Set(options.rscPaths ?? []);
@@ -257,7 +352,7 @@ var CdnOperationProgress = class {
 		this.lastLineLength = 0;
 	}
 };
-const REQUIRED_RSC_VARY_HEADERS = VINEXT_RSC_VARY_HEADER.split(",").map((name) => name.trim().toLowerCase());
+const REQUIRED_RSC_VARY_HEADERS = VINEXT_RSC_VARY_HEADER$1.split(",").map((name) => name.trim().toLowerCase());
 const ADMITTED_CF_CACHE_STATUSES = /* @__PURE__ */ new Set([
 	"HIT",
 	"MISS",
@@ -350,17 +445,35 @@ function validateCachePolicy(response, requireCacheStatus, requireCacheHit = fal
 		error: `CF-Cache-Status is ${cacheStatus}`
 	};
 }
-function validateBuildIdentity(response, expectedBuildId) {
-	if (expectedBuildId !== void 0 && response.headers.get("X-Vinext-Build-Id") !== expectedBuildId) return {
+function validateVinextCacheStatus(response) {
+	const status = response.headers.get(VINEXT_CACHE_HEADER)?.trim().toUpperCase();
+	if (status === "MISS" || status === "HIT" || status === "UPDATING") return { outcome: "warmed" };
+	if (status === "BYPASS" || status === "DYNAMIC") return {
+		outcome: "skipped",
+		reason: `${VINEXT_CACHE_HEADER} is ${status}`
+	};
+	return {
 		outcome: "failed",
-		error: `response ${VINEXT_CDN_BUILD_ID_HEADER} does not match build ${expectedBuildId} (received ${response.headers.get("X-Vinext-Build-Id") ?? "missing"})`
+		error: `response is missing ${VINEXT_CACHE_HEADER}`
 	};
+}
+function validateWarmAdmission(response, statusSource, requireCacheHit) {
+	return statusSource === "vinext" ? validateVinextCacheStatus(response) : validateCachePolicy(response, true, requireCacheHit);
+}
+function validateBuildIdentity(response, expectedBuildId) {
+	if (expectedBuildId !== void 0 && response.headers.get("X-Vinext-Build-Id") !== expectedBuildId) {
+		const actualBuildId = response.headers.get("X-Vinext-Build-Id") ?? "missing";
+		return {
+			outcome: "failed",
+			error: `response ${VINEXT_CDN_BUILD_ID_HEADER} does not match build ${expectedBuildId} (received ${actualBuildId})`
+		};
+	}
 	return null;
 }
 function isExpectedTerminalStatus(status) {
 	return status >= 300 && status < 400 || status === 404;
 }
-function validateRscWarmResponse(response, expectedBuildId, expectedRscBuildId, requireCacheHit = false) {
+function validateRscWarmResponse(response, expectedBuildId, expectedRscBuildId, requireCacheHit = false, statusSource = "cloudflare") {
 	const buildIdentityValidation = validateBuildIdentity(response, expectedBuildId);
 	if (buildIdentityValidation) return buildIdentityValidation;
 	if (expectedRscBuildId !== void 0 && response.headers.get(VINEXT_RSC_BUILD_ID_HEADER) !== expectedRscBuildId) return {
@@ -381,7 +494,7 @@ function validateRscWarmResponse(response, expectedBuildId, expectedRscBuildId,
 		outcome: "failed",
 		error: `expected ${VINEXT_RSC_CONTENT_TYPE} response`
 	};
-	const cachePolicyValidation = validateCachePolicy(response, true, requireCacheHit);
+	const cachePolicyValidation = validateWarmAdmission(response, statusSource, requireCacheHit);
 	if (cachePolicyValidation.outcome !== "warmed") return cachePolicyValidation;
 	if (terminalResponse && !response.headers.get("Content-Type")?.toLowerCase().startsWith(VINEXT_RSC_CONTENT_TYPE)) return {
 		outcome: "failed",
@@ -395,7 +508,7 @@ function validateRscWarmResponse(response, expectedBuildId, expectedRscBuildId,
 	};
 	return { outcome: "warmed" };
 }
-function validateHtmlWarmResponse(response, expectedBuildId, requireCacheHit = false) {
+function validateHtmlWarmResponse(response, expectedBuildId, requireCacheHit = false, statusSource = "cloudflare") {
 	const buildIdentityValidation = validateBuildIdentity(response, expectedBuildId);
 	if (buildIdentityValidation) return buildIdentityValidation;
 	if (response.redirected) return {
@@ -408,12 +521,12 @@ function validateHtmlWarmResponse(response, expectedBuildId, requireCacheHit = f
 			error: `HTTP ${response.status}`
 		};
 	}
-	const cachePolicyValidation = validateCachePolicy(response, true, requireCacheHit);
+	const cachePolicyValidation = validateWarmAdmission(response, statusSource, requireCacheHit);
 	if (cachePolicyValidation.outcome !== "warmed") return cachePolicyValidation;
 	return { outcome: "warmed" };
 }
-function validatePagesDataWarmResponse(response, expectedBuildId, requireCacheHit = false) {
-	const validation = validateHtmlWarmResponse(response, expectedBuildId, requireCacheHit);
+function validatePagesDataWarmResponse(response, expectedBuildId, requireCacheHit = false, statusSource = "cloudflare") {
+	const validation = validateHtmlWarmResponse(response, expectedBuildId, requireCacheHit, statusSource);
 	if (validation.outcome !== "warmed") return validation;
 	if (!response.headers.get("Content-Type")?.toLowerCase().startsWith("application/json")) return {
 		outcome: "failed",
@@ -536,6 +649,7 @@ async function warmOnePath(target, options) {
 	const url = buildWarmupUrl(options.targetUrl, target.pathname);
 	let lastError = "request failed before the first attempt";
 	let lastRetryable = true;
+	let lastSkippedReason = null;
 	const phaseDeadlineError = () => `CDN warmup exceeded its ${options.phaseTimeoutMs}ms phase deadline`;
 	const remainingPhaseMs = () => options.deadlineAt === void 0 ? options.timeoutMs : options.deadlineAt - Date.now();
 	const canRetry = (attempt) => attempt < options.retries;
@@ -555,6 +669,7 @@ async function warmOnePath(target, options) {
 			retryable: false
 		};
 		const attemptTimeoutMs = Math.min(options.timeoutMs, remainingMs);
+		const phaseLimitedAttempt = options.deadlineAt !== void 0 && remainingMs <= options.timeoutMs;
 		try {
 			const response = options.requireCacheHit ? await fetchHeadersWithTimeout(options.fetchImpl, url, attemptTimeoutMs, target.headers ?? options.headers) : (await fetchWithTimeout(options.fetchImpl, url, attemptTimeoutMs, target.headers ?? options.headers, "manual")).response;
 			if (options.deadlineAt !== void 0 && Date.now() >= options.deadlineAt) return {
@@ -566,18 +681,31 @@ async function warmOnePath(target, options) {
 			if (options.requireCacheHit) response.body?.cancel().catch(() => {});
 			if (process.env.VINEXT_CDN_WARM_DEBUG === "1") console.log(`  CDN warm debug ${target.label} attempt ${attempt + 1}: ${url.pathname}${url.search} HTTP ${response.status} cache=${response.headers.get("CF-Cache-Status") ?? "missing"} ray=${response.headers.get("CF-Ray") ?? "missing"} encoding=${response.headers.get("Content-Encoding") ?? "identity"} rscBuild=${response.headers.get(VINEXT_RSC_BUILD_ID_HEADER) ?? "missing"}`);
 			if (target.kind.startsWith("rsc-")) {
-				const validation = validateRscWarmResponse(response, options.expectedBuildId, options.expectedRscBuildId, options.requireCacheHit);
+				const validation = validateRscWarmResponse(response, options.expectedBuildId, options.expectedRscBuildId, options.requireCacheHit, options.statusSource);
 				if (validation.outcome === "warmed") return {
 					path: target.label,
 					ok: true,
 					skipped: false
 				};
-				if (validation.outcome === "skipped") return {
-					path: target.label,
-					ok: true,
-					skipped: true,
-					reason: validation.reason
-				};
+				if (validation.outcome === "skipped") {
+					if (!options.retrySkipped) return {
+						path: target.label,
+						ok: true,
+						skipped: true,
+						reason: validation.reason
+					};
+					lastSkippedReason = validation.reason;
+					lastRetryable = true;
+					if (!canRetry(attempt)) break;
+					if (!await waitBeforeRetry()) return {
+						path: target.label,
+						ok: false,
+						error: phaseDeadlineError(),
+						retryable: false
+					};
+					continue;
+				}
+				lastSkippedReason = null;
 				lastError = validation.error;
 				const cacheStatus = response.headers.get("CF-Cache-Status")?.trim().toUpperCase();
 				lastRetryable = options.requireCacheHit && ADMITTED_CF_CACHE_STATUSES.has(cacheStatus ?? "") && !REUSABLE_CF_CACHE_STATUSES.has(cacheStatus ?? "") || shouldRetryValidationFailure(response, target, options);
@@ -591,26 +719,47 @@ async function warmOnePath(target, options) {
 				};
 				continue;
 			}
-			const validation = target.kind === "pages-data" ? validatePagesDataWarmResponse(response, options.expectedBuildId, options.requireCacheHit) : validateHtmlWarmResponse(response, options.expectedBuildId, options.requireCacheHit);
+			const validation = target.kind === "pages-data" ? validatePagesDataWarmResponse(response, options.expectedBuildId, options.requireCacheHit, options.statusSource) : validateHtmlWarmResponse(response, options.expectedBuildId, options.requireCacheHit, options.statusSource);
 			if (validation.outcome === "warmed") return {
 				path: target.label,
 				ok: true,
 				skipped: false
 			};
-			if (validation.outcome === "skipped") return {
-				path: target.label,
-				ok: true,
-				skipped: true,
-				reason: validation.reason
-			};
+			if (validation.outcome === "skipped") {
+				if (!options.retrySkipped) return {
+					path: target.label,
+					ok: true,
+					skipped: true,
+					reason: validation.reason
+				};
+				lastSkippedReason = validation.reason;
+				lastRetryable = true;
+				if (!canRetry(attempt)) break;
+				if (!await waitBeforeRetry()) return {
+					path: target.label,
+					ok: false,
+					error: phaseDeadlineError(),
+					retryable: false
+				};
+				continue;
+			}
+			lastSkippedReason = null;
 			lastError = validation.error;
 			const cacheStatus = response.headers.get("CF-Cache-Status")?.trim().toUpperCase();
 			lastRetryable = options.requireCacheHit && ADMITTED_CF_CACHE_STATUSES.has(cacheStatus ?? "") && !REUSABLE_CF_CACHE_STATUSES.has(cacheStatus ?? "") || shouldRetryValidationFailure(response, target, options);
 			if (!lastRetryable) break;
 		} catch (error) {
+			lastSkippedReason = null;
 			lastRetryable = true;
-			if (error instanceof DOMException && error.name === "AbortError") lastError = options.deadlineAt !== void 0 && Date.now() >= options.deadlineAt ? phaseDeadlineError() : `timed out after ${attemptTimeoutMs}ms`;
-			else lastError = error instanceof Error ? error.message : String(error);
+			if (error instanceof DOMException && error.name === "AbortError") {
+				if (phaseLimitedAttempt) return {
+					path: target.label,
+					ok: false,
+					error: phaseDeadlineError(),
+					retryable: false
+				};
+				lastError = `timed out after ${attemptTimeoutMs}ms`;
+			} else lastError = error instanceof Error ? error.message : String(error);
 		}
 		if (!canRetry(attempt)) break;
 		if (!await waitBeforeRetry()) return {
@@ -620,11 +769,16 @@ async function warmOnePath(target, options) {
 			retryable: false
 		};
 	}
-	return {
+	return lastSkippedReason === null ? {
 		path: target.label,
 		ok: false,
 		error: lastError,
 		retryable: lastRetryable
+	} : {
+		path: target.label,
+		ok: true,
+		skipped: true,
+		reason: lastSkippedReason
 	};
 }
 async function runWithConcurrency(items, concurrency, fn) {
@@ -677,7 +831,8 @@ async function warmCdnCache(options) {
 			rscPaths: []
 		}
 	};
-	console.log(`\n  Warming CDN cache with ${requests.length} discovered request(s)...`);
+	console.log(`\n  Warming ${formatCount(requests.length, "CDN cache entry", "CDN cache entries")}...`);
+	printCdnWarmRouteReport(requests);
 	const progress = new CdnOperationProgress();
 	let completedRequests = 0;
 	progress.update(0, requests.length, "starting warmup");
@@ -697,7 +852,9 @@ async function warmCdnCache(options) {
 			retryDelayMs: isPropagationRequest ? propagationRetryDelayMs : normalRetryDelayMs,
 			retryNotFound: isPropagationRequest,
 			phaseTimeoutMs,
-			requireCacheHit: options.requireCacheHit === true
+			requireCacheHit: options.requireCacheHit === true,
+			statusSource: options.statusSource ?? "cloudflare",
+			retrySkipped: isPropagationRequest && options.retrySkippedTargetKeys?.has(cdnWarmTargetKey(target)) === true
 		});
 	};
 	const warmRequest = async (target, retryMode = "normal") => {
@@ -708,24 +865,24 @@ async function warmCdnCache(options) {
 	};
 	const warmPropagatingPass = async (targets) => {
 		const results = await runWithConcurrency(targets, concurrency, (target) => warmRequest(target, "propagation-pass"));
-		const retryableFailed = targets.map((target, index) => ({
+		const retryable = targets.map((target, index) => ({
 			index,
 			result: results[index],
 			target
-		})).filter((entry) => !entry.result.ok).filter(({ result }) => result.retryable);
-		if (retryableFailed.length === 0 || propagationRetries === 0) return results;
+		})).filter(({ result, target }) => result.ok ? result.skipped && options.retrySkippedTargetKeys?.has(cdnWarmTargetKey(target)) === true : result.retryable);
+		if (retryable.length === 0 || propagationRetries === 0) return results;
 		progress.finish();
-		console.log(`  CDN warmup: retrying ${retryableFailed.length} failed request(s) after completing the initial pass...`);
+		console.log(`  CDN warmup: retrying ${retryable.length} unresolved request(s) after completing the initial pass...`);
 		let completedRetries = 0;
-		progress.update(0, retryableFailed.length, "starting retry pass", "Retrying CDN cache");
-		const retried = await runWithConcurrency(retryableFailed.map(({ target }) => target), concurrency, async (target) => {
+		progress.update(0, retryable.length, "starting retry pass", "Retrying CDN cache");
+		const retried = await runWithConcurrency(retryable.map(({ target }) => target), concurrency, async (target) => {
 			const result = await warmTarget(target, "propagation-retry");
 			completedRetries++;
-			progress.update(completedRetries, retryableFailed.length, target.label, "Retrying CDN cache");
+			progress.update(completedRetries, retryable.length, target.label, "Retrying CDN cache");
 			return result;
 		});
 		progress.finish();
-		for (const [retryIndex, { index }] of retryableFailed.entries()) results[index] = retried[retryIndex];
+		for (const [retryIndex, { index }] of retryable.entries()) results[index] = retried[retryIndex];
 		return results;
 	};
 	let results;
@@ -752,6 +909,7 @@ async function warmCdnCache(options) {
 	const warmed = results.length - failures.length - skippedResults.length;
 	const warmedRouteHandlerPaths = warmedRequests.filter((target) => target.kind === "app-route").map((target) => target.sourcePathname);
 	const failedRouteHandlerPaths = failedRequests.filter(({ target }) => target.kind === "app-route").map(({ target }) => target.sourcePathname);
+	printCdnWarmRouteReport(requests, results.map((result) => !result.ok ? "failed" : result.skipped ? "skipped" : "warmed"));
 	console.log(`  CDN warmup: ${warmed} warmed, ${skippedResults.length} skipped, ${failures.length} failed.`);
 	for (const skipped of skippedResults.slice(0, 5)) console.log(`  CDN warmup skipped ${skipped.path}: ${skipped.reason}`);
 	if (failures.length > 0) {
@@ -804,4 +962,4 @@ async function warmCdnCacheFromPrerender(options) {
 	});
 }
 //#endregion
-export { CdnOperationProgress, DEFAULT_CDN_WARM_CONCURRENCY, DEFAULT_CDN_WARM_TIMEOUT_MS, DEFAULT_STAGED_READINESS_INTERVAL_MS, DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS, DEFAULT_STAGED_READINESS_RETRIES, buildWarmupUrl, createCdnWarmTargets, getWarmPathsFromPrerenderManifest, readPrerenderWarmPaths, readPrerenderWarmPlan, waitForCdnWarmTargetReadiness, warmCdnCache, warmCdnCacheFromPrerender };
+export { CdnOperationProgress, DEFAULT_CDN_WARM_CONCURRENCY, DEFAULT_CDN_WARM_TIMEOUT_MS, DEFAULT_STAGED_READINESS_INTERVAL_MS, DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS, DEFAULT_STAGED_READINESS_RETRIES, buildWarmupUrl, createCdnWarmTargets, createPrerenderWarmPlan, getWarmPathsFromPrerenderManifest, readPrerenderWarmPaths, readPrerenderWarmPlan, waitForCdnWarmTargetReadiness, warmCdnCache, warmCdnCacheFromPrerender };

package/dist/deploy-config.d.ts

@@ -8,7 +8,7 @@ import { VinextCacheConfig } from "vinext/internal/cache-adapters";
  * Returns true when the config both imports the package and invokes
  * `cloudflare(...)` in the plugin list.
  */
-declare function viteConfigHasCloudflarePlugin(root: string): boolean;
+export declare function viteConfigHasCloudflarePlugin(root: string): boolean;
 /**
  * Detect whether the Vite config assigns a CDN or data cache adapter — i.e. the
  * `cdn` or `data` field of the `vinext({ cache })` option is given a value.
@@ -17,18 +17,18 @@ declare function viteConfigHasCloudflarePlugin(root: string): boolean;
  * an unreadable or absent config is treated as configured so a deploy is never
  * blocked on a false negative.
  */
-declare function viteConfigHasCacheAdapter(root: string): boolean;
-type ResolvedKvDataAdapterConfig = {
+export declare function viteConfigHasCacheAdapter(root: string): boolean;
+export type ResolvedKvDataAdapterConfig = {
   binding: string;
   appPrefix?: string;
   ttlSeconds?: number;
 };
-type ResolvedCdnAdapterConfig = {
+export type ResolvedCdnAdapterConfig = {
   versionMetadataBinding: string;
 };
-declare function resolveCdnAdapterConfig(cache: VinextCacheConfig | null | undefined): ResolvedCdnAdapterConfig | null;
-declare function resolveKvDataAdapterConfig(cache: VinextCacheConfig | null | undefined): ResolvedKvDataAdapterConfig | null;
-declare function viteConfigHasImageAdapter(root: string): boolean;
+export declare function resolveCdnAdapterConfig(cache: VinextCacheConfig | null | undefined): ResolvedCdnAdapterConfig | null;
+export declare function resolveKvDataAdapterConfig(cache: VinextCacheConfig | null | undefined): ResolvedKvDataAdapterConfig | null;
+export declare function viteConfigHasImageAdapter(root: string): boolean;
 /**
  * Detect whether an existing user-authored Worker entry wires up a cache
  * backend imperatively via one of the `setCacheHandler` / `setDataCacheHandler`
@@ -43,16 +43,15 @@ declare function viteConfigHasImageAdapter(root: string): boolean;
  * missing Worker entry returns false (nothing to inspect — defer to other
  * checks).
  */
-declare function workerEntryHasCacheHandler(root: string): boolean;
+export declare function workerEntryHasCacheHandler(root: string): boolean;
 /**
  * Build the error thrown when an ISR/cached app is deployed without a cache
  * adapter configured in the Vite config. Production deployments need a
  * persistent cache backend; vinext no longer scaffolds one into the Worker
  * entry, so it must be declared via `vinext({ cache })`.
  */
-declare function formatMissingCacheAdapterError(options: {
+export declare function formatMissingCacheAdapterError(options: {
   configFile?: string;
 }): string;
-declare function formatImageOptimizationHint(): string;
-//#endregion
-export { ResolvedCdnAdapterConfig, ResolvedKvDataAdapterConfig, formatImageOptimizationHint, formatMissingCacheAdapterError, resolveCdnAdapterConfig, resolveKvDataAdapterConfig, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler };
+export declare function formatImageOptimizationHint(): string;
+//#endregion