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

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { ResponseStoreBinding, ResponseStoreMutationResult, ResponseStorePurgeOptions, ResponseStorePutOptions, ResponseStoreRefreshOptions, RevalidationInput, RevalidationReason, RevalidationService, SerializableValue, WorkersResponseStore, WorkersResponseStoreEnv } from "./binding.js";
+import { CacheMetadata } from "./metadata-do.js";
+import { WorkerEntrypoint } from "cloudflare:workers";
+//#region src/index.d.ts
+export type ResponseStoreRevalidationContext<Env> = {
+  env: Env;
+  ctx: ExecutionContext;
+};
+export type ResponseStoreRevalidatorEntrypoint<Env = WorkersResponseStoreEnv> = new (ctx: ExecutionContext, env: Env) => WorkerEntrypoint<Env> & RevalidationService;
+type WorkersResponseStoreDefinition<Env extends WorkersResponseStoreEnv = WorkersResponseStoreEnv> = WorkersResponseStore & {
+  entrypoints: {
+    CacheMetadata: typeof CacheMetadata;
+    ResponseStoreRevalidator: ResponseStoreRevalidatorEntrypoint<Env>;
+    ResponseStoreBinding: typeof ResponseStoreBinding;
+  };
+};
+type WorkersResponseStoreClientDefinition<Env> = WorkersResponseStore & {
+  entrypoints: {
+    ResponseStoreRevalidator: ResponseStoreRevalidatorEntrypoint<Env>;
+    ResponseStoreClient: new (ctx: ExecutionContext, env: Env) => WorkerEntrypoint<Env> & WorkersResponseStore;
+  };
+};
+export type ResponseStoreClientEntrypoint<Env = WorkersResponseStoreClientEnv> = new (ctx: ExecutionContext, env: Env) => WorkerEntrypoint<Env> & WorkersResponseStore;
+export type WorkersResponseStoreOptions<Env> = {
+  regenerate(input: RevalidationInput, context: ResponseStoreRevalidationContext<Env>): Response | Promise<Response>;
+};
+export declare function createWorkersResponseStore<Env extends WorkersResponseStoreEnv = WorkersResponseStoreEnv>(options: WorkersResponseStoreOptions<Env>): WorkersResponseStoreDefinition<Env>;
+export type WorkersResponseStoreClientEnv = {
+  RESPONSE_STORE: Service;
+  CF_VERSION_METADATA: WorkerVersionMetadata;
+};
+export declare function createWorkersResponseStoreClient<Env extends WorkersResponseStoreClientEnv = WorkersResponseStoreClientEnv>(options: WorkersResponseStoreOptions<Env>): WorkersResponseStoreClientDefinition<Env>;
+//#endregion
+export type { ResponseStoreMutationResult, ResponseStorePurgeOptions, ResponseStorePutOptions, ResponseStoreRefreshOptions, RevalidationInput, RevalidationReason, SerializableValue, WorkersResponseStore, WorkersResponseStoreEnv };

package/dist/index.js

