@cloudflare/workers-response-store 0.0.0 → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cloudflare, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# Workers Response Store
+
+`@cloudflare/workers-response-store` is an R2-backed programmatic response store for Cloudflare Workers. The core package has no vinext dependency; the optional vinext adapter lives in `@vinext/cloudflare`.
+
+## Single-Worker mode
+
+A user Worker can define a Response Store once, export its generated entrypoints, and call its methods directly. All of those entrypoints and bindings are deployed together from one Wrangler configuration.
+
+There is no second cache Worker, reverse service binding, circular deployment, or bootstrap deployment. `ctx.exports` supplies both directions inside the same Worker version: the user handler calls the cache-enabled `ResponseStoreBinding`, and that entrypoint calls the user's `ResponseStoreRevalidator` when regeneration is required.
+
+```text
+request ──► user Worker default entrypoint
+               │
+               └── ctx.exports.ResponseStoreBinding({ props })
+                          │
+                          ├── Workers Cache ──► cached Response
+                          └── cache miss / RPC
+                                  ├── response bodies ──► R2
+                                  ├── metadata/indexes ─► SQLite DO
+                                  └── same-Worker ResponseStoreRevalidator.regenerate()
+```
+
+The fixture in `example/worker.ts` demonstrates the integration:
+
+```ts
+import { createWorkersResponseStore } from "@cloudflare/workers-response-store";
+
+const responseStore = createWorkersResponseStore<Env>({
+  regenerate(input, { env, ctx }) {
+    return renderer.fetch(input.request, env, ctx);
+  },
+});
+
+export const { CacheMetadata, ResponseStoreRevalidator, ResponseStoreBinding } =
+  responseStore.entrypoints;
+
+export default {
+  fetch(request) {
+    return responseStore.fetch(request);
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+The Worker configuration enables Workers Cache only for `ResponseStoreBinding`, binds R2 and the SQLite Durable Object to the same Worker, and includes a version-metadata binding so backing data is automatically scoped to the deployed Worker version. `wrangler.jsonc` is the complete fixture configuration.
+
+## Service-binding mode
+
+The library can instead run R2, SQLite, and Workers Cache in a reusable cache Worker. Point that Worker's Wrangler `main` directly at the installed implementation:
+
+```jsonc
+{
+  "main": "./node_modules/@cloudflare/workers-response-store/dist/service.js",
+}
+```
+
+The user Worker has one `RESPONSE_STORE` service binding to the uncached `ResponseStoreService` gateway and a `CF_VERSION_METADATA` version-metadata binding. It still calls the same `fetch`, `put`, `refresh`, and `purge` API. The gateway forwards each operation to its cache-enabled local `ResponseStoreBinding` entrypoint. No custom service-binding props are required. These conventional binding names work directly with the `Env` generated by `wrangler types`.
+
+The user Worker passes its version-pinned `ctx.exports.ResponseStoreRevalidator` binding over RPC with each operation. The cache Worker places that binding in the local cache entrypoint's `ctx.props`, allowing misses, expiry, manual refresh, and background SWR to call the user Worker without a configured reverse service binding. Consequently there is no circular deployment or bootstrap: deploy the cache Worker once, then deploy or update the user Worker once.
+
+```ts
+const responseStore = createWorkersResponseStoreClient<Env>({
+  regenerate(input, { env, ctx }) {
+    return renderer.fetch(input.request, env, ctx);
+  },
+});
+
+export const { ResponseStoreRevalidator, ResponseStoreClient } = responseStore.entrypoints;
+```
+
+The complete pair lives in `example/service-binding`: `wrangler.cache.jsonc` owns the storage and cache entrypoints, while `user-worker.ts` consumes it through `wrangler.user.jsonc`.
+
+## API and storage model
+
+The library exposes `fetch`, `put`, `refresh({ tags, pathPrefixes })`, and `purge({ tags, pathPrefixes, purgeEverything })`. Cache identity is the request pathname plus query string. Response bodies live only in revision-specific R2 objects; SQLite stores metadata, freshness, revalidator descriptors, and tag invalidation timestamps. Explicit refresh and purge operations scan stored entry metadata instead of maintaining a write-heavy tag index.
+
+Framework soft-tag checks query their expiration only after a candidate cache hit and memoize each distinct tag set within the current request. Misses and repeated lookups therefore add no metadata DO request, while every check still reads the authoritative invalidation state directly.
+
+SQLite assigns monotonically increasing revisions and conditionally publishes metadata, so slow writes cannot replace newer writes or resurrect purged entries. User RPC, R2, and purge I/O happen outside SQLite transactions. Stale R2 responses within their SWR window return immediately while `ctx.waitUntil()` runs one claimed regeneration; hard-expired responses are never returned.
+
+The immediate stale return is deliberate. Workers Cache can invoke the cache Worker to fill an empty edge location or update a stale entry, but the Worker does not currently receive the reason for that invocation. The binding therefore cannot wait for regeneration only during an update without also blocking an empty-location read backed by stale R2 data. It returns stale R2 immediately in both cases, regenerates and conditionally publishes the complete response to R2, and allows a later Workers Cache request to promote that revision. This preserves non-blocking SWR but can produce one extra stale response. An invocation-status signal would remove that gap.
+
+R2 custom metadata contains only the response status, creation time, and initial age. The metadata remains tiny relative to R2's 8 KiB object-metadata limit. RPC-transferred response streams are currently materialized in the binding entrypoint before writing them to R2 because the transferred stream lacks the fixed-length marker required by R2's single-part put API.
+
+## Known behavior
+
+- Workers Cache hits bypass the Response Store Worker, R2, and SQLite entirely.
+- A stale R2 entry may be returned once more while its replacement is generated because Workers Cache does not expose whether the invocation is an SWR update or an empty-location fill.
+- Hard-expired entries are never returned; the request waits for regeneration when a revalidator is available.
+- Response bodies are stored only in R2. SQLite stores metadata, tag invalidations, and pending-object cleanup records.
+- Pending R2 objects are retained for one hour before an alarm-driven cleanup pass. Failed deletion is retried without making the active response unavailable.
+- Service-binding loopbacks stay pinned to the user Worker version that supplied the revalidator capability.
+- The store buffers RPC-transferred bodies before R2 writes. Consumers should account for Worker memory limits when choosing maximum response sizes.

package/dist/binding.d.ts

@@ -0,0 +1,115 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+//#region src/binding.d.ts
+type RevalidatorDescriptor = {
+  id: string;
+  args: SerializableValue[];
+};
+export type SerializableValue = null | boolean | number | string | SerializableValue[] | {
+  [key: string]: SerializableValue;
+};
+export type ResponseStorePutOptions = {
+  /** @internal Collapse overlapping framework writes for the same cache key. */
+  coalesce?: boolean;
+  revalidator?: RevalidatorDescriptor;
+  purgeExisting?: boolean;
+};
+export type ResponseStoreRefreshOptions = {
+  tags?: string[];
+  pathPrefixes?: string[];
+};
+export type ResponseStorePurgeOptions = ResponseStoreRefreshOptions & {
+  purgeEverything?: boolean;
+};
+export type ResponseStoreMutationResult = {
+  backingStoreUpdated: boolean;
+  edgePurgeAccepted: boolean;
+};
+export type RevalidationReason = "swr" | "expired" | "missing" | "manual";
+export type RevalidationInput = {
+  request: Request;
+  id: string;
+  args: SerializableValue[];
+  reason: RevalidationReason;
+};
+export type WorkersResponseStore = {
+  fetch(request: Request): Promise<Response>;
+  /** @internal Return the latest purge timestamp for framework-managed cache tags. */
+  getTagExpiration(tags: string[]): Promise<number>;
+  put(request: Request, response: Response, options?: ResponseStorePutOptions): Promise<ResponseStoreMutationResult>;
+  refresh(options: ResponseStoreRefreshOptions): Promise<ResponseStoreMutationResult>;
+  purge(options: ResponseStorePurgeOptions): Promise<ResponseStoreMutationResult>;
+};
+type EntryMetadata = {
+  objectKey: string;
+  statusText: string;
+  responseHeaders: [string, string][];
+  freshUntil: number;
+  swrUntil: number;
+  revalidator: RevalidatorDescriptor | null;
+  cacheTags: string[];
+};
+export type CandidateMetadata = EntryMetadata & {
+  fenceTags: string[];
+};
+export type StoredEntry = EntryMetadata & {
+  keyHash: string;
+  cacheKey: string;
+  activeRevision: number;
+  latestRevision: number;
+};
+export type PurgedEntry = {
+  keyHash: string;
+  cacheKey: string;
+  objectKey: string;
+};
+export type RevalidationService = {
+  regenerate(input: RevalidationInput): Promise<Response>;
+};
+export type WorkersResponseStoreEnv = {
+  CACHE_BODIES: R2Bucket;
+  CACHE_METADATA: DurableObjectNamespace<undefined>;
+  CF_VERSION_METADATA?: WorkerVersionMetadata;
+};
+export type WorkersResponseStoreProps = {
+  versionId?: string;
+  locationHint?: DurableObjectLocationHint;
+  revalidator?: RevalidationService;
+};
+export type ResponseStoreServiceProps = Pick<WorkersResponseStoreProps, "locationHint">;
+export type ResponseStoreServiceInvocation = {
+  versionId: string;
+  revalidator: RevalidationService;
+};
+export type ResponseStoreExecutionContext = Pick<ExecutionContext, "exports">;
+export declare function getWorkersResponseStore(ctx: ResponseStoreExecutionContext, props?: WorkersResponseStoreProps): WorkersResponseStore;
+export declare class ResponseStoreService extends WorkerEntrypoint<WorkersResponseStoreEnv, ResponseStoreServiceProps> {
+  private getStore;
+  read(request: Request, invocation: ResponseStoreServiceInvocation): Promise<Response>;
+  getTagExpiration(tags: string[], invocation: ResponseStoreServiceInvocation): Promise<number>;
+  put(request: Request, response: Response, options: ResponseStorePutOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
+  refresh(options: ResponseStoreRefreshOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
+  purge(options: ResponseStorePurgeOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
+}
+export type ResponseStoreServiceBinding = Pick<ResponseStoreService, "read" | "getTagExpiration" | "put" | "refresh" | "purge">;
+export declare class ResponseStoreBinding extends WorkerEntrypoint<WorkersResponseStoreEnv, WorkersResponseStoreProps> {
+  private getVersionId;
+  private getMetadata;
+  private deriveCacheKey;
+  private purgeEdgeCache;
+  private purgeEdgeCacheByTags;
+  private objectKeyRoot;
+  private objectKeyPrefix;
+  private reserveWrite;
+  private logCleanupFailure;
+  private releaseFailedWrite;
+  private readStoredResponse;
+  private storeResponse;
+  private regenerateEntry;
+  private revalidateEntryInBackground;
+  fetch(request: Request): Promise<Response>;
+  getTagExpiration(tags: string[]): Promise<number>;
+  put(request: Request, response: Response, options?: ResponseStorePutOptions): Promise<ResponseStoreMutationResult>;
+  refresh(options: ResponseStoreRefreshOptions): Promise<ResponseStoreMutationResult>;
+  purge(options: ResponseStorePurgeOptions): Promise<ResponseStoreMutationResult>;
+}
+//#endregion

package/dist/binding.js

@@ -0,0 +1,369 @@
+import { deriveCachePolicy, edgeCacheControl, representationAge } from "./cache-policy.js";
+import { WorkerEntrypoint } from "cloudflare:workers";
+//#region src/binding.ts
+function getWorkersResponseStore(ctx, props = {}) {
+	const binding = Reflect.get(ctx.exports, "ResponseStoreBinding");
+	if (typeof binding !== "function") throw new Error("The ResponseStoreBinding entrypoint is not exported");
+	return binding({ props });
+}
+var ResponseStoreService = class extends WorkerEntrypoint {
+	getStore(invocation) {
+		return getWorkersResponseStore(this.ctx, {
+			...this.ctx.props,
+			...invocation
+		});
+	}
+	read(request, invocation) {
+		return this.getStore(invocation).fetch(request);
+	}
+	getTagExpiration(tags, invocation) {
+		return this.getStore(invocation).getTagExpiration(tags);
+	}
+	put(request, response, options, invocation) {
+		return this.getStore(invocation).put(request, response, options);
+	}
+	refresh(options, invocation) {
+		return this.getStore(invocation).refresh(options);
+	}
+	purge(options, invocation) {
+		return this.getStore(invocation).purge(options);
+	}
+};
+const MISS_HEADERS = {
+	"Cache-Control": "no-store",
+	"Content-Type": "text/plain; charset=utf-8",
+	"X-Workers-Response-Store": "MISS"
+};
+const BACKGROUND_REVALIDATION_LEASE_MS = 3e4;
+const CACHE_PURGE_BATCH_SIZE = 100;
+const MAX_CACHE_TAG_HEADER_BYTES = 16384;
+const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
+	204,
+	205,
+	304
+]);
+const AGE_BASIS_HEADER = "X-Workers-Response-Store-Age-Basis";
+const pendingPuts = /* @__PURE__ */ new Map();
+function* batches(values, size) {
+	for (let offset = 0; offset < values.length; offset += size) yield values.slice(offset, offset + size);
+}
+function metadataInteger(value) {
+	if (!value || !/^\d+$/.test(value)) return;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) ? parsed : void 0;
+}
+function purgeTagForEntry(entry) {
+	return `runtime-cache-${entry.keyHash}`;
+}
+function cacheTagHeader(entry) {
+	const requiredTag = purgeTagForEntry(entry);
+	const tags = [requiredTag];
+	const seen = /* @__PURE__ */ new Set([requiredTag.toLowerCase()]);
+	let headerLength = requiredTag.length;
+	for (const tag of entry.cacheTags) {
+		const normalized = tag.toLowerCase();
+		if (!/^[!-~]+$/.test(tag) || tag.includes(",") || seen.has(normalized)) continue;
+		const addedLength = tag.length + 1;
+		if (headerLength + addedLength > MAX_CACHE_TAG_HEADER_BYTES) continue;
+		tags.push(tag);
+		seen.add(normalized);
+		headerLength += addedLength;
+	}
+	return tags.join(",");
+}
+function cacheTagsFromResponse(response) {
+	return [...new Set((response.headers.get("Cache-Tag") ?? "").split(",").map((tag) => tag.trim()).filter(Boolean))];
+}
+var ResponseStoreBinding = class extends WorkerEntrypoint {
+	getVersionId() {
+		const versionId = this.ctx.props?.versionId ?? this.env.CF_VERSION_METADATA?.id;
+		if (!versionId) throw new Error("Workers Response Store requires a version_metadata binding");
+		return versionId;
+	}
+	getMetadata() {
+		const locationHint = this.ctx.props?.locationHint;
+		return this.env.CACHE_METADATA.getByName(this.getVersionId(), locationHint ? { locationHint } : void 0);
+	}
+	async deriveCacheKey(request) {
+		if (request.method !== "GET") throw new TypeError("Workers Response Store keys must be GET requests");
+		const url = new URL(request.url);
+		const cacheKey = `${url.pathname}${url.search}`;
+		const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(cacheKey));
+		return {
+			cacheKey,
+			keyHash: [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("")
+		};
+	}
+	async purgeEdgeCache(options) {
+		if (!this.ctx.cache) {
+			console.error(JSON.stringify({
+				message: "Workers Response Store cache purge is unavailable",
+				reason: "ctx.cache is absent"
+			}));
+			return false;
+		}
+		try {
+			const result = await this.ctx.cache.purge(options);
+			if (!result.success) throw new Error(result.errors.map(({ code, message }) => `${code}: ${message}`).join(", ") || "Workers Response Store cache purge was rejected");
+			return true;
+		} catch (error) {
+			console.error(JSON.stringify({
+				message: "Workers Response Store cache purge failed",
+				error: error instanceof Error ? error.message : String(error)
+			}));
+			throw error;
+		}
+	}
+	async purgeEdgeCacheByTags(tags) {
+		let accepted = true;
+		for (const batch of batches(tags, CACHE_PURGE_BATCH_SIZE)) if (!await this.purgeEdgeCache({ tags: batch })) accepted = false;
+		return accepted;
+	}
+	objectKeyRoot() {
+		return ["runtime-cache", this.getVersionId()].join("/");
+	}
+	objectKeyPrefix(keyHash) {
+		return `${this.objectKeyRoot()}/${keyHash}`;
+	}
+	async reserveWrite(metadata, keyHash, cacheKey, cacheTags) {
+		return {
+			cacheKey,
+			fenceTags: cacheTags,
+			keyHash,
+			...await metadata.reserveWrite(keyHash, cacheKey, this.objectKeyPrefix(keyHash), Date.now())
+		};
+	}
+	logCleanupFailure(objectKey, error) {
+		console.error(JSON.stringify({
+			message: "Workers Response Store R2 cleanup failed",
+			objectKey,
+			error: error instanceof Error ? error.message : String(error)
+		}));
+	}
+	async releaseFailedWrite(metadata, write) {
+		await metadata.releaseWrite(write.keyHash, write.objectKey, write.claimId).catch((error) => this.logCleanupFailure(write.objectKey, error));
+	}
+	async readStoredResponse(entry, now = Date.now()) {
+		const object = await this.env.CACHE_BODIES.get(entry.objectKey);
+		if (!object) return null;
+		const status = metadataInteger(object.customMetadata?.status);
+		const createdAt = metadataInteger(object.customMetadata?.createdAt);
+		const initialAge = metadataInteger(object.customMetadata?.initialAge);
+		if (status === void 0 || status < 200 || status > 599 || createdAt === void 0 || initialAge === void 0) {
+			await object.body.cancel();
+			return null;
+		}
+		const headers = new Headers(entry.responseHeaders);
+		headers.set(AGE_BASIS_HEADER, `${createdAt}:${initialAge}`);
+		headers.set("Age", String(representationAge(createdAt, initialAge, now)));
+		headers.set("Cloudflare-CDN-Cache-Control", edgeCacheControl(entry.freshUntil, entry.swrUntil, now));
+		headers.set("Cache-Tag", cacheTagHeader(entry));
+		headers.set("X-Workers-Response-Store", now < entry.freshUntil ? "BLOB-FRESH" : "BLOB-STALE");
+		headers.set("X-Workers-Response-Store-Revision", String(entry.activeRevision));
+		headers.set("X-Workers-Response-Store-Binding-Invocation", crypto.randomUUID());
+		const body = NULL_BODY_STATUSES.has(status) ? null : object.body;
+		if (!body) await object.body.cancel();
+		return new Response(body, {
+			status,
+			statusText: entry.statusText,
+			headers
+		});
+	}
+	async storeResponse(metadata, request, response, revalidator, reservation, cacheTags = cacheTagsFromResponse(response)) {
+		const cacheKey = reservation ?? await this.deriveCacheKey(request);
+		const write = reservation ?? await this.reserveWrite(metadata, cacheKey.keyHash, cacheKey.cacheKey, cacheTags);
+		const { keyHash, objectKey, revision } = write;
+		let publication;
+		try {
+			const now = Date.now();
+			const policy = deriveCachePolicy(response.headers, now);
+			const responseHeaders = [...response.headers].filter(([name]) => {
+				const lower = name.toLowerCase();
+				return lower !== "age" && lower !== "cf-cache-status" && lower !== "content-length";
+			});
+			const candidate = {
+				fenceTags: [.../* @__PURE__ */ new Set([...write.fenceTags, ...cacheTags])],
+				objectKey,
+				statusText: response.statusText,
+				responseHeaders,
+				freshUntil: policy.freshUntil,
+				swrUntil: policy.swrUntil,
+				revalidator: revalidator ?? null,
+				cacheTags
+			};
+			const body = response.body ? await response.arrayBuffer() : /* @__PURE__ */ new ArrayBuffer(0);
+			await this.env.CACHE_BODIES.put(objectKey, body, { customMetadata: {
+				status: String(response.status),
+				createdAt: String(policy.createdAt),
+				initialAge: String(policy.initialAge)
+			} });
+			publication = await metadata.publish(keyHash, revision, candidate, write.claimId);
+		} catch (error) {
+			await this.releaseFailedWrite(metadata, write);
+			throw error;
+		}
+		if (!publication.published) return {
+			published: false,
+			entry: publication.entry
+		};
+		return {
+			published: true,
+			entry: publication.entry
+		};
+	}
+	async regenerateEntry(metadata, entry, reason, reservation) {
+		if (!entry.revalidator) throw new Error("Cache entry has no configured revalidator");
+		const cacheRequest = new Request(`https://runtime-cache.invalid${entry.cacheKey}`);
+		const writeReservation = reservation ?? await this.reserveWrite(metadata, entry.keyHash, entry.cacheKey, entry.cacheTags);
+		let response;
+		try {
+			const origin = this.ctx.props?.revalidator ?? Reflect.get(this.ctx.exports, "ResponseStoreRevalidator");
+			if (typeof origin?.regenerate !== "function") throw new Error("The ResponseStoreRevalidator entrypoint is unavailable");
+			response = await origin.regenerate({
+				request: cacheRequest,
+				id: entry.revalidator.id,
+				args: entry.revalidator.args,
+				reason
+			});
+		} catch (error) {
+			await this.releaseFailedWrite(metadata, writeReservation);
+			throw error;
+		}
+		return this.storeResponse(metadata, cacheRequest, response, entry.revalidator, writeReservation);
+	}
+	async revalidateEntryInBackground(metadata, entry) {
+		if (!entry.revalidator) return;
+		const claim = await metadata.claimRevalidation(entry.keyHash, entry.activeRevision, entry.cacheKey, this.objectKeyPrefix(entry.keyHash), Date.now(), BACKGROUND_REVALIDATION_LEASE_MS);
+		if (!claim) return;
+		try {
+			await this.regenerateEntry(metadata, entry, "swr", {
+				cacheKey: entry.cacheKey,
+				claimId: claim.claimId,
+				fenceTags: entry.cacheTags,
+				keyHash: entry.keyHash,
+				objectKey: claim.objectKey,
+				revision: claim.revision
+			});
+		} catch (error) {
+			console.error(JSON.stringify({
+				message: "Workers Response Store SWR regeneration failed",
+				cacheKey: entry.cacheKey,
+				error: error instanceof Error ? error.message : String(error)
+			}));
+		}
+	}
+	async fetch(request) {
+		const { keyHash } = await this.deriveCacheKey(request);
+		const metadata = this.getMetadata();
+		const entry = await metadata.getEntry(keyHash);
+		if (!entry) return new Response("Workers Response Store miss", {
+			status: 404,
+			headers: MISS_HEADERS
+		});
+		const now = Date.now();
+		if (now < entry.swrUntil) {
+			const stored = await this.readStoredResponse(entry, now);
+			if (stored) {
+				if (now < entry.freshUntil) return stored;
+				this.ctx.waitUntil(this.revalidateEntryInBackground(metadata, entry));
+				return stored;
+			}
+		}
+		const regenerated = await this.regenerateEntry(metadata, entry, now >= entry.swrUntil ? "expired" : "missing");
+		if (!regenerated.entry) throw new Error("Regeneration was superseded and no active entry remains");
+		const response = await this.readStoredResponse(regenerated.entry);
+		if (!response) throw new Error("The committed cache body is unavailable");
+		return response;
+	}
+	getTagExpiration(tags) {
+		return this.getMetadata().getTagExpiration(tags);
+	}
+	async put(request, response, options = {}) {
+		const metadata = this.getMetadata();
+		const { cacheKey, keyHash } = await this.deriveCacheKey(request);
+		const cacheTags = cacheTagsFromResponse(response);
+		const pendingPutKey = `${this.getVersionId()}:${keyHash}:${Boolean(options.purgeExisting)}`;
+		let reservation;
+		if (options.coalesce) for (;;) {
+			const pending = pendingPuts.get(pendingPutKey);
+			if (!pending) break;
+			reservation ??= await this.reserveWrite(metadata, keyHash, cacheKey, cacheTags);
+			let result;
+			try {
+				result = await pending;
+			} catch {
+				if (pendingPuts.get(pendingPutKey) === pending) pendingPuts.delete(pendingPutKey);
+				continue;
+			}
+			if (result.published && result.entry) {
+				const objectKey = reservation.objectKey;
+				await metadata.finishPendingObjects([objectKey]).catch((error) => this.logCleanupFailure(objectKey, error));
+				response.body?.cancel().catch(() => {});
+				return {
+					backingStoreUpdated: true,
+					edgePurgeAccepted: options.purgeExisting ? await this.purgeEdgeCacheByTags([purgeTagForEntry(result.entry)]) : true
+				};
+			}
+			if (pendingPuts.get(pendingPutKey) === pending) pendingPuts.delete(pendingPutKey);
+		}
+		const write = (async () => {
+			reservation ??= await this.reserveWrite(metadata, keyHash, cacheKey, cacheTags);
+			return this.storeResponse(metadata, request, response, options.revalidator, reservation, cacheTags);
+		})();
+		if (options.coalesce) pendingPuts.set(pendingPutKey, write);
+		try {
+			const result = await write;
+			if (!result.published || !result.entry) return {
+				backingStoreUpdated: false,
+				edgePurgeAccepted: false
+			};
+			return {
+				backingStoreUpdated: true,
+				edgePurgeAccepted: options.purgeExisting ? await this.purgeEdgeCacheByTags([purgeTagForEntry(result.entry)]) : true
+			};
+		} finally {
+			if (options.coalesce && pendingPuts.get(pendingPutKey) === write) pendingPuts.delete(pendingPutKey);
+		}
+	}
+	async refresh(options) {
+		if (!options.tags?.length && !options.pathPrefixes?.length) throw new TypeError("refresh() requires tags or pathPrefixes");
+		const metadata = this.getMetadata();
+		const candidates = await metadata.reserveRefresh(options, this.objectKeyRoot(), Date.now());
+		if (candidates.length === 0) return {
+			backingStoreUpdated: false,
+			edgePurgeAccepted: false
+		};
+		const settled = await Promise.allSettled(candidates.map(async ({ entry, reservation }) => {
+			const result = await this.regenerateEntry(metadata, entry, "manual", reservation ? {
+				cacheKey: entry.cacheKey,
+				fenceTags: entry.cacheTags,
+				keyHash: entry.keyHash,
+				...reservation
+			} : void 0);
+			return result.published ? result.entry : null;
+		}));
+		const refreshed = [];
+		const failures = [];
+		for (const result of settled) if (result.status === "rejected") failures.push(result.reason);
+		else if (result.value) refreshed.push(result.value);
+		const edgePurgeAccepted = refreshed.length ? await this.purgeEdgeCacheByTags(refreshed.map((entry) => purgeTagForEntry(entry))) : false;
+		if (failures.length) throw new AggregateError(failures, "One or more cache entries failed to refresh");
+		return {
+			backingStoreUpdated: refreshed.length === candidates.length,
+			edgePurgeAccepted
+		};
+	}
+	async purge(options) {
+		if (!options.purgeEverything && !options.tags?.length && !options.pathPrefixes?.length) throw new TypeError("purge() requires tags, pathPrefixes, or purgeEverything");
+		const purged = await this.getMetadata().purgeMatching(options);
+		let edgePurgeAccepted = true;
+		if (options.purgeEverything) edgePurgeAccepted = await this.purgeEdgeCache({ purgeEverything: true });
+		else if (purged.length) edgePurgeAccepted = await this.purgeEdgeCacheByTags(purged.map((entry) => purgeTagForEntry(entry)));
+		return {
+			backingStoreUpdated: true,
+			edgePurgeAccepted
+		};
+	}
+};
+//#endregion
+export { ResponseStoreBinding, ResponseStoreService, getWorkersResponseStore };

