@cloudflare/workers-response-store 1.0.0 → 1.1.0
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.
- package/README.md +27 -21
- package/dist/binding.d.ts +46 -4
- package/dist/binding.js +119 -51
- package/dist/index.d.ts +2 -2
- package/dist/index.js +4 -0
- package/dist/metadata-do.d.ts +20 -3
- package/dist/metadata-do.js +200 -58
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
`@cloudflare/workers-response-store` is a framework-agnostic, programmatic response store for Cloudflare Workers. It combines Workers Cache for edge delivery, R2 for response bodies, and a SQLite Durable Object for strongly consistent metadata, revisions, and tag invalidation.
|
|
4
4
|
|
|
5
|
-
Use it to add persistent response caching, stale-while-revalidate (SWR), on-demand refresh, and purge APIs to a Worker or framework adapter. It supports either a dedicated cache Worker accessed through a service binding or a self-contained Worker deployment.
|
|
5
|
+
Use it to add persistent response caching, stale-while-revalidate (SWR), on-demand refresh, invalidation, and purge APIs to a Worker or framework adapter. It supports either a dedicated cache Worker accessed through a service binding or a self-contained Worker deployment.
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
@@ -83,7 +83,7 @@ const responseStore = createWorkersResponseStoreClient<Env>({
|
|
|
83
83
|
export const { ResponseStoreRevalidator, ResponseStoreClient } = responseStore.entrypoints;
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
-
The client exposes the same read, write, refresh, and purge methods as self-contained mode. There is no reverse service binding or circular deployment: deploy the cache Worker, then deploy the application Worker.
|
|
86
|
+
The client exposes the same read, write, refresh, invalidate, and purge methods as self-contained mode. There is no reverse service binding or circular deployment: deploy the cache Worker, then deploy the application Worker.
|
|
87
87
|
|
|
88
88
|
## Single-Worker setup
|
|
89
89
|
|
|
@@ -175,13 +175,14 @@ This is the minimum integration loop. A framework can add its own cacheability r
|
|
|
175
175
|
|
|
176
176
|
The object returned by `createWorkersResponseStore()` and `createWorkersResponseStoreClient()` implements the same API:
|
|
177
177
|
|
|
178
|
-
| Method | Behavior
|
|
179
|
-
| ------------------------------------------------ |
|
|
180
|
-
| `fetch(request)` | Reads a canonical `GET` cache key. Returns a stored response or a `404` Response Store miss.
|
|
181
|
-
| `put(request, response, options?)` | Stores a response under a canonical `GET` cache key. `options.revalidator` supplies `{ id, args }` for future regeneration. Set `purgeExisting: true` when replacing an entry that may already be in Workers Cache.
|
|
182
|
-
| `refresh({ tags, pathPrefixes })` | Regenerates matching entries
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
178
|
+
| Method | Behavior |
|
|
179
|
+
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
180
|
+
| `fetch(request)` | Reads a canonical `GET` cache key. Returns a stored response or a `404` Response Store miss. Unconditional stale reads return immediately and regenerate in the background; Workers Cache conditional revalidations and hard-expired reads wait for regeneration, unless the entry was stored with `expiryBehavior: "miss"`. |
|
|
181
|
+
| `put(request, response, options?)` | Stores a response under a canonical `GET` cache key. `options.revalidator` supplies `{ id, args }` for future regeneration. Set `purgeExisting: true` when replacing an entry that may already be in Workers Cache. Set `expiryBehavior: "miss"` to get a miss instead of a regeneration once the entry expires. |
|
|
182
|
+
| `refresh({ tags, pathPrefixes })` | Regenerates matching entries, then invalidates their prior edge responses: Workers Cache marks them stale and refetches the committed revisions in the background. At least one selector is required. |
|
|
183
|
+
| `invalidate({ tags, pathPrefixes, expire })` | Marks matching entries stale without regenerating them. Reads keep serving them through their stale-while-revalidate window, capped at `expire` seconds after the call when set, and regenerate them like any stale entry. Like Next.js, an `expire` deadline also caps entries with those tags published before it. Workers Cache refetches the edge responses of entries with a revalidator in the background and purges the others. At least one selector is required. |
|
|
184
|
+
| `purge({ tags, pathPrefixes, purgeEverything })` | Removes matching metadata, records tag invalidations, deletes response bodies, and purges corresponding edge responses. At least one selector or `purgeEverything: true` is required. |
|
|
185
|
+
| `getTagExpiration(tags)` | Returns the latest invalidation timestamp for a set of framework-managed soft tags. Most integrations do not need this low-level method. |
|
|
185
186
|
|
|
186
187
|
Mutation methods return:
|
|
187
188
|
|
|
@@ -192,6 +193,8 @@ type ResponseStoreMutationResult = {
|
|
|
192
193
|
};
|
|
193
194
|
```
|
|
194
195
|
|
|
196
|
+
`edgePurgeAccepted` reports whether Workers Cache accepted the edge update: a purge for `put()` and `purge()`, or an invalidation for `refresh()` and `invalidate()` (which purges entries without a revalidator). Local Miniflare does not implement `ctx.cache.invalidate()` yet, so `refresh()` and `invalidate()` purge there instead.
|
|
197
|
+
|
|
195
198
|
### Cache keys
|
|
196
199
|
|
|
197
200
|
- Keys must be `GET` requests.
|
|
@@ -204,16 +207,18 @@ type ResponseStoreMutationResult = {
|
|
|
204
207
|
|
|
205
208
|
Freshness is derived from `Cloudflare-CDN-Cache-Control`, then `CDN-Cache-Control`, then `Cache-Control`. The store preserves an incoming `Age` value and advances it while the response is stored.
|
|
206
209
|
|
|
207
|
-
|
|
210
|
+
Stored responses preserve application-provided validators and include a revision-specific `ETag` when none is provided. A generated `Last-Modified` would conflate revisions written within the same second. Workers Cache sends validators back as `If-None-Match` or `If-Modified-Since` when revalidating. If the backing response is stale, that invocation claims regeneration and returns the committed response directly to Workers Cache, avoiding a second layer of SWR. If another invocation already holds the claim, the callback fails so Workers Cache can retain its stale response and retry. Fresh backing responses are reused without regeneration. Conditional headers identify revalidation, including foreground expiry; they do not identify background execution specifically.
|
|
211
|
+
|
|
212
|
+
Set `Cache-Tag` on the response passed to `put()` to associate comma-separated purge tags. `refresh()`, `invalidate()`, and `purge()` also accept pathname prefixes. Tags are matched case-insensitively for invalidation.
|
|
208
213
|
|
|
209
214
|
The `regenerate` callback receives the stored `id` and `args`, a canonical cache-key request, and one of these reasons:
|
|
210
215
|
|
|
211
|
-
| Reason | Trigger
|
|
212
|
-
| --------- |
|
|
213
|
-
| `swr` | A stale
|
|
214
|
-
| `expired` | The response passed its SWR window and the read must wait.
|
|
215
|
-
| `missing` | The R2 object exists but its committed response content is unavailable.
|
|
216
|
-
| `manual` | `refresh()` selected the entry.
|
|
216
|
+
| Reason | Trigger |
|
|
217
|
+
| --------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
218
|
+
| `swr` | A stale entry inside its SWR window is regenerated, either for an unconditional read or a Workers Cache revalidation. |
|
|
219
|
+
| `expired` | The response passed its SWR window and the read must wait. |
|
|
220
|
+
| `missing` | The R2 object exists but its committed response content is unavailable. |
|
|
221
|
+
| `manual` | `refresh()` selected the entry. |
|
|
217
222
|
|
|
218
223
|
### Response headers
|
|
219
224
|
|
|
@@ -245,7 +250,7 @@ const responseStore = createWorkersResponseStore<Env>({
|
|
|
245
250
|
|
|
246
251
|
`shards` must be an integer greater than one. Without it, all version-scoped metadata uses the original single Durable Object.
|
|
247
252
|
|
|
248
|
-
Each cache key and all its revisions, claims, and pending objects route to one deterministic shard. Refresh and purge fan out across every shard, while tag invalidation timestamps are replicated so publication fencing and soft-tag checks remain correct. Soft-tag reads select a stable replica to distribute load.
|
|
253
|
+
Each cache key and all its revisions, claims, and pending objects route to one deterministic shard. Refresh, invalidation, and purge fan out across every shard, while tag invalidation timestamps are replicated so publication fencing and soft-tag checks remain correct. Soft-tag reads select a stable replica to distribute load.
|
|
249
254
|
|
|
250
255
|
Changing the shard count selects a new metadata and R2 layout. Treat it as a cache-cold deployment change, not an in-place scaling control.
|
|
251
256
|
|
|
@@ -274,12 +279,13 @@ application Worker
|
|
|
274
279
|
└─ regeneration ───────► application callback
|
|
275
280
|
```
|
|
276
281
|
|
|
277
|
-
- Responses use `runtime-cache/<version-id>/r2-
|
|
282
|
+
- Responses use `runtime-cache/<version-id>/r2-v2/[shards-<count>/]<digest>/active`. The layout segment isolates this R2-backed implementation from older cache-Worker versions during service-binding rollbacks and rolling deployments.
|
|
278
283
|
- SQLite revisions and conditional publication prevent slow writes from replacing newer writes or resurrecting purged entries. User RPC, R2, and cache-purge I/O run outside SQLite transactions.
|
|
279
284
|
- Purging replaces the active R2 object with a higher-revision tombstone. A later put can replace that tombstone, but an older delayed write cannot recreate purged content.
|
|
280
285
|
- R2 tombstones are durably queued in SQLite and drained in bounded batches. A failed R2 operation leaves its tombstone queued so a later purge can retry it instead of losing the anti-resurrection fence.
|
|
281
|
-
-
|
|
282
|
-
-
|
|
286
|
+
- Invalidation rewrites each matching R2 object as a stale copy under a higher revision through the same queue, so a write reserved before the invalidation cannot publish over it. If R2 does not hold the entry's committed revision yet, the key is tombstoned instead.
|
|
287
|
+
- An unconditional read of stale R2 content returns immediately while `ctx.waitUntil()` runs one claimed regeneration. A conditional Workers Cache revalidation instead waits for regeneration and returns the committed replacement in that same invocation.
|
|
288
|
+
- Hard-expired responses are never served. Reads wait for regeneration and therefore require a stored revalidator descriptor, unless the entry was stored with `expiryBehavior: "miss"`: such a read returns a Response Store miss and starts no regeneration, so the caller regenerates the value itself. `refresh()` still regenerates the entry through its revalidator.
|
|
283
289
|
- Abandoned write reservations are retained for one hour before alarm-driven cleanup fences them from later publication. Response bodies are written only after Durable Object publication, so this cleanup does not perform R2 operations.
|
|
284
290
|
- RPC-transferred response bodies are buffered before R2 writes because transferred streams do not retain the fixed-length marker required by R2's single-part put API. Account for Worker memory limits when choosing maximum response sizes.
|
|
285
291
|
- Service-binding callbacks remain pinned to the application Worker version that supplied the revalidator capability.
|
|
@@ -294,7 +300,7 @@ Keep every version that can still receive traffic or be rolled back to. When a v
|
|
|
294
300
|
|
|
295
301
|
1. If it is still addressable, call `purge({ purgeEverything: true })` through that version to tombstone its metadata and active R2 response objects. This also requests a broad edge-cache purge, so other versions may need to refill.
|
|
296
302
|
2. Delete any remaining objects under its R2 prefix: `runtime-cache/<version-id>/` contains every storage layout and shard count for that application version.
|
|
297
|
-
3. If you need to reclaim the retired metadata Durable Object's SQLite storage, use an application-owned administrative path to call `deleteAll()` on each known object. The current layout is named `<version-id>:r2-
|
|
303
|
+
3. If you need to reclaim the retired metadata Durable Object's SQLite storage, use an application-owned administrative path to call `deleteAll()` on each known object. The current layout is named `<version-id>:r2-v2` without sharding, or `<version-id>:r2-v2:metadata-shard:<index>-of-<count>` for each shard. Older layouts may have additional objects. This cleanup is outside the package API.
|
|
298
304
|
|
|
299
305
|
Do not delete the shared Durable Object namespace while active versions use it. Avoid an age-only R2 lifecycle rule unless it is guaranteed to outlive every valid response and rollback window; explicit retired-version prefixes avoid deleting old but still-active cache entries.
|
|
300
306
|
|
package/dist/binding.d.ts
CHANGED
|
@@ -12,11 +12,26 @@ export type ResponseStorePutOptions = {
|
|
|
12
12
|
coalesce?: boolean;
|
|
13
13
|
revalidator?: RevalidatorDescriptor;
|
|
14
14
|
purgeExisting?: boolean;
|
|
15
|
-
|
|
15
|
+
/**
|
|
16
|
+
* What a read does once the entry is past its stale-while-revalidate window.
|
|
17
|
+
* `"regenerate"` (the default) waits for the revalidator. `"miss"` returns a
|
|
18
|
+
* Response Store miss so the caller regenerates the value itself; `refresh()`
|
|
19
|
+
* still regenerates the entry through its revalidator.
|
|
20
|
+
*/
|
|
21
|
+
expiryBehavior?: ExpiryBehavior;
|
|
22
|
+
};
|
|
23
|
+
export type ExpiryBehavior = "regenerate" | "miss";
|
|
16
24
|
export type ResponseStoreRefreshOptions = {
|
|
17
25
|
tags?: string[];
|
|
18
26
|
pathPrefixes?: string[];
|
|
19
27
|
};
|
|
28
|
+
export type ResponseStoreInvalidateOptions = ResponseStoreRefreshOptions & {
|
|
29
|
+
/**
|
|
30
|
+
* Seconds after the invalidation when matching entries stop being served
|
|
31
|
+
* stale. Without it, entries keep their stored stale-while-revalidate window.
|
|
32
|
+
*/
|
|
33
|
+
expire?: number;
|
|
34
|
+
};
|
|
20
35
|
export type ResponseStorePurgeOptions = ResponseStoreRefreshOptions & {
|
|
21
36
|
purgeEverything?: boolean;
|
|
22
37
|
};
|
|
@@ -37,6 +52,7 @@ export type WorkersResponseStore = {
|
|
|
37
52
|
getTagExpiration(tags: string[]): Promise<number>;
|
|
38
53
|
put(request: Request, response: Response, options?: ResponseStorePutOptions): Promise<ResponseStoreMutationResult>;
|
|
39
54
|
refresh(options: ResponseStoreRefreshOptions): Promise<ResponseStoreMutationResult>;
|
|
55
|
+
invalidate(options: ResponseStoreInvalidateOptions): Promise<ResponseStoreMutationResult>;
|
|
40
56
|
purge(options: ResponseStorePurgeOptions): Promise<ResponseStoreMutationResult>;
|
|
41
57
|
};
|
|
42
58
|
type EntryMetadata = {
|
|
@@ -46,6 +62,7 @@ type EntryMetadata = {
|
|
|
46
62
|
freshUntil: number;
|
|
47
63
|
swrUntil: number;
|
|
48
64
|
revalidator: RevalidatorDescriptor | null;
|
|
65
|
+
expiryBehavior: ExpiryBehavior;
|
|
49
66
|
cacheTags: string[];
|
|
50
67
|
};
|
|
51
68
|
export type CandidateMetadata = EntryMetadata & {
|
|
@@ -69,6 +86,8 @@ export type PurgedEntry = {
|
|
|
69
86
|
cacheKey: string;
|
|
70
87
|
objectKey: string;
|
|
71
88
|
revision: number;
|
|
89
|
+
/** Invalidate rather than purge the edge response: the entry was marked stale. */
|
|
90
|
+
edgeInvalidate?: boolean;
|
|
72
91
|
};
|
|
73
92
|
export type RevalidationService = {
|
|
74
93
|
regenerate(input: RevalidationInput): Promise<Response>;
|
|
@@ -102,9 +121,10 @@ export declare class ResponseStoreService extends WorkerEntrypoint<WorkersRespon
|
|
|
102
121
|
getTagExpiration(tags: string[], invocation: ResponseStoreServiceInvocation): Promise<number>;
|
|
103
122
|
put(request: Request, response: Response, options: ResponseStorePutOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
|
|
104
123
|
refresh(options: ResponseStoreRefreshOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
|
|
124
|
+
invalidate(options: ResponseStoreInvalidateOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
|
|
105
125
|
purge(options: ResponseStorePurgeOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
|
|
106
126
|
}
|
|
107
|
-
export type ResponseStoreServiceBinding = Pick<ResponseStoreService, "read" | "getTagExpiration" | "put" | "refresh" | "purge">;
|
|
127
|
+
export type ResponseStoreServiceBinding = Pick<ResponseStoreService, "read" | "getTagExpiration" | "put" | "refresh" | "invalidate" | "purge">;
|
|
108
128
|
export declare function validateResponseStoreShards(shards: number | undefined): number | undefined;
|
|
109
129
|
export declare class ResponseStoreBinding extends WorkerEntrypoint<WorkersResponseStoreEnv, WorkersResponseStoreProps> {
|
|
110
130
|
private readonly shardCount;
|
|
@@ -116,8 +136,19 @@ export declare class ResponseStoreBinding extends WorkerEntrypoint<WorkersRespon
|
|
|
116
136
|
private invalidateEntryRead;
|
|
117
137
|
private getTagMetadata;
|
|
118
138
|
private deriveCacheKey;
|
|
119
|
-
|
|
120
|
-
|
|
139
|
+
/**
|
|
140
|
+
* `purge` deletes matching edge responses. `invalidate` marks them stale so
|
|
141
|
+
* Workers Cache keeps serving them while it refetches from this binding in
|
|
142
|
+
* the background.
|
|
143
|
+
*/
|
|
144
|
+
private updateEdgeCache;
|
|
145
|
+
private updateEdgeCacheByTags;
|
|
146
|
+
/**
|
|
147
|
+
* Update drained entries' edge responses. Stale entries with a revalidator
|
|
148
|
+
* are invalidated, so Workers Cache keeps serving them while it refetches.
|
|
149
|
+
* Tombstones are purged, as are stale entries the Store cannot regenerate,
|
|
150
|
+
* so their next read reaches R2 and sees `BLOB-STALE`.
|
|
151
|
+
*/
|
|
121
152
|
purgeR2TombstoneEdges(entries: PurgedEntry[]): Promise<boolean>;
|
|
122
153
|
private purgePendingEdgeEntries;
|
|
123
154
|
private objectKeyRoot;
|
|
@@ -136,11 +167,22 @@ export declare class ResponseStoreBinding extends WorkerEntrypoint<WorkersRespon
|
|
|
136
167
|
private readStoredResponse;
|
|
137
168
|
private storeResponse;
|
|
138
169
|
private regenerateEntry;
|
|
170
|
+
private revalidateEntry;
|
|
139
171
|
private revalidateEntryInBackground;
|
|
140
172
|
fetch(request: Request): Promise<Response>;
|
|
141
173
|
getTagExpiration(tags: string[]): Promise<number>;
|
|
142
174
|
put(request: Request, response: Response, options?: ResponseStorePutOptions): Promise<ResponseStoreMutationResult>;
|
|
143
175
|
refresh(options: ResponseStoreRefreshOptions): Promise<ResponseStoreMutationResult>;
|
|
176
|
+
/**
|
|
177
|
+
* Marks matching entries stale. Reads keep serving them within their
|
|
178
|
+
* stale-while-revalidate window (capped by `expire`) while the next read
|
|
179
|
+
* regenerates them, instead of `refresh()` regenerating every match now.
|
|
180
|
+
*/
|
|
181
|
+
invalidate(options: ResponseStoreInvalidateOptions): Promise<ResponseStoreMutationResult>;
|
|
182
|
+
/** Write each shard's queued R2 tombstones and stale rewrites in bounded batches. */
|
|
183
|
+
private drainReservations;
|
|
184
|
+
/** Update the edge responses of drained entries, collecting failures. */
|
|
185
|
+
private updatePendingEdges;
|
|
144
186
|
purge(options: ResponseStorePurgeOptions): Promise<ResponseStoreMutationResult>;
|
|
145
187
|
}
|
|
146
188
|
//#endregion
|
package/dist/binding.js
CHANGED
|
@@ -48,6 +48,9 @@ var ResponseStoreService = class extends WorkerEntrypoint {
|
|
|
48
48
|
refresh(options, invocation) {
|
|
49
49
|
return this.getStore(invocation).refresh(options);
|
|
50
50
|
}
|
|
51
|
+
invalidate(options, invocation) {
|
|
52
|
+
return this.getStore(invocation).invalidate(options);
|
|
53
|
+
}
|
|
51
54
|
purge(options, invocation) {
|
|
52
55
|
return this.getStore(invocation).purge(options);
|
|
53
56
|
}
|
|
@@ -72,7 +75,7 @@ const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
|
|
|
72
75
|
304
|
|
73
76
|
]);
|
|
74
77
|
const AGE_BASIS_HEADER = "X-Workers-Response-Store-Age-Basis";
|
|
75
|
-
const STORAGE_LAYOUT_VERSION = "r2-
|
|
78
|
+
const STORAGE_LAYOUT_VERSION = "r2-v2";
|
|
76
79
|
const pendingPuts = /* @__PURE__ */ new Map();
|
|
77
80
|
const pendingR2Reads = /* @__PURE__ */ new Map();
|
|
78
81
|
const entryReads = new IsolateNegativeCache(ISOLATE_MISS_CACHE_CAPACITY, ISOLATE_MISS_CACHE_TTL_MS);
|
|
@@ -234,40 +237,54 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
234
237
|
keyHash: [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("")
|
|
235
238
|
};
|
|
236
239
|
}
|
|
237
|
-
|
|
240
|
+
/**
|
|
241
|
+
* `purge` deletes matching edge responses. `invalidate` marks them stale so
|
|
242
|
+
* Workers Cache keeps serving them while it refetches from this binding in
|
|
243
|
+
* the background.
|
|
244
|
+
*/
|
|
245
|
+
async updateEdgeCache(options, operation = "purge") {
|
|
238
246
|
if (this.env.WORKERS_RESPONSE_STORE_E2E_EDGE_PURGE_MODE === "disabled") return false;
|
|
239
|
-
|
|
247
|
+
const cache = this.ctx.cache;
|
|
248
|
+
if (!cache) {
|
|
240
249
|
console.error(JSON.stringify({
|
|
241
|
-
message:
|
|
250
|
+
message: `Workers Response Store cache ${operation} is unavailable`,
|
|
242
251
|
reason: "ctx.cache is absent"
|
|
243
252
|
}));
|
|
244
253
|
return false;
|
|
245
254
|
}
|
|
246
255
|
try {
|
|
247
|
-
const result = await
|
|
248
|
-
if (!result.success) throw new Error(result.errors.map(({ code, message }) => `${code}: ${message}`).join(", ") ||
|
|
256
|
+
const result = operation === "invalidate" && typeof cache.invalidate === "function" ? await cache.invalidate(options) : await cache.purge(options);
|
|
257
|
+
if (!result.success) throw new Error(result.errors.map(({ code, message }) => `${code}: ${message}`).join(", ") || `Workers Response Store cache ${operation} was rejected`);
|
|
249
258
|
return true;
|
|
250
259
|
} catch (error) {
|
|
251
260
|
console.error(JSON.stringify({
|
|
252
|
-
message:
|
|
261
|
+
message: `Workers Response Store cache ${operation} failed`,
|
|
253
262
|
error: error instanceof Error ? error.message : String(error)
|
|
254
263
|
}));
|
|
255
|
-
|
|
264
|
+
return false;
|
|
256
265
|
}
|
|
257
266
|
}
|
|
258
|
-
async
|
|
267
|
+
async updateEdgeCacheByTags(tags, operation = "purge") {
|
|
259
268
|
let accepted = true;
|
|
260
|
-
for (const batch of batches(tags, CACHE_PURGE_BATCH_SIZE)) if (!await this.
|
|
269
|
+
for (const batch of batches(tags, CACHE_PURGE_BATCH_SIZE)) if (!await this.updateEdgeCache({ tags: batch }, operation)) accepted = false;
|
|
261
270
|
return accepted;
|
|
262
271
|
}
|
|
272
|
+
/**
|
|
273
|
+
* Update drained entries' edge responses. Stale entries with a revalidator
|
|
274
|
+
* are invalidated, so Workers Cache keeps serving them while it refetches.
|
|
275
|
+
* Tombstones are purged, as are stale entries the Store cannot regenerate,
|
|
276
|
+
* so their next read reaches R2 and sees `BLOB-STALE`.
|
|
277
|
+
*/
|
|
263
278
|
async purgeR2TombstoneEdges(entries) {
|
|
264
|
-
|
|
279
|
+
const invalidated = entries.filter((entry) => entry.edgeInvalidate);
|
|
280
|
+
const purged = entries.filter((entry) => !entry.edgeInvalidate);
|
|
281
|
+
return (await Promise.all([!purged.length || this.updateEdgeCacheByTags(purged.map(purgeTagForEntry)), !invalidated.length || this.updateEdgeCacheByTags(invalidated.map(purgeTagForEntry), "invalidate")])).every(Boolean);
|
|
265
282
|
}
|
|
266
283
|
async purgePendingEdgeEntries(metadata, tombstoneSequence) {
|
|
267
284
|
for (;;) {
|
|
268
285
|
const entries = await metadata.listPendingEdgePurges(PURGE_TOMBSTONE_BATCH_SIZE, tombstoneSequence);
|
|
269
286
|
if (!entries.length) return true;
|
|
270
|
-
if (!await this.
|
|
287
|
+
if (!await this.purgeR2TombstoneEdges(entries)) return false;
|
|
271
288
|
await metadata.markTombstonesEdgePurged(entries);
|
|
272
289
|
}
|
|
273
290
|
}
|
|
@@ -305,6 +322,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
305
322
|
freshUntil,
|
|
306
323
|
swrUntil,
|
|
307
324
|
revalidator: null,
|
|
325
|
+
expiryBehavior: metadata.expiryBehavior === "miss" ? "miss" : "regenerate",
|
|
308
326
|
cacheTags: [],
|
|
309
327
|
activeRevision: latestRevision,
|
|
310
328
|
latestRevision
|
|
@@ -370,7 +388,8 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
370
388
|
responseHeaders,
|
|
371
389
|
freshUntil: String(entry.freshUntil),
|
|
372
390
|
swrUntil: String(entry.swrUntil),
|
|
373
|
-
latestRevision: String(entry.activeRevision)
|
|
391
|
+
latestRevision: String(entry.activeRevision),
|
|
392
|
+
...entry.expiryBehavior === "miss" ? { expiryBehavior: "miss" } : {}
|
|
374
393
|
};
|
|
375
394
|
if (customMetadataSize(customMetadata) > R2_CUSTOM_METADATA_SAFE_BYTES) {
|
|
376
395
|
const responseMetadata = new TextEncoder().encode(JSON.stringify({
|
|
@@ -385,7 +404,8 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
385
404
|
responseMetadataBytes: String(responseMetadata.byteLength),
|
|
386
405
|
freshUntil: String(entry.freshUntil),
|
|
387
406
|
swrUntil: String(entry.swrUntil),
|
|
388
|
-
latestRevision: String(entry.activeRevision)
|
|
407
|
+
latestRevision: String(entry.activeRevision),
|
|
408
|
+
...entry.expiryBehavior === "miss" ? { expiryBehavior: "miss" } : {}
|
|
389
409
|
};
|
|
390
410
|
}
|
|
391
411
|
return await this.writeR2Revision(this.r2ObjectKey(entry.keyHash), entry.activeRevision, storedBody, customMetadata, expectedEtag);
|
|
@@ -420,6 +440,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
420
440
|
}
|
|
421
441
|
createStoredResponse(entry, body, status, createdAt, initialAge, now = Date.now()) {
|
|
422
442
|
const headers = new Headers(entry.responseHeaders);
|
|
443
|
+
if (!headers.has("ETag")) headers.set("ETag", `W/"${encodeURIComponent(entry.objectKey)}:${entry.activeRevision}"`);
|
|
423
444
|
headers.set(AGE_BASIS_HEADER, `${createdAt}:${initialAge}`);
|
|
424
445
|
headers.set("Age", String(representationAge(createdAt, initialAge, now)));
|
|
425
446
|
headers.set("Cloudflare-CDN-Cache-Control", edgeCacheControl(entry.freshUntil, entry.swrUntil, now));
|
|
@@ -467,7 +488,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
467
488
|
if (!body) await storedBody.cancel();
|
|
468
489
|
return this.createStoredResponse(storedEntry, body, status, createdAt, initialAge, now);
|
|
469
490
|
}
|
|
470
|
-
async storeResponse(metadata, request, response, revalidator, reservation, cacheTags = cacheTagsFromResponse(response), expectedR2Etag) {
|
|
491
|
+
async storeResponse(metadata, request, response, revalidator, expiryBehavior, reservation, cacheTags = cacheTagsFromResponse(response), expectedR2Etag) {
|
|
471
492
|
const cacheKey = reservation ?? await this.deriveCacheKey(request);
|
|
472
493
|
const write = reservation ?? await this.reserveWrite(metadata, cacheKey, cacheTags);
|
|
473
494
|
const { keyHash, objectKey: reservationObjectKey, revision } = write;
|
|
@@ -489,6 +510,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
489
510
|
freshUntil: policy.freshUntil,
|
|
490
511
|
swrUntil: policy.swrUntil,
|
|
491
512
|
revalidator: revalidator ?? null,
|
|
513
|
+
expiryBehavior,
|
|
492
514
|
cacheTags
|
|
493
515
|
};
|
|
494
516
|
body = response.body ? await response.arrayBuffer() : /* @__PURE__ */ new ArrayBuffer(0);
|
|
@@ -513,8 +535,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
513
535
|
}));
|
|
514
536
|
const reconciliationFailures = reconciliation.failures.map((failure) => new Error(failure));
|
|
515
537
|
if (reconciliation.purged.length) try {
|
|
516
|
-
await this.
|
|
517
|
-
await metadata.markTombstonesEdgePurged(reconciliation.purged);
|
|
538
|
+
if (await this.updateEdgeCacheByTags(reconciliation.purged.map(purgeTagForEntry))) await metadata.markTombstonesEdgePurged(reconciliation.purged);
|
|
518
539
|
} catch (reconciliationError) {
|
|
519
540
|
reconciliationFailures.push(reconciliationError instanceof Error ? reconciliationError : new Error(String(reconciliationError)));
|
|
520
541
|
}
|
|
@@ -555,20 +576,23 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
555
576
|
await this.releaseFailedWrite(metadata, writeReservation);
|
|
556
577
|
throw error;
|
|
557
578
|
}
|
|
558
|
-
return this.storeResponse(metadata, cacheRequest, response, entry.revalidator, writeReservation, void 0, expectedR2Etag);
|
|
579
|
+
return this.storeResponse(metadata, cacheRequest, response, entry.revalidator, entry.expiryBehavior, writeReservation, void 0, expectedR2Etag);
|
|
559
580
|
}
|
|
560
|
-
async
|
|
581
|
+
async revalidateEntry(metadata, entry, expectedR2Etag) {
|
|
561
582
|
const claim = await metadata.claimRevalidation(entry.keyHash, entry.activeRevision, entry.cacheKey, this.objectKeyPrefix(entry.keyHash), Date.now(), BACKGROUND_REVALIDATION_LEASE_MS);
|
|
562
|
-
if (!claim) return;
|
|
583
|
+
if (!claim) return null;
|
|
584
|
+
return this.regenerateEntry(metadata, claim.entry, "swr", {
|
|
585
|
+
cacheKey: claim.entry.cacheKey,
|
|
586
|
+
claimId: claim.claimId,
|
|
587
|
+
fenceTags: claim.entry.cacheTags,
|
|
588
|
+
keyHash: claim.entry.keyHash,
|
|
589
|
+
objectKey: claim.objectKey,
|
|
590
|
+
revision: claim.revision
|
|
591
|
+
}, expectedR2Etag);
|
|
592
|
+
}
|
|
593
|
+
async revalidateEntryInBackground(metadata, entry, expectedR2Etag) {
|
|
563
594
|
try {
|
|
564
|
-
await this.
|
|
565
|
-
cacheKey: claim.entry.cacheKey,
|
|
566
|
-
claimId: claim.claimId,
|
|
567
|
-
fenceTags: claim.entry.cacheTags,
|
|
568
|
-
keyHash: claim.entry.keyHash,
|
|
569
|
-
objectKey: claim.objectKey,
|
|
570
|
-
revision: claim.revision
|
|
571
|
-
}, expectedR2Etag);
|
|
595
|
+
await this.revalidateEntry(metadata, entry, expectedR2Etag);
|
|
572
596
|
} catch (error) {
|
|
573
597
|
console.error(JSON.stringify({
|
|
574
598
|
message: "Workers Response Store SWR regeneration failed",
|
|
@@ -588,7 +612,8 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
588
612
|
headers: MISS_HEADERS
|
|
589
613
|
});
|
|
590
614
|
const now = Date.now();
|
|
591
|
-
|
|
615
|
+
const revalidateStale = now >= entry.freshUntil && (request.headers.has("If-None-Match") || request.headers.has("If-Modified-Since"));
|
|
616
|
+
if (now < entry.swrUntil && !revalidateStale) {
|
|
592
617
|
const stored = await this.readStoredResponse(entry, now, r2Read?.object);
|
|
593
618
|
if (stored) {
|
|
594
619
|
if (now < entry.freshUntil) return stored;
|
|
@@ -600,17 +625,28 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
600
625
|
}
|
|
601
626
|
}
|
|
602
627
|
await r2Read?.object?.body.cancel().catch(() => {});
|
|
603
|
-
|
|
604
|
-
const regeneration = await metadata.reserveRegeneration(keyHash, cacheKey.cacheKey, this.objectKeyPrefix(keyHash), now);
|
|
605
|
-
if (!regeneration) return new Response("Workers Response Store miss", {
|
|
628
|
+
if (now >= entry.swrUntil && entry.expiryBehavior === "miss") return new Response("Workers Response Store miss", {
|
|
606
629
|
status: 404,
|
|
607
630
|
headers: MISS_HEADERS
|
|
608
631
|
});
|
|
609
|
-
const
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
632
|
+
const metadata = this.getMetadata(keyHash);
|
|
633
|
+
let regenerated;
|
|
634
|
+
if (revalidateStale && now < entry.swrUntil) {
|
|
635
|
+
const result = await this.revalidateEntry(metadata, entry, expectedR2Etag);
|
|
636
|
+
if (!result?.published) throw new Error("Cache entry revalidation is already in progress or was superseded");
|
|
637
|
+
regenerated = result;
|
|
638
|
+
} else {
|
|
639
|
+
const regeneration = await metadata.reserveRegeneration(keyHash, cacheKey.cacheKey, this.objectKeyPrefix(keyHash), now);
|
|
640
|
+
if (!regeneration) return new Response("Workers Response Store miss", {
|
|
641
|
+
status: 404,
|
|
642
|
+
headers: MISS_HEADERS
|
|
643
|
+
});
|
|
644
|
+
regenerated = await this.regenerateEntry(metadata, regeneration.entry, now >= entry.swrUntil ? "expired" : "missing", regeneration.reservation ? {
|
|
645
|
+
...cacheKey,
|
|
646
|
+
fenceTags: regeneration.entry.cacheTags,
|
|
647
|
+
...regeneration.reservation
|
|
648
|
+
} : void 0, expectedR2Etag);
|
|
649
|
+
}
|
|
614
650
|
if (!regenerated.entry) throw new Error("Regeneration was superseded and no active entry remains");
|
|
615
651
|
let response = regenerated.response;
|
|
616
652
|
if (!response) {
|
|
@@ -662,14 +698,14 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
662
698
|
response.body?.cancel().catch(() => {});
|
|
663
699
|
return {
|
|
664
700
|
backingStoreUpdated: true,
|
|
665
|
-
edgePurgeAccepted: options.purgeExisting && result.edgePurgeRequired ? await this.
|
|
701
|
+
edgePurgeAccepted: options.purgeExisting && result.edgePurgeRequired ? await this.updateEdgeCacheByTags([purgeTagForEntry(result.entry)]) : true
|
|
666
702
|
};
|
|
667
703
|
}
|
|
668
704
|
if (pendingPuts.get(pendingPutKey) === pending) pendingPuts.delete(pendingPutKey);
|
|
669
705
|
}
|
|
670
706
|
const write = (async () => {
|
|
671
707
|
reservation ??= await this.reserveWrite(metadata, cacheKey, cacheTags);
|
|
672
|
-
return this.storeResponse(metadata, request, response, options.revalidator, reservation, cacheTags);
|
|
708
|
+
return this.storeResponse(metadata, request, response, options.revalidator, options.expiryBehavior === "miss" ? "miss" : "regenerate", reservation, cacheTags);
|
|
673
709
|
})();
|
|
674
710
|
if (options.coalesce) pendingPuts.set(pendingPutKey, write);
|
|
675
711
|
try {
|
|
@@ -680,7 +716,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
680
716
|
};
|
|
681
717
|
return {
|
|
682
718
|
backingStoreUpdated: true,
|
|
683
|
-
edgePurgeAccepted: options.purgeExisting && result.edgePurgeRequired ? await this.
|
|
719
|
+
edgePurgeAccepted: options.purgeExisting && result.edgePurgeRequired ? await this.updateEdgeCacheByTags([purgeTagForEntry(result.entry)]) : true
|
|
684
720
|
};
|
|
685
721
|
} finally {
|
|
686
722
|
if (options.coalesce && pendingPuts.get(pendingPutKey) === write) pendingPuts.delete(pendingPutKey);
|
|
@@ -719,17 +755,37 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
719
755
|
const refreshed = [];
|
|
720
756
|
for (const result of settled) if (result.status === "rejected") failures.push(result.reason);
|
|
721
757
|
else if (result.value) refreshed.push(result.value);
|
|
722
|
-
const edgePurgeAccepted = refreshed.length ? await this.
|
|
758
|
+
const edgePurgeAccepted = refreshed.length ? await this.updateEdgeCacheByTags(refreshed.map((entry) => purgeTagForEntry(entry)), "invalidate") : false;
|
|
723
759
|
if (failures.length) throw new AggregateError(failures, "One or more cache entries failed to refresh");
|
|
724
760
|
return {
|
|
725
761
|
backingStoreUpdated: refreshed.length === candidates.length,
|
|
726
762
|
edgePurgeAccepted
|
|
727
763
|
};
|
|
728
764
|
}
|
|
729
|
-
|
|
730
|
-
|
|
765
|
+
/**
|
|
766
|
+
* Marks matching entries stale. Reads keep serving them within their
|
|
767
|
+
* stale-while-revalidate window (capped by `expire`) while the next read
|
|
768
|
+
* regenerates them, instead of `refresh()` regenerating every match now.
|
|
769
|
+
*/
|
|
770
|
+
async invalidate(options) {
|
|
771
|
+
if (!options.tags?.length && !options.pathPrefixes?.length) throw new TypeError("invalidate() requires tags or pathPrefixes");
|
|
772
|
+
if (options.expire !== void 0 && !(typeof options.expire === "number" && options.expire >= 0)) throw new TypeError("invalidate() expire must be a non-negative number of seconds");
|
|
731
773
|
const invalidatedAt = Date.now();
|
|
732
|
-
const
|
|
774
|
+
const expiresAt = options.expire === void 0 || !Number.isFinite(options.expire) ? void 0 : invalidatedAt + Math.ceil(options.expire * 1e3);
|
|
775
|
+
const selectors = {
|
|
776
|
+
tags: options.tags,
|
|
777
|
+
pathPrefixes: options.pathPrefixes
|
|
778
|
+
};
|
|
779
|
+
const { failures, reservations } = await this.drainReservations(await Promise.allSettled(this.getMetadataShards().map((metadata) => metadata.invalidateMatching(selectors, invalidatedAt, expiresAt))));
|
|
780
|
+
const edgePurgeAccepted = await this.updatePendingEdges(reservations, failures);
|
|
781
|
+
if (failures.length) throw new AggregateError(failures, "One or more metadata shards failed to invalidate");
|
|
782
|
+
return {
|
|
783
|
+
backingStoreUpdated: reservations.some(({ reservation }) => reservation.backingStoreUpdated),
|
|
784
|
+
edgePurgeAccepted
|
|
785
|
+
};
|
|
786
|
+
}
|
|
787
|
+
/** Write each shard's queued R2 tombstones and stale rewrites in bounded batches. */
|
|
788
|
+
async drainReservations(settled) {
|
|
733
789
|
const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
|
|
734
790
|
const reservations = settled.flatMap((result, index) => result.status === "fulfilled" ? [{
|
|
735
791
|
metadata: this.getMetadataShard(index),
|
|
@@ -746,9 +802,26 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
746
802
|
failures.push(error);
|
|
747
803
|
}
|
|
748
804
|
}
|
|
805
|
+
return {
|
|
806
|
+
failures,
|
|
807
|
+
reservations
|
|
808
|
+
};
|
|
809
|
+
}
|
|
810
|
+
/** Update the edge responses of drained entries, collecting failures. */
|
|
811
|
+
async updatePendingEdges(reservations, failures) {
|
|
812
|
+
let edgePurgeAccepted = true;
|
|
813
|
+
const acknowledged = await Promise.allSettled(reservations.filter(({ reservation }) => reservation.pendingTombstones > 0).map(({ metadata, reservation }) => this.purgePendingEdgeEntries(metadata, reservation.tombstoneSequence)));
|
|
814
|
+
for (const result of acknowledged) if (result.status === "rejected") failures.push(result.reason);
|
|
815
|
+
else if (!result.value) edgePurgeAccepted = false;
|
|
816
|
+
return edgePurgeAccepted;
|
|
817
|
+
}
|
|
818
|
+
async purge(options) {
|
|
819
|
+
if (!options.purgeEverything && !options.tags?.length && !options.pathPrefixes?.length) throw new TypeError("purge() requires tags, pathPrefixes, or purgeEverything");
|
|
820
|
+
const invalidatedAt = Date.now();
|
|
821
|
+
const { failures, reservations } = await this.drainReservations(await Promise.allSettled(this.getMetadataShards().map((metadata) => metadata.purgeMatching(options, invalidatedAt))));
|
|
749
822
|
let edgePurgeAccepted = true;
|
|
750
823
|
if (options.purgeEverything && failures.length === 0) try {
|
|
751
|
-
edgePurgeAccepted = await this.
|
|
824
|
+
edgePurgeAccepted = await this.updateEdgeCache({ purgeEverything: true });
|
|
752
825
|
if (edgePurgeAccepted) {
|
|
753
826
|
const acknowledged = await Promise.allSettled(reservations.map(({ metadata, reservation }) => metadata.markTombstonesEdgePurgedThrough(reservation.tombstoneSequence)));
|
|
754
827
|
for (const result of acknowledged) if (result.status === "rejected") failures.push(result.reason);
|
|
@@ -757,12 +830,7 @@ var ResponseStoreBinding = class extends WorkerEntrypoint {
|
|
|
757
830
|
edgePurgeAccepted = false;
|
|
758
831
|
failures.push(error);
|
|
759
832
|
}
|
|
760
|
-
else
|
|
761
|
-
if (options.purgeEverything) edgePurgeAccepted = false;
|
|
762
|
-
const acknowledged = await Promise.allSettled(reservations.filter(({ reservation }) => reservation.pendingTombstones > 0).map(({ metadata, reservation }) => this.purgePendingEdgeEntries(metadata, reservation.tombstoneSequence)));
|
|
763
|
-
for (const result of acknowledged) if (result.status === "rejected") failures.push(result.reason);
|
|
764
|
-
else if (!result.value) edgePurgeAccepted = false;
|
|
765
|
-
}
|
|
833
|
+
else edgePurgeAccepted = await this.updatePendingEdges(reservations, failures) && !options.purgeEverything;
|
|
766
834
|
if (failures.length) throw new AggregateError(failures, "One or more metadata shards failed to purge");
|
|
767
835
|
return {
|
|
768
836
|
backingStoreUpdated: reservations.some(({ reservation }) => reservation.backingStoreUpdated || reservation.pendingTombstones > 0),
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ResponseStoreBinding, ResponseStoreLocationHint, ResponseStoreMutationResult, ResponseStorePurgeOptions, ResponseStorePutOptions, ResponseStoreRefreshOptions, RevalidationInput, RevalidationReason, RevalidationService, SerializableValue, WorkersResponseStore, WorkersResponseStoreEnv } from "./binding.js";
|
|
1
|
+
import { ExpiryBehavior, ResponseStoreBinding, ResponseStoreInvalidateOptions, ResponseStoreLocationHint, ResponseStoreMutationResult, ResponseStorePurgeOptions, ResponseStorePutOptions, ResponseStoreRefreshOptions, RevalidationInput, RevalidationReason, RevalidationService, SerializableValue, WorkersResponseStore, WorkersResponseStoreEnv } from "./binding.js";
|
|
2
2
|
import { CacheMetadata } from "./metadata-do.js";
|
|
3
3
|
import { WorkerEntrypoint } from "cloudflare:workers";
|
|
4
4
|
//#region src/index.d.ts
|
|
@@ -39,4 +39,4 @@ export type WorkersResponseStoreClientEnv = {
|
|
|
39
39
|
};
|
|
40
40
|
export declare function createWorkersResponseStoreClient<Env extends WorkersResponseStoreClientEnv = WorkersResponseStoreClientEnv>(options: WorkersResponseStoreOptions<Env>): WorkersResponseStoreClientDefinition<Env>;
|
|
41
41
|
//#endregion
|
|
42
|
-
export type { ResponseStoreLocationHint, ResponseStoreMutationResult, ResponseStorePurgeOptions, ResponseStorePutOptions, ResponseStoreRefreshOptions, RevalidationInput, RevalidationReason, SerializableValue, WorkersResponseStore, WorkersResponseStoreEnv };
|
|
42
|
+
export type { ExpiryBehavior, ResponseStoreInvalidateOptions, ResponseStoreLocationHint, ResponseStoreMutationResult, ResponseStorePurgeOptions, ResponseStorePutOptions, ResponseStoreRefreshOptions, RevalidationInput, RevalidationReason, SerializableValue, WorkersResponseStore, WorkersResponseStoreEnv };
|
package/dist/index.js
CHANGED
|
@@ -18,6 +18,7 @@ function createStoreFacade(getStore) {
|
|
|
18
18
|
getTagExpiration: (tags) => getStore().getTagExpiration(tags),
|
|
19
19
|
put: (request, response, options) => getStore().put(request, response, options),
|
|
20
20
|
refresh: (options) => getStore().refresh(options),
|
|
21
|
+
invalidate: (options) => getStore().invalidate(options),
|
|
21
22
|
purge: (options) => getStore().purge(options)
|
|
22
23
|
};
|
|
23
24
|
}
|
|
@@ -70,6 +71,9 @@ function createWorkersResponseStoreClient(options) {
|
|
|
70
71
|
refresh(refreshOptions) {
|
|
71
72
|
return this.service.refresh(refreshOptions, this.getInvocation());
|
|
72
73
|
}
|
|
74
|
+
invalidate(invalidateOptions) {
|
|
75
|
+
return this.service.invalidate(invalidateOptions, this.getInvocation());
|
|
76
|
+
}
|
|
73
77
|
purge(purgeOptions) {
|
|
74
78
|
return this.service.purge(purgeOptions, this.getInvocation());
|
|
75
79
|
}
|
package/dist/metadata-do.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { CandidateMetadata, PurgedEntry, RefreshCandidate, ResponseStorePurgeOptions, ResponseStoreRefreshOptions, StoredEntry } from "./binding.js";
|
|
1
|
+
import { CandidateMetadata, PurgedEntry, RefreshCandidate, ResponseStoreInvalidateOptions, ResponseStorePurgeOptions, ResponseStoreRefreshOptions, StoredEntry } from "./binding.js";
|
|
2
2
|
import { DurableObject } from "cloudflare:workers";
|
|
3
3
|
//#region src/metadata-do.d.ts
|
|
4
4
|
type RevalidationClaim = {
|
|
@@ -21,7 +21,7 @@ type RegenerationReservation = {
|
|
|
21
21
|
entry: StoredEntry;
|
|
22
22
|
reservation?: WriteReservation;
|
|
23
23
|
};
|
|
24
|
-
type PurgeReservation = {
|
|
24
|
+
export type PurgeReservation = {
|
|
25
25
|
backingStoreUpdated: boolean;
|
|
26
26
|
pendingTombstones: number;
|
|
27
27
|
tombstoneSequence: number;
|
|
@@ -50,6 +50,7 @@ export type CacheMetadataStub = DurableObjectStub & {
|
|
|
50
50
|
findRefreshCandidates(options: ResponseStoreRefreshOptions): Promise<StoredEntry[]>;
|
|
51
51
|
findRefreshCandidates(options: ResponseStoreRefreshOptions, projection: "reservation"): Promise<RefreshCandidate[]>;
|
|
52
52
|
purgeMatching(options: ResponseStorePurgeOptions, invalidatedAt?: number): Promise<PurgeReservation>;
|
|
53
|
+
invalidateMatching(options: Pick<ResponseStoreInvalidateOptions, "tags" | "pathPrefixes">, invalidatedAt: number, expiresAt?: number): Promise<PurgeReservation>;
|
|
53
54
|
drainPendingTombstones(limit: number, keyHash?: string, afterKeyHash?: string, tombstoneSequence?: number): Promise<TombstoneDrainResult>;
|
|
54
55
|
retryPendingTombstones(): Promise<boolean>;
|
|
55
56
|
listPendingEdgePurges(limit: number, tombstoneSequence?: number): Promise<PurgedEntry[]>;
|
|
@@ -87,11 +88,27 @@ export declare class CacheMetadata extends DurableObject<CacheMetadataEnv> {
|
|
|
87
88
|
invalidatePublishedRevision(keyHash: string, revision: number): Promise<TombstoneDrainResult>;
|
|
88
89
|
getEntry(keyHash: string): StoredEntry | null;
|
|
89
90
|
private getTagInvalidationMaximum;
|
|
91
|
+
/** The earliest `expire` deadline still ahead of `now` among `tags`, or Infinity. */
|
|
92
|
+
private getTagExpiryDeadline;
|
|
90
93
|
getTagExpiration(tags: string[]): number;
|
|
91
94
|
findRefreshCandidates(options: ResponseStoreRefreshOptions): StoredEntry[];
|
|
92
95
|
findRefreshCandidates(options: ResponseStoreRefreshOptions, projection: "reservation"): RefreshCandidate[];
|
|
96
|
+
/**
|
|
97
|
+
* Fence writes reserved before an invalidation from publishing over it.
|
|
98
|
+
* `invalidatedAt` also expires the tags for soft-tag reads; pass 0 to leave
|
|
99
|
+
* their expiration unchanged. Like Next.js, `expiresAt` replaces the tags'
|
|
100
|
+
* deadline for entries published before it; null keeps the current one.
|
|
101
|
+
*/
|
|
102
|
+
private recordInvalidations;
|
|
93
103
|
purgeMatching(options: ResponseStorePurgeOptions, invalidatedAt?: number): Promise<PurgeReservation>;
|
|
94
|
-
|
|
104
|
+
/**
|
|
105
|
+
* Mark matching entries stale without deleting them. Each entry moves to a
|
|
106
|
+
* new revision with its freshness ended and its SWR window capped at
|
|
107
|
+
* `expiresAt`, and its R2 object is queued for the same rewrite, so writes
|
|
108
|
+
* reserved before the invalidation cannot publish over it.
|
|
109
|
+
*/
|
|
110
|
+
invalidateMatching(options: Pick<ResponseStoreInvalidateOptions, "tags" | "pathPrefixes">, invalidatedAt: number, expiresAt?: number): Promise<PurgeReservation>;
|
|
111
|
+
private writeR2Update;
|
|
95
112
|
private finishCompletedTombstones;
|
|
96
113
|
drainPendingTombstones(limit: number, keyHash?: string, afterKeyHash?: string, tombstoneSequence?: number): Promise<TombstoneDrainResult>;
|
|
97
114
|
listPendingEdgePurges(limit: number, tombstoneSequence?: number): PurgedEntry[];
|
package/dist/metadata-do.js
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import { mapSettledWithR2Concurrency } from "./r2-concurrency.js";
|
|
2
2
|
import { DurableObject } from "cloudflare:workers";
|
|
3
3
|
//#region src/metadata-do.ts
|
|
4
|
+
const REFRESHABLE_ENTRY = `tombstoned = 0 AND active_revision IS NOT NULL
|
|
5
|
+
AND object_key IS NOT NULL AND response_headers IS NOT NULL
|
|
6
|
+
AND fresh_until IS NOT NULL AND swr_until IS NOT NULL`;
|
|
4
7
|
const MAX_SQL_PARAMETERS = 100;
|
|
5
8
|
const ORPHAN_RETENTION_MS = 36e5;
|
|
6
9
|
const ORPHAN_CLEANUP_LIMIT = 100;
|
|
@@ -34,9 +37,19 @@ function storedEntryFromRow(row) {
|
|
|
34
37
|
id: row.revalidator_id,
|
|
35
38
|
args: JSON.parse(row.revalidator_args ?? "[]")
|
|
36
39
|
},
|
|
40
|
+
expiryBehavior: row.expiry_behavior === "miss" ? "miss" : "regenerate",
|
|
37
41
|
cacheTags: JSON.parse(row.cache_tags ?? "[]")
|
|
38
42
|
};
|
|
39
43
|
}
|
|
44
|
+
function pendingEntryFromRow(row) {
|
|
45
|
+
return {
|
|
46
|
+
keyHash: row.key_hash,
|
|
47
|
+
cacheKey: row.cache_key,
|
|
48
|
+
objectKey: row.object_key,
|
|
49
|
+
revision: row.revision,
|
|
50
|
+
...row.edge_invalidate ? { edgeInvalidate: true } : {}
|
|
51
|
+
};
|
|
52
|
+
}
|
|
40
53
|
function storedEntriesFromRows(rows) {
|
|
41
54
|
const entries = [];
|
|
42
55
|
for (const row of rows) {
|
|
@@ -63,6 +76,7 @@ var CacheMetadata = class extends DurableObject {
|
|
|
63
76
|
swr_until INTEGER,
|
|
64
77
|
revalidator_id TEXT,
|
|
65
78
|
revalidator_args TEXT,
|
|
79
|
+
expiry_behavior TEXT,
|
|
66
80
|
cache_tags TEXT,
|
|
67
81
|
tombstoned INTEGER NOT NULL DEFAULT 0
|
|
68
82
|
);
|
|
@@ -86,7 +100,8 @@ var CacheMetadata = class extends DurableObject {
|
|
|
86
100
|
CREATE TABLE IF NOT EXISTS tag_invalidations (
|
|
87
101
|
tag TEXT PRIMARY KEY,
|
|
88
102
|
invalidated_at INTEGER NOT NULL,
|
|
89
|
-
invalidation_sequence INTEGER NOT NULL DEFAULT 0
|
|
103
|
+
invalidation_sequence INTEGER NOT NULL DEFAULT 0,
|
|
104
|
+
expires_at INTEGER
|
|
90
105
|
) WITHOUT ROWID;
|
|
91
106
|
CREATE TABLE IF NOT EXISTS metadata_schema_migrations (
|
|
92
107
|
version INTEGER PRIMARY KEY
|
|
@@ -115,15 +130,19 @@ var CacheMetadata = class extends DurableObject {
|
|
|
115
130
|
revision INTEGER NOT NULL,
|
|
116
131
|
r2_complete INTEGER NOT NULL DEFAULT 0,
|
|
117
132
|
edge_purge_complete INTEGER NOT NULL DEFAULT 0,
|
|
118
|
-
tombstone_sequence INTEGER NOT NULL DEFAULT 0
|
|
133
|
+
tombstone_sequence INTEGER NOT NULL DEFAULT 0,
|
|
134
|
+
source_revision INTEGER,
|
|
135
|
+
fresh_until INTEGER,
|
|
136
|
+
swr_until INTEGER,
|
|
137
|
+
edge_invalidate INTEGER NOT NULL DEFAULT 0
|
|
119
138
|
) WITHOUT ROWID;
|
|
120
139
|
`);
|
|
121
140
|
ctx.storage.transactionSync(() => {
|
|
122
|
-
const migrations = new Set(ctx.storage.sql.exec("SELECT version FROM metadata_schema_migrations WHERE version IN (2, 3, 4, 5, 6)").toArray().map(({ version }) => version));
|
|
123
|
-
if (migrations.size ===
|
|
141
|
+
const migrations = new Set(ctx.storage.sql.exec("SELECT version FROM metadata_schema_migrations WHERE version IN (2, 3, 4, 5, 6, 7, 8)").toArray().map(({ version }) => version));
|
|
142
|
+
if (migrations.size === 7) return;
|
|
124
143
|
const schemas = ctx.storage.sql.exec(`SELECT name, sql FROM sqlite_schema
|
|
125
144
|
WHERE type = 'table'
|
|
126
|
-
AND name IN ('tag_invalidations', 'metadata_state', 'pending_objects', 'pending_r2_tombstones')`).toArray();
|
|
145
|
+
AND name IN ('entries', 'tag_invalidations', 'metadata_state', 'pending_objects', 'pending_r2_tombstones')`).toArray();
|
|
127
146
|
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");
|
|
128
147
|
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");
|
|
129
148
|
if (!migrations.has(2)) ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (2)");
|
|
@@ -150,6 +169,20 @@ var CacheMetadata = class extends DurableObject {
|
|
|
150
169
|
for (const entry of entries) this.replaceEntryTags(entry.key_hash, JSON.parse(entry.cache_tags));
|
|
151
170
|
ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (6)");
|
|
152
171
|
}
|
|
172
|
+
if (!migrations.has(7)) {
|
|
173
|
+
if (!schemas.find(({ name }) => name === "entries")?.sql.includes("expiry_behavior")) ctx.storage.sql.exec("ALTER TABLE entries ADD COLUMN expiry_behavior TEXT");
|
|
174
|
+
ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (7)");
|
|
175
|
+
}
|
|
176
|
+
if (!migrations.has(8)) {
|
|
177
|
+
if (!schemas.find(({ name }) => name === "tag_invalidations")?.sql.includes("expires_at")) ctx.storage.sql.exec("ALTER TABLE tag_invalidations ADD COLUMN expires_at INTEGER");
|
|
178
|
+
if (!(schemas.find(({ name }) => name === "pending_r2_tombstones")?.sql)?.includes("edge_invalidate")) ctx.storage.sql.exec(`
|
|
179
|
+
ALTER TABLE pending_r2_tombstones ADD COLUMN source_revision INTEGER;
|
|
180
|
+
ALTER TABLE pending_r2_tombstones ADD COLUMN fresh_until INTEGER;
|
|
181
|
+
ALTER TABLE pending_r2_tombstones ADD COLUMN swr_until INTEGER;
|
|
182
|
+
ALTER TABLE pending_r2_tombstones ADD COLUMN edge_invalidate INTEGER NOT NULL DEFAULT 0;
|
|
183
|
+
`);
|
|
184
|
+
ctx.storage.sql.exec("INSERT INTO metadata_schema_migrations (version) VALUES (8)");
|
|
185
|
+
}
|
|
153
186
|
});
|
|
154
187
|
ctx.storage.sql.exec(`
|
|
155
188
|
CREATE INDEX IF NOT EXISTS pending_r2_tombstones_r2_pending
|
|
@@ -215,10 +248,10 @@ var CacheMetadata = class extends DurableObject {
|
|
|
215
248
|
}
|
|
216
249
|
if (!options.purgeEverything && !selectors.length) return [];
|
|
217
250
|
const conditions = [];
|
|
218
|
-
if (projection
|
|
219
|
-
if (projection === "refresh") conditions.push(
|
|
251
|
+
if (projection === "entry") conditions.push("tombstoned = 0 AND active_revision IS NOT NULL");
|
|
252
|
+
if (projection === "refresh") conditions.push(REFRESHABLE_ENTRY);
|
|
220
253
|
if (!options.purgeEverything) conditions.push(`(${selectors.join(" OR ")})`);
|
|
221
|
-
return this.ctx.storage.sql.exec(`SELECT ${projection === "purge" ? "key_hash, cache_key, latest_revision, object_key" : projection === "refresh" ?
|
|
254
|
+
return this.ctx.storage.sql.exec(`SELECT ${projection === "purge" ? "key_hash, cache_key, latest_revision, object_key" : projection === "refresh" || projection === "invalidate" ? `key_hash, cache_key, active_revision, latest_revision, object_key, fresh_until, swr_until, revalidator_id IS NOT NULL AS has_revalidator${projection === "invalidate" ? `, ${REFRESHABLE_ENTRY} AS refreshable` : ""}` : "*"} FROM entries ${conditions.length ? `WHERE ${conditions.join(" AND ")}` : ""}`, ...parameters).toArray();
|
|
222
255
|
}
|
|
223
256
|
replaceEntryTags(keyHash, tags) {
|
|
224
257
|
this.ctx.storage.sql.exec("DELETE FROM entry_tags WHERE key_hash = ?", keyHash);
|
|
@@ -428,13 +461,16 @@ var CacheMetadata = class extends DurableObject {
|
|
|
428
461
|
published: false
|
|
429
462
|
};
|
|
430
463
|
}
|
|
464
|
+
const deadline = this.getTagExpiryDeadline(metadata.cacheTags, Date.now());
|
|
465
|
+
const freshUntil = Math.min(metadata.freshUntil, deadline);
|
|
466
|
+
const swrUntil = Math.min(metadata.swrUntil, deadline);
|
|
431
467
|
const published = this.ctx.storage.sql.exec(`UPDATE entries SET
|
|
432
468
|
active_revision = ?, object_key = ?, status_text = ?, response_headers = ?,
|
|
433
469
|
fresh_until = ?, swr_until = ?,
|
|
434
|
-
revalidator_id = ?, revalidator_args = ?, cache_tags = ?, tombstoned = 0
|
|
470
|
+
revalidator_id = ?, revalidator_args = ?, expiry_behavior = ?, cache_tags = ?, tombstoned = 0
|
|
435
471
|
WHERE key_hash = ? AND latest_revision >= ?
|
|
436
472
|
AND (active_revision IS NULL OR active_revision < ?)
|
|
437
|
-
RETURNING key_hash`, revision, metadata.objectKey, metadata.statusText, JSON.stringify(metadata.responseHeaders),
|
|
473
|
+
RETURNING key_hash`, revision, metadata.objectKey, metadata.statusText, JSON.stringify(metadata.responseHeaders), freshUntil, swrUntil, metadata.revalidator?.id ?? null, metadata.revalidator ? JSON.stringify(metadata.revalidator.args) : null, metadata.expiryBehavior === "miss" ? "miss" : null, JSON.stringify(metadata.cacheTags), keyHash, revision, revision).toArray().length === 1;
|
|
438
474
|
if (published) this.replaceEntryTags(keyHash, metadata.cacheTags);
|
|
439
475
|
this.ctx.storage.sql.exec("DELETE FROM pending_objects WHERE object_key = ?", reservationObjectKey);
|
|
440
476
|
if (claimId) this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ? AND claim_id = ?", keyHash, claimId);
|
|
@@ -446,9 +482,10 @@ var CacheMetadata = class extends DurableObject {
|
|
|
446
482
|
objectKey: metadata.objectKey,
|
|
447
483
|
statusText: metadata.statusText,
|
|
448
484
|
responseHeaders: metadata.responseHeaders,
|
|
449
|
-
freshUntil
|
|
450
|
-
swrUntil
|
|
485
|
+
freshUntil,
|
|
486
|
+
swrUntil,
|
|
451
487
|
revalidator: metadata.revalidator,
|
|
488
|
+
expiryBehavior: metadata.expiryBehavior,
|
|
452
489
|
cacheTags: metadata.cacheTags
|
|
453
490
|
};
|
|
454
491
|
return {
|
|
@@ -471,7 +508,7 @@ var CacheMetadata = class extends DurableObject {
|
|
|
471
508
|
latest_revision = ?, active_revision = ?, object_key = NULL,
|
|
472
509
|
status_text = NULL, response_headers = NULL, fresh_until = NULL,
|
|
473
510
|
swr_until = NULL, revalidator_id = NULL, revalidator_args = NULL,
|
|
474
|
-
cache_tags = NULL, tombstoned = 1
|
|
511
|
+
expiry_behavior = NULL, cache_tags = NULL, tombstoned = 1
|
|
475
512
|
WHERE key_hash = ? AND active_revision = ?`, tombstoneRevision, tombstoneRevision, keyHash, revision);
|
|
476
513
|
this.ctx.storage.sql.exec("DELETE FROM revalidation_claims WHERE key_hash = ?", keyHash);
|
|
477
514
|
this.ctx.storage.sql.exec("DELETE FROM entry_tags WHERE key_hash = ?", keyHash);
|
|
@@ -499,6 +536,16 @@ var CacheMetadata = class extends DurableObject {
|
|
|
499
536
|
}
|
|
500
537
|
return expiration;
|
|
501
538
|
}
|
|
539
|
+
/** The earliest `expire` deadline still ahead of `now` among `tags`, or Infinity. */
|
|
540
|
+
getTagExpiryDeadline(tags, now) {
|
|
541
|
+
let deadline = Number.POSITIVE_INFINITY;
|
|
542
|
+
for (const batch of batches(normalizeTags(tags), 99)) {
|
|
543
|
+
const row = this.ctx.storage.sql.exec(`SELECT MIN(expires_at) AS deadline FROM tag_invalidations
|
|
544
|
+
WHERE expires_at > ? AND tag IN (${batch.map(() => "?").join(", ")})`, now, ...batch).one();
|
|
545
|
+
deadline = Math.min(deadline, row.deadline ?? Number.POSITIVE_INFINITY);
|
|
546
|
+
}
|
|
547
|
+
return deadline;
|
|
548
|
+
}
|
|
502
549
|
getTagExpiration(tags) {
|
|
503
550
|
return this.getTagInvalidationMaximum(tags, "invalidated_at");
|
|
504
551
|
}
|
|
@@ -512,24 +559,38 @@ var CacheMetadata = class extends DurableObject {
|
|
|
512
559
|
hasRevalidator: row.has_revalidator === 1
|
|
513
560
|
}));
|
|
514
561
|
}
|
|
562
|
+
/**
|
|
563
|
+
* Fence writes reserved before an invalidation from publishing over it.
|
|
564
|
+
* `invalidatedAt` also expires the tags for soft-tag reads; pass 0 to leave
|
|
565
|
+
* their expiration unchanged. Like Next.js, `expiresAt` replaces the tags'
|
|
566
|
+
* deadline for entries published before it; null keeps the current one.
|
|
567
|
+
*/
|
|
568
|
+
recordInvalidations(keyHashes, tags, invalidatedAt, expiresAt) {
|
|
569
|
+
this.ctx.storage.sql.exec(`UPDATE metadata_state SET tag_invalidation_sequence = tag_invalidation_sequence + 1
|
|
570
|
+
WHERE singleton = 1`);
|
|
571
|
+
for (const batch of batches(keyHashes, 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(", ")}
|
|
572
|
+
ON CONFLICT(key_hash) DO UPDATE SET invalidation_sequence =
|
|
573
|
+
MAX(key_invalidations.invalidation_sequence, excluded.invalidation_sequence)`, ...batch);
|
|
574
|
+
for (const batch of batches(tags, Math.floor(MAX_SQL_PARAMETERS / 3))) this.ctx.storage.sql.exec(`INSERT INTO tag_invalidations
|
|
575
|
+
(tag, invalidated_at, expires_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
|
|
576
|
+
ON CONFLICT(tag) DO UPDATE SET invalidated_at =
|
|
577
|
+
MAX(tag_invalidations.invalidated_at, excluded.invalidated_at),
|
|
578
|
+
expires_at = COALESCE(excluded.expires_at, tag_invalidations.expires_at),
|
|
579
|
+
invalidation_sequence = MAX(
|
|
580
|
+
tag_invalidations.invalidation_sequence,
|
|
581
|
+
excluded.invalidation_sequence
|
|
582
|
+
)`, ...batch.flatMap((tag) => [
|
|
583
|
+
tag,
|
|
584
|
+
invalidatedAt,
|
|
585
|
+
expiresAt
|
|
586
|
+
]));
|
|
587
|
+
}
|
|
515
588
|
async purgeMatching(options, invalidatedAt = Date.now()) {
|
|
516
589
|
const reservation = this.ctx.storage.transactionSync(() => {
|
|
517
590
|
const matches = this.findMatchingEntryRows(options, "purge");
|
|
518
591
|
const tombstoneSequence = this.tombstoneSequence(matches.some((row) => row.object_key !== null));
|
|
519
592
|
const tags = normalizeTags(options.tags ?? []);
|
|
520
|
-
this.
|
|
521
|
-
WHERE singleton = 1`);
|
|
522
|
-
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(", ")}
|
|
523
|
-
ON CONFLICT(key_hash) DO UPDATE SET invalidation_sequence =
|
|
524
|
-
MAX(key_invalidations.invalidation_sequence, excluded.invalidation_sequence)`, ...batch.map((row) => row.key_hash));
|
|
525
|
-
for (const batch of batches(tags, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`INSERT INTO tag_invalidations
|
|
526
|
-
(tag, invalidated_at, invalidation_sequence) VALUES ${batch.map(() => "(?, ?, (SELECT tag_invalidation_sequence FROM metadata_state WHERE singleton = 1))").join(", ")}
|
|
527
|
-
ON CONFLICT(tag) DO UPDATE SET invalidated_at =
|
|
528
|
-
MAX(tag_invalidations.invalidated_at, excluded.invalidated_at),
|
|
529
|
-
invalidation_sequence = MAX(
|
|
530
|
-
tag_invalidations.invalidation_sequence,
|
|
531
|
-
excluded.invalidation_sequence
|
|
532
|
-
)`, ...batch.flatMap((tag) => [tag, invalidatedAt]));
|
|
593
|
+
this.recordInvalidations(matches.map((row) => row.key_hash), tags, invalidatedAt, invalidatedAt);
|
|
533
594
|
for (const batch of batches(matches, 99)) {
|
|
534
595
|
const active = batch.filter((row) => row.object_key !== null);
|
|
535
596
|
for (const entryBatch of batches(active, MAX_SQL_PARAMETERS / 5)) this.ctx.storage.sql.exec(`INSERT OR REPLACE INTO pending_r2_tombstones
|
|
@@ -552,6 +613,7 @@ var CacheMetadata = class extends DurableObject {
|
|
|
552
613
|
swr_until = NULL,
|
|
553
614
|
revalidator_id = NULL,
|
|
554
615
|
revalidator_args = NULL,
|
|
616
|
+
expiry_behavior = NULL,
|
|
555
617
|
cache_tags = NULL,
|
|
556
618
|
tombstoned = 1
|
|
557
619
|
WHERE key_hash IN (${placeholders})`, ...keyHashes);
|
|
@@ -567,24 +629,108 @@ var CacheMetadata = class extends DurableObject {
|
|
|
567
629
|
if (reservation.pendingTombstones > 0) await this.scheduleCleanupAlarm(Date.now() + ORPHAN_CLEANUP_RETRY_MS).catch((error) => this.logCleanupFailure(error));
|
|
568
630
|
return reservation;
|
|
569
631
|
}
|
|
570
|
-
|
|
571
|
-
|
|
632
|
+
/**
|
|
633
|
+
* Mark matching entries stale without deleting them. Each entry moves to a
|
|
634
|
+
* new revision with its freshness ended and its SWR window capped at
|
|
635
|
+
* `expiresAt`, and its R2 object is queued for the same rewrite, so writes
|
|
636
|
+
* reserved before the invalidation cannot publish over it.
|
|
637
|
+
*/
|
|
638
|
+
async invalidateMatching(options, invalidatedAt, expiresAt) {
|
|
639
|
+
const reservation = this.ctx.storage.transactionSync(() => {
|
|
640
|
+
const rows = this.findMatchingEntryRows(options, "invalidate");
|
|
641
|
+
const matches = rows.filter((row) => Boolean(row.refreshable));
|
|
642
|
+
const reserved = rows.filter((row) => !row.refreshable).map((row) => row.key_hash);
|
|
643
|
+
const tags = normalizeTags(options.tags ?? []);
|
|
644
|
+
const tombstoneSequence = this.tombstoneSequence(matches.length > 0);
|
|
645
|
+
this.recordInvalidations(rows.map((row) => row.key_hash), tags, 0, expiresAt ?? null);
|
|
646
|
+
for (const batch of batches(reserved, MAX_SQL_PARAMETERS)) this.ctx.storage.sql.exec(`UPDATE entries SET
|
|
647
|
+
latest_revision = latest_revision + 1,
|
|
648
|
+
active_revision = latest_revision + 1
|
|
649
|
+
WHERE tombstoned = 1 AND key_hash IN (${batch.map(() => "?").join(", ")})`, ...batch);
|
|
650
|
+
for (const batch of batches(matches, MAX_SQL_PARAMETERS / 10)) this.ctx.storage.sql.exec(`INSERT INTO pending_r2_tombstones
|
|
651
|
+
(key_hash, cache_key, object_key, revision, tombstone_sequence,
|
|
652
|
+
source_revision, fresh_until, swr_until, edge_invalidate) VALUES ${batch.map(() => "(?, ?, ?, ?, ?, ?, ?, ?, ?)").join(", ")}
|
|
653
|
+
ON CONFLICT(key_hash) DO UPDATE SET
|
|
654
|
+
cache_key = excluded.cache_key,
|
|
655
|
+
object_key = excluded.object_key,
|
|
656
|
+
revision = excluded.revision,
|
|
657
|
+
tombstone_sequence = excluded.tombstone_sequence,
|
|
658
|
+
source_revision = CASE
|
|
659
|
+
WHEN pending_r2_tombstones.r2_complete = 0
|
|
660
|
+
AND pending_r2_tombstones.source_revision IS NOT NULL
|
|
661
|
+
AND pending_r2_tombstones.revision = excluded.source_revision
|
|
662
|
+
THEN pending_r2_tombstones.source_revision
|
|
663
|
+
ELSE excluded.source_revision
|
|
664
|
+
END,
|
|
665
|
+
fresh_until = excluded.fresh_until,
|
|
666
|
+
swr_until = excluded.swr_until,
|
|
667
|
+
edge_invalidate = MIN(pending_r2_tombstones.edge_invalidate, excluded.edge_invalidate),
|
|
668
|
+
r2_complete = 0,
|
|
669
|
+
edge_purge_complete = 0`, ...batch.flatMap((row) => [
|
|
670
|
+
row.key_hash,
|
|
671
|
+
row.cache_key,
|
|
672
|
+
row.object_key,
|
|
673
|
+
row.latest_revision + 1,
|
|
674
|
+
tombstoneSequence,
|
|
675
|
+
row.active_revision,
|
|
676
|
+
Math.min(row.fresh_until, invalidatedAt),
|
|
677
|
+
Math.min(row.swr_until, expiresAt ?? row.swr_until),
|
|
678
|
+
row.has_revalidator
|
|
679
|
+
]));
|
|
680
|
+
for (const batch of batches(matches, 98)) {
|
|
681
|
+
const keyHashes = batch.map((row) => row.key_hash);
|
|
682
|
+
const placeholders = keyHashes.map(() => "?").join(", ");
|
|
683
|
+
this.ctx.storage.sql.exec(`UPDATE entries SET
|
|
684
|
+
latest_revision = latest_revision + 1,
|
|
685
|
+
active_revision = latest_revision + 1,
|
|
686
|
+
fresh_until = MIN(fresh_until, ?),
|
|
687
|
+
swr_until = MIN(swr_until, COALESCE(?, swr_until))
|
|
688
|
+
WHERE key_hash IN (${placeholders})`, invalidatedAt, expiresAt ?? null, ...keyHashes);
|
|
689
|
+
this.ctx.storage.sql.exec(`DELETE FROM revalidation_claims WHERE key_hash IN (${placeholders})`, ...keyHashes);
|
|
690
|
+
}
|
|
691
|
+
return {
|
|
692
|
+
backingStoreUpdated: matches.length > 0 || reserved.length > 0 || tags.length > 0,
|
|
693
|
+
pendingTombstones: matches.length,
|
|
694
|
+
tombstoneSequence
|
|
695
|
+
};
|
|
696
|
+
});
|
|
697
|
+
if (reservation.pendingTombstones > 0) await this.scheduleCleanupAlarm(Date.now() + ORPHAN_CLEANUP_RETRY_MS).catch((error) => this.logCleanupFailure(error));
|
|
698
|
+
return reservation;
|
|
699
|
+
}
|
|
700
|
+
async writeR2Update(entry) {
|
|
701
|
+
const { stale, ...updated } = entry;
|
|
702
|
+
const completed = (tombstoned) => tombstoned ? {
|
|
703
|
+
...updated,
|
|
704
|
+
edgeInvalidate: false
|
|
705
|
+
} : updated;
|
|
572
706
|
for (let attempt = 0; attempt < MAX_R2_CAS_ATTEMPTS; attempt++) {
|
|
573
|
-
const
|
|
707
|
+
const object = stale ? await this.env.CACHE_BODIES.get(entry.objectKey) : null;
|
|
708
|
+
const current = stale ? object : await this.env.CACHE_BODIES.head(entry.objectKey);
|
|
574
709
|
const currentRevision = metadataInteger(current?.customMetadata?.latestRevision);
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
710
|
+
const tombstoned = current?.customMetadata?.tombstoned === "1";
|
|
711
|
+
if (currentRevision !== void 0 && currentRevision >= entry.revision) {
|
|
712
|
+
await object?.body.cancel();
|
|
713
|
+
return completed(tombstoned);
|
|
714
|
+
}
|
|
715
|
+
const restale = stale !== void 0 && !tombstoned && currentRevision !== void 0 && currentRevision >= stale.sourceRevision;
|
|
716
|
+
if (object && !restale) await object.body.cancel();
|
|
717
|
+
if (await this.env.CACHE_BODIES.put(entry.objectKey, restale && object ? object.body : /* @__PURE__ */ new Uint8Array(), {
|
|
718
|
+
onlyIf: current ? { etagMatches: current.etag } : { etagDoesNotMatch: "*" },
|
|
719
|
+
customMetadata: restale && object ? {
|
|
720
|
+
...object.customMetadata,
|
|
721
|
+
latestRevision: String(entry.revision),
|
|
722
|
+
freshUntil: String(stale.freshUntil),
|
|
723
|
+
swrUntil: String(stale.swrUntil)
|
|
724
|
+
} : {
|
|
580
725
|
latestRevision: String(entry.revision),
|
|
581
726
|
tombstoned: "1"
|
|
582
727
|
}
|
|
583
|
-
})) return;
|
|
728
|
+
})) return completed(!restale);
|
|
584
729
|
}
|
|
585
|
-
const
|
|
586
|
-
|
|
587
|
-
|
|
730
|
+
const current = await this.env.CACHE_BODIES.head(entry.objectKey);
|
|
731
|
+
const currentRevision = metadataInteger(current?.customMetadata?.latestRevision);
|
|
732
|
+
if (currentRevision !== void 0 && currentRevision >= entry.revision) return completed(current?.customMetadata?.tombstoned === "1");
|
|
733
|
+
throw new Error(`R2 revision ${entry.revision} could not be ${stale ? "invalidated" : "tombstoned"} after concurrent writes`);
|
|
588
734
|
}
|
|
589
735
|
finishCompletedTombstones(entries) {
|
|
590
736
|
for (const batch of batches(entries, MAX_SQL_PARAMETERS / 2)) this.ctx.storage.sql.exec(`DELETE FROM pending_r2_tombstones
|
|
@@ -606,23 +752,25 @@ var CacheMetadata = class extends DurableObject {
|
|
|
606
752
|
parameters.push(tombstoneSequence);
|
|
607
753
|
}
|
|
608
754
|
parameters.push(limit);
|
|
609
|
-
const rows = this.ctx.storage.sql.exec(`SELECT
|
|
610
|
-
FROM pending_r2_tombstones
|
|
755
|
+
const rows = this.ctx.storage.sql.exec(`SELECT * FROM pending_r2_tombstones
|
|
611
756
|
WHERE ${filters.join(" AND ")}
|
|
612
757
|
ORDER BY key_hash LIMIT ?`, ...parameters).toArray();
|
|
613
|
-
const pending = rows.map(
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
758
|
+
const pending = rows.map(pendingEntryFromRow);
|
|
759
|
+
const updates = rows.map((row, index) => ({
|
|
760
|
+
...pending[index],
|
|
761
|
+
...row.source_revision !== null && row.fresh_until !== null && row.swr_until !== null ? { stale: {
|
|
762
|
+
freshUntil: row.fresh_until,
|
|
763
|
+
sourceRevision: row.source_revision,
|
|
764
|
+
swrUntil: row.swr_until
|
|
765
|
+
} } : {}
|
|
618
766
|
}));
|
|
619
|
-
const settled = await mapSettledWithR2Concurrency(
|
|
620
|
-
await this.writeR2Tombstone(entry);
|
|
621
|
-
return entry;
|
|
622
|
-
});
|
|
767
|
+
const settled = await mapSettledWithR2Concurrency(updates, (update) => this.writeR2Update(update));
|
|
623
768
|
const purged = settled.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
|
|
624
769
|
this.ctx.storage.transactionSync(() => {
|
|
625
|
-
for (const
|
|
770
|
+
for (const edgeInvalidate of [true, false]) {
|
|
771
|
+
const completed = purged.filter((entry) => Boolean(entry.edgeInvalidate) === edgeInvalidate);
|
|
772
|
+
for (const batch of batches(completed, MAX_SQL_PARAMETERS / 2 - 1)) this.ctx.storage.sql.exec(`UPDATE pending_r2_tombstones SET r2_complete = 1, edge_invalidate = ? WHERE ${batch.map(() => "(key_hash = ? AND revision = ?)").join(" OR ")}`, Number(edgeInvalidate), ...batch.flatMap((entry) => [entry.keyHash, entry.revision]));
|
|
773
|
+
}
|
|
626
774
|
this.finishCompletedTombstones(purged);
|
|
627
775
|
});
|
|
628
776
|
return {
|
|
@@ -634,15 +782,9 @@ var CacheMetadata = class extends DurableObject {
|
|
|
634
782
|
}
|
|
635
783
|
listPendingEdgePurges(limit, tombstoneSequence) {
|
|
636
784
|
const sequenceFilter = tombstoneSequence === void 0 ? "" : " AND tombstone_sequence = ?";
|
|
637
|
-
return this.ctx.storage.sql.exec(`SELECT
|
|
638
|
-
FROM pending_r2_tombstones
|
|
785
|
+
return this.ctx.storage.sql.exec(`SELECT * FROM pending_r2_tombstones
|
|
639
786
|
WHERE r2_complete = 1 AND edge_purge_complete = 0${sequenceFilter}
|
|
640
|
-
ORDER BY key_hash LIMIT ?`, ...tombstoneSequence === void 0 ? [] : [tombstoneSequence], limit).toArray().map(
|
|
641
|
-
keyHash: row.key_hash,
|
|
642
|
-
cacheKey: row.cache_key,
|
|
643
|
-
objectKey: row.object_key,
|
|
644
|
-
revision: row.revision
|
|
645
|
-
}));
|
|
787
|
+
ORDER BY key_hash LIMIT ?`, ...tombstoneSequence === void 0 ? [] : [tombstoneSequence], limit).toArray().map(pendingEntryFromRow);
|
|
646
788
|
}
|
|
647
789
|
markTombstonesEdgePurged(entries) {
|
|
648
790
|
this.ctx.storage.transactionSync(() => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cloudflare/workers-response-store",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "An R2-backed programmatic response store for Cloudflare Workers.",
|
|
5
5
|
"homepage": "https://vinext.dev/",
|
|
6
6
|
"license": "MIT",
|
|
@@ -24,13 +24,13 @@
|
|
|
24
24
|
}
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
|
-
"@cloudflare/workers-types": "5.
|
|
27
|
+
"@cloudflare/workers-types": "5.20261004.1",
|
|
28
28
|
"@types/node": "^25.9.2",
|
|
29
29
|
"miniflare": "5.20260730.0-alpha",
|
|
30
30
|
"typescript": "^7.0.0",
|
|
31
|
-
"vite": "npm:@voidzero-dev/vite-plus-core@
|
|
32
|
-
"vite-plus": "
|
|
33
|
-
"vitest": "
|
|
31
|
+
"vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
|
|
32
|
+
"vite-plus": "1.1.0",
|
|
33
|
+
"vitest": "5.0.3",
|
|
34
34
|
"wrangler": "^4.118.0"
|
|
35
35
|
},
|
|
36
36
|
"engines": {
|