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

package/dist/cacheability-probe.js

@@ -0,0 +1,496 @@
+import { MAX_CACHEABILITY_MANIFEST_BYTES, cacheabilityManifestByteLimitError } from "./cacheability-manifest-limits.js";
+import "./cache/cdn-build-id.js";
+import fs from "node:fs";
+import path from "node:path";
+import { Buffer } from "node:buffer";
+import { cacheabilityManifestRouteKey, cacheabilityRequestIdentity, cacheabilityRoutePathname, normalizeCacheabilityRoutePathname } from "vinext/internal/server/cacheability-manifest";
+import { randomUUID } from "node:crypto";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { VINEXT_CACHEABILITY_PROBE_HEADER, VINEXT_CACHEABILITY_PROBE_QUERY_PARAM, VINEXT_PRERENDER_SECRET_HEADER } from "vinext/internal/server/headers";
+//#region src/cacheability-probe.ts
+const DEFAULT_CACHEABILITY_PROBE_PHASE_TIMEOUT_MS = 12e4;
+const DEFAULT_CACHEABILITY_PROBE_RETRIES = 2;
+const DEFAULT_CACHEABILITY_PROBE_RETRY_DELAY_MS = 1e3;
+const DEFAULT_CACHEABILITY_PROBE_REQUEST_TIMEOUT_MS = 3e4;
+const MAX_CACHEABILITY_PROBE_ENVELOPE_BYTES = 64 * 1024;
+function sharedPathPrefix(pathnames) {
+	if (pathnames.length === 0) return null;
+	let prefix = pathnames[0];
+	for (const pathname of pathnames.slice(1)) {
+		const limit = Math.min(prefix.length, pathname.length);
+		let length = 0;
+		while (length < limit && prefix.charCodeAt(length) === pathname.charCodeAt(length)) length++;
+		prefix = prefix.slice(0, length);
+	}
+	while (prefix.length > 1 && pathnames.some((pathname) => pathname !== prefix && (prefix.endsWith("/") ? !pathname.startsWith(prefix) : !pathname.startsWith(`${prefix}/`)))) {
+		const slash = prefix.lastIndexOf("/");
+		prefix = slash <= 0 ? "/" : prefix.slice(0, slash + 1);
+	}
+	return prefix || null;
+}
+/** Remove a shared pathname prefix only when it makes the serialized route smaller. */
+function compactManifestRoutePaths(route) {
+	const pathPrefix = sharedPathPrefix([...route.runtimePaths ?? [], ...Object.values(route.staticPaths ?? {}).flatMap((paths) => paths ?? [])]);
+	if (!pathPrefix) return route;
+	const compacted = {
+		...route,
+		pathPrefix,
+		...route.runtimePaths ? { runtimePaths: route.runtimePaths.map((pathname) => pathname.slice(pathPrefix.length)) } : {},
+		...route.staticPaths ? { staticPaths: Object.fromEntries(Object.entries(route.staticPaths).map(([representation, paths]) => [representation, paths.map((pathname) => pathname.slice(pathPrefix.length))])) } : {}
+	};
+	return Buffer.byteLength(JSON.stringify(compacted)) < Buffer.byteLength(JSON.stringify(route)) ? compacted : route;
+}
+function isProbeRouteState(value) {
+	return value === "static-candidate" || value === "dynamic" || value === "probe-failed";
+}
+function readPrerenderSecret(root) {
+	const manifestPath = path.join(root, "dist", "server", "vinext-server.json");
+	const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+	const secret = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.prerenderSecret : void 0;
+	if (typeof secret !== "string" || secret.length === 0) throw new Error("Cannot probe staged Worker cacheability because dist/server/vinext-server.json does not contain a prerender secret. Rebuild the app before deploying.");
+	return secret;
+}
+async function readProbeEnvelope(response) {
+	if (!response.body) return {
+		reason: "probe returned invalid JSON",
+		state: "probe-failed",
+		version: 1
+	};
+	const reader = response.body.getReader();
+	const chunks = [];
+	let bytes = 0;
+	try {
+		while (true) {
+			const result = await reader.read();
+			if (result.done) break;
+			bytes += result.value.byteLength;
+			if (bytes > MAX_CACHEABILITY_PROBE_ENVELOPE_BYTES) {
+				await reader.cancel().catch(() => {});
+				return {
+					reason: `probe response exceeded ${MAX_CACHEABILITY_PROBE_ENVELOPE_BYTES} bytes`,
+					state: "probe-failed",
+					version: 1
+				};
+			}
+			chunks.push(result.value);
+		}
+	} catch (error) {
+		return {
+			reason: error instanceof Error ? error.message : String(error),
+			state: "probe-failed",
+			version: 1
+		};
+	} finally {
+		reader.releaseLock();
+	}
+	try {
+		return JSON.parse(Buffer.concat(chunks, bytes).toString("utf8"));
+	} catch {
+		return {
+			reason: "probe returned invalid JSON",
+			state: "probe-failed",
+			version: 1
+		};
+	}
+}
+async function probeTarget(options) {
+	const headers = new Headers(options.headers);
+	for (const [name, value] of new Headers(options.target.headers)) headers.set(name, value);
+	headers.set("Cache-Control", "no-cache");
+	headers.set(VINEXT_CACHEABILITY_PROBE_HEADER, "1");
+	headers.set(VINEXT_PRERENDER_SECRET_HEADER, options.secret);
+	let reason = "probe failed";
+	const probeId = randomUUID();
+	const phaseTimeoutPayload = () => ({
+		phaseTimedOut: true,
+		reason: `cacheability probing made no progress for ${options.phaseTimeoutMs}ms`,
+		state: "probe-failed",
+		version: 1
+	});
+	for (let attempt = 0; attempt <= options.retries; attempt++) {
+		if (options.getDeadlineAt() - Date.now() <= 0) return phaseTimeoutPayload();
+		const controller = new AbortController();
+		const requestDeadlineAt = Date.now() + options.timeoutMs;
+		let timeout;
+		let timedOutBy = null;
+		let retryable = true;
+		try {
+			const url = new URL(options.target.pathname, options.targetUrl);
+			url.searchParams.set(VINEXT_CACHEABILITY_PROBE_QUERY_PARAM, `${probeId}-${attempt}`);
+			const request = (async () => {
+				const response = await options.fetchImpl(url, {
+					headers,
+					redirect: "manual",
+					signal: controller.signal
+				});
+				if (options.expectedBuildId !== void 0 && response.headers.get("X-Vinext-Build-Id") !== options.expectedBuildId) {
+					response.body?.cancel().catch(() => {});
+					return {
+						kind: "retry",
+						reason: "probe reached an unexpected Worker build",
+						retryable: true
+					};
+				}
+				if (!response.ok) {
+					response.body?.cancel().catch(() => {});
+					return {
+						kind: "retry",
+						reason: `probe returned HTTP ${response.status}`,
+						retryable: response.status === 404 || response.status === 503
+					};
+				}
+				return {
+					kind: "complete",
+					payload: await readProbeEnvelope(response)
+				};
+			})();
+			const timedOut = new Promise((_resolve, reject) => {
+				const checkDeadline = () => {
+					const phaseDeadlineAt = options.getDeadlineAt();
+					const remainingMs = Math.min(requestDeadlineAt, phaseDeadlineAt) - Date.now();
+					if (remainingMs > 0) {
+						timeout = setTimeout(checkDeadline, remainingMs);
+						return;
+					}
+					timedOutBy = requestDeadlineAt <= phaseDeadlineAt ? "request" : "phase";
+					controller.abort();
+					reject(new DOMException("Probe deadline exceeded", "AbortError"));
+				};
+				checkDeadline();
+			});
+			const result = await Promise.race([request, timedOut]);
+			if (Date.now() >= options.getDeadlineAt()) return phaseTimeoutPayload();
+			if (result.kind === "complete") return result.payload;
+			reason = result.reason;
+			retryable = result.retryable;
+		} catch (error) {
+			if (timedOutBy === "phase" || Date.now() >= options.getDeadlineAt()) return phaseTimeoutPayload();
+			reason = error instanceof Error && error.name === "AbortError" ? `probe timed out after ${options.timeoutMs}ms` : error instanceof Error ? error.message : String(error);
+		} finally {
+			if (timeout !== void 0) clearTimeout(timeout);
+		}
+		if (!retryable || attempt === options.retries) break;
+		if (options.retryDelayMs > 0) {
+			const delayMs = Math.min(options.retryDelayMs, Math.max(0, options.getDeadlineAt() - Date.now()));
+			if (delayMs <= 0) return phaseTimeoutPayload();
+			await setTimeout$1(delayMs);
+		}
+	}
+	return {
+		reason,
+		state: "probe-failed",
+		version: 1
+	};
+}
+async function probeStagedWorkerCacheability(options) {
+	const secret = readPrerenderSecret(options.root);
+	const concurrency = Math.max(1, options.concurrency ?? 25);
+	const retries = Math.max(0, options.retries ?? 2);
+	const retryDelayMs = Math.max(0, options.retryDelayMs ?? 1e3);
+	const timeoutMs = Math.max(1, options.timeoutMs ?? DEFAULT_CACHEABILITY_PROBE_REQUEST_TIMEOUT_MS);
+	const phaseTimeoutMs = Math.max(1, options.phaseTimeoutMs ?? 12e4);
+	let lastProgressAt = Date.now();
+	const getDeadlineAt = () => lastProgressAt + phaseTimeoutMs;
+	const routes = {};
+	const cacheableTargets = [];
+	const speculativeTargets = [];
+	const failures = [];
+	const maxManifestBytes = Math.min(options.manifestLimits?.maxBytes ?? 2097152, MAX_CACHEABILITY_MANIFEST_BYTES);
+	const emptyManifest = {
+		buildId: options.buildId,
+		routes: {},
+		version: 1
+	};
+	let manifestBytes = Buffer.byteLength(JSON.stringify(emptyManifest));
+	const routeEntryBytes = /* @__PURE__ */ new Map();
+	let limitFailure = null;
+	let phaseTimedOut = false;
+	let probed = 0;
+	let completedPathCount = 0;
+	let skippedPathCount = 0;
+	let staticPathCount = 0;
+	let dynamicPathCount = 0;
+	const targetPreference = (target) => {
+		if (target.route?.kind === "app-route") return target.kind === "app-route" ? 0 : 1;
+		return target.kind === "html" ? 0 : target.kind === "rsc-full" ? 1 : 2;
+	};
+	const patterns = /* @__PURE__ */ new Map();
+	const targetsByConcretePath = /* @__PURE__ */ new Map();
+	let missingRouteMetadata = 0;
+	for (const target of options.targets) {
+		if (!target.route) {
+			missingRouteMetadata++;
+			continue;
+		}
+		const key = cacheabilityManifestRouteKey(target.route.kind, target.route.pattern);
+		const pattern = patterns.get(key) ?? {
+			canPrune: true,
+			groups: [],
+			key,
+			pathnames: /* @__PURE__ */ new Set(),
+			pruned: false,
+			results: /* @__PURE__ */ new Map(),
+			route: target.route
+		};
+		pattern.canPrune &&= target.route.cacheabilityProbe?.canPrunePattern === true;
+		patterns.set(key, pattern);
+		const routePathname = target.route.cacheabilityProbe?.concretePathname ?? cacheabilityRoutePathname(target.pathname, target.kind);
+		pattern.pathnames.add(routePathname);
+		const concreteKey = `${key}\0${routePathname}`;
+		const groupTargets = targetsByConcretePath.get(concreteKey) ?? [];
+		groupTargets.push(target);
+		targetsByConcretePath.set(concreteKey, groupTargets);
+	}
+	if (missingRouteMetadata > 0) failures.push(`${missingRouteMetadata} warm target${missingRouteMetadata === 1 ? " is" : "s are"} missing route-pattern metadata`);
+	const groups = Array.from(targetsByConcretePath, ([concreteKey, groupTargets]) => {
+		const route = groupTargets[0].route;
+		const key = cacheabilityManifestRouteKey(route.kind, route.pattern);
+		const pattern = patterns.get(key);
+		const routePathname = concreteKey.slice(key.length + 1);
+		groupTargets.sort((first, second) => {
+			return targetPreference(first) - targetPreference(second) || first.sourcePathname.localeCompare(second.sourcePathname);
+		});
+		const group = {
+			pattern,
+			primary: groupTargets[0],
+			routePathname,
+			targets: groupTargets
+		};
+		pattern.groups.push(group);
+		return group;
+	});
+	const reportProgress = () => {
+		options.onProgress?.({
+			completed: completedPathCount + (missingRouteMetadata > 0 ? 1 : 0),
+			dynamic: dynamicPathCount,
+			failed: failures.length,
+			probed,
+			skipped: skippedPathCount,
+			static: staticPathCount,
+			total: groups.length + (missingRouteMetadata > 0 ? 1 : 0)
+		});
+	};
+	const addRouteWithinManifestLimits = (key, route) => {
+		const previousBytes = routeEntryBytes.get(key);
+		const nextEntryBytes = Buffer.byteLength(`${JSON.stringify(key)}:${JSON.stringify(route)}`);
+		const nextManifestBytes = previousBytes === void 0 ? manifestBytes + nextEntryBytes + (routeEntryBytes.size > 0 ? 1 : 0) : manifestBytes - previousBytes + nextEntryBytes;
+		if (nextManifestBytes > maxManifestBytes) {
+			limitFailure = cacheabilityManifestByteLimitError(nextManifestBytes, maxManifestBytes);
+			return false;
+		}
+		routes[key] = route;
+		routeEntryBytes.set(key, nextEntryBytes);
+		manifestBytes = nextManifestBytes;
+		return true;
+	};
+	const classifyConcretePath = async (group) => {
+		if (group.pattern.pruned) {
+			skippedPathCount += 1;
+			completedPathCount += 1;
+			reportProgress();
+			return;
+		}
+		const target = group.primary;
+		const identity = cacheabilityRequestIdentity(new Request(new URL(target.pathname, options.targetUrl), { headers: target.headers }));
+		if (!identity || identity.representation !== target.kind) {
+			failures.push(`${target.label}: warm request does not have a cacheable request identity`);
+			completedPathCount += 1;
+			reportProgress();
+			return;
+		}
+		const result = await probeTarget({
+			expectedBuildId: options.expectedResponseBuildId,
+			fetchImpl: options.fetchImpl ?? fetch,
+			getDeadlineAt,
+			headers: options.headers,
+			retries,
+			retryDelayMs,
+			phaseTimeoutMs,
+			secret,
+			target,
+			targetUrl: options.targetUrl,
+			timeoutMs
+		});
+		probed += 1;
+		lastProgressAt = Date.now();
+		if (limitFailure) return;
+		if (result.phaseTimedOut) {
+			phaseTimedOut = true;
+			return;
+		}
+		if (result.version !== 1 || result.kind !== "app-page" && result.kind !== "app-route" && result.kind !== "pages-page" || typeof result.pattern !== "string" || !result.pattern.startsWith("/") || !isProbeRouteState(result.state) || result.scope !== void 0 && result.scope !== "identity" && result.scope !== "pattern" || result.scope === "pattern" && result.state !== "dynamic" || result.rendererStatic !== void 0 && typeof result.rendererStatic !== "boolean" || !Number.isInteger(result.status) || result.status < 100 || result.status > 599) {
+			failures.push(`${target.label}: ${result.reason ?? "probe returned an invalid envelope"}`);
+			completedPathCount += 1;
+			reportProgress();
+			return;
+		}
+		if (result.state === "probe-failed") {
+			failures.push(`${target.label}: ${result.reason ?? "probe failed"}`);
+			completedPathCount += 1;
+			reportProgress();
+			return;
+		}
+		if (!target.route || result.kind !== target.route.kind || result.pattern !== target.route.pattern) {
+			failures.push(`${target.label}: probe resolved to unexpected route ${result.pattern ?? ""}`);
+			completedPathCount += 1;
+			reportProgress();
+			return;
+		}
+		if (result.state === "dynamic" && result.scope === "pattern" && group.pattern.canPrune) {
+			group.pattern.pruned = true;
+			dynamicPathCount += 1;
+			completedPathCount += 1;
+			reportProgress();
+			return;
+		}
+		group.pattern.results.set(group.routePathname, {
+			rendererStatic: result.rendererStatic === true,
+			representation: target.kind,
+			state: result.state
+		});
+		if (result.state === "static-candidate") staticPathCount += 1;
+		else dynamicPathCount += 1;
+		completedPathCount += 1;
+		reportProgress();
+	};
+	const runGroups = async (scheduledGroups) => {
+		let nextIndex = 0;
+		const worker = async () => {
+			while (!limitFailure && !phaseTimedOut && nextIndex < scheduledGroups.length) await classifyConcretePath(scheduledGroups[nextIndex++]);
+		};
+		await Promise.all(Array.from({ length: Math.min(concurrency, scheduledGroups.length) }, () => worker()));
+	};
+	reportProgress();
+	const representativeGroups = [];
+	const siblingGroups = [];
+	const scheduledPatterns = /* @__PURE__ */ new Set();
+	for (const group of groups) if (scheduledPatterns.has(group.pattern.key)) siblingGroups.push(group);
+	else {
+		scheduledPatterns.add(group.pattern.key);
+		representativeGroups.push(group);
+	}
+	await runGroups(representativeGroups);
+	if (!limitFailure && !phaseTimedOut) await runGroups(siblingGroups);
+	if (limitFailure) throw limitFailure;
+	if (phaseTimedOut || Date.now() >= getDeadlineAt()) throw new Error(`cacheability probing made no progress for ${phaseTimeoutMs}ms`);
+	let classified = 0;
+	let dynamic = 0;
+	let skipped = 0;
+	const fallbackRoutes = /* @__PURE__ */ new Map();
+	for (const fallbackRoute of options.fallbackRoutePatterns ?? []) {
+		const key = cacheabilityManifestRouteKey(fallbackRoute.kind, fallbackRoute.pattern);
+		fallbackRoutes.set(key, fallbackRoute);
+	}
+	for (const [key, fallbackRoute] of fallbackRoutes) {
+		if (patterns.has(key)) continue;
+		if (!addRouteWithinManifestLimits(key, {
+			kind: fallbackRoute.kind,
+			pattern: fallbackRoute.pattern,
+			state: "static-candidate"
+		})) break;
+		classified += 1;
+	}
+	if (limitFailure) throw limitFailure;
+	for (const pattern of patterns.values()) {
+		if (pattern.pruned) {
+			classified += 1;
+			dynamic += 1;
+			skipped += 1;
+			const loadingShellTargets = pattern.groups.flatMap((group) => group.targets.filter((target) => target.kind === "rsc-loading-shell"));
+			if (loadingShellTargets.length > 0) {
+				cacheableTargets.push(...loadingShellTargets);
+				speculativeTargets.push(...loadingShellTargets);
+				const route = {
+					kind: pattern.route.kind,
+					pattern: pattern.route.pattern,
+					runtimeRepresentation: "rsc-loading-shell",
+					state: "runtime-check"
+				};
+				if (!addRouteWithinManifestLimits(pattern.key, route)) break;
+			}
+			continue;
+		}
+		if (pattern.results.size === 0) continue;
+		classified += 1;
+		if (Array.from(pattern.results.values()).some((result) => result.state === "dynamic")) dynamic += 1;
+		const staticPaths = {};
+		const runtimePathSet = /* @__PURE__ */ new Set();
+		for (const group of pattern.groups) {
+			const result = pattern.results.get(group.routePathname);
+			if (result?.state === "static-candidate") {
+				if (result.rendererStatic) {
+					const paths = staticPaths[result.representation] ?? [];
+					paths.push(group.routePathname);
+					staticPaths[result.representation] = paths;
+				} else runtimePathSet.add(group.routePathname);
+				cacheableTargets.push(...group.targets);
+				speculativeTargets.push(...group.targets.filter((target) => target !== group.primary));
+				continue;
+			}
+			runtimePathSet.add(group.routePathname);
+			if (!pattern.pruned) {
+				const pairedTargets = group.targets.filter((target) => target !== group.primary);
+				cacheableTargets.push(...pairedTargets);
+				speculativeTargets.push(...pairedTargets);
+			}
+		}
+		for (const paths of Object.values(staticPaths)) paths?.sort();
+		const allObservedPathsStaticallyGenerated = pattern.results.size === pattern.pathnames.size && runtimePathSet.size === 0 && Array.from(pattern.results.values()).every((result) => result.rendererStatic);
+		const hasStaticFallback = fallbackRoutes.has(pattern.key);
+		const soleGroup = pattern.groups.length === 1 ? pattern.groups[0] : null;
+		const literalPatternNamesSolePath = soleGroup !== null && !/(^|\/):/.test(pattern.route.pattern) && normalizeCacheabilityRoutePathname(pattern.route.pattern) === soleGroup.routePathname;
+		let route;
+		if (literalPatternNamesSolePath) {
+			const result = pattern.results.get(soleGroup.routePathname);
+			route = result?.state === "static-candidate" ? pattern.route.kind === "app-route" ? {
+				kind: pattern.route.kind,
+				pattern: pattern.route.pattern,
+				state: "static-candidate"
+			} : result.rendererStatic ? {
+				kind: pattern.route.kind,
+				pattern: pattern.route.pattern,
+				state: "runtime-check",
+				staticRepresentation: result.representation
+			} : {
+				kind: pattern.route.kind,
+				pattern: pattern.route.pattern,
+				state: "runtime-check"
+			} : {
+				kind: pattern.route.kind,
+				pattern: pattern.route.pattern,
+				state: "runtime-check"
+			};
+		} else route = compactManifestRoutePaths({
+			kind: pattern.route.kind,
+			pattern: pattern.route.pattern,
+			state: "runtime-check",
+			...hasStaticFallback || allObservedPathsStaticallyGenerated ? {
+				allowUnknown: true,
+				unknownState: "static-candidate"
+			} : {},
+			...runtimePathSet.size > 0 ? { runtimePaths: Array.from(runtimePathSet).sort() } : {},
+			...Object.keys(staticPaths).length > 0 ? { staticPaths } : {}
+		});
+		if (!addRouteWithinManifestLimits(pattern.key, route)) break;
+	}
+	if (limitFailure) throw limitFailure;
+	const sortedRoutes = Object.fromEntries(Object.entries(routes).sort(([first], [second]) => first.localeCompare(second)));
+	cacheableTargets.sort((first, second) => `${first.kind}\0${first.sourcePathname}`.localeCompare(`${second.kind}\0${second.sourcePathname}`));
+	speculativeTargets.sort((first, second) => `${first.kind}\0${first.sourcePathname}`.localeCompare(`${second.kind}\0${second.sourcePathname}`));
+	return {
+		cacheableTargets,
+		classified,
+		dynamic,
+		failures,
+		manifest: {
+			buildId: options.buildId,
+			routes: sortedRoutes,
+			version: 1
+		},
+		probed,
+		skipped,
+		speculativeTargets
+	};
+}
+//#endregion
+export { DEFAULT_CACHEABILITY_PROBE_PHASE_TIMEOUT_MS, DEFAULT_CACHEABILITY_PROBE_RETRIES, DEFAULT_CACHEABILITY_PROBE_RETRY_DELAY_MS, probeStagedWorkerCacheability, readPrerenderSecret };

