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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,599 @@
1
+ import { DurableObject } from "cloudflare:workers";
2
+ //#region src/metadata-do.ts
3
+ const MAX_SQL_PARAMETERS = 100;
4
+ const ORPHAN_RETENTION_MS = 36e5;
5
+ const ORPHAN_CLEANUP_LIMIT = 100;
6
+ const ORPHAN_CLEANUP_RETRY_MS = 6e4;
7
+ const MAX_R2_CAS_ATTEMPTS = 3;
8
+ function metadataInteger(value) {
9
+ if (value === void 0 || !/^\d+$/.test(value)) return void 0;
10
+ const parsed = Number(value);
11
+ return Number.isSafeInteger(parsed) ? parsed : void 0;
12
+ }
13
+ function normalizeTags(tags) {
14
+ const normalized = tags.map((tag) => tag.trim().toLowerCase()).filter(Boolean);
15
+ return [...new Set(normalized)];
16
+ }
17
+ function* batches(values, size) {
18
+ for (let offset = 0; offset < values.length; offset += size) yield values.slice(offset, offset + size);
19
+ }
20
+ function storedEntryFromRow(row) {
21
+ 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;
22
+ return {
23
+ keyHash: row.key_hash,
24
+ cacheKey: row.cache_key,
25
+ activeRevision: row.active_revision,
26
+ latestRevision: row.latest_revision,
27
+ objectKey: row.object_key,
28
+ statusText: row.status_text ?? "",
29
+ responseHeaders: JSON.parse(row.response_headers),
30
+ freshUntil: row.fresh_until,
31
+ swrUntil: row.swr_until,
32
+ revalidator: row.revalidator_id === null ? null : {
33
+ id: row.revalidator_id,
34
+ args: JSON.parse(row.revalidator_args ?? "[]")
35
+ },
36
+ cacheTags: JSON.parse(row.cache_tags ?? "[]")
37
+ };
38
+ }
39
+ function storedEntriesFromRows(rows) {
40
+ const entries = [];
41
+ for (const row of rows) {
42
+ const entry = storedEntryFromRow(row);
43
+ if (entry) entries.push(entry);
44
+ }
45
+ return entries;
46
+ }
47
+ var CacheMetadata = class extends DurableObject {
48
+ cleanupAlarmKnown = false;
49
+ constructor(ctx, env) {
50
+ super(ctx, env);
51
+ ctx.blockConcurrencyWhile(async () => {
52
+ ctx.storage.sql.exec(`
53
+ CREATE TABLE IF NOT EXISTS entries (
54
+ key_hash TEXT PRIMARY KEY,
55
+ cache_key TEXT NOT NULL,
56
+ active_revision INTEGER,
57
+ latest_revision INTEGER NOT NULL,
58
+ object_key TEXT,
59
+ status_text TEXT,
60
+ response_headers TEXT,
61
+ fresh_until INTEGER,
62
+ swr_until INTEGER,
63
+ revalidator_id TEXT,
64
+ revalidator_args TEXT,
65
+ cache_tags TEXT,
66
+ tombstoned INTEGER NOT NULL DEFAULT 0
67
+ );
68
+ CREATE INDEX IF NOT EXISTS entries_cache_key ON entries(cache_key);
69
+ CREATE INDEX IF NOT EXISTS entries_active_object_key
70
+ ON entries(object_key) WHERE tombstoned = 0;
71
+ CREATE TABLE IF NOT EXISTS revalidation_claims (
72
+ key_hash TEXT PRIMARY KEY,
73
+ active_revision INTEGER NOT NULL,
74
+ revision INTEGER NOT NULL,
75
+ claim_id TEXT NOT NULL,
76
+ claimed_at INTEGER NOT NULL,
77
+ expires_at INTEGER NOT NULL
78
+ );
79
+ CREATE TABLE IF NOT EXISTS tag_invalidations (
80
+ tag TEXT PRIMARY KEY,
81
+ invalidated_at INTEGER NOT NULL,
82
+ invalidation_sequence INTEGER NOT NULL DEFAULT 0
83
+ ) WITHOUT ROWID;
84
+ CREATE TABLE IF NOT EXISTS metadata_schema_migrations (
85
+ version INTEGER PRIMARY KEY
86
+ );
87
+ CREATE TABLE IF NOT EXISTS metadata_state (
88
+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
89
+ tag_invalidation_sequence INTEGER NOT NULL
90
+ );
91
+ INSERT OR IGNORE INTO metadata_state (singleton, tag_invalidation_sequence) VALUES (1, 0);
92
+ CREATE TABLE IF NOT EXISTS key_invalidations (
93
+ key_hash TEXT PRIMARY KEY,
94
+ invalidation_sequence INTEGER NOT NULL
95
+ ) WITHOUT ROWID;
96
+ CREATE TABLE IF NOT EXISTS pending_objects (
97
+ object_key TEXT PRIMARY KEY,
98
+ invalidation_sequence INTEGER NOT NULL DEFAULT 0,
99
+ publishable INTEGER NOT NULL DEFAULT 1,
100
+ created_at INTEGER NOT NULL
101
+ );
102
+ CREATE INDEX IF NOT EXISTS pending_objects_created_at ON pending_objects(created_at);
103
+ CREATE TABLE IF NOT EXISTS pending_r2_tombstones (
104
+ key_hash TEXT PRIMARY KEY,
105
+ cache_key TEXT NOT NULL,
106
+ object_key TEXT NOT NULL,
107
+ revision INTEGER NOT NULL,
108
+ r2_complete INTEGER NOT NULL DEFAULT 0,
109
+ edge_purge_complete INTEGER NOT NULL DEFAULT 0
110
+ ) WITHOUT ROWID;
111
+ `);
112
+ ctx.storage.transactionSync(() => {
113
+ const migrations = new Set(ctx.storage.sql.exec("SELECT version FROM metadata_schema_migrations WHERE version IN (2, 3, 4)").toArray().map(({ version }) => version));
114
+ if (migrations.size === 3) return;
115
+ const schemas = ctx.storage.sql.exec(`SELECT name, sql FROM sqlite_schema
116
+ WHERE type = 'table'
117
+ AND name IN ('tag_invalidations', 'pending_objects', 'pending_r2_tombstones')`).toArray();
118
+ 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");
119
+ 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");
120
+ if (!migrations.has(2)) ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (2)");
121
+ if (!migrations.has(3)) {
122
+ 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");
123
+ ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (3)");
124
+ }
125
+ if (!migrations.has(4)) {
126
+ const tombstones = schemas.find(({ name }) => name === "pending_r2_tombstones")?.sql;
127
+ if (!tombstones?.includes("r2_complete")) ctx.storage.sql.exec("ALTER TABLE pending_r2_tombstones ADD COLUMN r2_complete INTEGER NOT NULL DEFAULT 0");
128
+ if (!tombstones?.includes("edge_purge_complete")) ctx.storage.sql.exec("ALTER TABLE pending_r2_tombstones ADD COLUMN edge_purge_complete INTEGER NOT NULL DEFAULT 0");
129
+ ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (4)");
130
+ }
131
+ });
132
+ });
133
+ }
134
+ async ensureCleanupAlarm(createdAt) {
135
+ if (this.cleanupAlarmKnown) return;
136
+ await this.scheduleCleanupAlarm(createdAt + ORPHAN_RETENTION_MS);
137
+ }
138
+ async scheduleCleanupAlarm(scheduledTime) {
139
+ const current = await this.ctx.storage.getAlarm();
140
+ if (current === null || current > scheduledTime) await this.ctx.storage.setAlarm(scheduledTime);
141
+ this.cleanupAlarmKnown = true;
142
+ }
143
+ logCleanupFailure(error) {
144
+ console.error(JSON.stringify({
145
+ message: "Workers Response Store cleanup scheduling failed",
146
+ error: error instanceof Error ? error.message : String(error)
147
+ }));
148
+ }
149
+ getR2TombstoneEdgePurger() {
150
+ const factory = Reflect.get(this.ctx.exports, "ResponseStoreBinding");
151
+ if (typeof factory !== "function") throw new Error("The ResponseStoreBinding entrypoint is not exported");
152
+ return factory({ props: {} });
153
+ }
154
+ findMatchingEntryRows(options, includePending = false) {
155
+ const rows = this.ctx.storage.sql.exec(includePending ? "SELECT * FROM entries" : "SELECT * FROM entries WHERE tombstoned = 0 AND active_revision IS NOT NULL").toArray();
156
+ if (options.purgeEverything) return rows;
157
+ const tags = new Set(normalizeTags(options.tags ?? []));
158
+ const prefixes = options.pathPrefixes ?? [];
159
+ return rows.filter((row) => prefixes.some((prefix) => row.cache_key.startsWith(prefix)) || normalizeTags(JSON.parse(row.cache_tags ?? "[]")).some((tag) => tags.has(tag)));
160
+ }
161
+ async trackPendingObjects(objectKeys, createdAt) {
162
+ if (!objectKeys.length) return;
163
+ this.ctx.storage.transactionSync(() => {
164
+ for (const batch of batches(objectKeys, MAX_SQL_PARAMETERS / 2)) {
165
+ const values = batch.flatMap((objectKey) => [objectKey, createdAt]);
166
+ this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
167
+ (object_key, created_at, publishable) VALUES ${batch.map(() => "(?, ?, 0)").join(", ")}`, ...values);
168
+ }
169
+ });
170
+ await this.ensureCleanupAlarm(createdAt);
171
+ }
172
+ trackPendingObject(objectKey, createdAt) {
173
+ return this.trackPendingObjects([objectKey], createdAt);
174
+ }
175
+ releaseWrite(keyHash, objectKey, claimId) {
176
+ this.ctx.storage.transactionSync(() => {
177
+ this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", objectKey);
178
+ if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
179
+ });
180
+ }
181
+ finishPendingObjects(objectKeys) {
182
+ if (!objectKeys.length) return;
183
+ this.ctx.storage.transactionSync(() => {
184
+ 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);
185
+ });
186
+ }
187
+ listExpiredPendingObjects(cutoff, limit) {
188
+ return this.ctx.storage.sql.exec(`SELECT pending_objects.object_key FROM pending_objects
189
+ LEFT JOIN entries
190
+ ON entries.object_key = pending_objects.object_key AND entries.tombstoned = 0
191
+ WHERE pending_objects.created_at <= ? AND entries.object_key IS NULL
192
+ ORDER BY pending_objects.created_at
193
+ LIMIT ?`, cutoff, limit).toArray().map((row) => row.object_key);
194
+ }
195
+ async sweepExpiredPendingObjects(cutoff = Date.now() - ORPHAN_RETENTION_MS) {
196
+ this.cleanupAlarmKnown = false;
197
+ const rows = this.ctx.storage.sql.exec(`SELECT pending_objects.object_key, pending_objects.created_at,
198
+ entries.object_key IS NOT NULL AS active
199
+ FROM pending_objects
200
+ LEFT JOIN entries
201
+ ON entries.object_key = pending_objects.object_key AND entries.tombstoned = 0
202
+ ORDER BY pending_objects.created_at
203
+ LIMIT ?`, 101).toArray();
204
+ const batch = rows.slice(0, ORPHAN_CLEANUP_LIMIT);
205
+ const activeObjectKeys = batch.filter(({ active }) => active).map(({ object_key }) => object_key);
206
+ const expiredObjectKeys = batch.filter(({ active, created_at }) => !active && created_at <= cutoff).map(({ object_key }) => object_key);
207
+ this.finishPendingObjects([...activeObjectKeys, ...expiredObjectKeys]);
208
+ const next = batch.find(({ active, created_at }) => !active && created_at > cutoff);
209
+ if (!next && rows.length > ORPHAN_CLEANUP_LIMIT) {
210
+ await this.ctx.storage.setAlarm(Date.now());
211
+ this.cleanupAlarmKnown = true;
212
+ } else if (next) await this.ensureCleanupAlarm(next.created_at);
213
+ return expiredObjectKeys.length;
214
+ }
215
+ async alarm() {
216
+ try {
217
+ if (await this.retryPendingTombstones()) {
218
+ await this.ctx.storage.setAlarm(Date.now());
219
+ this.cleanupAlarmKnown = true;
220
+ return;
221
+ }
222
+ await this.sweepExpiredPendingObjects();
223
+ } catch (error) {
224
+ console.error(JSON.stringify({
225
+ message: "Workers Response Store orphan cleanup failed",
226
+ error: error instanceof Error ? error.message : String(error)
227
+ }));
228
+ await this.ctx.storage.setAlarm(Date.now() + ORPHAN_CLEANUP_RETRY_MS);
229
+ this.cleanupAlarmKnown = true;
230
+ }
231
+ }
232
+ async retryPendingTombstones() {
233
+ const drained = await this.drainPendingTombstones(400);
234
+ if (drained.failures.length) throw new AggregateError(drained.failures.map((failure) => new Error(failure)), "R2 tombstone cleanup failed");
235
+ const edgeEntries = this.listPendingEdgePurges(400);
236
+ if (edgeEntries.length) {
237
+ if (!await this.getR2TombstoneEdgePurger().purgeR2TombstoneEdges(edgeEntries)) throw new Error("Workers Response Store cache purge is unavailable");
238
+ this.markTombstonesEdgePurged(edgeEntries);
239
+ }
240
+ return this.ctx.storage.sql.exec("SELECT COUNT(*) AS count FROM pending_r2_tombstones").one().count > 0;
241
+ }
242
+ async claimRevalidation(keyHash, activeRevision, cacheKey, objectKeyPrefix, now, leaseMs) {
243
+ const claim = this.ctx.storage.transactionSync(() => {
244
+ const entry = this.ctx.storage.sql.exec(`SELECT entries.*,
245
+ revalidation_claims.active_revision AS claim_active_revision,
246
+ revalidation_claims.expires_at AS claim_expires_at
247
+ FROM entries
248
+ LEFT JOIN revalidation_claims ON revalidation_claims.key_hash = entries.key_hash
249
+ WHERE entries.key_hash = ? AND entries.cache_key = ?`, keyHash, cacheKey).toArray()[0];
250
+ if (entry?.tombstoned || entry?.active_revision !== activeRevision) return null;
251
+ const storedEntry = storedEntryFromRow(entry);
252
+ if (!storedEntry?.revalidator) return null;
253
+ if (entry.claim_active_revision === activeRevision && (entry.claim_expires_at ?? 0) > now) return null;
254
+ const revision = entry.latest_revision + 1;
255
+ const claimId = crypto.randomUUID();
256
+ const objectKey = `${objectKeyPrefix}/${revision}`;
257
+ this.ctx.storage.sql.exec("UPDATE entries SET latest_revision = ? WHERE key_hash = ? AND active_revision = ?", revision, keyHash, activeRevision);
258
+ this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO revalidation_claims
259
+ (key_hash, active_revision, revision, claim_id, claimed_at, expires_at)
260
+ VALUES (?, ?, ?, ?, ?, ?)`, keyHash, activeRevision, revision, claimId, now, now + leaseMs);
261
+ this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
262
+ (object_key, created_at, invalidation_sequence)
263
+ VALUES (?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))`, objectKey, now);
264
+ return {
265
+ claimId,
266
+ entry: storedEntry,
267
+ objectKey,
268
+ revision
269
+ };
270
+ });
271
+ if (claim) await this.ensureCleanupAlarm(now);
272
+ return claim;
273
+ }
274
+ reserveRevision(keyHash, cacheKey, current) {
275
+ const revision = (current?.latest_revision ?? 0) + 1;
276
+ if (!current) this.ctx.storage.sql.exec("INSERT INTO entries (key_hash, cache_key, latest_revision, tombstoned) VALUES (?, ?, ?, 1)", keyHash, cacheKey, revision);
277
+ else this.ctx.storage.sql.exec("UPDATE entries SET cache_key = ?, latest_revision = ? WHERE key_hash = ?", cacheKey, revision, keyHash);
278
+ return revision;
279
+ }
280
+ async reserveWrite(keyHash, cacheKey, objectKeyPrefix, createdAt) {
281
+ const reservation = this.ctx.storage.transactionSync(() => {
282
+ const current = this.ctx.storage.sql.exec("SELECT active_revision, latest_revision FROM entries WHERE key_hash = ?", keyHash).toArray()[0];
283
+ const revision = this.reserveRevision(keyHash, cacheKey, current);
284
+ const objectKey = `${objectKeyPrefix}/${revision}`;
285
+ this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
286
+ (object_key, created_at, invalidation_sequence)
287
+ VALUES (?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))`, objectKey, createdAt);
288
+ return {
289
+ objectKey,
290
+ r2ObjectAbsent: current === void 0,
291
+ revision
292
+ };
293
+ });
294
+ await this.ensureCleanupAlarm(createdAt);
295
+ return reservation;
296
+ }
297
+ async replaceFailedWrite(keyHash, cacheKey, objectKeyPrefix, failedObjectKey, fenceTags, createdAt) {
298
+ const reservation = this.ctx.storage.transactionSync(() => {
299
+ const pending = this.ctx.storage.sql.exec("SELECT invalidation_sequence, publishable FROM pending_objects WHERE object_key = ?", failedObjectKey).toArray()[0];
300
+ const currentInvalidationSequence = this.ctx.storage.sql.exec("SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1").one().tag_invalidation_sequence;
301
+ const keyInvalidationSequence = this.ctx.storage.sql.exec("SELECT invalidation_sequence FROM key_invalidations WHERE key_hash = ?", keyHash).toArray()[0]?.invalidation_sequence;
302
+ this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", failedObjectKey);
303
+ if (!pending || pending.publishable !== 1 || (keyInvalidationSequence ?? 0) > pending.invalidation_sequence || currentInvalidationSequence > pending.invalidation_sequence && this.getTagInvalidationMaximum(fenceTags, "invalidation_sequence") > pending.invalidation_sequence) return null;
304
+ const current = this.ctx.storage.sql.exec("SELECT active_revision, latest_revision FROM entries WHERE key_hash = ?", keyHash).toArray()[0];
305
+ const revision = this.reserveRevision(keyHash, cacheKey, current);
306
+ const objectKey = `${objectKeyPrefix}/${revision}`;
307
+ this.ctx.storage.sql.exec(`INSERT INTO pending_objects
308
+ (object_key, created_at, invalidation_sequence) VALUES (?, ?, ?)`, objectKey, createdAt, currentInvalidationSequence);
309
+ return {
310
+ objectKey,
311
+ r2ObjectAbsent: false,
312
+ revision
313
+ };
314
+ });
315
+ if (reservation) await this.ensureCleanupAlarm(createdAt);
316
+ return reservation;
317
+ }
318
+ async reserveRegeneration(keyHash, cacheKey, objectKeyPrefix, createdAt) {
319
+ const result = this.ctx.storage.transactionSync(() => {
320
+ const current = this.ctx.storage.sql.exec("SELECT * FROM entries WHERE key_hash = ? AND cache_key = ?", keyHash, cacheKey).toArray()[0];
321
+ const entry = current ? storedEntryFromRow(current) : null;
322
+ if (!entry) return null;
323
+ if (!entry.revalidator) return { entry };
324
+ const revision = this.reserveRevision(keyHash, cacheKey, current);
325
+ const objectKey = `${objectKeyPrefix}/${revision}`;
326
+ this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
327
+ (object_key, created_at, invalidation_sequence)
328
+ VALUES (?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))`, objectKey, createdAt);
329
+ return {
330
+ entry,
331
+ reservation: {
332
+ objectKey,
333
+ r2ObjectAbsent: false,
334
+ revision
335
+ }
336
+ };
337
+ });
338
+ if (result?.reservation) await this.ensureCleanupAlarm(createdAt);
339
+ return result;
340
+ }
341
+ async publish(keyHash, revision, metadata, claimId, reservationObjectKey = metadata.objectKey) {
342
+ return this.ctx.storage.transactionSync(() => {
343
+ const current = this.ctx.storage.sql.exec(`SELECT entries.*,
344
+ revalidation_claims.active_revision AS claim_active_revision,
345
+ revalidation_claims.claim_id AS claim_id,
346
+ revalidation_claims.revision AS claim_revision,
347
+ pending_objects.invalidation_sequence AS pending_invalidation_sequence,
348
+ pending_objects.publishable AS pending_publishable,
349
+ metadata_state.tag_invalidation_sequence AS current_invalidation_sequence
350
+ FROM entries
351
+ CROSS JOIN metadata_state
352
+ LEFT JOIN pending_objects ON pending_objects.object_key = ?
353
+ LEFT JOIN revalidation_claims ON revalidation_claims.key_hash = entries.key_hash
354
+ WHERE entries.key_hash = ?`, reservationObjectKey, keyHash).toArray()[0];
355
+ 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) {
356
+ if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
357
+ this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", reservationObjectKey);
358
+ return {
359
+ entry: current ? storedEntryFromRow(current) : null,
360
+ published: false
361
+ };
362
+ }
363
+ const published = this.ctx.storage.sql.exec(`UPDATE entries SET
364
+ active_revision = ?, object_key = ?, status_text = ?, response_headers = ?,
365
+ fresh_until = ?, swr_until = ?,
366
+ revalidator_id = ?, revalidator_args = ?, cache_tags = ?, tombstoned = 0
367
+ WHERE key_hash = ? AND latest_revision >= ?
368
+ AND (active_revision IS NULL OR active_revision < ?)
369
+ RETURNING key_hash`, 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).toArray().length === 1;
370
+ this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", reservationObjectKey);
371
+ if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
372
+ const entry = {
373
+ keyHash,
374
+ cacheKey: current.cache_key,
375
+ activeRevision: revision,
376
+ latestRevision: current.latest_revision,
377
+ objectKey: metadata.objectKey,
378
+ statusText: metadata.statusText,
379
+ responseHeaders: metadata.responseHeaders,
380
+ freshUntil: metadata.freshUntil,
381
+ swrUntil: metadata.swrUntil,
382
+ revalidator: metadata.revalidator,
383
+ cacheTags: metadata.cacheTags
384
+ };
385
+ return {
386
+ entry: published ? entry : null,
387
+ published
388
+ };
389
+ });
390
+ }
391
+ async invalidatePublishedRevision(keyHash, revision) {
392
+ if (!this.ctx.storage.transactionSync(() => {
393
+ const current = this.ctx.storage.sql.exec("SELECT * FROM entries WHERE key_hash = ?", keyHash).toArray()[0];
394
+ if (!current || current.active_revision !== revision || current.object_key === null) return false;
395
+ const tombstoneRevision = current.latest_revision + 1;
396
+ this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_r2_tombstones
397
+ (key_hash, cache_key, object_key, revision) VALUES (?, ?, ?, ?)`, keyHash, current.cache_key, current.object_key, tombstoneRevision);
398
+ this.ctx.storage.sql.exec(`UPDATE entries SET
399
+ latest_revision = ?, active_revision = ?, object_key = NULL,
400
+ status_text = NULL, response_headers = NULL, fresh_until = NULL,
401
+ swr_until = NULL, revalidator_id = NULL, revalidator_args = NULL,
402
+ cache_tags = NULL, tombstoned = 1
403
+ WHERE key_hash = ? AND active_revision = ?`, tombstoneRevision, tombstoneRevision, keyHash, revision);
404
+ this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ?", keyHash);
405
+ return true;
406
+ })) return {
407
+ failures: [],
408
+ pending: [],
409
+ purged: []
410
+ };
411
+ await this.scheduleCleanupAlarm(Date.now() + ORPHAN_CLEANUP_RETRY_MS).catch((error) => this.logCleanupFailure(error));
412
+ return this.drainPendingTombstones(1, keyHash);
413
+ }
414
+ getEntry(keyHash) {
415
+ const row = this.ctx.storage.sql.exec("SELECT * FROM entries WHERE key_hash = ?", keyHash).toArray()[0];
416
+ return row ? storedEntryFromRow(row) : null;
417
+ }
418
+ getTagInvalidationMaximum(tags, column) {
419
+ const normalized = normalizeTags(tags);
420
+ let expiration = 0;
421
+ for (const batch of batches(normalized, MAX_SQL_PARAMETERS)) {
422
+ const placeholders = batch.map(() => "?").join(", ");
423
+ const row = this.ctx.storage.sql.exec(`SELECT MAX(${column}) AS invalidated_at
424
+ FROM tag_invalidations WHERE tag IN (${placeholders})`, ...batch).one();
425
+ expiration = Math.max(expiration, row.invalidated_at ?? 0);
426
+ }
427
+ return expiration;
428
+ }
429
+ getTagExpiration(tags) {
430
+ return this.getTagInvalidationMaximum(tags, "invalidated_at");
431
+ }
432
+ async reserveRefresh(options, objectKeyRoot, createdAt) {
433
+ const candidates = this.ctx.storage.transactionSync(() => {
434
+ const matches = this.findMatchingEntryRows(options);
435
+ const reservations = matches.flatMap((row) => {
436
+ return storedEntryFromRow(row)?.revalidator ? [{
437
+ keyHash: row.key_hash,
438
+ objectKey: `${objectKeyRoot}/${row.key_hash}/${row.latest_revision + 1}`,
439
+ revision: row.latest_revision + 1
440
+ }] : [];
441
+ });
442
+ for (const batch of batches(reservations, MAX_SQL_PARAMETERS)) {
443
+ const keyHashes = batch.map(({ keyHash }) => keyHash);
444
+ this.ctx.storage.sql.exec(`UPDATE entries SET latest_revision = latest_revision + 1
445
+ WHERE key_hash IN (${keyHashes.map(() => "?").join(", ")})`, ...keyHashes);
446
+ }
447
+ for (const batch of batches(reservations, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_objects
448
+ (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]));
449
+ const byKey = new Map(reservations.map((reservation) => [reservation.keyHash, reservation]));
450
+ return matches.flatMap((row) => {
451
+ const entry = storedEntryFromRow(row);
452
+ if (!entry) return [];
453
+ const reservation = byKey.get(row.key_hash);
454
+ return [{
455
+ entry,
456
+ ...reservation ? { reservation: {
457
+ objectKey: reservation.objectKey,
458
+ revision: reservation.revision
459
+ } } : {}
460
+ }];
461
+ });
462
+ });
463
+ if (candidates.some(({ reservation }) => reservation)) await this.ensureCleanupAlarm(createdAt);
464
+ return candidates;
465
+ }
466
+ async purgeMatching(options, invalidatedAt = Date.now()) {
467
+ const reservation = this.ctx.storage.transactionSync(() => {
468
+ const matches = this.findMatchingEntryRows(options, true);
469
+ const tags = normalizeTags(options.tags ?? []);
470
+ this.ctx.storage.sql.exec(`UPDATE metadata_state SET tag_invalidation_sequence = tag_invalidation_sequence + 1
471
+ WHERE singleton = 1`);
472
+ for (const batch of batches(matches, MAX_SQL_PARAMETERS)) this.ctx.storage.sql.exec(`INSERT INTO key_invalidations (key_hash, invalidation_sequence) VALUES ${batch.map(() => "(?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
473
+ ON CONFLICT(key_hash) DO UPDATE SET invalidation_sequence =
474
+ MAX(key_invalidations.invalidation_sequence, excluded.invalidation_sequence)`, ...batch.map((row) => row.key_hash));
475
+ for (const batch of batches(tags, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`INSERT INTO tag_invalidations
476
+ (tag, invalidated_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
477
+ ON CONFLICT(tag) DO UPDATE SET invalidated_at =
478
+ MAX(tag_invalidations.invalidated_at, excluded.invalidated_at),
479
+ invalidation_sequence = MAX(
480
+ tag_invalidations.invalidation_sequence,
481
+ excluded.invalidation_sequence
482
+ )`, ...batch.flatMap((tag) => [tag, invalidatedAt]));
483
+ for (const batch of batches(matches, 99)) {
484
+ const active = batch.filter((row) => row.object_key !== null);
485
+ for (const entryBatch of batches(active, MAX_SQL_PARAMETERS / 4)) this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_r2_tombstones
486
+ (key_hash, cache_key, object_key, revision) VALUES ${entryBatch.map(() => "(?, ?, ?, ?)").join(", ")}`, ...entryBatch.flatMap((row) => [
487
+ row.key_hash,
488
+ row.cache_key,
489
+ row.object_key,
490
+ row.latest_revision + 1
491
+ ]));
492
+ const keyHashes = batch.map((row) => row.key_hash);
493
+ const placeholders = keyHashes.map(() => "?").join(", ");
494
+ this.ctx.storage.sql.exec(`UPDATE entries SET
495
+ latest_revision = latest_revision + 1,
496
+ active_revision = latest_revision + 1,
497
+ object_key = NULL,
498
+ status_text = NULL,
499
+ response_headers = NULL,
500
+ fresh_until = NULL,
501
+ swr_until = NULL,
502
+ revalidator_id = NULL,
503
+ revalidator_args = NULL,
504
+ cache_tags = NULL,
505
+ tombstoned = 1
506
+ WHERE key_hash IN (${placeholders})`, ...keyHashes);
507
+ this.ctx.storage.sql.exec(`DELETE FROM revalidation_claims WHERE key_hash IN (${placeholders})`, ...keyHashes);
508
+ }
509
+ const pendingTombstones = this.ctx.storage.sql.exec("SELECT COUNT(*) AS count FROM pending_r2_tombstones").one().count;
510
+ return {
511
+ backingStoreUpdated: matches.length > 0 || tags.length > 0,
512
+ pendingTombstones
513
+ };
514
+ });
515
+ if (reservation.pendingTombstones > 0) await this.scheduleCleanupAlarm(Date.now() + ORPHAN_CLEANUP_RETRY_MS).catch((error) => this.logCleanupFailure(error));
516
+ return reservation;
517
+ }
518
+ async writeR2Tombstone(entry) {
519
+ let etag;
520
+ for (let attempt = 0; attempt < MAX_R2_CAS_ATTEMPTS; attempt++) {
521
+ const current = await this.env.CACHE_BODIES.head(entry.objectKey);
522
+ const currentRevision = metadataInteger(current?.customMetadata?.latestRevision);
523
+ if (currentRevision !== void 0 && currentRevision >= entry.revision) return;
524
+ etag = current?.etag ?? null;
525
+ if (await this.env.CACHE_BODIES.put(entry.objectKey, /* @__PURE__ */ new Uint8Array(), {
526
+ onlyIf: etag === null ? { etagDoesNotMatch: "*" } : { etagMatches: etag },
527
+ customMetadata: {
528
+ latestRevision: String(entry.revision),
529
+ tombstoned: "1"
530
+ }
531
+ })) return;
532
+ }
533
+ const currentRevision = metadataInteger((await this.env.CACHE_BODIES.head(entry.objectKey))?.customMetadata?.latestRevision);
534
+ if (currentRevision !== void 0 && currentRevision >= entry.revision) return;
535
+ throw new Error(`R2 revision ${entry.revision} could not be tombstoned after concurrent writes`);
536
+ }
537
+ finishCompletedTombstones() {
538
+ this.ctx.storage.sql.exec("DELETE FROM pending_r2_tombstones WHERE r2_complete = 1 AND edge_purge_complete = 1");
539
+ }
540
+ async drainPendingTombstones(limit, keyHash, afterKeyHash) {
541
+ const filters = ["r2_complete = 0"];
542
+ const parameters = [];
543
+ if (keyHash !== void 0) {
544
+ filters.push("key_hash = ?");
545
+ parameters.push(keyHash);
546
+ }
547
+ if (afterKeyHash !== void 0) {
548
+ filters.push("key_hash > ?");
549
+ parameters.push(afterKeyHash);
550
+ }
551
+ parameters.push(limit);
552
+ const rows = this.ctx.storage.sql.exec(`SELECT key_hash, cache_key, object_key, revision, r2_complete, edge_purge_complete
553
+ FROM pending_r2_tombstones
554
+ WHERE ${filters.join(" AND ")}
555
+ ORDER BY key_hash LIMIT ?`, ...parameters).toArray();
556
+ const pending = rows.map((row) => ({
557
+ keyHash: row.key_hash,
558
+ cacheKey: row.cache_key,
559
+ objectKey: row.object_key,
560
+ revision: row.revision
561
+ }));
562
+ const settled = await Promise.allSettled(pending.map(async (entry) => {
563
+ await this.writeR2Tombstone(entry);
564
+ return entry;
565
+ }));
566
+ const purged = settled.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
567
+ this.ctx.storage.transactionSync(() => {
568
+ for (const batch of batches(purged, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`UPDATE pending_r2_tombstones SET r2_complete = 1 WHERE ${batch.map(() => "(key_hash = ? AND revision = ?)").join(" OR ")}`, ...batch.flatMap((entry) => [entry.keyHash, entry.revision]));
569
+ this.finishCompletedTombstones();
570
+ });
571
+ return {
572
+ ...rows.length ? { cursor: rows.at(-1).key_hash } : {},
573
+ failures: settled.flatMap((result) => result.status === "rejected" ? [result.reason instanceof Error ? result.reason.message : String(result.reason)] : []),
574
+ pending,
575
+ purged
576
+ };
577
+ }
578
+ listPendingEdgePurges(limit) {
579
+ return this.ctx.storage.sql.exec(`SELECT key_hash, cache_key, object_key, revision, r2_complete, edge_purge_complete
580
+ FROM pending_r2_tombstones
581
+ WHERE r2_complete = 1 AND edge_purge_complete = 0 ORDER BY key_hash LIMIT ?`, limit).toArray().map((row) => ({
582
+ keyHash: row.key_hash,
583
+ cacheKey: row.cache_key,
584
+ objectKey: row.object_key,
585
+ revision: row.revision
586
+ }));
587
+ }
588
+ markTombstonesEdgePurged(entries) {
589
+ this.ctx.storage.transactionSync(() => {
590
+ for (const batch of batches(entries, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`UPDATE pending_r2_tombstones SET edge_purge_complete = 1 WHERE ${batch.map(() => "(key_hash = ? AND revision = ?)").join(" OR ")}`, ...batch.flatMap((entry) => [entry.keyHash, entry.revision]));
591
+ this.finishCompletedTombstones();
592
+ });
593
+ }
594
+ inspect() {
595
+ return storedEntriesFromRows(this.ctx.storage.sql.exec("SELECT * FROM entries ORDER BY cache_key").toArray());
596
+ }
597
+ };
598
+ //#endregion
599
+ export { CacheMetadata };
@@ -0,0 +1,8 @@
1
+ import { ResponseStoreBinding, ResponseStoreService } from "./binding.js";
2
+ import { CacheMetadata } from "./metadata-do.js";
3
+ //#region src/service.d.ts
4
+ declare const _default: {
5
+ fetch(): Response;
6
+ };
7
+ //#endregion
8
+ export { CacheMetadata, ResponseStoreBinding, ResponseStoreService, _default as default };
@@ -0,0 +1,8 @@
1
+ import { ResponseStoreBinding, ResponseStoreService } from "./binding.js";
2
+ import { CacheMetadata } from "./metadata-do.js";
3
+ //#region src/service.ts
4
+ var service_default = { fetch() {
5
+ return new Response("Use the ResponseStoreService service binding entrypoint.", { status: 404 });
6
+ } };
7
+ //#endregion
8
+ export { CacheMetadata, ResponseStoreBinding, ResponseStoreService, service_default as default };
package/package.json CHANGED
@@ -1,9 +1,51 @@
1
1
  {
2
2
  "name": "@cloudflare/workers-response-store",
3
- "version": "0.0.0",
4
- "description": "Reserved for Workers Response Store.",
3
+ "version": "0.1.0-beta.1",
4
+ "description": "An R2-backed programmatic response store for Cloudflare Workers.",
5
+ "homepage": "https://vinext.dev/",
5
6
  "license": "MIT",
6
- "publishConfig": {
7
- "access": "public"
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/cloudflare/vinext.git",
10
+ "directory": "packages/workers-response-store"
11
+ },
12
+ "files": [
13
+ "dist"
14
+ ],
15
+ "type": "module",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js"
20
+ },
21
+ "./service": {
22
+ "types": "./dist/service.d.ts",
23
+ "import": "./dist/service.js"
24
+ }
25
+ },
26
+ "devDependencies": {
27
+ "@cloudflare/workers-types": "5.20260904.1",
28
+ "@types/node": "^25.9.2",
29
+ "miniflare": "5.20260730.0-alpha",
30
+ "typescript": "^7.0.0",
31
+ "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
32
+ "vite-plus": "0.3.2",
33
+ "vitest": "4.1.11",
34
+ "wrangler": "^4.118.0"
35
+ },
36
+ "engines": {
37
+ "node": ">=22"
38
+ },
39
+ "scripts": {
40
+ "build": "vp pack",
41
+ "build:examples": "npm run build && wrangler deploy --dry-run --outdir dist/worker && wrangler deploy --dry-run --config example/service-binding/wrangler.cache.jsonc --outdir ../../dist/service-cache && wrangler deploy --dry-run --config example/service-binding/wrangler.user.jsonc --outdir ../../dist/service-user",
42
+ "build:worker": "npm run build && wrangler deploy --dry-run --outdir dist/worker",
43
+ "build:service-workers": "npm run build && wrangler deploy --dry-run --config example/service-binding/wrangler.cache.jsonc --outdir ../../dist/service-cache && wrangler deploy --dry-run --config example/service-binding/wrangler.user.jsonc --outdir ../../dist/service-user",
44
+ "check": "vp check src example tests README.md package.json tsconfig.json vite.config.ts vitest.config.ts wrangler.jsonc && tsc --noEmit",
45
+ "deploy": "npm run build && wrangler deploy",
46
+ "deploy:service": "npm run build && wrangler deploy --config example/service-binding/wrangler.cache.jsonc && wrangler deploy --config example/service-binding/wrangler.user.jsonc",
47
+ "lint": "vp lint .",
48
+ "test": "npm run check && npm run build:examples && vitest run tests/e2e.test.ts tests/service-binding-e2e.test.ts",
49
+ "test:live": "vitest run tests/live-e2e.test.ts tests/service-binding-live-e2e.test.ts"
8
50
  }
9
- }
51
+ }