@vinext/cloudflare 1.0.0-beta.9 → 1.0.1

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

@@ -1,6 +1,6 @@
 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 { SHARED_RESPONSE_STAGE_HEADER, finalizeGatewayResponse } from "./browser-cache-policy.js";
+import { VINEXT_PRERENDER_READINESS_PATH, VINEXT_RSC_VARY_HEADER } from "vinext/internal/server/headers";
 import { WorkerEntrypoint } from "cloudflare:workers";
 import "vinext/internal/server/cloudflare-workers-tracing";
 import { loadVinextRequestStage } from "vinext/server/request-stage";
@@ -13,8 +13,6 @@ 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"
@@ -209,33 +207,6 @@ function markSharedResponseStage(response, provenanceToken, responseStageProps,
 		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));
@@ -320,7 +291,7 @@ var VinextCachedResponse = class extends WorkerEntrypoint {
 		return cache.purge(options);
 	}
 };
-/** Uncached response entrypoint. Bypass and probe renders execute only here. */
+/** Uncached response entrypoint retained for deployment readiness probes. */
 var VinextUncachedResponse = class extends WorkerEntrypoint {
 	async fetch(request) {
 		const context = withResponseStagePurge(withWorkerHostRuntime(this.ctx, this.env));
@@ -336,7 +307,7 @@ var VinextUncachedResponse = class extends WorkerEntrypoint {
 /** 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 sharedResponses = /* @__PURE__ */ new Map();
 	const stageContext = withResponseStagePurge(withWorkerHostRuntime(context, env));
 	const dispatchResponseStage = async (stageRequest, props, options) => {
 		const expectedResponseStageBuildIdentity = getVinextCdnBuildIdentity();
@@ -349,6 +320,7 @@ var cdn_adapter_worker_default = { async fetch(request, env, context) {
 		};
 		const usesSharedCache = options.cache === "shared";
 		try {
+			if (!usesSharedCache && !isResponseStageReadinessRequest(stageRequest)) return stampResponseStageBuildIdentity(await invokeResponseStage(stageRequest, env, stageContext, invocation));
 			const serializedInvocation = JSON.stringify({
 				...invocation,
 				options: expectedResponseStageBuildIdentity === null ? options : {
@@ -360,14 +332,17 @@ var cdn_adapter_worker_default = { async fetch(request, env, context) {
 			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;
+			if (!usesSharedCache) return response;
+			const shared = markSharedResponseStage(response, crypto.randomUUID(), props, true);
+			sharedResponses.set(shared.headers.get(SHARED_RESPONSE_STAGE_HEADER), { headers: new Headers(shared.headers) });
+			return shared;
 		} catch (error) {
 			if (isResponseStageReadinessRequest(stageRequest)) return responseStageUnavailable();
 			throw error;
 		}
 	};
 	const { handleRequestStage } = await loadVinextRequestStage();
-	return finalizeGatewayResponse(await handleRequestStage(request, env, stageContext, dispatchResponseStage), sharedResponseStageProvenance);
+	return finalizeGatewayResponse(await handleRequestStage(request, env, stageContext, dispatchResponseStage), sharedResponses);
 } };
 //#endregion
 export { VinextCachedResponse, VinextUncachedResponse, cdn_adapter_worker_default as default };

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

@@ -1,6 +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 vinext build. */
+/** 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

@@ -1,7 +1,7 @@
 //#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 vinext build. */
+/** 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;
 }

package/dist/cache/config.d.ts

@@ -0,0 +1,137 @@
+import { CloudflareConfig, WorkerConfig } from "cf/config";
+//#region src/cache/config.d.ts
+type ResponseStoreStorageOptions = {
+  worker: string;
+  bucket: string;
+};
+export declare function createWorkersResponseStoreSelfContainedConfig(options: ResponseStoreStorageOptions): Promise<{
+  cache: {
+    enabled: true;
+  };
+  exports: {
+    CacheMetadata: {
+      state?: "created";
+      type: "durable-object";
+      storage: "sqlite";
+      container: undefined;
+    } | {
+      state?: "created";
+      type: "durable-object";
+      storage: "sqlite";
+      container: undefined;
+    };
+    ResponseStoreBinding: import("cf/config").WorkerEntrypointExport;
+  };
+  env: {
+    CACHE_BODIES: import("cf/config").R2Binding;
+    CACHE_METADATA: {
+      type: "durable-object";
+      worker: string;
+      exportName: string;
+    };
+    CF_VERSION_METADATA: import("cf/config").VersionMetadataBinding;
+  };
+}>;
+export declare function createWorkersResponseStoreServiceBindingConfig(options: {
+  accountId?: CloudflareConfig["accountId"];
+  worker: {
+    name: string;
+    compatibilityDate: string;
+    compatibilityFlags?: string[];
+    observability?: WorkerConfig["observability"];
+  };
+  bucket: string;
+}): Promise<{
+  accountId: string | undefined;
+  serviceBindingWorker: {
+    cache: {
+      enabled: true;
+    };
+    exports: {
+      CacheMetadata: {
+        state?: "created";
+        type: "durable-object";
+        storage: "sqlite";
+        container: undefined;
+      } | {
+        state?: "created";
+        type: "durable-object";
+        storage: "sqlite";
+        container: undefined;
+      };
+      ResponseStoreBinding: import("cf/config").WorkerEntrypointExport;
+    };
+    env: {
+      CACHE_BODIES: import("cf/config").R2Binding;
+      CACHE_METADATA: {
+        type: "durable-object";
+        worker: string;
+        exportName: string;
+      };
+    };
+    name: string;
+    compatibilityDate: string;
+    compatibilityFlags?: string[];
+    observability?: WorkerConfig["observability"];
+    entrypoint: string;
+    workersDev: false;
+    previewUrls: false;
+  };
+  applicationWorker: {
+    cache: {
+      enabled: false;
+    };
+    env: {
+      RESPONSE_STORE: import("cf/config").WorkerBinding<{
+        cache: {
+          enabled: true;
+        };
+        exports: {
+          CacheMetadata: {
+            state?: "created";
+            type: "durable-object";
+            storage: "sqlite";
+            container: undefined;
+          } | {
+            state?: "created";
+            type: "durable-object";
+            storage: "sqlite";
+            container: undefined;
+          };
+          ResponseStoreBinding: import("cf/config").WorkerEntrypointExport;
+        };
+        env: {
+          CACHE_BODIES: import("cf/config").R2Binding;
+          CACHE_METADATA: {
+            type: "durable-object";
+            worker: string;
+            exportName: string;
+          };
+        };
+        name: string;
+        compatibilityDate: string;
+        compatibilityFlags?: string[];
+        observability?: WorkerConfig["observability"];
+        entrypoint: string;
+        workersDev: false;
+        previewUrls: false;
+      }, "ResponseStoreService">;
+      CF_VERSION_METADATA: import("cf/config").VersionMetadataBinding;
+    };
+  };
+}>;
+export declare function createWorkersCacheConfig({ versionMetadataBinding }?: {
+  versionMetadataBinding?: string;
+}): Promise<{
+  cache: {
+    enabled: false;
+  };
+  env: {
+    [versionMetadataBinding]: import("cf/config").VersionMetadataBinding;
+  };
+  exports: {
+    VinextCachedResponse: import("cf/config").WorkerEntrypointExport;
+    VinextUncachedResponse: import("cf/config").WorkerEntrypointExport;
+  };
+}>;
+//#endregion

package/dist/cache/config.js

@@ -0,0 +1,87 @@
+//#region src/cache/config.ts
+const RESPONSE_STORE_BINDING = "RESPONSE_STORE";
+const RESPONSE_STORE_ENTRYPOINT = "ResponseStoreService";
+const DEFAULT_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+const CACHE_BODIES_BINDING = "CACHE_BODIES";
+const CACHE_METADATA_BINDING = "CACHE_METADATA";
+const CACHE_METADATA_CLASS = "CacheMetadata";
+const RESPONSE_STORE_CACHE_ENTRYPOINT = "ResponseStoreBinding";
+const RESPONSE_STORE_SERVICE_ENTRYPOINT = "@cloudflare/workers-response-store/service";
+async function createResponseStoreWorkerConfig(options) {
+	const { bindings, exports } = await import("cf/config");
+	return {
+		cache: { enabled: true },
+		exports: {
+			[CACHE_METADATA_CLASS]: {
+				...exports.durableObject({ storage: "sqlite" }),
+				storage: "sqlite",
+				container: void 0
+			},
+			[RESPONSE_STORE_CACHE_ENTRYPOINT]: exports.worker({ cache: { enabled: true } })
+		},
+		env: {
+			[CACHE_BODIES_BINDING]: bindings.r2({ name: options.bucket }),
+			[CACHE_METADATA_BINDING]: {
+				...bindings.durableObject({
+					worker: options.worker,
+					exportName: CACHE_METADATA_CLASS
+				}),
+				worker: options.worker,
+				exportName: CACHE_METADATA_CLASS
+			}
+		}
+	};
+}
+async function createWorkersResponseStoreSelfContainedConfig(options) {
+	const { bindings } = await import("cf/config");
+	const storage = await createResponseStoreWorkerConfig(options);
+	return {
+		...storage,
+		env: {
+			...storage.env,
+			[DEFAULT_VERSION_METADATA_BINDING]: bindings.versionMetadata()
+		}
+	};
+}
+async function createWorkersResponseStoreServiceBindingConfig(options) {
+	const { bindings } = await import("cf/config");
+	const storage = await createResponseStoreWorkerConfig({
+		worker: options.worker.name,
+		bucket: options.bucket
+	});
+	const serviceBindingWorker = {
+		...options.worker,
+		entrypoint: RESPONSE_STORE_SERVICE_ENTRYPOINT,
+		workersDev: false,
+		previewUrls: false,
+		...storage
+	};
+	return {
+		accountId: options.accountId,
+		serviceBindingWorker,
+		applicationWorker: {
+			cache: { enabled: false },
+			env: {
+				[RESPONSE_STORE_BINDING]: bindings.worker({
+					worker: serviceBindingWorker,
+					exportName: RESPONSE_STORE_ENTRYPOINT
+				}),
+				[DEFAULT_VERSION_METADATA_BINDING]: bindings.versionMetadata()
+			}
+		}
+	};
+}
+async function createWorkersCacheConfig({ versionMetadataBinding = DEFAULT_VERSION_METADATA_BINDING } = {}) {
+	if (versionMetadataBinding.length === 0) throw new TypeError("versionMetadataBinding must be a non-empty string");
+	const { bindings, exports } = await import("cf/config");
+	return {
+		cache: { enabled: false },
+		env: { [versionMetadataBinding]: bindings.versionMetadata() },
+		exports: {
+			VinextCachedResponse: exports.worker({ cache: { enabled: true } }),
+			VinextUncachedResponse: exports.worker({ cache: { enabled: false } })
+		}
+	};
+}
+//#endregion
+export { createWorkersCacheConfig, createWorkersResponseStoreSelfContainedConfig, createWorkersResponseStoreServiceBindingConfig };

package/dist/cache/kv-data-adapter.d.ts

@@ -36,7 +36,7 @@ export type KvDataAdapterOptions = {
  * // wrangler.jsonc
  * {
  *   "kv_namespaces": [
- *     { "binding": "VINEXT_KV_CACHE", "id": "<your-kv-namespace-id>" }
+ *     { "binding": "VINEXT_KV_CACHE" }
  *   ]
  * }
  * ```

package/dist/cache/kv-data-adapter.js

@@ -9,7 +9,7 @@ const DEFAULT_KV_DATA_CACHE_BINDING = "VINEXT_KV_CACHE";
 * // wrangler.jsonc
 * {
 *   "kv_namespaces": [
-*     { "binding": "VINEXT_KV_CACHE", "id": "<your-kv-namespace-id>" }
+*     { "binding": "VINEXT_KV_CACHE" }
 *   ]
 * }
 * ```

package/dist/cache/kv-data-adapter.runtime.js

@@ -1,5 +1,5 @@
-import { ENTRY_PREFIX, createKvKeySpace } from "./kv-key.js";
 import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
+import { ENTRY_PREFIX, createKvKeySpace, resolveKvExpirationTtlSeconds } from "./kv-key.js";
 import { Buffer } from "node:buffer";
 import { getRequestExecutionContext } from "vinext/shims/request-context";
 //#region src/cache/kv-data-adapter.runtime.ts
@@ -20,14 +20,12 @@ import { getRequestExecutionContext } from "vinext/shims/request-context";
 *
 * Wrangler config (wrangler.jsonc):
 *
-*   { "kv_namespaces": [{ "binding": "VINEXT_KV_CACHE", "id": "<your-kv-namespace-id>" }] }
+*   { "kv_namespaces": [{ "binding": "VINEXT_KV_CACHE" }] }
 */
 /** Default KV namespace binding name read from the Worker `env`. */
 const DEFAULT_BINDING = "VINEXT_KV_CACHE";
 /** Prefix used by revalidatePath for path-based tags. */
 const PATH_TAG_PREFIX = "_N_T_";
-/** Max tag length to prevent KV key abuse. */
-const MAX_TAG_LENGTH = 256;
 /** The runtime rejects a lower `cacheTtl` with "Cache TTL must be at least 30". */
 const MIN_KV_CACHE_TTL_SECONDS = 30;
 /** Cloudflare caps a bulk `get()` at 100 keys per call. */
@@ -36,12 +34,12 @@ const KV_BULK_GET_LIMIT = 100;
 const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 /**
 * Validate a cache tag. Returns null if invalid.
-* Note: `:` is rejected because TAG_PREFIX and ENTRY_PREFIX use `:` as a
-* separator — allowing `:` in user tags could cause ambiguous key lookups.
+* Tags may already be header-encoded, so their length is not the raw API tag
+* length. The key builder bounds KV keys and safely handles colon tags.
 */
 function validateTag(tag) {
-	if (typeof tag !== "string" || tag.length === 0 || tag.length > MAX_TAG_LENGTH) return null;
-	if (/[\x00-\x1f\\:]/.test(tag)) return null;
+	if (typeof tag !== "string" || tag.length === 0) return null;
+	if (/[\x00-\x1f\\]/.test(tag)) return null;
 	return tag;
 }
 function readStringArrayField(ctx, field) {
@@ -112,7 +110,7 @@ var KVCacheHandler = class {
 		this.kv = kvNamespace;
 		this.keySpace = createKvKeySpace(options?.appPrefix);
 		this.ctx = options?.ctx;
-		this.ttlSeconds = options?.ttlSeconds ?? 2592e3;
+		this.ttlSeconds = resolveKvExpirationTtlSeconds(options?.ttlSeconds);
 		this._tagCacheTtl = options?.tagCacheTtlMs ?? 5e3;
 		const entryCacheTtl = options?.entryCacheTtlSeconds;
 		this._entryReadOptions = typeof entryCacheTtl === "number" && Number.isFinite(entryCacheTtl) ? { cacheTtl: Math.max(MIN_KV_CACHE_TTL_SECONDS, Math.floor(entryCacheTtl)) } : void 0;
@@ -280,10 +278,10 @@ var KVCacheHandler = class {
 		if (data && "revalidate" in data && typeof data.revalidate === "number") effectiveRevalidate = data.revalidate;
 		if (effectiveRevalidate === 0) return Promise.resolve();
 		const now = Date.now();
-		const revalidateAt = typeof effectiveRevalidate === "number" && effectiveRevalidate > 0 ? now + effectiveRevalidate * 1e3 : null;
+		const revalidateAt = typeof effectiveRevalidate === "number" && effectiveRevalidate > 0 && Number.isFinite(effectiveRevalidate) ? now + effectiveRevalidate * 1e3 : null;
 		const expireAt = typeof effectiveExpire === "number" && effectiveExpire > 0 ? now + effectiveExpire * 1e3 : null;
 		const cacheControl = typeof effectiveRevalidate === "number" ? {
-			revalidate: effectiveRevalidate,
+			revalidate: Number.isFinite(effectiveRevalidate) ? effectiveRevalidate : false,
 			...effectiveExpire === void 0 ? {} : { expire: effectiveExpire },
 			...effectiveStale === void 0 ? {} : { stale: effectiveStale }
 		} : void 0;
@@ -295,7 +293,7 @@ var KVCacheHandler = class {
 			expireAt,
 			cacheControl
 		};
-		const expirationTtl = revalidateAt !== null ? this.ttlSeconds : void 0;
+		const expirationTtl = this.ttlSeconds;
 		const metadata = JSON.stringify({ tags }).length <= 1024 ? { tags } : void 0;
 		return this._put(this._entryKey(key), JSON.stringify(entry), {
 			expirationTtl,
@@ -306,7 +304,7 @@ var KVCacheHandler = class {
 		const tagList = Array.isArray(tags) ? tags : [tags];
 		const now = Date.now();
 		const validTags = tagList.filter((t) => validateTag(t) !== null);
-		await Promise.all(validTags.map((tag) => this.kv.put(this._tagKey(tag), String(now), { expirationTtl: 2592e3 })));
+		await Promise.all(validTags.map((tag) => this.kv.put(this._tagKey(tag), String(now))));
 		const order = ++this._tagCacheOrder;
 		for (const tag of validTags) this._tagCache.set(tag, {
 			timestamp: now,
@@ -423,7 +421,7 @@ function validateCacheEntry(raw) {
 	if (obj.expireAt !== void 0 && obj.expireAt !== null && typeof obj.expireAt !== "number") return null;
 	if (obj.cacheControl !== void 0) {
 		if (!isUnknownRecord(obj.cacheControl)) return null;
-		if (typeof obj.cacheControl.revalidate !== "number") return null;
+		if (typeof obj.cacheControl.revalidate !== "number" && obj.cacheControl.revalidate !== false) return null;
 		if (obj.cacheControl.expire !== void 0 && typeof obj.cacheControl.expire !== "number") return null;
 		if (obj.cacheControl.stale !== void 0 && typeof obj.cacheControl.stale !== "number") return null;
 	}
@@ -432,6 +430,10 @@ function validateCacheEntry(raw) {
 		const value = obj.value;
 		if (typeof value.kind !== "string" || !VALID_KINDS.has(value.kind)) return null;
 	}
+	if (obj.cacheControl?.revalidate === false) obj.cacheControl = {
+		...obj.cacheControl,
+		revalidate: Infinity
+	};
 	return raw;
 }
 /**
@@ -522,7 +524,7 @@ function safeBase64ToArrayBuffer(base64) {
 const createKvDataCacheAdapter = ({ env, options }) => {
 	const binding = options?.binding ?? DEFAULT_BINDING;
 	const namespace = env?.[binding];
-	if (!namespace) throw new Error(`[vinext] The KV data cache adapter requires a \`${binding}\` KV namespace binding.\n  Add it to wrangler.jsonc:\n    "kv_namespaces": [{ "binding": "${binding}", "id": "<your-kv-namespace-id>" }]`);
+	if (!namespace) throw new Error(`[vinext] The KV data cache adapter requires a \`${binding}\` KV namespace binding.\n  Add it to wrangler.jsonc:\n    "kv_namespaces": [{ "binding": "${binding}" }]`);
 	return new KVCacheHandler(namespace, {
 		appPrefix: options?.appPrefix,
 		ttlSeconds: options?.ttlSeconds,

package/dist/cache/kv-key.d.ts

@@ -1,15 +1,18 @@
 //#region src/cache/kv-key.d.ts
 /** Key prefix for cache entries. */
 export declare const ENTRY_PREFIX = "cache:";
+/**
+ * The KV TTL for a configured `ttlSeconds`. A missing, non-finite or
+ * nonpositive value falls back to 30 days. Any other value is truncated to
+ * whole seconds, as the binding does, and kept within the range KV accepts.
+ */
+export declare function resolveKvExpirationTtlSeconds(ttlSeconds: number | undefined): number;
 export type KvKeySpace = {
   /** Prefix shared by every cache entry, including entries with hashed logical keys. */
   entryPrefix: string;
   entryKey(logicalKey: string): string;
   tagKey(tag: string): string;
 };
-/**
- * Create the deterministic key namespace shared by runtime cache operations
- * and deploy-time prerender population.
- */
+/** Create the deterministic key namespace for runtime cache operations. */
 export declare function createKvKeySpace(appPrefix: string | undefined): KvKeySpace;
 //#endregion

package/dist/cache/kv-key.js

@@ -9,6 +9,20 @@ const KV_KEY_MAX_BYTES = 512;
 /** Marker for logical keys that must be hashed to fit in KV. */
 const HASHED_KEY_PREFIX = "__hash:";
 const KV_KEY_ENCODER = new TextEncoder();
+/** KV rejects an expiration TTL below 60 seconds. */
+const MIN_KV_EXPIRATION_TTL_SECONDS = 60;
+/** The Workers KV binding types `expirationTtl` as a signed 32-bit integer. */
+const MAX_KV_EXPIRATION_TTL_SECONDS = 2147483647;
+/** Default KV TTL for cache entries. */
+const DEFAULT_KV_EXPIRATION_TTL_SECONDS = 2592e3;
+/**
+* The KV TTL for a configured `ttlSeconds`. A missing, non-finite or
+* nonpositive value falls back to 30 days. Any other value is truncated to
+* whole seconds, as the binding does, and kept within the range KV accepts.
+*/
+function resolveKvExpirationTtlSeconds(ttlSeconds) {
+	return Math.min(MAX_KV_EXPIRATION_TTL_SECONDS, Math.max(MIN_KV_EXPIRATION_TTL_SECONDS, Math.trunc(typeof ttlSeconds === "number" && Number.isFinite(ttlSeconds) && ttlSeconds > 0 ? ttlSeconds : DEFAULT_KV_EXPIRATION_TTL_SECONDS)));
+}
 function kvKeyByteLength(key) {
 	return KV_KEY_ENCODER.encode(key).length;
 }
@@ -24,13 +38,10 @@ function normalizeAppPrefix(appPrefix) {
 }
 function buildStorageKey(prefix, categoryPrefix, logicalKey) {
 	const key = `${prefix}${categoryPrefix}${logicalKey}`;
-	if (kvKeyByteLength(key) <= KV_KEY_MAX_BYTES) return key;
+	if (!(categoryPrefix === TAG_PREFIX && logicalKey.includes(":")) && kvKeyByteLength(key) <= KV_KEY_MAX_BYTES) return key;
 	return `${prefix}${categoryPrefix}${HASHED_KEY_PREFIX}${fnv1a64(logicalKey)}`;
 }
-/**
-* Create the deterministic key namespace shared by runtime cache operations
-* and deploy-time prerender population.
-*/
+/** Create the deterministic key namespace for runtime cache operations. */
 function createKvKeySpace(appPrefix) {
 	const prefix = normalizeAppPrefix(appPrefix);
 	return {
@@ -40,4 +51,4 @@ function createKvKeySpace(appPrefix) {
 	};
 }
 //#endregion
-export { ENTRY_PREFIX, createKvKeySpace };
+export { ENTRY_PREFIX, createKvKeySpace, resolveKvExpirationTtlSeconds };

package/dist/cache/response-store-adapter.d.ts

@@ -1,5 +1,12 @@
+import { ResponseStoreLocationHint } from "@cloudflare/workers-response-store";
 //#region src/cache/response-store-adapter.d.ts
 export type ResponseStoreAdapterOptions = {
+  /**
+   * Best-effort location for metadata Durable Objects on first creation.
+   * Changing this does not move existing objects and should be treated as a
+   * cache-cold deployment change.
+   */
+  locationHint?: ResponseStoreLocationHint;
   mode?: "self-contained" | "service-binding";
   /** Split version-scoped metadata across this many Durable Objects. */
   shards?: number;
@@ -33,9 +40,7 @@ export declare function responseStoreAdapter(options?: ResponseStoreAdapterOptio
       warmup: "response-store";
     };
   } | {
-    options: {
-      shards: number;
-    };
+    options: Pick<ResponseStoreAdapterOptions, "locationHint" | "shards">;
     adapter: string;
     output: {
       entry: string;
@@ -61,9 +66,7 @@ export declare function responseStoreAdapter(options?: ResponseStoreAdapterOptio
     options?: undefined;
     adapter: string;
   } | {
-    options: {
-      shards: number;
-    };
+    options: Pick<ResponseStoreAdapterOptions, "locationHint" | "shards">;
     adapter: string;
   };
 };

package/dist/cache/response-store-adapter.js

@@ -1,16 +1,35 @@
 import { fileURLToPath } from "node:url";
 //#region src/cache/response-store-adapter.ts
 const CLOUDFLARE_WORKER_ENTRY_ID = "virtual:cloudflare/worker-entry";
+const RESPONSE_STORE_LOCATION_HINTS = {
+	afr: true,
+	apac: true,
+	"apac-ne": true,
+	"apac-se": true,
+	eeur: true,
+	enam: true,
+	me: true,
+	oc: true,
+	sam: true,
+	weur: true,
+	wnam: true
+};
 /**
 * Use Workers Response Store for both vinext response-stage and data caching.
 * Service-binding mode keeps storage in a separate cache Worker. Self-contained
 * mode keeps the same API and loopback in the application Worker.
 */
 function responseStoreAdapter(options = {}) {
+	const locationHint = options.locationHint;
+	if (locationHint !== void 0 && (typeof locationHint !== "string" || !Object.hasOwn(RESPONSE_STORE_LOCATION_HINTS, locationHint))) throw new TypeError("Workers Response Store locationHint is not supported by Cloudflare");
 	const mode = options.mode ?? "service-binding";
 	if (mode !== "service-binding" && mode !== "self-contained") throw new Error(`Unknown Workers Response Store mode: ${String(mode)}`);
 	if (options.shards !== void 0 && (!Number.isSafeInteger(options.shards) || options.shards <= 1)) throw new TypeError("Workers Response Store shards must be an integer greater than 1");
-	const runtimeOptions = options.shards === void 0 ? {} : { options: { shards: options.shards } };
+	const configuredOptions = {
+		...locationHint === void 0 ? {} : { locationHint },
+		...options.shards === void 0 ? {} : { shards: options.shards }
+	};
+	const runtimeOptions = Object.keys(configuredOptions).length === 0 ? {} : { options: configuredOptions };
 	const workerEntry = fileURLToPath(import.meta.resolve(mode === "self-contained" ? "./response-store-adapter.self-contained.worker.js" : "./response-store-adapter.service-binding.worker.js"));
 	const entrypoints = mode === "self-contained" ? "CacheMetadata, ResponseStoreBinding, ResponseStoreRevalidator" : "ResponseStoreClient, ResponseStoreRevalidator";
 	return {