@cloudflare/workers-response-store 0.1.0-beta.0 → 0.1.0-beta.2
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 +250 -45
- package/dist/binding.d.ts +32 -1
- package/dist/binding.js +485 -80
- package/dist/index.d.ts +10 -2
- package/dist/index.js +12 -3
- package/dist/isolate-negative-cache.d.ts +11 -0
- package/dist/isolate-negative-cache.js +34 -0
- package/dist/metadata-do.d.ts +48 -11
- package/dist/metadata-do.js +348 -133
- package/dist/r2-concurrency.d.ts +3 -0
- package/dist/r2-concurrency.js +25 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,92 +1,297 @@
|
|
|
1
1
|
# Workers Response Store
|
|
2
2
|
|
|
3
|
-
`@cloudflare/workers-response-store` is
|
|
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
|
-
|
|
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.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Install
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
```sh
|
|
10
|
+
npm install @cloudflare/workers-response-store
|
|
11
|
+
```
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
13
|
+
The examples below use a current compatibility date, `nodejs_compat`, generated Wrangler types, and Workers observability. Create the configured R2 bucket before deploying, then run `wrangler types` after adding the bindings.
|
|
14
|
+
|
|
15
|
+
## Service-binding setup
|
|
16
|
+
|
|
17
|
+
Service-binding mode separates cache infrastructure from application code. It is useful for a standalone application as well as for multiple Workers: the cache Worker can be deployed and observed independently, storage bindings stay out of the application Worker, and the same cache service can be reused later without changing the integration API.
|
|
18
|
+
|
|
19
|
+
The cache Worker owns Workers Cache, R2, and a SQLite Durable Object. Each application Worker keeps its own regeneration callback and passes that version-pinned capability over RPC.
|
|
20
|
+
|
|
21
|
+
### Cache Worker
|
|
22
|
+
|
|
23
|
+
Point `main` at the installed service entrypoint:
|
|
24
|
+
|
|
25
|
+
```jsonc
|
|
26
|
+
{
|
|
27
|
+
"$schema": "./node_modules/wrangler/config-schema.json",
|
|
28
|
+
"name": "response-store",
|
|
29
|
+
"main": "./node_modules/@cloudflare/workers-response-store/dist/service.js",
|
|
30
|
+
"compatibility_date": "2026-09-16",
|
|
31
|
+
"compatibility_flags": ["nodejs_compat"],
|
|
32
|
+
"workers_dev": false,
|
|
33
|
+
"cache": { "enabled": true },
|
|
34
|
+
"exports": {
|
|
35
|
+
"default": { "type": "worker", "cache": { "enabled": false } },
|
|
36
|
+
"ResponseStoreBinding": { "type": "worker", "cache": { "enabled": true } },
|
|
37
|
+
"CacheMetadata": { "type": "durable-object", "storage": "sqlite" },
|
|
38
|
+
},
|
|
39
|
+
"r2_buckets": [{ "binding": "CACHE_BODIES", "bucket_name": "my-response-bodies" }],
|
|
40
|
+
"durable_objects": {
|
|
41
|
+
"bindings": [{ "name": "CACHE_METADATA", "class_name": "CacheMetadata" }],
|
|
42
|
+
},
|
|
43
|
+
"observability": { "enabled": true },
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`CacheMetadata` is a declarative SQLite Durable Object export. Do not also add it to Wrangler `migrations`.
|
|
48
|
+
|
|
49
|
+
### Application Worker
|
|
50
|
+
|
|
51
|
+
Bind the application to the uncached `ResponseStoreService` entrypoint and include version metadata:
|
|
52
|
+
|
|
53
|
+
```jsonc
|
|
54
|
+
{
|
|
55
|
+
"$schema": "./node_modules/wrangler/config-schema.json",
|
|
56
|
+
"name": "my-app",
|
|
57
|
+
"main": "src/worker.ts",
|
|
58
|
+
"compatibility_date": "2026-09-16",
|
|
59
|
+
"compatibility_flags": ["nodejs_compat"],
|
|
60
|
+
"services": [
|
|
61
|
+
{
|
|
62
|
+
"binding": "RESPONSE_STORE",
|
|
63
|
+
"service": "response-store",
|
|
64
|
+
"entrypoint": "ResponseStoreService",
|
|
65
|
+
},
|
|
66
|
+
],
|
|
67
|
+
"version_metadata": { "binding": "CF_VERSION_METADATA" },
|
|
68
|
+
"observability": { "enabled": true },
|
|
69
|
+
}
|
|
21
70
|
```
|
|
22
71
|
|
|
23
|
-
|
|
72
|
+
Create the client and export its generated entrypoints:
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { createWorkersResponseStoreClient } from "@cloudflare/workers-response-store";
|
|
76
|
+
|
|
77
|
+
const responseStore = createWorkersResponseStoreClient<Env>({
|
|
78
|
+
regenerate(input, { env, ctx }) {
|
|
79
|
+
return render(input.request, env, ctx, input);
|
|
80
|
+
},
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
export const { ResponseStoreRevalidator, ResponseStoreClient } = responseStore.entrypoints;
|
|
84
|
+
```
|
|
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.
|
|
87
|
+
|
|
88
|
+
## Single-Worker setup
|
|
89
|
+
|
|
90
|
+
Single-Worker mode keeps the application, cache entrypoint, R2 bucket, and metadata Durable Object in one deployment. Choose it when one deployment and one Wrangler configuration are more useful than independently managed cache infrastructure.
|
|
91
|
+
|
|
92
|
+
### 1. Create and export the store
|
|
24
93
|
|
|
25
94
|
```ts
|
|
26
95
|
import { createWorkersResponseStore } from "@cloudflare/workers-response-store";
|
|
27
96
|
|
|
28
97
|
const responseStore = createWorkersResponseStore<Env>({
|
|
29
98
|
regenerate(input, { env, ctx }) {
|
|
30
|
-
return
|
|
99
|
+
return render(input.request, env, ctx, {
|
|
100
|
+
id: input.id,
|
|
101
|
+
args: input.args,
|
|
102
|
+
reason: input.reason,
|
|
103
|
+
});
|
|
31
104
|
},
|
|
32
105
|
});
|
|
33
106
|
|
|
34
107
|
export const { CacheMetadata, ResponseStoreRevalidator, ResponseStoreBinding } =
|
|
35
108
|
responseStore.entrypoints;
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The named exports must match the Wrangler configuration. `regenerate` is called for SWR, expired entries, missing R2 bodies, and explicit refreshes. Give each stored response a serializable revalidator descriptor so the callback can reconstruct it later.
|
|
112
|
+
|
|
113
|
+
### 2. Read through and fill the store
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
function isResponseStoreMiss(response: Response): boolean {
|
|
117
|
+
return response.status === 404 && response.headers.get("X-Workers-Response-Store") === "MISS";
|
|
118
|
+
}
|
|
36
119
|
|
|
37
120
|
export default {
|
|
38
|
-
fetch(request) {
|
|
39
|
-
|
|
121
|
+
async fetch(request, env, ctx) {
|
|
122
|
+
if (request.method !== "GET") {
|
|
123
|
+
return render(request, env, ctx);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
// Cache identity is pathname + query string. Use a canonical GET request
|
|
127
|
+
// with only information that is safe to share between visitors.
|
|
128
|
+
const cacheRequest = new Request(request.url);
|
|
129
|
+
const cached = await responseStore.fetch(cacheRequest);
|
|
130
|
+
if (!isResponseStoreMiss(cached)) {
|
|
131
|
+
return cached;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
const response = await render(request, env, ctx);
|
|
135
|
+
await responseStore.put(cacheRequest, response.clone(), {
|
|
136
|
+
revalidator: { id: "page", args: [] },
|
|
137
|
+
});
|
|
138
|
+
return response;
|
|
40
139
|
},
|
|
41
140
|
} satisfies ExportedHandler<Env>;
|
|
42
141
|
```
|
|
43
142
|
|
|
44
|
-
|
|
143
|
+
This is the minimum integration loop. A framework can add its own cacheability rules, vary dimensions, streaming policy, error handling, and mapping from routes to revalidator IDs and arguments.
|
|
45
144
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
The library can instead run R2, SQLite, and Workers Cache in a reusable cache Worker. Point that Worker's Wrangler `main` directly at the installed implementation:
|
|
145
|
+
### 3. Configure Wrangler
|
|
49
146
|
|
|
50
147
|
```jsonc
|
|
51
148
|
{
|
|
52
|
-
"
|
|
149
|
+
"$schema": "./node_modules/wrangler/config-schema.json",
|
|
150
|
+
"name": "my-app",
|
|
151
|
+
"main": "src/worker.ts",
|
|
152
|
+
"compatibility_date": "2026-09-16",
|
|
153
|
+
"compatibility_flags": ["nodejs_compat"],
|
|
154
|
+
"cache": { "enabled": true },
|
|
155
|
+
"exports": {
|
|
156
|
+
"default": { "type": "worker", "cache": { "enabled": false } },
|
|
157
|
+
"ResponseStoreBinding": { "type": "worker", "cache": { "enabled": true } },
|
|
158
|
+
"CacheMetadata": { "type": "durable-object", "storage": "sqlite" },
|
|
159
|
+
},
|
|
160
|
+
"r2_buckets": [{ "binding": "CACHE_BODIES", "bucket_name": "my-response-bodies" }],
|
|
161
|
+
"durable_objects": {
|
|
162
|
+
"bindings": [{ "name": "CACHE_METADATA", "class_name": "CacheMetadata" }],
|
|
163
|
+
},
|
|
164
|
+
"version_metadata": { "binding": "CF_VERSION_METADATA" },
|
|
165
|
+
"observability": { "enabled": true },
|
|
53
166
|
}
|
|
54
167
|
```
|
|
55
168
|
|
|
56
|
-
|
|
169
|
+
`CacheMetadata` is a declarative SQLite Durable Object export. Do not also add it to Wrangler `migrations`. Create the configured R2 bucket before deploying, then run `wrangler types` to generate `Env` from the completed configuration.
|
|
170
|
+
|
|
171
|
+
## API
|
|
172
|
+
|
|
173
|
+
The object returned by `createWorkersResponseStore()` and `createWorkersResponseStoreClient()` implements the same API:
|
|
57
174
|
|
|
58
|
-
|
|
175
|
+
| Method | Behavior |
|
|
176
|
+
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
177
|
+
| `fetch(request)` | Reads a canonical `GET` cache key. Returns a stored response or a `404` Response Store miss. Stale entries inside their SWR window return immediately and regenerate in the background; hard-expired entries wait for regeneration. |
|
|
178
|
+
| `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. |
|
|
179
|
+
| `refresh({ tags, pathPrefixes })` | Regenerates matching entries and purges their prior edge responses. At least one selector is required. |
|
|
180
|
+
| `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. |
|
|
181
|
+
| `getTagExpiration(tags)` | Returns the latest invalidation timestamp for a set of framework-managed soft tags. Most integrations do not need this low-level method. |
|
|
182
|
+
|
|
183
|
+
Mutation methods return:
|
|
59
184
|
|
|
60
185
|
```ts
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
186
|
+
type ResponseStoreMutationResult = {
|
|
187
|
+
backingStoreUpdated: boolean;
|
|
188
|
+
edgePurgeAccepted: boolean;
|
|
189
|
+
};
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Cache keys
|
|
193
|
+
|
|
194
|
+
- Keys must be `GET` requests.
|
|
195
|
+
- Identity is the URL pathname plus query string; scheme and host are ignored.
|
|
196
|
+
- Every key stores its response and read metadata together in one version-scoped R2 object by default, so fresh hits and misses do not query the metadata Durable Object. No special key format is required.
|
|
197
|
+
- Build the key from trusted route and vary data. Do not include arbitrary visitor headers or other unbounded input unless it intentionally creates a distinct shared response.
|
|
198
|
+
|
|
199
|
+
### Freshness and tags
|
|
200
|
+
|
|
201
|
+
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.
|
|
202
|
+
|
|
203
|
+
Set `Cache-Tag` on the response passed to `put()` to associate comma-separated purge tags. `refresh()` and `purge()` also accept pathname prefixes. Tags are matched case-insensitively for invalidation.
|
|
204
|
+
|
|
205
|
+
The `regenerate` callback receives the stored `id` and `args`, a canonical cache-key request, and one of these reasons:
|
|
206
|
+
|
|
207
|
+
| Reason | Trigger |
|
|
208
|
+
| --------- | ----------------------------------------------------------------------- |
|
|
209
|
+
| `swr` | A stale response was returned inside its SWR window. |
|
|
210
|
+
| `expired` | The response passed its SWR window and the read must wait. |
|
|
211
|
+
| `missing` | The R2 object exists but its committed response content is unavailable. |
|
|
212
|
+
| `manual` | `refresh()` selected the entry. |
|
|
213
|
+
|
|
214
|
+
### Response headers
|
|
215
|
+
|
|
216
|
+
`fetch()` responses include these Response Store protocol headers:
|
|
217
|
+
|
|
218
|
+
| Header | Value | Meaning |
|
|
219
|
+
| --------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
220
|
+
| `X-Workers-Response-Store` | `MISS`, `BLOB-FRESH`, or `BLOB-STALE` | Whether metadata was absent or the R2 response was fresh or stale when the binding read it. A miss is a `404` with `Cache-Control: no-store`. |
|
|
221
|
+
| `X-Workers-Response-Store-Revision` | Positive integer | The active stored revision returned to the caller. It is absent on a miss. |
|
|
222
|
+
| `X-Workers-Response-Store-Binding-Invocation` | UUID | Identifies the binding invocation that loaded the response from R2. Workers Cache reuses the value from its cached fill, making it useful for diagnosing whether the binding ran. It is absent on a miss. |
|
|
223
|
+
| `X-Workers-Response-Store-Age-Basis` | `<created-at-ms>:<initial-age-seconds>` | The response creation timestamp and its original `Age`. Calculate the current age as `initialAgeSeconds + max(0, floor((Date.now() - createdAtMs) / 1000))`. |
|
|
224
|
+
|
|
225
|
+
These headers describe the Response Store binding result, not the current Workers Cache edge state; use `CF-Cache-Status` for the latter. An adapter may consume and remove protocol headers before returning an application response.
|
|
226
|
+
|
|
227
|
+
## Performance
|
|
228
|
+
|
|
229
|
+
Workers Cache hits bypass the Response Store binding Worker, R2, and every metadata Durable Object. The backing store and sharding path run only when Workers Cache invokes the binding for a miss or update.
|
|
230
|
+
|
|
231
|
+
### Metadata sharding
|
|
232
|
+
|
|
233
|
+
Metadata sharding is opt-in:
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
const responseStore = createWorkersResponseStore<Env>({
|
|
237
|
+
shards: 16,
|
|
238
|
+
regenerate,
|
|
65
239
|
});
|
|
240
|
+
```
|
|
66
241
|
|
|
67
|
-
|
|
242
|
+
`shards` must be an integer greater than one. Without it, all version-scoped metadata uses the original single Durable Object.
|
|
243
|
+
|
|
244
|
+
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.
|
|
245
|
+
|
|
246
|
+
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.
|
|
247
|
+
|
|
248
|
+
### Metadata location
|
|
249
|
+
|
|
250
|
+
Both deployment modes accept a Durable Object location hint:
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
const responseStore = createWorkersResponseStore<Env>({
|
|
254
|
+
locationHint: "weur",
|
|
255
|
+
regenerate,
|
|
256
|
+
});
|
|
68
257
|
```
|
|
69
258
|
|
|
70
|
-
|
|
259
|
+
Use the same `locationHint` option with `createWorkersResponseStoreClient()` in service-binding mode. The hint is best-effort and only affects the first creation of each metadata Durable Object. Existing objects never move when this option changes, so roll out a changed hint as a cache-cold deployment and choose it alongside the R2 bucket's location.
|
|
260
|
+
|
|
261
|
+
## Storage and operational behavior
|
|
262
|
+
|
|
263
|
+
```text
|
|
264
|
+
application Worker
|
|
265
|
+
└─ ResponseStoreBinding (Workers Cache enabled)
|
|
266
|
+
├─ cache hit ───────────────► stored Response
|
|
267
|
+
└─ cache miss
|
|
268
|
+
├─ response + read metadata ─► R2
|
|
269
|
+
├─ write coordination/revisions ─► SQLite Durable Object
|
|
270
|
+
└─ regeneration ───────► application callback
|
|
271
|
+
```
|
|
71
272
|
|
|
72
|
-
|
|
273
|
+
- Responses use `runtime-cache/<version-id>/r2-v1/[shards-<count>/]<digest>/active`. The layout segment isolates this R2-backed implementation from older cache-Worker versions during service-binding rollbacks and rolling deployments.
|
|
274
|
+
- 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.
|
|
275
|
+
- 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.
|
|
276
|
+
- 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.
|
|
277
|
+
- A stale R2 response inside its SWR window returns immediately while `ctx.waitUntil()` runs one claimed regeneration. A later Workers Cache request promotes the completed revision, so one extra stale response is possible.
|
|
278
|
+
- Hard-expired responses are never served. Reads wait for regeneration and therefore require a stored revalidator descriptor.
|
|
279
|
+
- 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.
|
|
280
|
+
- 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.
|
|
281
|
+
- Service-binding callbacks remain pinned to the application Worker version that supplied the revalidator capability.
|
|
73
282
|
|
|
74
|
-
|
|
283
|
+
### Version retention and cleanup
|
|
75
284
|
|
|
76
|
-
|
|
285
|
+
Backing data is scoped by the application Worker version ID. A new deployment therefore starts with a cold backing layout while retaining prior versions for rollback. Deploying a new version does not delete the old version's R2 objects or metadata Durable Objects, and the library does not currently run cross-version garbage collection.
|
|
77
286
|
|
|
78
|
-
|
|
287
|
+
This is deployment compatibility, not an in-place object-layout migration. Every invocation remains partitioned by its application Worker version ID. In self-contained mode, a newly deployed application version starts cold and leaves the previous version's data available for rollback. In service-binding mode, upgrading only the cache Worker keeps the existing application version IDs but treats entries in the previous R2 layout as cold misses; existing clients refill them through the unchanged API, and legacy cache-key formats remain valid ordinary keys. The old R2 objects are retained until that application version is cleaned up. Do not manually assign one application version ID to unrelated deployments.
|
|
79
288
|
|
|
80
|
-
|
|
289
|
+
Keep every version that can still receive traffic or be rolled back to. When a version is permanently retired:
|
|
81
290
|
|
|
82
|
-
|
|
291
|
+
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.
|
|
292
|
+
2. Delete any remaining objects under its R2 prefix: `runtime-cache/<version-id>/` contains every storage layout and shard count for that application version.
|
|
293
|
+
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-v1` without sharding, or `<version-id>:r2-v1:metadata-shard:<index>-of-<count>` for each shard. Older layouts may have additional objects. This cleanup is outside the package API.
|
|
83
294
|
|
|
84
|
-
|
|
295
|
+
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.
|
|
85
296
|
|
|
86
|
-
-
|
|
87
|
-
- A stale R2 entry may be returned once more while its replacement is generated because Workers Cache does not expose whether the invocation is an SWR update or an empty-location fill.
|
|
88
|
-
- Hard-expired entries are never returned; the request waits for regeneration when a revalidator is available.
|
|
89
|
-
- Response bodies are stored only in R2. SQLite stores metadata, tag invalidations, and pending-object cleanup records.
|
|
90
|
-
- Pending R2 objects are retained for one hour before an alarm-driven cleanup pass. Failed deletion is retried without making the active response unavailable.
|
|
91
|
-
- Service-binding loopbacks stay pinned to the user Worker version that supplied the revalidator capability.
|
|
92
|
-
- The store buffers RPC-transferred bodies before R2 writes. Consumers should account for Worker memory limits when choosing maximum response sizes.
|
|
297
|
+
Runnable single-Worker and service-binding integrations are available under `example/` in this package's source repository.
|
package/dist/binding.d.ts
CHANGED
|
@@ -57,10 +57,18 @@ export type StoredEntry = EntryMetadata & {
|
|
|
57
57
|
activeRevision: number;
|
|
58
58
|
latestRevision: number;
|
|
59
59
|
};
|
|
60
|
+
export type RefreshCandidate = Pick<StoredEntry, "keyHash" | "cacheKey" | "activeRevision" | "latestRevision"> & ({
|
|
61
|
+
hasRevalidator: boolean;
|
|
62
|
+
revalidator?: never;
|
|
63
|
+
} | {
|
|
64
|
+
hasRevalidator?: never;
|
|
65
|
+
revalidator: RevalidatorDescriptor | null;
|
|
66
|
+
});
|
|
60
67
|
export type PurgedEntry = {
|
|
61
68
|
keyHash: string;
|
|
62
69
|
cacheKey: string;
|
|
63
70
|
objectKey: string;
|
|
71
|
+
revision: number;
|
|
64
72
|
};
|
|
65
73
|
export type RevalidationService = {
|
|
66
74
|
regenerate(input: RevalidationInput): Promise<Response>;
|
|
@@ -69,16 +77,22 @@ export type WorkersResponseStoreEnv = {
|
|
|
69
77
|
CACHE_BODIES: R2Bucket;
|
|
70
78
|
CACHE_METADATA: DurableObjectNamespace<undefined>;
|
|
71
79
|
CF_VERSION_METADATA?: WorkerVersionMetadata;
|
|
80
|
+
WORKERS_RESPONSE_STORE_E2E_EDGE_PURGE_MODE?: "disabled";
|
|
72
81
|
};
|
|
73
82
|
export type WorkersResponseStoreProps = {
|
|
74
83
|
versionId?: string;
|
|
75
|
-
locationHint?:
|
|
84
|
+
locationHint?: ResponseStoreLocationHint;
|
|
76
85
|
revalidator?: RevalidationService;
|
|
86
|
+
shards?: number;
|
|
77
87
|
};
|
|
88
|
+
export type ResponseStoreLocationHint = DurableObjectLocationHint;
|
|
89
|
+
export declare function validateResponseStoreLocationHint(locationHint: unknown): ResponseStoreLocationHint | undefined;
|
|
78
90
|
export type ResponseStoreServiceProps = Pick<WorkersResponseStoreProps, "locationHint">;
|
|
79
91
|
export type ResponseStoreServiceInvocation = {
|
|
80
92
|
versionId: string;
|
|
81
93
|
revalidator: RevalidationService;
|
|
94
|
+
locationHint?: ResponseStoreLocationHint;
|
|
95
|
+
shards?: number;
|
|
82
96
|
};
|
|
83
97
|
export type ResponseStoreExecutionContext = Pick<ExecutionContext, "exports">;
|
|
84
98
|
export declare function getWorkersResponseStore(ctx: ResponseStoreExecutionContext, props?: WorkersResponseStoreProps): WorkersResponseStore;
|
|
@@ -91,17 +105,34 @@ export declare class ResponseStoreService extends WorkerEntrypoint<WorkersRespon
|
|
|
91
105
|
purge(options: ResponseStorePurgeOptions, invocation: ResponseStoreServiceInvocation): Promise<ResponseStoreMutationResult>;
|
|
92
106
|
}
|
|
93
107
|
export type ResponseStoreServiceBinding = Pick<ResponseStoreService, "read" | "getTagExpiration" | "put" | "refresh" | "purge">;
|
|
108
|
+
export declare function validateResponseStoreShards(shards: number | undefined): number | undefined;
|
|
94
109
|
export declare class ResponseStoreBinding extends WorkerEntrypoint<WorkersResponseStoreEnv, WorkersResponseStoreProps> {
|
|
110
|
+
private readonly shardCount;
|
|
95
111
|
private getVersionId;
|
|
112
|
+
private getMetadataShard;
|
|
96
113
|
private getMetadata;
|
|
114
|
+
private getMetadataShards;
|
|
115
|
+
private entryReadKey;
|
|
116
|
+
private invalidateEntryRead;
|
|
117
|
+
private getTagMetadata;
|
|
97
118
|
private deriveCacheKey;
|
|
98
119
|
private purgeEdgeCache;
|
|
99
120
|
private purgeEdgeCacheByTags;
|
|
121
|
+
purgeR2TombstoneEdges(entries: PurgedEntry[]): Promise<boolean>;
|
|
122
|
+
private purgePendingEdgeEntries;
|
|
100
123
|
private objectKeyRoot;
|
|
101
124
|
private objectKeyPrefix;
|
|
125
|
+
private r2ObjectKey;
|
|
126
|
+
private entryFromR2Metadata;
|
|
127
|
+
private readR2Metadata;
|
|
128
|
+
private readR2MetadataCached;
|
|
129
|
+
private writeR2Revision;
|
|
130
|
+
private writeR2Response;
|
|
131
|
+
private readableEntry;
|
|
102
132
|
private reserveWrite;
|
|
103
133
|
private logCleanupFailure;
|
|
104
134
|
private releaseFailedWrite;
|
|
135
|
+
private createStoredResponse;
|
|
105
136
|
private readStoredResponse;
|
|
106
137
|
private storeResponse;
|
|
107
138
|
private regenerateEntry;
|