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

package/README.md

@@ -9,8 +9,11 @@ This package provides Cloudflare-specific cache and image backends for vinext:
   data cache (`fetch`, `"use cache"`, `unstable_cache`) with a Workers KV
   namespace.
 - **`cdnAdapter()`** (`@vinext/cloudflare/cache/cdn-adapter`) — delegates
-  page-level ISR serving and revalidation to Cloudflare Workers Cache. This is
-  opt-in and requires Workers Cache to be enabled in Wrangler config.
+  page-level ISR serving and revalidation to Cloudflare Workers Cache through
+  an automatically generated cache-enabled response entrypoint.
+- **`responseStoreAdapter()`** (`@vinext/cloudflare/cache/response-store-adapter`) —
+  uses Workers Response Store for both response and data caching, either in a
+  separate cache Worker or inside the application Worker.
 - **`imagesOptimizer()`** (`@vinext/cloudflare/images/images-optimizer`) — backs
   `next/image` transformations with a Cloudflare Images binding.
 
@@ -37,19 +40,13 @@ export default defineConfig({
 
 ### Workers Cache
 
-`cdnAdapter()` is optional. Only configure it when Workers Cache is enabled in
-`wrangler.jsonc`:
-
-```jsonc
-{
-  "cache": {
-    "enabled": true,
-  },
-  "version_metadata": {
-    "binding": "CF_VERSION_METADATA",
-  },
-}
-```
+`cdnAdapter()` is optional. Configuring it asks the Cloudflare build for two
+Worker entrypoints: the default entrypoint runs middleware and request-time
+routing with caching disabled, while `VinextCachedResponse` lazily loads the
+render stage with Workers Cache enabled. These settings are written to the
+generated `dist/server/wrangler.json`; do not enable Workers Cache on the
+default entrypoint in your source config. The generated config also declares
+the version metadata binding used for staged warmup.
 
 ```ts
 import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
@@ -57,19 +54,55 @@ import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
 vinext({ cache: { cdn: cdnAdapter() } });
 ```
 
-The version metadata binding lets staged warmup prove that every discovery,
-probe, and fill request reached the uploaded Worker version. Wrangler named
-environments do not inherit `version_metadata`; repeat the binding inside every
-`env.<name>` used with CDN warming.
+The generated version metadata binding lets staged warmup prove that every
+discovery, probe, and fill request reached the uploaded Worker version. Pass
+`versionMetadataBinding` to `cdnAdapter()` only when the deployment needs a
+custom binding name.
 
 Use `--experimental-warm-cdn-cache` for the two-stage deploy. The default flow
 makes one final fill request per admitted identity. Add `--warm-cdn-certify`
 only when you want an opt-in second, header-only request that must prove every
 planned entry reusable before promotion.
 
-Do not configure a Cache Rule that ignores or normalizes query strings for
-these responses. The two-stage cacheability manifest authorizes the full
-pathname + query identity, but an edge HIT happens before Worker admission.
+The response entrypoint hashes the complete transport identity into its
+Workers Cache URL, independently of zone Cache Rules, so distinct query and
+representation variants cannot collide.
+
+### Workers Response Store
+
+`responseStoreAdapter()` replaces both `cdnAdapter()` and `kvDataAdapter()`.
+It defaults to a separate cache Worker reached through the `RESPONSE_STORE`
+service binding. `vinext init` writes two collocated source configs:
+`wrangler.jsonc` for the application and `wrangler.response-store.jsonc` for the
+cache Worker. The latter points directly at the installed
+`@cloudflare/workers-response-store` implementation and owns its R2 bucket,
+SQLite Durable Object, Worker name, and cache settings. Edit those configs to
+choose or reuse names, keeping the application service binding aligned with the
+cache Worker name.
+
+The two Workers are deliberately deployed separately. Deploy the Response Store
+when its package or config changes, then deploy the application normally:
+
+```sh
+npx wrangler deploy --config wrangler.response-store.jsonc
+npx @vinext/cloudflare deploy
+```
+
+`vinext-cloudflare deploy` never creates, rewrites, or deploys the Response
+Store Worker.
+
+To deploy storage and cache entrypoints with the application instead, select
+self-contained mode:
+
+```ts
+import { responseStoreAdapter } from "@vinext/cloudflare/cache/response-store-adapter";
+
+vinext({ cache: responseStoreAdapter({ mode: "self-contained" }) });
+```
+
+In this mode `vinext init` places the required R2, SQLite Durable Object,
+Workers Cache entrypoint, and version-metadata configuration in
+`wrangler.jsonc`; no second Wrangler config is required.
 
 ## Deploy
 

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

@@ -1,5 +1,15 @@
 //#region src/cache/cdn-adapter-config.d.ts
+type WranglerWorkerExport = {
+  cache?: {
+    enabled: boolean;
+  };
+  type?: string;
+  [key: string]: unknown;
+};
 type WranglerOutputConfig = {
+  compatibility_date?: string;
+  compatibility_flags?: string[];
+  exports?: Record<string, WranglerWorkerExport>;
   version_metadata?: unknown;
   [key: string]: unknown;
 };
@@ -7,16 +17,14 @@ type VersionMetadataOptions = {
   binding: string;
   bindingIsExplicit: boolean;
 };
-declare function configureCdnVersionMetadata(config: WranglerOutputConfig, options: VersionMetadataOptions): WranglerOutputConfig;
-/**
- * Add the CDN adapter's version metadata binding to the Cloudflare Vite
- * plugin's primary generated deployment config.
- */
-declare function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }: {
+export declare function configureCdnVersionMetadata(config: WranglerOutputConfig, options: VersionMetadataOptions): WranglerOutputConfig;
+/** Add the per-entrypoint Workers Cache policy to an emitted Wrangler config. */
+export declare function configureWorkersCacheEntrypoints(config: WranglerOutputConfig): WranglerOutputConfig;
+/** Apply the complete CDN adapter policy to the primary generated config. */
+export declare function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }: {
   outDir: string;
   isPrimaryServerOutput: boolean;
   binding: string;
   bindingIsExplicit: boolean;
 }): Promise<void>;
