@vinext/cloudflare 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/cache/cdn-adapter.runtime.js

@@ -1,5 +1,80 @@
+import { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity } from "./cdn-build-id.js";
+import { VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "../version-headers.js";
+import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
+import { fnv1a64 } from "vinext/internal/utils/hash";
 import { getRequestExecutionContext } from "vinext/shims/request-context";
 //#region src/cache/cdn-adapter.runtime.ts
+/**
+* Cloudflare CDN cache adapter — edge-managed page-level ISR backed by the
+* Cloudflare Workers Cache (`ctx.cache`).
+*
+* Unlike the origin-managed default adapter (which stores rendered artifacts in
+* the data cache and serves HIT/STALE itself), this adapter delegates serving
+* to Cloudflare's edge:
+*
+* - The origin never serves from a store — `get` returns `null`, so any
+*   request that reaches the Worker renders fresh. The edge absorbs HIT/STALE
+*   traffic and revalidates in the background (the `UPDATING` cache status).
+* - `set` is a no-op: the platform caches the *response* based on its
+*   cache headers, so there is nothing to persist at the origin.
+* - `buildResponseHeaders` emits the SWR policy as `Cloudflare-CDN-Cache-Control`
+*   (`public, max-age=…, stale-while-revalidate=…`) so the edge caches and
+*   revalidates. The inner response's `Cache-Control` is
+*   `public, max-age=0, must-revalidate` so a browser never serves a stored copy
+*   without revalidating against the edge; the uncached gateway changes that to
+*   `private, max-age=0, must-revalidate` before public egress so personalized
+*   request-stage headers cannot enter another shared cache. A `Cache-Tag`
+*   header lets entries be purged by tag. Note the edge directive uses `max-age`
+*   (not `s-maxage`):
+*   the framework computes the policy with `s-maxage` for shared caches, but
+*   `Cloudflare-CDN-Cache-Control` is already CDN-scoped so `max-age` is the correct knob
+*   for the edge to honor max-age + stale-while-revalidate.
+* - `revalidateTag` purges the edge via the request context's `cache.purge({ tags })`.
+*
+* Tags use fixed-size lowercase digests before emission and purge because
+* Workers Cache tags are case-insensitive printable ASCII, while Next.js tags
+* are case-sensitive arbitrary strings.
+*
+* The default export is the adapter factory the generated
+* `virtual:vinext-cache-adapters` registration imports; configure it from
+* vite.config via the {@link cdnAdapter} builder in `./cdn-adapter.ts` (which
+* `require.resolve`s this file).
+*/
+const DEFAULT_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+const WORKER_VERSION_OVERRIDE_HEADER = "Cloudflare-Workers-Version-Overrides";
+function versionValidationFailure(message, status = 500) {
+	return Response.json({ error: message }, {
+		status,
+		headers: { "Cache-Control": "no-store" }
+	});
+}
+const CACHEABLE_EDGE_DIRECTIVE_RE = /(?:^|,)\s*(?:s-maxage|max-age)\s*=/i;
+const EDGE_POLICY_HEADERS = ["CDN-Cache-Control", "Cloudflare-CDN-Cache-Control"];
+function getBuildIdentityResponseHeader() {
+	const buildId = getVinextCdnBuildIdentity();
+	return buildId ? { [VINEXT_CDN_BUILD_ID_HEADER]: buildId } : {};
+}
+/** Remove every response header whose cache semantics are owned by Cloudflare. */
+function clearCloudflareCdnResponseHeaders(cacheControl) {
+	return {
+		...getBuildIdentityResponseHeader(),
+		"Cache-Control": cacheControl,
+		"CDN-Cache-Control": null,
+		"Cloudflare-CDN-Cache-Control": null,
+		"Cache-Tag": null
+	};
+}
+/** Interpret Cloudflare's edge policy before core applies a replacement policy. */
+function hasExplicitCloudflareNonCacheableResponsePolicy(headers) {
+	const edgePolicies = EDGE_POLICY_HEADERS.map((name) => headers.get(name));
+	if (edgePolicies.some((value) => value && isNonCacheableCacheControl(value))) return true;
+	const hasCacheableEdgePolicy = edgePolicies.some((value) => value && CACHEABLE_EDGE_DIRECTIVE_RE.test(value));
+	const browserPolicy = headers.get("Cache-Control");
+	return Boolean(!hasCacheableEdgePolicy && browserPolicy && isNonCacheableCacheControl(browserPolicy));
+}
+function readCloudflareResponseCacheControl(headers) {
+	return headers.get("Cloudflare-CDN-Cache-Control") ?? headers.get("CDN-Cache-Control") ?? headers.get("Cache-Control");
+}
 function getWorkersCache() {
 	const cache = getRequestExecutionContext()?.cache;
 	if (cache && typeof cache.purge === "function") return cache;
@@ -28,7 +103,7 @@ const UNBOUNDED_SWR_SECONDS = 31536e3;
 /**
 * Convert the framework's shared-cache policy into a CDN-scoped one:
 * `s-maxage=…` → `max-age=…` (the edge honors `max-age` inside
-* `CDN-Cache-Control`), give a value-less `stale-while-revalidate` an explicit
+* `Cloudflare-CDN-Cache-Control`), give a value-less `stale-while-revalidate` an explicit
 * seconds value (Cloudflare ignores the bare directive), and ensure a leading
 * `public`.
 */
@@ -37,30 +112,61 @@ function toEdgeCacheControl(cacheControl) {
 	return /\bpublic\b/.test(withMaxAge) ? withMaxAge : `public, ${withMaxAge}`;
 }
 /**
-* Cloudflare's `Cache-Tag` header budget is 16 KB total with each tag capped at
-* 1024 bytes. Keep a conservative ceiling so a page with a large tag set never
-* produces an oversized (silently-dropped) header.
+* Cloudflare's `Cache-Tag` header budget is 16 KB total. Fixed-size digests let
+* the full Next.js tag set fit without dropping valid long or Unicode tags.
 */
-const MAX_CACHE_TAG_BYTES = 8 * 1024;
-const MAX_SINGLE_TAG_BYTES = 1024;
+const MAX_CACHE_TAG_BYTES = 16384;
+const CACHE_TAG_PREFIX = "vinext-";
+/** Encode a case-sensitive Next.js tag into a fixed Workers Cache tag. */
+function encodeCloudflareCacheTag(tag) {
+	return `${CACHE_TAG_PREFIX}${fnv1a64(`0:${tag}`)}${fnv1a64(`1:${tag}`)}`;
+}
 /**
-* Build a `Cache-Tag` header value from canonicalised tags. Tags containing a
-* comma (the header separator) or exceeding the per-tag size are skipped, and
-* the whole value is bounded to stay within Cloudflare's limit.
+* Build a complete `Cache-Tag` header value from canonicalised tags. Returning
+* null makes the response uncacheable rather than caching with incomplete
+* invalidation metadata.
 */
 function formatCacheTag(tags) {
-	const parts = [];
-	let total = 0;
-	for (const tag of tags) {
-		if (!tag || tag.includes(",") || tag.length > MAX_SINGLE_TAG_BYTES) continue;
-		const next = total + tag.length + (parts.length > 0 ? 1 : 0);
-		if (next > MAX_CACHE_TAG_BYTES) break;
-		parts.push(tag);
-		total = next;
-	}
-	return parts.length > 0 ? parts.join(",") : null;
+	const value = tags.map(encodeCloudflareCacheTag).join(",");
+	return value && value.length <= MAX_CACHE_TAG_BYTES ? value : null;
 }
 var CloudflareCdnCacheAdapter = class {
+	versionMetadata;
+	versionMetadataBinding;
+	requiresCompletedResponseAdmission = true;
+	responseVary = "verbatim";
+	responsePolicy = {
+		isHeader(name) {
+			const normalized = name.toLowerCase();
+			return EDGE_POLICY_HEADERS.some((header) => header.toLowerCase() === normalized);
+		},
+		readCacheControl(headers) {
+			return readCloudflareResponseCacheControl(headers);
+		},
+		hasExplicitNonCacheablePolicy(headers, baseline) {
+			if (baseline) {
+				for (const name of EDGE_POLICY_HEADERS) {
+					const value = headers.get(name);
+					if (value !== baseline.get(name) && value !== null && isNonCacheableCacheControl(value)) return true;
+				}
+				const browserPolicy = headers.get("Cache-Control");
+				return Boolean(browserPolicy !== baseline.get("Cache-Control") && browserPolicy && isNonCacheableCacheControl(browserPolicy));
+			}
+			return hasExplicitCloudflareNonCacheableResponsePolicy(headers);
+		}
+	};
+	constructor(versionMetadata, versionMetadataBinding = DEFAULT_VERSION_METADATA_BINDING) {
+		this.versionMetadata = versionMetadata;
+		this.versionMetadataBinding = versionMetadataBinding;
+	}
+	validateRequest(request) {
+		const expectedVersionId = request.headers.get(VINEXT_EXPECTED_WORKER_VERSION_HEADER);
+		if (expectedVersionId === null) return null;
+		if (!request.headers.has(WORKER_VERSION_OVERRIDE_HEADER)) return versionValidationFailure(`received ${VINEXT_EXPECTED_WORKER_VERSION_HEADER} without ${WORKER_VERSION_OVERRIDE_HEADER}.`);
+		if (!this.versionMetadata) return versionValidationFailure(`Cloudflare CDN prewarming requires the \`${this.versionMetadataBinding}\` version metadata binding. Add "version_metadata": { "binding": "${this.versionMetadataBinding}" } to the active Wrangler environment. Named environments do not inherit this binding from the top level.`);
+		if (expectedVersionId !== this.versionMetadata.id) return versionValidationFailure(`Cloudflare invoked Worker version ${this.versionMetadata.id}, but vinext warmup expected ${expectedVersionId}.`, 503);
+		return null;
+	}
 	ownsBackgroundRevalidation = false;
 	/**
 	* The origin keeps no page store — return null so the request renders fresh.
@@ -71,33 +177,40 @@ var CloudflareCdnCacheAdapter = class {
 	}
 	/** No-op: the platform caches the response via its headers, not an origin store. */
 	async set(_key, _data, _ctx) {}
+	buildResponseIdentityHeaders() {
+		return getBuildIdentityResponseHeader();
+	}
 	buildResponseHeaders(input) {
-		if (!input.cacheControl) return { "Cache-Control": NO_STORE };
-		if (/\b(?:no-store|no-cache|private)\b/.test(input.cacheControl)) return {
-			"Cache-Control": input.cacheControl,
-			"CDN-Cache-Control": null,
-			"Cloudflare-CDN-Cache-Control": null,
-			"Cache-Tag": null
-		};
-		const headers = {
+		if (input.pendingDynamicCheck) return clearCloudflareCdnResponseHeaders(NO_STORE);
+		if (!input.cacheControl) return clearCloudflareCdnResponseHeaders(NO_STORE);
+		if (isNonCacheableCacheControl(input.cacheControl)) return clearCloudflareCdnResponseHeaders(input.cacheControl);
+		const cacheTag = input.tags?.length ? formatCacheTag(input.tags) : null;
+		if (input.tags?.length && !cacheTag) return clearCloudflareCdnResponseHeaders(NO_STORE);
+		return {
+			...getBuildIdentityResponseHeader(),
 			"Cache-Control": BROWSER_REVALIDATE,
-			"CDN-Cache-Control": toEdgeCacheControl(input.cacheControl)
+			"CDN-Cache-Control": null,
+			"Cloudflare-CDN-Cache-Control": toEdgeCacheControl(input.cacheControl),
+			"Cache-Tag": cacheTag
 		};
-		if (input.tags && input.tags.length > 0) {
-			const cacheTag = formatCacheTag(input.tags);
-			if (cacheTag) headers["Cache-Tag"] = cacheTag;
-		}
-		return headers;
 	}
 	/** Purge edge-cached responses by tag via the request context's `cache.purge`. */
 	async revalidateTag(tags, _durations) {
 		const cache = getWorkersCache();
 		if (!cache) return;
-		const tagList = (Array.isArray(tags) ? tags : [tags]).filter((t) => typeof t === "string" && t.length > 0);
+		const tagList = (Array.isArray(tags) ? tags : [tags]).filter((t) => typeof t === "string");
 		if (tagList.length === 0) return;
-		await cache.purge({ tags: tagList });
+		const result = await cache.purge({ tags: tagList.map(encodeCloudflareCacheTag) });
+		if (result?.success === false) {
+			const errors = result.errors.map(({ code, message }) => `${code}: ${message}`).join(", ");
+			throw new Error(`[vinext] Workers Cache purge failed${errors ? `: ${errors}` : ""}`);
+		}
 	}
 };
-const createCloudflareCdnCacheAdapter = () => new CloudflareCdnCacheAdapter();
+const createCloudflareCdnCacheAdapter = ({ env, options } = {}) => {
+	const binding = options?.versionMetadataBinding ?? DEFAULT_VERSION_METADATA_BINDING;
+	const candidate = env?.[binding];
+	return new CloudflareCdnCacheAdapter(candidate && typeof candidate === "object" && "id" in candidate && typeof candidate.id === "string" ? { id: candidate.id } : void 0, binding);
+};
 //#endregion
-export { CloudflareCdnCacheAdapter, createCloudflareCdnCacheAdapter as default };
+export { CloudflareCdnCacheAdapter, createCloudflareCdnCacheAdapter as default, encodeCloudflareCacheTag };

package/dist/cache/cdn-adapter.worker.d.ts

@@ -0,0 +1,31 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+import "vinext/internal/server/cloudflare-workers-tracing";
+import { VinextAssetFetcher } from "vinext/server/multi-stage";
+//#region src/cache/cdn-adapter.worker.d.ts
+type CloudflareStageContext = {
+  assets?: VinextAssetFetcher;
+  cache?: unknown;
+  exports?: Record<string, unknown>;
+  props?: unknown;
+  hostRuntime?: "worker";
+  passThroughOnException?(): void;
+  waitUntil?(promise: Promise<unknown>): void;
+};
+type CachePurgeOptions = {
+  tags: string[];
+};
+/** Cache-bearing entrypoint. Workers Cache HITs bypass this class entirely. */
+export declare class VinextCachedResponse extends WorkerEntrypoint<unknown, unknown> {
+  fetch(request: Request): Promise<Response>;
+  purge(options: CachePurgeOptions): Promise<unknown>;
+}
+/** Uncached response entrypoint. Bypass and probe renders execute only here. */
+export declare class VinextUncachedResponse extends WorkerEntrypoint<unknown, unknown> {
+  fetch(request: Request): Promise<Response>;
+}
+/** Uncached gateway: request routing and middleware always execute here. */
+declare const _default: {
+  fetch(request: Request, env: unknown, context: CloudflareStageContext | undefined): Promise<Response>;
+};
+//#endregion
+export { _default as default };

package/dist/cache/cdn-adapter.worker.js

@@ -0,0 +1,373 @@
+import { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity } from "./cdn-build-id.js";
+import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER, VINEXT_PRERENDER_READINESS_PATH, VINEXT_RSC_VARY_HEADER } from "vinext/internal/server/headers";
+import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
+import { WorkerEntrypoint } from "cloudflare:workers";
+import "vinext/internal/server/cloudflare-workers-tracing";
+import { loadVinextRequestStage } from "vinext/server/request-stage";
+import { loadVinextResponseStage } from "vinext/server/response-stage";
+import { traceCachedResponseStart } from "vinext/internal/server/response-start-tracing";
+//#region src/cache/cdn-adapter.worker.ts
+const CACHED_RESPONSE_STAGE_EXPORT = "VinextCachedResponse";
+const UNCACHED_RESPONSE_STAGE_EXPORT = "VinextUncachedResponse";
+const AUTHORIZATION_TRANSPORT_HEADER = "x-vinext-internal-authorization";
+const REQUEST_CACHE_CONTROL_TRANSPORT_HEADER = "x-vinext-internal-request-cache-control";
+const REQUEST_CF_TRANSPORT_HEADER = "x-vinext-internal-request-cf";
+const REQUEST_PRAGMA_TRANSPORT_HEADER = "x-vinext-internal-request-pragma";
+const CLOUDFLARE_EDGE_POLICY_HEADER = "Cloudflare-CDN-Cache-Control";
+const SHARED_RESPONSE_STAGE_HEADER = "x-vinext-cloudflare-shared-response-stage";
+const RESPONSE_STAGE_WIRE_CACHE = {
+	bypass: "vinext-cloudflare-v1:bypass",
+	shared: "vinext-cloudflare-v1:shared"
+};
+const FRAMEWORK_RESPONSE_VARY_FIELDS = new Set(VINEXT_RSC_VARY_HEADER.split(",").map((name) => name.trim().toLowerCase()));
+function isResponseStageReadinessRequest(request) {
+	return request.url.includes(VINEXT_PRERENDER_READINESS_PATH) && new URL(request.url).pathname === VINEXT_PRERENDER_READINESS_PATH;
+}
+function responseStageUnavailable() {
+	return new Response(null, {
+		status: 503,
+		headers: { "Cache-Control": "no-store" }
+	});
+}
+/** Stamp the entrypoint that actually produced a response, before Workers Cache stores it. */
+function stampResponseStageBuildIdentity(response) {
+	const buildIdentity = getVinextCdnBuildIdentity();
+	if (!buildIdentity) return response;
+	try {
+		response.headers.set(VINEXT_CDN_BUILD_ID_HEADER, buildIdentity);
+		return response;
+	} catch {
+		const headers = new Headers(response.headers);
+		headers.set(VINEXT_CDN_BUILD_ID_HEADER, buildIdentity);
+		const webSocket = response.webSocket;
+		if (!webSocket && (response.status < 200 || response.status > 599)) {
+			const unavailable = responseStageUnavailable();
+			unavailable.headers.set(VINEXT_CDN_BUILD_ID_HEADER, buildIdentity);
+			return unavailable;
+		}
+		const init = {
+			headers,
+			status: response.status,
+			statusText: response.statusText
+		};
+		if (webSocket) init.webSocket = webSocket;
+		return new Response(response.body, init);
+	}
+}
+/** Reject a response routed to an entrypoint from another propagating build. */
+function validateResponseStageBuildIdentity(response) {
+	const expectedBuildIdentity = getVinextCdnBuildIdentity();
+	if (!expectedBuildIdentity || response.headers.get("X-Vinext-Build-Id") === expectedBuildIdentity) return response;
+	response.body?.cancel().catch(() => {});
+	return responseStageUnavailable();
+}
+function stripUntrustedTransportHeaders(request) {
+	if (!request.headers.has(AUTHORIZATION_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CF_TRANSPORT_HEADER) && !request.headers.has(REQUEST_PRAGMA_TRANSPORT_HEADER)) return request;
+	const headers = new Headers(request.headers);
+	headers.delete(AUTHORIZATION_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
+	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	const sanitized = new Request(request, { headers });
+	const requestCf = Reflect.get(request, "cf");
+	if (requestCf !== void 0) Object.defineProperty(sanitized, "cf", {
+		configurable: true,
+		enumerable: true,
+		value: requestCf
+	});
+	return sanitized;
+}
+function withWorkerHostRuntime(context, env) {
+	const candidateAssets = env && typeof env === "object" && Reflect.has(env, "ASSETS") ? Reflect.get(env, "ASSETS") : void 0;
+	const assets = candidateAssets && (typeof candidateAssets === "object" || typeof candidateAssets === "function") && Reflect.has(candidateAssets, "fetch") && typeof Reflect.get(candidateAssets, "fetch") === "function" ? candidateAssets : context?.assets;
+	return {
+		...assets === void 0 ? {} : { assets },
+		...context?.cache === void 0 ? {} : { cache: context.cache },
+		...context?.exports === void 0 ? {} : { exports: context.exports },
+		hostRuntime: "worker",
+		...typeof context?.passThroughOnException === "function" ? { passThroughOnException: () => context.passThroughOnException?.() } : {},
+		...context?.props === void 0 ? {} : { props: context.props },
+		...typeof context?.waitUntil === "function" ? { waitUntil: (promise) => context.waitUntil?.(promise) } : {}
+	};
+}
+function hasFetch(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && "fetch" in value && typeof value.fetch === "function";
+}
+function hasPurge(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && "purge" in value && typeof value.purge === "function";
+}
+function getResponseStageBinding(context, exportName, serializedInvocation) {
+	const binding = context.exports?.[exportName];
+	if (typeof binding !== "function") return null;
+	const target = binding({ props: JSON.parse(serializedInvocation) });
+	return hasFetch(target) ? target : null;
+}
+async function createCacheFacingRequest(request, serializedInvocation) {
+	const authorization = request.headers.get("Authorization");
+	let serializedRequestCf = null;
+	const requestCf = Reflect.get(request, "cf");
+	if (requestCf !== void 0) try {
+		const json = JSON.stringify(requestCf);
+		if (json !== void 0) serializedRequestCf = encodeURIComponent(json);
+	} catch {}
+	const authorizationIdentity = authorization === null ? "absent" : `present:${authorization.length}:${authorization}`;
+	const frameworkVaryIdentity = JSON.stringify([...FRAMEWORK_RESPONSE_VARY_FIELDS].map((name) => [name, request.headers.get(name)]));
+	const responseStageBuildIdentity = getVinextCdnBuildIdentity() ?? "";
+	const bytes = new TextEncoder().encode(`${request.url}\0${serializedInvocation}\0${authorizationIdentity}\0${frameworkVaryIdentity}\0${responseStageBuildIdentity}`);
+	const key = [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+	const url = new URL(request.url);
+	url.searchParams.set("__vinext_cache_key", key);
+	const headers = new Headers(request.headers);
+	const requestCacheControl = headers.get("Cache-Control");
+	const requestPragma = headers.get("Pragma");
+	headers.delete("Cache-Control");
+	headers.delete("Pragma");
+	headers.delete("Authorization");
+	headers.delete(AUTHORIZATION_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
+	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	if (authorization !== null) headers.set(AUTHORIZATION_TRANSPORT_HEADER, encodeURIComponent(authorization));
+	if (serializedRequestCf !== null) headers.set(REQUEST_CF_TRANSPORT_HEADER, serializedRequestCf);
+	if (requestCacheControl !== null) headers.set(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER, encodeURIComponent(requestCacheControl));
+	if (requestPragma !== null) headers.set(REQUEST_PRAGMA_TRANSPORT_HEADER, encodeURIComponent(requestPragma));
+	return new Request(url, {
+		cf: { vary: { default: { action: "passthrough" } } },
+		headers,
+		method: request.method
+	});
+}
+function restoreResponseStageRequest(request, requestUrl, requestMethod) {
+	const headers = new Headers(request.headers);
+	const serializedAuthorization = headers.get(AUTHORIZATION_TRANSPORT_HEADER);
+	const serializedRequestCacheControl = headers.get(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	const serializedRequestCf = headers.get(REQUEST_CF_TRANSPORT_HEADER);
+	const serializedRequestPragma = headers.get(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	headers.delete("Cache-Control");
+	headers.delete("Pragma");
+	headers.delete("Authorization");
+	headers.delete(AUTHORIZATION_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
+	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	if (serializedAuthorization !== null) try {
+		headers.set("Authorization", decodeURIComponent(serializedAuthorization));
+	} catch {}
+	let requestCf;
+	if (serializedRequestCf !== null) try {
+		requestCf = JSON.parse(decodeURIComponent(serializedRequestCf));
+	} catch {}
+	if (serializedRequestCacheControl !== null) try {
+		headers.set("Cache-Control", decodeURIComponent(serializedRequestCacheControl));
+	} catch {}
+	if (serializedRequestPragma !== null) try {
+		headers.set("Pragma", decodeURIComponent(serializedRequestPragma));
+	} catch {}
+	const restored = new Request(new Request(requestUrl, request), {
+		headers,
+		method: requestMethod
+	});
+	let didAccessRequestCf = false;
+	if (requestCf !== void 0) Object.defineProperty(restored, "cf", {
+		configurable: true,
+		enumerable: true,
+		get() {
+			didAccessRequestCf = true;
+			return requestCf;
+		}
+	});
+	return {
+		didAccessRequestCf: () => didAccessRequestCf,
+		request: restored
+	};
+}
+function preventResponseCaching(response) {
+	const headers = new Headers(response.headers);
+	headers.set("Cache-Control", "no-store");
+	headers.delete("CDN-Cache-Control");
+	headers.delete("Cloudflare-CDN-Cache-Control");
+	headers.delete("Cache-Tag");
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+/**
+* Cloudflare consumes its private cache policy before returning a cached
+* entrypoint response. Strip it here as well for uncached/local fallbacks so
+* the outer gateway never forwards an inner shared-cache policy after adding
+* request-specific middleware or routing headers.
+*/
+function markSharedResponseStage(response, provenanceToken, responseStageProps, exposeEntrypointCacheStatus = false) {
+	const headers = new Headers(response.headers);
+	const cacheStatus = exposeEntrypointCacheStatus ? headers.get("CF-Cache-Status") : null;
+	headers.set(SHARED_RESPONSE_STAGE_HEADER, cacheStatus ? `${provenanceToken}:${encodeURIComponent(cacheStatus)}` : provenanceToken);
+	return traceCachedResponseStart(new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	}), cacheStatus, responseStageProps);
+}
+function finalizeGatewayResponse(response, provenanceToken) {
+	const provenance = response.headers.get(SHARED_RESPONSE_STAGE_HEADER);
+	const usedSharedResponseStage = provenance === provenanceToken || provenance?.startsWith(`${provenanceToken}:`) === true;
+	const sharedResponseStageCollision = provenance !== null && !usedSharedResponseStage;
+	const cacheControl = response.headers.get("Cache-Control");
+	if (!response.headers.has(CLOUDFLARE_EDGE_POLICY_HEADER) && !usedSharedResponseStage && !sharedResponseStageCollision) return response;
+	const headers = new Headers(response.headers);
+	headers.delete(SHARED_RESPONSE_STAGE_HEADER);
+	headers.delete(CLOUDFLARE_EDGE_POLICY_HEADER);
+	if (usedSharedResponseStage || sharedResponseStageCollision) {
+		headers.delete("CDN-Cache-Control");
+		headers.delete("Cache-Tag");
+		headers.delete(VINEXT_CACHE_HEADER);
+		headers.delete(NEXTJS_CACHE_HEADER);
+		if (!cacheControl || !isNonCacheableCacheControl(cacheControl)) headers.set("Cache-Control", "private, max-age=0, must-revalidate");
+	}
+	if (usedSharedResponseStage && provenance?.startsWith(`${provenanceToken}:`)) {
+		const cacheStatus = decodeURIComponent(provenance.slice(provenanceToken.length + 1));
+		headers.set(VINEXT_CACHE_HEADER, cacheStatus);
+		headers.set(NEXTJS_CACHE_HEADER, cacheStatus);
+	}
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+function hasTaggedCustomVary(response) {
+	if (!response.headers.get("Cache-Tag")) return false;
+	return (response.headers.get("Vary") ?? "").split(",").map((name) => name.trim().toLowerCase()).filter(Boolean).some((name) => !FRAMEWORK_RESPONSE_VARY_FIELDS.has(name));
+}
+function withResponseStagePurge(context) {
+	const factory = context.exports?.[CACHED_RESPONSE_STAGE_EXPORT];
+	if (typeof factory !== "function") return context;
+	const fallback = context.cache;
+	return {
+		...context,
+		cache: { purge(options) {
+			const target = factory({ props: {} });
+			if (hasPurge(target)) return target.purge(options);
+			return hasPurge(fallback) ? fallback.purge(options) : void 0;
+		} }
+	};
+}
+function getResponseStageInvocation(value, expectedCache) {
+	if (!value || typeof value !== "object") return null;
+	const expectedResponseStageBuildIdentity = Reflect.get(value, "expectedResponseStageBuildIdentity");
+	if (expectedResponseStageBuildIdentity !== void 0 && typeof expectedResponseStageBuildIdentity !== "string") return null;
+	const options = Reflect.get(value, "options");
+	if (!options || typeof options !== "object") return null;
+	const wireCache = Reflect.get(options, "cache");
+	let cache;
+	if (expectedResponseStageBuildIdentity !== void 0 && wireCache === RESPONSE_STAGE_WIRE_CACHE.shared) cache = "shared";
+	else if (expectedResponseStageBuildIdentity !== void 0 && wireCache === RESPONSE_STAGE_WIRE_CACHE.bypass) cache = "bypass";
+	else if (expectedResponseStageBuildIdentity === void 0 && getVinextCdnBuildIdentity() === null && (wireCache === "shared" || wireCache === "bypass")) cache = wireCache;
+	else return null;
+	if (expectedCache !== void 0 && cache !== expectedCache) return null;
+	const requestUrl = Reflect.get(value, "requestUrl");
+	if (typeof requestUrl !== "string") return null;
+	const requestMethod = Reflect.get(value, "requestMethod");
+	if (typeof requestMethod !== "string" || requestMethod.length === 0) return null;
+	try {
+		new URL(requestUrl);
+	} catch {
+		return null;
+	}
+	return {
+		...typeof expectedResponseStageBuildIdentity === "string" ? { expectedResponseStageBuildIdentity } : {},
+		options: {
+			...options,
+			cache
+		},
+		props: Reflect.get(value, "props"),
+		requestMethod,
+		requestUrl
+	};
+}
+async function invokeResponseStage(request, env, context, invocation) {
+	const dispatchResponseStage = (stageRequest, props, options) => invokeResponseStage(stageRequest, env, context, {
+		options,
+		props,
+		requestMethod: stageRequest.method,
+		requestUrl: stageRequest.url
+	});
+	const dispatchRequestStage = async (stageRequest) => {
+		const { handleRequestStage } = await loadVinextRequestStage();
+		return handleRequestStage(stageRequest, env, context, dispatchResponseStage);
+	};
+	const { handleResponseStage } = await loadVinextResponseStage();
+	return handleResponseStage(request, env, context, invocation.props, dispatchRequestStage, invocation.options);
+}
+/** Cache-bearing entrypoint. Workers Cache HITs bypass this class entirely. */
+var VinextCachedResponse = class extends WorkerEntrypoint {
+	async fetch(request) {
+		const context = withWorkerHostRuntime(this.ctx, this.env);
+		const invocation = getResponseStageInvocation(context.props, "shared");
+		if (!invocation) return stampResponseStageBuildIdentity(new Response("Invalid vinext response-stage invocation", {
+			status: 400,
+			headers: { "Cache-Control": "no-store" }
+		}));
+		if (invocation.expectedResponseStageBuildIdentity !== void 0 && invocation.expectedResponseStageBuildIdentity !== getVinextCdnBuildIdentity()) return stampResponseStageBuildIdentity(responseStageUnavailable());
+		const restored = restoreResponseStageRequest(request, invocation.requestUrl, invocation.requestMethod);
+		const response = await invokeResponseStage(restored.request, this.env, context, invocation);
+		return stampResponseStageBuildIdentity(restored.didAccessRequestCf() || hasTaggedCustomVary(response) ? preventResponseCaching(response) : response);
+	}
+	async purge(options) {
+		const cache = Reflect.get(this.ctx, "cache");
+		if (!hasPurge(cache)) return void 0;
+		return cache.purge(options);
+	}
+};
+/** Uncached response entrypoint. Bypass and probe renders execute only here. */
+var VinextUncachedResponse = class extends WorkerEntrypoint {
+	async fetch(request) {
+		const context = withResponseStagePurge(withWorkerHostRuntime(this.ctx, this.env));
+		const invocation = getResponseStageInvocation(context.props, "bypass");
+		if (!invocation) return stampResponseStageBuildIdentity(new Response("Invalid vinext response-stage invocation", {
+			status: 400,
+			headers: { "Cache-Control": "no-store" }
+		}));
+		if (invocation.expectedResponseStageBuildIdentity !== void 0 && invocation.expectedResponseStageBuildIdentity !== getVinextCdnBuildIdentity()) return stampResponseStageBuildIdentity(responseStageUnavailable());
+		return stampResponseStageBuildIdentity(await invokeResponseStage(request, this.env, context, invocation));
+	}
+};
+/** Uncached gateway: request routing and middleware always execute here. */
+var cdn_adapter_worker_default = { async fetch(request, env, context) {
+	request = stripUntrustedTransportHeaders(request);
+	const sharedResponseStageProvenance = crypto.randomUUID();
+	const stageContext = withResponseStagePurge(withWorkerHostRuntime(context, env));
+	const dispatchResponseStage = async (stageRequest, props, options) => {
+		const expectedResponseStageBuildIdentity = getVinextCdnBuildIdentity();
+		const invocation = {
+			...expectedResponseStageBuildIdentity === null ? {} : { expectedResponseStageBuildIdentity },
+			options,
+			props,
+			requestMethod: stageRequest.method,
+			requestUrl: stageRequest.url
+		};
+		const usesSharedCache = options.cache === "shared";
+		try {
+			const serializedInvocation = JSON.stringify({
+				...invocation,
+				options: expectedResponseStageBuildIdentity === null ? options : {
+					...options,
+					cache: RESPONSE_STAGE_WIRE_CACHE[options.cache]
+				}
+			});
+			const binding = getResponseStageBinding(stageContext, usesSharedCache ? CACHED_RESPONSE_STAGE_EXPORT : UNCACHED_RESPONSE_STAGE_EXPORT, serializedInvocation);
+			if (!binding) return responseStageUnavailable();
+			const entrypointRequest = usesSharedCache ? await createCacheFacingRequest(stageRequest, serializedInvocation) : stageRequest;
+			const response = validateResponseStageBuildIdentity(await binding.fetch(entrypointRequest));
+			return usesSharedCache ? markSharedResponseStage(response, sharedResponseStageProvenance, props, true) : response;
+		} catch (error) {
+			if (isResponseStageReadinessRequest(stageRequest)) return responseStageUnavailable();
+			throw error;
+		}
+	};
+	const { handleRequestStage } = await loadVinextRequestStage();
+	return finalizeGatewayResponse(await handleRequestStage(request, env, stageContext, dispatchResponseStage), sharedResponseStageProvenance);
+} };
+//#endregion
+export { VinextCachedResponse, VinextUncachedResponse, cdn_adapter_worker_default as default };

package/dist/cache/cdn-build-id.d.ts

@@ -0,0 +1,6 @@
+//#region src/cache/cdn-build-id.d.ts
+/** Build identity stamped by the Cloudflare CDN adapter on page responses. */
+export declare const VINEXT_CDN_BUILD_ID_HEADER = "X-Vinext-Build-Id";
+/** Opaque identity shared by every server entry emitted by one vite build. */
+export declare function getVinextCdnBuildIdentity(): string | null;
+//#endregion

package/dist/cache/cdn-build-id.js

@@ -0,0 +1,9 @@
+//#region src/cache/cdn-build-id.ts
+/** Build identity stamped by the Cloudflare CDN adapter on page responses. */
+const VINEXT_CDN_BUILD_ID_HEADER = "X-Vinext-Build-Id";
+/** Opaque identity shared by every server entry emitted by one vite build. */
+function getVinextCdnBuildIdentity() {
+	return process.env.__VINEXT_RSC_BUILD_IDENTITY || process.env.__VINEXT_BUILD_ID || null;
+}
+//#endregion
+export { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity };