@vinext/cloudflare 1.0.0-beta.9 → 1.0.0

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,7 +20,7 @@ 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";
@@ -112,7 +112,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 +280,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 +295,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 +306,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 +423,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 +432,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 +526,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;
 }
@@ -27,10 +41,7 @@ function buildStorageKey(prefix, categoryPrefix, logicalKey) {
 	if (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 {