@@ -0,0 +1,82 @@
+import { ResponseStoreBinding, getWorkersResponseStore } from "./binding.js";
+import { CacheMetadata } from "./metadata-do.js";
+import { WorkerEntrypoint, exports } from "cloudflare:workers";
+//#region src/index.ts
+function createRevalidatorEntrypoint(options) {
+	return class ResponseStoreRevalidator extends WorkerEntrypoint {
+		async regenerate(input) {
+			return options.regenerate(input, {
+				env: this.env,
+				ctx: this.ctx
+			});
+		}
+	};
+}
+function createStoreFacade(getStore) {
+	return {
+		fetch: (request) => getStore().fetch(request),
+		getTagExpiration: (tags) => getStore().getTagExpiration(tags),
+		put: (request, response, options) => getStore().put(request, response, options),
+		refresh: (options) => getStore().refresh(options),
+		purge: (options) => getStore().purge(options)
+	};
+}
+function createWorkersResponseStore(options) {
+	const ResponseStoreRevalidator = createRevalidatorEntrypoint(options);
+	const getStore = () => getWorkersResponseStore({ exports });
+	return {
+		entrypoints: {
+			CacheMetadata,
+			ResponseStoreRevalidator,
+			ResponseStoreBinding
+		},
+		...createStoreFacade(getStore)
+	};
+}
+function createWorkersResponseStoreClient(options) {
+	const ResponseStoreRevalidator = createRevalidatorEntrypoint(options);
+	class ResponseStoreClient extends WorkerEntrypoint {
+		get service() {
+			return this.env.RESPONSE_STORE;
+		}
+		getInvocation() {
+			const factory = Reflect.get(this.ctx.exports, "ResponseStoreRevalidator");
+			if (typeof factory !== "function") throw new Error("The ResponseStoreRevalidator entrypoint is not exported");
+			const versionId = this.env.CF_VERSION_METADATA.id;
+			if (!versionId) throw new Error("Workers Response Store requires the user Worker version ID");
+			return {
+				versionId,
+				revalidator: factory({ props: {} })
+			};
+		}
+		fetch(request) {
+			return this.service.read(request, this.getInvocation());
+		}
+		getTagExpiration(tags) {
+			return this.service.getTagExpiration(tags, this.getInvocation());
+		}
+		put(request, response, putOptions = {}) {
+			return this.service.put(request, response, putOptions, this.getInvocation());
+		}
+		refresh(refreshOptions) {
+			return this.service.refresh(refreshOptions, this.getInvocation());
+		}
+		purge(purgeOptions) {
+			return this.service.purge(purgeOptions, this.getInvocation());
+		}
+	}
+	const getClient = () => {
+		const factory = Reflect.get(exports, "ResponseStoreClient");
+		if (typeof factory !== "function") throw new Error("The ResponseStoreClient entrypoint is not exported");
+		return factory({ props: {} });
+	};
+	return {
+		entrypoints: {
+			ResponseStoreRevalidator,
+			ResponseStoreClient
+		},
+		...createStoreFacade(getClient)
+	};
+}
+//#endregion
+export { createWorkersResponseStore, createWorkersResponseStoreClient };

package/dist/metadata-do.d.ts

@@ -0,0 +1,65 @@
+import { CandidateMetadata, PurgedEntry, ResponseStorePurgeOptions, ResponseStoreRefreshOptions, StoredEntry } from "./binding.js";
+import { DurableObject } from "cloudflare:workers";
+//#region src/metadata-do.d.ts
+type RevalidationClaim = {
+  claimId: string;
+  objectKey: string;
+  revision: number;
+};
+type PublicationResult = {
+  entry: StoredEntry | null;
+  published: boolean;
+};
+type WriteReservation = {
+  objectKey: string;
+  revision: number;
+};
+type RefreshCandidate = {
+  entry: StoredEntry;
+  reservation?: Pick<WriteReservation, "objectKey" | "revision">;
+};
+export type CacheMetadataStub = DurableObjectStub & {
+  reserveWrite(keyHash: string, cacheKey: string, objectKeyPrefix: string, createdAt: number): Promise<WriteReservation>;
+  claimRevalidation(keyHash: string, activeRevision: number, cacheKey: string, objectKeyPrefix: string, now: number, leaseMs: number): Promise<RevalidationClaim | null>;
+  trackPendingObject(objectKey: string, createdAt: number): Promise<void>;
+  trackPendingObjects(objectKeys: string[], createdAt: number): Promise<void>;
+  releaseWrite(keyHash: string, objectKey: string, claimId?: string): Promise<void>;
+  finishPendingObjects(objectKeys: string[]): Promise<void>;
+  listExpiredPendingObjects(cutoff: number, limit: number): Promise<string[]>;
+  sweepExpiredPendingObjects(cutoff?: number): Promise<number>;
+  publish(keyHash: string, revision: number, metadata: CandidateMetadata, claimId?: string): Promise<PublicationResult>;
+  getEntry(keyHash: string): Promise<StoredEntry | null>;
+  getTagExpiration(tags: string[]): Promise<number>;
+  reserveRefresh(options: ResponseStoreRefreshOptions, objectKeyRoot: string, createdAt: number): Promise<RefreshCandidate[]>;
+  purgeMatching(options: ResponseStorePurgeOptions): Promise<PurgedEntry[]>;
+  inspect(): Promise<StoredEntry[]>;
+};
+type CacheMetadataEnv = {
+  CACHE_BODIES: R2Bucket;
+};
+export declare class CacheMetadata extends DurableObject<CacheMetadataEnv> {
+  private cleanupAlarmKnown;
+  constructor(ctx: DurableObjectState, env: CacheMetadataEnv);
+  private ensureCleanupAlarm;
+  private maintainCleanupAlarm;
+  private findMatchingEntryRows;
+  trackPendingObjects(objectKeys: string[], createdAt: number): Promise<void>;
+  trackPendingObject(objectKey: string, createdAt: number): Promise<void>;
+  releaseWrite(keyHash: string, objectKey: string, claimId?: string): void;
+  finishPendingObjects(objectKeys: string[]): void;
+  private deleteTrackedObjects;
+  listExpiredPendingObjects(cutoff: number, limit: number): string[];
+  sweepExpiredPendingObjects(cutoff?: number): Promise<number>;
+  alarm(): Promise<void>;
+  claimRevalidation(keyHash: string, activeRevision: number, cacheKey: string, objectKeyPrefix: string, now: number, leaseMs: number): Promise<RevalidationClaim | null>;
+  private reserveRevision;
+  reserveWrite(keyHash: string, cacheKey: string, objectKeyPrefix: string, createdAt: number): Promise<WriteReservation>;
+  publish(keyHash: string, revision: number, metadata: CandidateMetadata, claimId?: string): Promise<PublicationResult>;
+  getEntry(keyHash: string): StoredEntry | null;
+  private getTagInvalidationMaximum;
+  getTagExpiration(tags: string[]): number;
+  reserveRefresh(options: ResponseStoreRefreshOptions, objectKeyRoot: string, createdAt: number): Promise<RefreshCandidate[]>;
+  purgeMatching(options: ResponseStorePurgeOptions): Promise<PurgedEntry[]>;
+  inspect(): StoredEntry[];
+}
+//#endregion