-//#endregion
-export { configureCdnVersionMetadata, finalizeCdnAdapterBuildOutput };
+//#endregion

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

@@ -1,6 +1,9 @@
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region src/cache/cdn-adapter-config.ts
+const CACHED_RESPONSE_STAGE_EXPORT = "VinextCachedResponse";
+const UNCACHED_RESPONSE_STAGE_EXPORT = "VinextUncachedResponse";
+const CTX_EXPORTS_DEFAULT_DATE = "2025-11-17";
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -19,29 +22,66 @@ function configureCdnVersionMetadata(config, options) {
 		version_metadata: { binding: options.binding }
 	};
 }
-/**
-* Add the CDN adapter's version metadata binding to the Cloudflare Vite
-* plugin's primary generated deployment config.
-*/
-async function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }) {
-	if (!isPrimaryServerOutput) return;
-	await configureGeneratedCdnVersionMetadata(path.resolve(outDir, "wrangler.json"), {
-		binding,
-		bindingIsExplicit
-	});
+/** Add the per-entrypoint Workers Cache policy to an emitted Wrangler config. */
+function configureWorkersCacheEntrypoints(config) {
+	const configuredExports = config.exports ?? {};
+	const compatibilityFlags = config.compatibility_flags ?? [];
+	if (compatibilityFlags.includes("disable_ctx_exports")) throw new Error("[vinext] cdnAdapter() requires ctx.exports, but the generated Wrangler config explicitly disables it with disable_ctx_exports.");
+	const configuredCompatibilityFlags = config.compatibility_date === void 0 || config.compatibility_date < CTX_EXPORTS_DEFAULT_DATE ? compatibilityFlags.includes("enable_ctx_exports") ? compatibilityFlags : [...compatibilityFlags, "enable_ctx_exports"] : compatibilityFlags.filter((flag) => flag !== "enable_ctx_exports");
+	for (const name of [
+		"default",
+		CACHED_RESPONSE_STAGE_EXPORT,
+		UNCACHED_RESPONSE_STAGE_EXPORT
+	]) {
+		const existing = configuredExports[name];
+		if (existing?.type !== void 0 && existing.type !== "worker") throw new Error(`[vinext] cdnAdapter() cannot configure the reserved Worker export ${JSON.stringify(name)} because it is already declared as ${JSON.stringify(existing.type)}.`);
+	}
+	return {
+		...config,
+		compatibility_flags: configuredCompatibilityFlags,
+		exports: {
+			...configuredExports,
+			default: {
+				...configuredExports.default,
+				type: "worker",
+				cache: { enabled: false }
+			},
+			[CACHED_RESPONSE_STAGE_EXPORT]: {
+				...configuredExports[CACHED_RESPONSE_STAGE_EXPORT],
+				type: "worker",
+				cache: { enabled: true }
+			},
+			[UNCACHED_RESPONSE_STAGE_EXPORT]: {
+				...configuredExports[UNCACHED_RESPONSE_STAGE_EXPORT],
+				type: "worker",
+				cache: { enabled: false }
+			}
+		}
+	};
 }
-async function configureGeneratedCdnVersionMetadata(generatedConfigPath, options) {
-	let generatedConfig;
+async function readGeneratedConfig(generatedConfigPath, allowMissing) {
 	try {
 		const parsed = JSON.parse(await fs.readFile(generatedConfigPath, "utf8"));
 		if (!isRecord(parsed)) throw new TypeError("the root value must be an object");
-		generatedConfig = parsed;
+		return parsed;
 	} catch (cause) {
+		if (allowMissing && cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT") return null;
 		throw new Error(`[vinext] Could not read the generated Wrangler config at ${generatedConfigPath}.`, { cause });
 	}
-	const configured = configureCdnVersionMetadata(generatedConfig, options);
-	if (configured === generatedConfig) return;
-	await fs.writeFile(generatedConfigPath, `${JSON.stringify(configured, null, 2)}\n`);
+}
+async function writeGeneratedConfig(generatedConfigPath, config) {
+	await fs.writeFile(generatedConfigPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+/** Apply the complete CDN adapter policy to the primary generated config. */
+async function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }) {
+	if (!isPrimaryServerOutput) return;
+	const generatedConfigPath = path.resolve(outDir, "wrangler.json");
+	const generatedConfig = await readGeneratedConfig(generatedConfigPath, false);
+	if (!generatedConfig) return;
+	await writeGeneratedConfig(generatedConfigPath, configureWorkersCacheEntrypoints(configureCdnVersionMetadata(generatedConfig, {
+		binding,
+		bindingIsExplicit
+	})));
 }
 //#endregion
-export { configureCdnVersionMetadata, finalizeCdnAdapterBuildOutput };
+export { configureCdnVersionMetadata, configureWorkersCacheEntrypoints, finalizeCdnAdapterBuildOutput };

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

@@ -1,7 +1,7 @@
 //#region src/cache/cdn-adapter.d.ts
-declare const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+export declare const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
 /** Options accepted by {@link cdnAdapter}, forwarded to the runtime factory. */
-type CdnAdapterOptions = {
+export type CdnAdapterOptions = {
   /** Version metadata binding used to verify version-overridden requests. */
   versionMetadataBinding?: string;
 };
@@ -10,47 +10,48 @@ type CdnAdapterOptions = {
  * Cloudflare Workers Cache.
  *
  * Unlike the data adapter (which stores cache entries in a durable store and
- * serves HIT/STALE itself), this adapter delegates serving to Cloudflare's
- * edge cache.
+ * serves HIT/STALE itself), this adapter delegates serving to Workers Cache on
+ * a named Worker entrypoint. The default entrypoint always runs middleware and
+ * request-time routing before dispatching to cached or uncached response-stage
+ * entrypoints.
  *
- * Workers Cache must be enabled in your Wrangler config for this to work.
- * ```jsonc
- * // wrangler.jsonc
- * {
- *   "cache": {
- *     "enabled": true,
- *   },
- *   "version_metadata": {
- *     "binding": "CF_VERSION_METADATA"
- *   }
- * }
- * ```
- * Wrangler does not inherit `version_metadata` into named environments. Repeat
- * the binding in every `env.<name>` used for CDN warmup.
+ * The emitted Wrangler configuration enables Workers Cache only for that
+ * response-stage export, so cache hits do not start the application stage.
+ * The generated deployment config automatically enables Workers Cache for the
+ * cached response entrypoint and adds the version metadata binding used by
+ * warmup. The uncached response entrypoint keeps bypass and probe renders out
+ * of the gateway without enabling Workers Cache for them.
  *
- * Cache Rules must preserve the full query string in the incoming cache key.
- * Two-stage admission certifies exact pathname + search identities, while an
- * edge HIT is served before the Worker can reject a differently keyed request.
+ * The adapter adds a transport-only URL digest so distinct response-stage
+ * identities cannot collide. Workers Cache owns this key independently of
+ * zone Cache Rules.
  */
-declare function cdnAdapter(options?: CdnAdapterOptions): {
+export declare function cdnAdapter(options?: CdnAdapterOptions): {
   adapter: string;
   options: CdnAdapterOptions | undefined;
   output: {
+    entry: string;
     matchesBuild({ plugins }: {
       plugins: readonly {
         name?: string;
       }[];
     }): boolean;
+    transformHostEntry({ code, id }: {
+      code: string;
+      id: string;
+    }): string | null;
     finalizeBuildOutput({ outDir, isPrimaryServerOutput }: {
       outDir: string;
       isPrimaryServerOutput: boolean;
     }): Promise<void>;
+    type: "multi-stage";
   };
   capabilities: {
     buildIdentity: "response-header";
+    isResponsePolicyHeader: (name: string) => boolean;
+    requestRouting: "uncached-stage";
     responseVary: "verbatim";
     routeCacheability: "probe-manifest";
   };
 };
-//#endregion
-export { CdnAdapterOptions, DEFAULT_CDN_VERSION_METADATA_BINDING, cdnAdapter };
+//#endregion

package/dist/cache/cdn-adapter.js

@@ -2,44 +2,45 @@ import { finalizeCdnAdapterBuildOutput } from "./cdn-adapter-config.js";
 import { fileURLToPath } from "node:url";
 //#region src/cache/cdn-adapter.ts
 const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+const CLOUDFLARE_WORKER_ENTRY_ID = "virtual:cloudflare/worker-entry";
 /**
 * Cloudflare CDN cache adapter - edge-managed page-level ISR backed by the
 * Cloudflare Workers Cache.
 *
 * Unlike the data adapter (which stores cache entries in a durable store and
-* serves HIT/STALE itself), this adapter delegates serving to Cloudflare's
-* edge cache.
+* serves HIT/STALE itself), this adapter delegates serving to Workers Cache on
+* a named Worker entrypoint. The default entrypoint always runs middleware and
+* request-time routing before dispatching to cached or uncached response-stage
+* entrypoints.
 *
-* Workers Cache must be enabled in your Wrangler config for this to work.
-* ```jsonc
-* // wrangler.jsonc
-* {
-*   "cache": {
-*     "enabled": true,
-*   },
-*   "version_metadata": {
-*     "binding": "CF_VERSION_METADATA"
-*   }
-* }
-* ```
-* Wrangler does not inherit `version_metadata` into named environments. Repeat
-* the binding in every `env.<name>` used for CDN warmup.
+* The emitted Wrangler configuration enables Workers Cache only for that
+* response-stage export, so cache hits do not start the application stage.
+* The generated deployment config automatically enables Workers Cache for the
+* cached response entrypoint and adds the version metadata binding used by
+* warmup. The uncached response entrypoint keeps bypass and probe renders out
+* of the gateway without enabling Workers Cache for them.
 *
-* Cache Rules must preserve the full query string in the incoming cache key.
-* Two-stage admission certifies exact pathname + search identities, while an
-* edge HIT is served before the Worker can reject a differently keyed request.
+* The adapter adds a transport-only URL digest so distinct response-stage
+* identities cannot collide. Workers Cache owns this key independently of
+* zone Cache Rules.
 */
 function cdnAdapter(options) {
 	if (options?.versionMetadataBinding !== void 0 && (typeof options.versionMetadataBinding !== "string" || options.versionMetadataBinding.length === 0)) throw new TypeError("[vinext] cdnAdapter({ versionMetadataBinding }) must be a non-empty string binding name.");
 	const versionMetadataBinding = options?.versionMetadataBinding ?? "CF_VERSION_METADATA";
 	const bindingIsExplicit = options?.versionMetadataBinding !== void 0;
+	const workerEntry = fileURLToPath(import.meta.resolve("./cdn-adapter.worker.js"));
 	return {
 		adapter: fileURLToPath(import.meta.resolve("./cdn-adapter.runtime.js")),
 		options,
 		output: {
+			entry: workerEntry,
 			matchesBuild({ plugins }) {
 				return plugins.some(({ name }) => name === "vite-plugin-cloudflare" || name?.startsWith("vite-plugin-cloudflare:"));
 			},
+			transformHostEntry({ code, id }) {
+				if ((id.charCodeAt(0) === 0 ? id.slice(1) : id) !== CLOUDFLARE_WORKER_ENTRY_ID) return null;
+				return `${code}\nexport { VinextCachedResponse, VinextUncachedResponse } from ${JSON.stringify(workerEntry)};\n`;
+			},
 			finalizeBuildOutput({ outDir, isPrimaryServerOutput }) {
 				return finalizeCdnAdapterBuildOutput({
 					outDir,
@@ -47,10 +48,13 @@ function cdnAdapter(options) {
 					binding: versionMetadataBinding,
 					bindingIsExplicit
 				});
-			}
+			},
+			type: "multi-stage"
 		},
 		capabilities: {
 			buildIdentity: "response-header",
+			isResponsePolicyHeader: (name) => name.toLowerCase() === "cdn-cache-control" || name.toLowerCase() === "cloudflare-cdn-cache-control",
+			requestRouting: "uncached-stage",
 			responseVary: "verbatim",
 			routeCacheability: "probe-manifest"
 		}

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

@@ -7,11 +7,18 @@ type WorkerVersionMetadata = {
 type CdnAdapterOptions = {
   versionMetadataBinding?: string;
 };
-declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
+/** Encode a case-sensitive Next.js tag into a fixed Workers Cache tag. */
+export declare function encodeCloudflareCacheTag(tag: string): string;
+export declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
   private readonly versionMetadata?;
   private readonly versionMetadataBinding;
   readonly requiresCompletedResponseAdmission = true;
   readonly responseVary: "verbatim";
+  readonly responsePolicy: {
+    isHeader(name: string): boolean;
+    readCacheControl(headers: Headers): string | null;
+    hasExplicitNonCacheablePolicy(headers: Headers, baseline?: Headers): boolean;
+  };
   constructor(versionMetadata?: WorkerVersionMetadata | undefined, versionMetadataBinding?: string);
   validateRequest(request: Request): Response | null;
   readonly ownsBackgroundRevalidation = false;
@@ -24,7 +31,6 @@ declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
   set(_key: string, _data: IncrementalCacheValue | null, _ctx?: Record<string, unknown>): Promise<void>;
   buildResponseIdentityHeaders(): CdnResponseHeaders;
   buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
-  hasExplicitNonCacheableResponsePolicy(headers: Headers): boolean;
   /** Purge edge-cached responses by tag via the request context's `cache.purge`. */
   revalidateTag(tags: string | string[], _durations?: {
     expire?: number;
@@ -35,4 +41,4 @@ declare const createCloudflareCdnCacheAdapter: ({ env, options }?: {
   options?: CdnAdapterOptions;
 }) => CdnCacheAdapter;
 //#endregion
-export { CloudflareCdnCacheAdapter, createCloudflareCdnCacheAdapter as default };
+export { createCloudflareCdnCacheAdapter as default };

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

@@ -1,6 +1,7 @@
-import { VINEXT_CDN_BUILD_ID_HEADER } from "./cdn-build-id.js";
+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
 /**
@@ -16,22 +17,23 @@ import { getRequestExecutionContext } from "vinext/shims/request-context";
 *   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 `CDN-Cache-Control`
+* - `buildResponseHeaders` emits the SWR policy as `Cloudflare-CDN-Cache-Control`
 *   (`public, max-age=…, stale-while-revalidate=…`) so the edge caches and
-*   revalidates, while the browser-facing `Cache-Control` is
+*   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. A `Cache-Tag` header lets entries be
-*   purged by tag. Note the edge directive uses `max-age` (not `s-maxage`):
+*   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
-*   `CDN-Cache-Control` is already CDN-scoped so `max-age` is the correct knob
+*   `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 })`.
 *
-* Tag alignment: the tags emitted in `Cache-Tag` come from the page's render
-* tags (already canonicalised via `encodeCacheTag`), and the framework's
-* `revalidateTag` / `revalidatePath` pass the same canonical form to this
-* adapter's `revalidateTag`, so a purge targets exactly the responses that
-* carried the tag.
+* 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
@@ -49,7 +51,7 @@ function versionValidationFailure(message, status = 500) {
 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 = process.env.__VINEXT_RSC_BUILD_IDENTITY ?? process.env.__VINEXT_BUILD_ID;
+	const buildId = getVinextCdnBuildIdentity();
 	return buildId ? { [VINEXT_CDN_BUILD_ID_HEADER]: buildId } : {};
 }
 /** Remove every response header whose cache semantics are owned by Cloudflare. */
@@ -70,6 +72,9 @@ function hasExplicitCloudflareNonCacheableResponsePolicy(headers) {
 	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;
@@ -98,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`.
 */
@@ -107,34 +112,49 @@ 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;
@@ -164,24 +184,27 @@ var CloudflareCdnCacheAdapter = class {
 		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),
-			"Cloudflare-CDN-Cache-Control": null,
-			"Cache-Tag": input.tags ? formatCacheTag(input.tags) : null
+			"CDN-Cache-Control": null,
+			"Cloudflare-CDN-Cache-Control": toEdgeCacheControl(input.cacheControl),
+			"Cache-Tag": cacheTag
 		};
 	}
-	hasExplicitNonCacheableResponsePolicy(headers) {
-		return hasExplicitCloudflareNonCacheableResponsePolicy(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 = ({ env, options } = {}) => {
@@ -190,4 +213,4 @@ const createCloudflareCdnCacheAdapter = ({ env, options } = {}) => {
 	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,30 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+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 };