package/dist/cdn-warm.d.ts

@@ -1,36 +1,129 @@
+import { PrerenderRoutePattern } from "vinext/internal/build/prerender-paths";
 import { PrerenderManifest, PrerenderedPathSelectionOptions } from "vinext/internal/server/prerender-manifest";
 //#region src/cdn-warm.d.ts
 type CdnWarmOptions = {
   targetUrl: string;
   paths: readonly string[];
+  /** Pages Router JSON data identities used by client navigation. */
+  pagesDataPaths?: readonly string[];
+  /** Statically eligible App Route Handler request identities. */
+  routeHandlerPaths?: readonly string[];
+  routePatterns?: Readonly<Record<string, PrerenderRoutePattern>>;
+  /** App Router ISR paths whose definitive client-navigation payload is warmed. */
+  rscPaths?: readonly string[];
+  /** App Router paths whose deterministic loading-boundary payload is warmed. */
+  loadingShellPaths?: readonly string[];
+  /** Build identity that the warmed RSC response must have been rendered by. */
+  expectedRscBuildId?: string;
+  /** Application build identity stamped by the configured CDN adapter. */
+  expectedBuildId?: string;
+  deploymentId?: string;
   headers?: HeadersInit;
   concurrency?: number;
   timeoutMs?: number;
   retries?: number;
+  retryDelayMs?: number;
+  /** Bound the whole warm phase, including queued targets and retries. */
+  phaseTimeoutMs?: number;
+  /** Retry a newly staged version or preview alias until its routing has propagated. */
+  propagatingTarget?: boolean;
+  /** Require the response to come from a reusable cache entry, not merely an eligible MISS. */
+  requireCacheHit?: boolean;
   strict?: boolean;
   fetchImpl?: typeof fetch;
 };