package/dist/cache-policy.d.ts

@@ -0,0 +1,11 @@
+//#region src/cache-policy.d.ts
+export type CachePolicy = {
+  createdAt: number;
+  initialAge: number;
+  freshUntil: number;
+  swrUntil: number;
+};
+export declare function deriveCachePolicy(headers: Headers, now?: number): CachePolicy;
+export declare function representationAge(createdAt: number, initialAge: number, now?: number): number;
+export declare function edgeCacheControl(freshUntil: number, swrUntil: number, now?: number): string;
+//#endregion

package/dist/cache-policy.js

@@ -0,0 +1,37 @@
+//#region src/cache-policy.ts
+function parseSeconds(value) {
+	if (value === void 0) return;
+	const match = /^(?:"(\d+)"|(\d+))$/.exec(value);
+	if (!match) return;
+	const parsed = Number(match[1] ?? match[2]);
+	return Number.isSafeInteger(parsed) ? parsed : void 0;
+}
+function deriveCachePolicy(headers, now = Date.now()) {
+	const cacheControl = headers.get("Cloudflare-CDN-Cache-Control") ?? headers.get("CDN-Cache-Control") ?? headers.get("Cache-Control");
+	const directives = /* @__PURE__ */ new Map();
+	for (const part of cacheControl?.split(",") ?? []) {
+		const [rawName, ...rawValue] = part.trim().split("=");
+		if (!rawName) continue;
+		directives.set(rawName.toLowerCase(), rawValue.length ? rawValue.join("=").trim() : void 0);
+	}
+	const cacheStorageForbidden = directives.has("no-store") || directives.has("private");
+	const staleServingForbidden = directives.has("s-maxage") || directives.has("must-revalidate") || directives.has("proxy-revalidate");
+	const maxAge = cacheStorageForbidden || directives.has("no-cache") ? 0 : parseSeconds(directives.get("s-maxage")) ?? parseSeconds(directives.get("max-age")) ?? 0;
+	const initialAge = parseSeconds(headers.get("Age") ?? void 0) ?? 0;
+	const freshUntil = now + Math.max(0, maxAge - initialAge) * 1e3;
+	return {
+		createdAt: now,
+		initialAge,
+		freshUntil,
+		swrUntil: freshUntil + (cacheStorageForbidden || staleServingForbidden ? 0 : parseSeconds(directives.get("stale-while-revalidate")) ?? 0) * 1e3
+	};
+}
+function representationAge(createdAt, initialAge, now = Date.now()) {
+	return initialAge + Math.max(0, Math.floor((now - createdAt) / 1e3));
+}
+function edgeCacheControl(freshUntil, swrUntil, now = Date.now()) {
+	if (now < freshUntil) return `max-age=${Math.max(0, Math.ceil((freshUntil - now) / 1e3))}, stale-while-revalidate=${Math.max(0, Math.ceil((swrUntil - freshUntil) / 1e3))}`;
+	return `max-age=0, stale-while-revalidate=${Math.max(0, Math.ceil((swrUntil - now) / 1e3))}`;
+}
+//#endregion
+export { deriveCachePolicy, edgeCacheControl, representationAge };