package/dist/metadata-do.js

@@ -0,0 +1,447 @@
+import { DurableObject } from "cloudflare:workers";
+//#region src/metadata-do.ts
+const MAX_SQL_PARAMETERS = 100;
+const R2_DELETE_BATCH_SIZE = 1e3;
+const ORPHAN_RETENTION_MS = 36e5;
+const ORPHAN_CLEANUP_LIMIT = 100;
+const ORPHAN_CLEANUP_RETRY_MS = 6e4;
+function normalizeTags(tags) {
+	const normalized = tags.map((tag) => tag.trim().toLowerCase()).filter(Boolean);
+	return [...new Set(normalized)];
+}
+function* batches(values, size) {
+	for (let offset = 0; offset < values.length; offset += size) yield values.slice(offset, offset + size);
+}
+function storedEntryFromRow(row) {
+	if (row.tombstoned || row.active_revision === null || row.object_key === null || row.response_headers === null || row.fresh_until === null || row.swr_until === null) return null;
+	return {
+		keyHash: row.key_hash,
+		cacheKey: row.cache_key,
+		activeRevision: row.active_revision,
+		latestRevision: row.latest_revision,
+		objectKey: row.object_key,
+		statusText: row.status_text ?? "",
+		responseHeaders: JSON.parse(row.response_headers),
+		freshUntil: row.fresh_until,
+		swrUntil: row.swr_until,
+		revalidator: row.revalidator_id === null ? null : {
+			id: row.revalidator_id,
+			args: JSON.parse(row.revalidator_args ?? "[]")
+		},
+		cacheTags: JSON.parse(row.cache_tags ?? "[]")
+	};
+}
+function storedEntriesFromRows(rows) {
+	const entries = [];
+	for (const row of rows) {
+		const entry = storedEntryFromRow(row);
+		if (entry) entries.push(entry);
+	}
+	return entries;
+}
+var CacheMetadata = class extends DurableObject {
+	cleanupAlarmKnown = false;
+	constructor(ctx, env) {
+		super(ctx, env);
+		ctx.blockConcurrencyWhile(async () => {
+			ctx.storage.sql.exec(`
+        CREATE TABLE IF NOT EXISTS entries (
+          key_hash TEXT PRIMARY KEY,
+          cache_key TEXT NOT NULL,
+          active_revision INTEGER,
+          latest_revision INTEGER NOT NULL,
+          object_key TEXT,
+          status_text TEXT,
+          response_headers TEXT,
+          fresh_until INTEGER,
+          swr_until INTEGER,
+          revalidator_id TEXT,
+          revalidator_args TEXT,
+          cache_tags TEXT,
+          tombstoned INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX IF NOT EXISTS entries_cache_key ON entries(cache_key);
+        CREATE TABLE IF NOT EXISTS revalidation_claims (
+          key_hash TEXT PRIMARY KEY,
+          active_revision INTEGER NOT NULL,
+          revision INTEGER NOT NULL,
+          claim_id TEXT NOT NULL,
+          claimed_at INTEGER NOT NULL,
+          expires_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS tag_invalidations (
+          tag TEXT PRIMARY KEY,
+          invalidated_at INTEGER NOT NULL,
+          invalidation_sequence INTEGER NOT NULL DEFAULT 0
+        ) WITHOUT ROWID;
+        CREATE TABLE IF NOT EXISTS metadata_schema_migrations (
+          version INTEGER PRIMARY KEY
+        );
+        CREATE TABLE IF NOT EXISTS metadata_state (
+          singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+          tag_invalidation_sequence INTEGER NOT NULL
+        );
+        INSERT OR IGNORE INTO metadata_state (singleton, tag_invalidation_sequence) VALUES (1, 0);
+        CREATE TABLE IF NOT EXISTS pending_objects (
+          object_key TEXT PRIMARY KEY,
+          invalidation_sequence INTEGER NOT NULL DEFAULT 0,
+          publishable INTEGER NOT NULL DEFAULT 1,
+          created_at INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS pending_objects_created_at ON pending_objects(created_at);
+      `);
+			ctx.storage.transactionSync(() => {
+				const migrations = new Set(ctx.storage.sql.exec("SELECT version FROM metadata_schema_migrations WHERE version IN (2, 3)").toArray().map(({ version }) => version));
+				if (migrations.size === 2) return;
+				const schemas = ctx.storage.sql.exec(`SELECT name, sql FROM sqlite_schema
+            WHERE type = 'table' AND name IN ('tag_invalidations', 'pending_objects')`).toArray();
+				if (!migrations.has(2) && !schemas.find(({ name }) => name === "tag_invalidations")?.sql.includes("invalidation_sequence")) ctx.storage.sql.exec("ALTER TABLE tag_invalidations ADD COLUMN invalidation_sequence INTEGER NOT NULL DEFAULT 0");
+				if (!migrations.has(2) && !schemas.find(({ name }) => name === "pending_objects")?.sql.includes("invalidation_sequence")) ctx.storage.sql.exec("ALTER TABLE pending_objects ADD COLUMN invalidation_sequence INTEGER NOT NULL DEFAULT 0");
+				if (!migrations.has(2)) ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (2)");
+				if (!migrations.has(3)) {
+					if (!schemas.find(({ name }) => name === "pending_objects")?.sql.includes("publishable")) ctx.storage.sql.exec("ALTER TABLE pending_objects ADD COLUMN publishable INTEGER NOT NULL DEFAULT 1");
+					ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (3)");
+				}
+			});
+		});
+	}
+	async ensureCleanupAlarm(createdAt) {
+		if (this.cleanupAlarmKnown) return;
+		if (await this.ctx.storage.getAlarm() === null) await this.ctx.storage.setAlarm(createdAt + ORPHAN_RETENTION_MS);
+		this.cleanupAlarmKnown = true;
+	}
+	async maintainCleanupAlarm(createdAt) {
+		await this.ensureCleanupAlarm(createdAt).catch((error) => {
+			console.error(JSON.stringify({
+				message: "Workers Response Store cleanup alarm update failed",
+				error: error instanceof Error ? error.message : String(error)
+			}));
+		});
+	}
+	findMatchingEntryRows(options, includePending = false) {
+		const rows = this.ctx.storage.sql.exec(includePending ? `SELECT * FROM entries
+            WHERE (tombstoned = 0 AND active_revision IS NOT NULL)
+              OR active_revision IS NULL OR latest_revision > active_revision` : "SELECT * FROM entries WHERE tombstoned = 0 AND active_revision IS NOT NULL").toArray();
+		if (options.purgeEverything) return rows;
+		const tags = new Set(normalizeTags(options.tags ?? []));
+		const prefixes = options.pathPrefixes ?? [];
+		return rows.filter((row) => prefixes.some((prefix) => row.cache_key.startsWith(prefix)) || normalizeTags(JSON.parse(row.cache_tags ?? "[]")).some((tag) => tags.has(tag)));
+	}
+	async trackPendingObjects(objectKeys, createdAt) {
+		if (!objectKeys.length) return;
+		this.ctx.storage.transactionSync(() => {
+			for (const batch of batches(objectKeys, MAX_SQL_PARAMETERS / 2)) {
+				const values = batch.flatMap((objectKey) => [objectKey, createdAt]);
+				this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
+            (object_key, created_at, publishable) VALUES ${batch.map(() => "(?, ?, 0)").join(", ")}`, ...values);
+			}
+		});
+		await this.ensureCleanupAlarm(createdAt);
+	}
+	trackPendingObject(objectKey, createdAt) {
+		return this.trackPendingObjects([objectKey], createdAt);
+	}
+	releaseWrite(keyHash, objectKey, claimId) {
+		this.ctx.storage.transactionSync(() => {
+			this.ctx.storage.sql.exec("UPDATE pending_objects SET created_at = 0, publishable = 0 WHERE object_key = ?", objectKey);
+			if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
+		});
+	}
+	finishPendingObjects(objectKeys) {
+		if (!objectKeys.length) return;
+		this.ctx.storage.transactionSync(() => {
+			for (const batch of batches(objectKeys, MAX_SQL_PARAMETERS)) this.ctx.storage.sql.exec(`DELETE FROM pending_objects WHERE object_key IN (${batch.map(() => "?").join(", ")})`, ...batch);
+		});
+	}
+	async deleteTrackedObjects(objectKeys) {
+		for (const batch of batches(objectKeys, R2_DELETE_BATCH_SIZE)) try {
+			await this.env.CACHE_BODIES.delete(batch);
+			this.finishPendingObjects(batch);
+		} catch (error) {
+			for (const retryBatch of batches(batch, MAX_SQL_PARAMETERS)) this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
+              (object_key, created_at, publishable) VALUES ${retryBatch.map(() => "(?, 0, 0)").join(", ")}`, ...retryBatch);
+			console.error(JSON.stringify({
+				message: "Workers Response Store R2 cleanup failed",
+				objectKeys: batch,
+				error: error instanceof Error ? error.message : String(error)
+			}));
+			try {
+				await this.ctx.storage.setAlarm(Date.now() + ORPHAN_CLEANUP_RETRY_MS);
+				this.cleanupAlarmKnown = true;
+			} catch (alarmError) {
+				console.error(JSON.stringify({
+					message: "Workers Response Store cleanup retry scheduling failed",
+					error: alarmError instanceof Error ? alarmError.message : String(alarmError)
+				}));
+			}
+		}
+	}
+	listExpiredPendingObjects(cutoff, limit) {
+		return this.ctx.storage.sql.exec(`SELECT pending_objects.object_key FROM pending_objects
+        LEFT JOIN entries
+          ON entries.object_key = pending_objects.object_key AND entries.tombstoned = 0
+        WHERE pending_objects.created_at <= ? AND entries.object_key IS NULL
+        ORDER BY pending_objects.created_at
+        LIMIT ?`, cutoff, limit).toArray().map((row) => row.object_key);
+	}
+	async sweepExpiredPendingObjects(cutoff = Date.now() - ORPHAN_RETENTION_MS) {
+		this.cleanupAlarmKnown = false;
+		const rows = this.ctx.storage.sql.exec(`SELECT pending_objects.object_key, pending_objects.created_at,
+          pending_objects.publishable,
+          entries.object_key IS NOT NULL AS active
+        FROM pending_objects
+        LEFT JOIN entries
+          ON entries.object_key = pending_objects.object_key AND entries.tombstoned = 0
+        ORDER BY pending_objects.created_at
+        LIMIT ?`, 101).toArray();
+		const batch = rows.slice(0, ORPHAN_CLEANUP_LIMIT);
+		const activeObjectKeys = batch.filter(({ active }) => active).map(({ object_key }) => object_key);
+		const expired = batch.filter(({ active, created_at }) => !active && created_at <= cutoff);
+		const reservations = expired.filter(({ publishable }) => publishable === 1);
+		const cleanupObjectKeys = expired.filter(({ publishable }) => publishable === 0).map(({ object_key }) => object_key);
+		const fencedAt = Date.now();
+		const expiredObjectKeys = expired.map(({ object_key }) => object_key);
+		this.finishPendingObjects(activeObjectKeys);
+		for (const reservationBatch of batches(reservations, 99)) this.ctx.storage.sql.exec(`UPDATE pending_objects SET created_at = ?, publishable = 0
+        WHERE object_key IN (${reservationBatch.map(() => "?").join(", ")})`, fencedAt, ...reservationBatch.map(({ object_key }) => object_key));
+		if (expiredObjectKeys.length) {
+			await this.env.CACHE_BODIES.delete(expiredObjectKeys);
+			this.finishPendingObjects(cleanupObjectKeys);
+		}
+		const next = batch.find(({ active, created_at }) => !active && created_at > cutoff);
+		if (!next && rows.length > ORPHAN_CLEANUP_LIMIT) {
+			await this.ctx.storage.setAlarm(Date.now());
+			this.cleanupAlarmKnown = true;
+		} else if (next || reservations.length) await this.ensureCleanupAlarm(Math.min(next?.created_at ?? Number.POSITIVE_INFINITY, fencedAt));
+		return expiredObjectKeys.length;
+	}
+	async alarm() {
+		try {
+			await this.sweepExpiredPendingObjects();
+		} catch (error) {
+			console.error(JSON.stringify({
+				message: "Workers Response Store orphan cleanup failed",
+				error: error instanceof Error ? error.message : String(error)
+			}));
+			await this.ctx.storage.setAlarm(Date.now() + ORPHAN_CLEANUP_RETRY_MS);
+			this.cleanupAlarmKnown = true;
+		}
+	}
+	async claimRevalidation(keyHash, activeRevision, cacheKey, objectKeyPrefix, now, leaseMs) {
+		const claim = this.ctx.storage.transactionSync(() => {
+			const entry = this.ctx.storage.sql.exec(`SELECT entries.active_revision, entries.latest_revision, entries.tombstoned,
+            revalidation_claims.active_revision AS claim_active_revision,
+            revalidation_claims.expires_at AS claim_expires_at
+          FROM entries
+          LEFT JOIN revalidation_claims ON revalidation_claims.key_hash = entries.key_hash
+          WHERE entries.key_hash = ? AND entries.cache_key = ?`, keyHash, cacheKey).toArray()[0];
+			if (entry?.tombstoned || entry?.active_revision !== activeRevision) return null;
+			if (entry.claim_active_revision === activeRevision && (entry.claim_expires_at ?? 0) > now) return null;
+			const revision = entry.latest_revision + 1;
+			const claimId = crypto.randomUUID();
+			const objectKey = `${objectKeyPrefix}/${revision}`;
+			this.ctx.storage.sql.exec("UPDATE entries SET latest_revision = ? WHERE key_hash = ? AND active_revision = ?", revision, keyHash, activeRevision);
+			this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO revalidation_claims
+          (key_hash, active_revision, revision, claim_id, claimed_at, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?)`, keyHash, activeRevision, revision, claimId, now, now + leaseMs);
+			this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
+          (object_key, created_at, invalidation_sequence)
+        VALUES (?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))`, objectKey, now);
+			return {
+				claimId,
+				objectKey,
+				revision
+			};
+		});
+		if (claim) await this.ensureCleanupAlarm(now);
+		return claim;
+	}
+	reserveRevision(keyHash, cacheKey, current) {
+		const revision = (current?.latest_revision ?? 0) + 1;
+		if (!current) this.ctx.storage.sql.exec("INSERT INTO entries (key_hash, cache_key, latest_revision, tombstoned) VALUES (?, ?, ?, 1)", keyHash, cacheKey, revision);
+		else this.ctx.storage.sql.exec("UPDATE entries SET cache_key = ?, latest_revision = ? WHERE key_hash = ?", cacheKey, revision, keyHash);
+		return revision;
+	}
+	async reserveWrite(keyHash, cacheKey, objectKeyPrefix, createdAt) {
+		const reservation = this.ctx.storage.transactionSync(() => {
+			const current = this.ctx.storage.sql.exec("SELECT active_revision, latest_revision FROM entries WHERE key_hash = ?", keyHash).toArray()[0];
+			const revision = this.reserveRevision(keyHash, cacheKey, current);
+			const objectKey = `${objectKeyPrefix}/${revision}`;
+			this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
+          (object_key, created_at, invalidation_sequence)
+        VALUES (?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))`, objectKey, createdAt);
+			return {
+				objectKey,
+				revision
+			};
+		});
+		await this.ensureCleanupAlarm(createdAt);
+		return reservation;
+	}
+	async publish(keyHash, revision, metadata, claimId) {
+		const { cleanupObjectKey, result } = this.ctx.storage.transactionSync(() => {
+			const current = this.ctx.storage.sql.exec(`SELECT entries.*,
+            revalidation_claims.active_revision AS claim_active_revision,
+            revalidation_claims.claim_id AS claim_id,
+            revalidation_claims.revision AS claim_revision,
+            pending_objects.invalidation_sequence AS pending_invalidation_sequence,
+            pending_objects.publishable AS pending_publishable,
+            metadata_state.tag_invalidation_sequence AS current_invalidation_sequence
+          FROM entries
+          CROSS JOIN metadata_state
+          LEFT JOIN pending_objects ON pending_objects.object_key = ?
+          LEFT JOIN revalidation_claims ON revalidation_claims.key_hash = entries.key_hash
+          WHERE entries.key_hash = ?`, metadata.objectKey, keyHash).toArray()[0];
+			if (!current || current.pending_invalidation_sequence === null || current.pending_invalidation_sequence === void 0 || current.pending_publishable !== 1 || revision > current.latest_revision || current.active_revision !== null && revision <= current.active_revision || claimId !== void 0 && (current.claim_id !== claimId || current.claim_revision !== revision || current.claim_active_revision !== current.active_revision) || metadata.fenceTags.length > 0 && current.current_invalidation_sequence > current.pending_invalidation_sequence && this.getTagInvalidationMaximum(metadata.fenceTags, "invalidation_sequence") > current.pending_invalidation_sequence) {
+				if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
+				return {
+					cleanupObjectKey: current?.object_key === metadata.objectKey ? void 0 : metadata.objectKey,
+					result: {
+						entry: current ? storedEntryFromRow(current) : null,
+						published: false
+					}
+				};
+			}
+			const published = this.ctx.storage.sql.exec(`UPDATE entries SET
+          active_revision = ?, object_key = ?, status_text = ?, response_headers = ?,
+          fresh_until = ?, swr_until = ?,
+          revalidator_id = ?, revalidator_args = ?, cache_tags = ?, tombstoned = 0
+        WHERE key_hash = ? AND latest_revision >= ?
+          AND (active_revision IS NULL OR active_revision < ?)`, revision, metadata.objectKey, metadata.statusText, JSON.stringify(metadata.responseHeaders), metadata.freshUntil, metadata.swrUntil, metadata.revalidator?.id ?? null, metadata.revalidator ? JSON.stringify(metadata.revalidator.args) : null, JSON.stringify(metadata.cacheTags), keyHash, revision, revision).rowsWritten === 1;
+			if (published) this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", metadata.objectKey);
+			if (published && current.object_key && current.object_key !== metadata.objectKey) this.ctx.storage.sql.exec(`INSERT OR IGNORE INTO pending_objects
+            (object_key, created_at, publishable) VALUES (?, ?, 0)`, current.object_key, Date.now());
+			if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
+			const entry = {
+				keyHash,
+				cacheKey: current.cache_key,
+				activeRevision: revision,
+				latestRevision: current.latest_revision,
+				objectKey: metadata.objectKey,
+				statusText: metadata.statusText,
+				responseHeaders: metadata.responseHeaders,
+				freshUntil: metadata.freshUntil,
+				swrUntil: metadata.swrUntil,
+				revalidator: metadata.revalidator,
+				cacheTags: metadata.cacheTags
+			};
+			return {
+				cleanupObjectKey: published ? current.object_key && current.object_key !== metadata.objectKey ? current.object_key : void 0 : metadata.objectKey,
+				result: {
+					entry: published ? entry : null,
+					published
+				}
+			};
+		});
+		if (cleanupObjectKey) {
+			await this.maintainCleanupAlarm(Date.now());
+			await this.deleteTrackedObjects([cleanupObjectKey]);
+		}
+		return result;
+	}
+	getEntry(keyHash) {
+		const row = this.ctx.storage.sql.exec("SELECT * FROM entries WHERE key_hash = ?", keyHash).toArray()[0];
+		return row ? storedEntryFromRow(row) : null;
+	}
+	getTagInvalidationMaximum(tags, column) {
+		const normalized = normalizeTags(tags);
+		let expiration = 0;
+		for (const batch of batches(normalized, MAX_SQL_PARAMETERS)) {
+			const placeholders = batch.map(() => "?").join(", ");
+			const row = this.ctx.storage.sql.exec(`SELECT MAX(${column}) AS invalidated_at
+          FROM tag_invalidations WHERE tag IN (${placeholders})`, ...batch).one();
+			expiration = Math.max(expiration, row.invalidated_at ?? 0);
+		}
+		return expiration;
+	}
+	getTagExpiration(tags) {
+		return this.getTagInvalidationMaximum(tags, "invalidated_at");
+	}
+	async reserveRefresh(options, objectKeyRoot, createdAt) {
+		const candidates = this.ctx.storage.transactionSync(() => {
+			const matches = this.findMatchingEntryRows(options);
+			const reservations = matches.flatMap((row) => {
+				return storedEntryFromRow(row)?.revalidator ? [{
+					keyHash: row.key_hash,
+					objectKey: `${objectKeyRoot}/${row.key_hash}/${row.latest_revision + 1}`,
+					revision: row.latest_revision + 1
+				}] : [];
+			});
+			for (const batch of batches(reservations, MAX_SQL_PARAMETERS)) {
+				const keyHashes = batch.map(({ keyHash }) => keyHash);
+				this.ctx.storage.sql.exec(`UPDATE entries SET latest_revision = latest_revision + 1
+          WHERE key_hash IN (${keyHashes.map(() => "?").join(", ")})`, ...keyHashes);
+			}
+			for (const batch of batches(reservations, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
+            (object_key, created_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}`, ...batch.flatMap(({ objectKey }) => [objectKey, createdAt]));
+			const byKey = new Map(reservations.map((reservation) => [reservation.keyHash, reservation]));
+			return matches.flatMap((row) => {
+				const entry = storedEntryFromRow(row);
+				if (!entry) return [];
+				const reservation = byKey.get(row.key_hash);
+				return [{
+					entry,
+					...reservation ? { reservation: {
+						objectKey: reservation.objectKey,
+						revision: reservation.revision
+					} } : {}
+				}];
+			});
+		});
+		if (candidates.some(({ reservation }) => reservation)) await this.ensureCleanupAlarm(createdAt);
+		return candidates;
+	}
+	async purgeMatching(options) {
+		const invalidatedAt = Date.now();
+		const matches = this.ctx.storage.transactionSync(() => {
+			const matches = this.findMatchingEntryRows(options, true);
+			const tags = normalizeTags(options.tags ?? []);
+			if (tags.length) this.ctx.storage.sql.exec(`UPDATE metadata_state SET tag_invalidation_sequence = tag_invalidation_sequence + 1
+          WHERE singleton = 1`);
+			for (const batch of batches(tags, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`INSERT INTO tag_invalidations
+            (tag, invalidated_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
+          ON CONFLICT(tag) DO UPDATE SET invalidated_at =
+            MAX(tag_invalidations.invalidated_at, excluded.invalidated_at),
+            invalidation_sequence = MAX(
+              tag_invalidations.invalidation_sequence,
+              excluded.invalidation_sequence
+            )`, ...batch.flatMap((tag) => [tag, invalidatedAt]));
+			for (const batch of batches(matches, 99)) {
+				const keyHashes = batch.map((row) => row.key_hash);
+				const placeholders = keyHashes.map(() => "?").join(", ");
+				this.ctx.storage.sql.exec(`INSERT OR IGNORE INTO pending_objects (object_key, created_at, publishable)
+          SELECT object_key, ?, 0 FROM entries
+          WHERE key_hash IN (${placeholders}) AND object_key IS NOT NULL`, invalidatedAt, ...keyHashes);
+				this.ctx.storage.sql.exec(`UPDATE entries SET
+            latest_revision = latest_revision + 1,
+            active_revision = latest_revision + 1,
+            object_key = NULL,
+            status_text = NULL,
+            response_headers = NULL,
+            fresh_until = NULL,
+            swr_until = NULL,
+            revalidator_id = NULL,
+            revalidator_args = NULL,
+            cache_tags = NULL,
+            tombstoned = 1
+          WHERE key_hash IN (${placeholders})`, ...keyHashes);
+				this.ctx.storage.sql.exec(`DELETE FROM revalidation_claims WHERE key_hash IN (${placeholders})`, ...keyHashes);
+			}
+			return matches.flatMap((row) => row.object_key === null ? [] : [{
+				keyHash: row.key_hash,
+				cacheKey: row.cache_key,
+				objectKey: row.object_key
+			}]);
+		});
+		if (matches.length) {
+			await this.maintainCleanupAlarm(invalidatedAt);
+			await this.deleteTrackedObjects(matches.map((entry) => entry.objectKey));
+		}
+		return matches;
+	}
+	inspect() {
+		return storedEntriesFromRows(this.ctx.storage.sql.exec("SELECT * FROM entries ORDER BY cache_key").toArray());
+	}
+};
+//#endregion
+export { CacheMetadata };

package/dist/service.d.ts

@@ -0,0 +1,8 @@
+import { ResponseStoreBinding, ResponseStoreService } from "./binding.js";
+import { CacheMetadata } from "./metadata-do.js";
+//#region src/service.d.ts
+declare const _default: {
+  fetch(): Response;
+};
+//#endregion
+export { CacheMetadata, ResponseStoreBinding, ResponseStoreService, _default as default };

package/dist/service.js

@@ -0,0 +1,8 @@
+import { ResponseStoreBinding, ResponseStoreService } from "./binding.js";
+import { CacheMetadata } from "./metadata-do.js";
+//#region src/service.ts
+var service_default = { fetch() {
+	return new Response("Use the ResponseStoreService service binding entrypoint.", { status: 404 });
+} };
+//#endregion
+export { CacheMetadata, ResponseStoreBinding, ResponseStoreService, service_default as default };