-declare const DEFAULT_CDN_WARM_TIMEOUT_MS = 5000;
+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"> & {
   root: string;
   includeFallbackShells?: boolean;
+  /** Use the manifest build identity unless the configured adapter cannot expose it. */
+  validateBuildIdentity?: boolean;
 };
 type CdnWarmResult = {
   total: number;
   warmed: number;
+  skipped: number;
   failed: number;
   failures: Array<{
     path: string;
     error: string;
   }>;
+  skippedTargets: CdnWarmTarget[];
+  warmedPlan: CdnWarmRequestPlan;
+  retryPlan: CdnWarmRequestPlan;
 };
+type CdnWarmRequestPlan = {
+  loadingShellPaths: string[];
+  pagesDataPaths: string[];
+  paths: string[];
+  rscPaths: string[];
+  routeHandlerPaths?: string[];
+  routePatterns?: Record<string, PrerenderRoutePattern>;
+};
+type CdnWarmReadinessResult = {
+  ready: true;
+} | {
+  error: string;
+  ready: false;
+};
+type PrerenderWarmPlan = {
+  appPaths?: string[];
+  buildId?: string;
+  buildIdentity?: string;
+  deploymentId?: string;
+  fallbackRoutePatterns?: PrerenderRoutePattern[];
+  loadingShellPaths: string[];
+  pagesDataPaths?: string[];
+  pagesPaths?: string[];
+  paths: string[];
+  routeHandlerPaths?: string[];
+  routePatterns?: Record<string, PrerenderRoutePattern>;
+  rscBuildId?: string;
+  rscPaths: string[];
+};
+declare function readPrerenderWarmPlan(root: string, options?: {
+  includeFallbackShells?: boolean;
+  strict?: boolean;
+}): PrerenderWarmPlan;
 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 = {
+  headers?: HeadersInit;
+  kind: "app-route" | "html" | "pages-data" | "rsc-full" | "rsc-loading-shell";
+  label: string;
+  pathname: string;
+  sourcePathname: string;
+  route?: PrerenderRoutePattern;
+};
+declare function createCdnWarmTargets(options: Pick<CdnWarmOptions, "deploymentId" | "headers" | "loadingShellPaths" | "pagesDataPaths" | "paths" | "routeHandlerPaths" | "routePatterns" | "rscPaths">): Promise<CdnWarmTarget[]>;
+declare class CdnOperationProgress {
+  private readonly isTTY;
+  private lastLineLength;
+  update(completed: number, total: number, label: string, phase?: string): void;
+  finish(): void;
+}
+/**
+ * Wait until version-override requests consistently reach the uploaded build
+ * 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"> & {
+  plan: CdnWarmRequestPlan;
+  maxAttempts?: number;
+  phaseTimeoutMs?: number;
+  prerenderSecret?: string;
+  probeIntervalMs?: number;
+  requiredConsecutiveSuccesses?: number;
+}): Promise<CdnWarmReadinessResult>;
 declare function warmCdnCache(options: CdnWarmOptions): Promise<CdnWarmResult>;
 declare function warmCdnCacheFromPrerender(options: PrerenderCdnWarmOptions): Promise<CdnWarmResult>;
 //#endregion
-export { CdnWarmOptions, CdnWarmResult, DEFAULT_CDN_WARM_TIMEOUT_MS, PrerenderCdnWarmOptions, buildWarmupUrl, getWarmPathsFromPrerenderManifest, readPrerenderWarmPaths, warmCdnCache, warmCdnCacheFromPrerender };
+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 };