@syncular/server-workers 0.32.0 → 0.33.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.
@@ -45,10 +45,13 @@
45
45
  * an async generator draining over `ws.send`; while it is pending it holds
46
46
  * the DO's event loop, so the DO cannot be evicted mid-round. (This is the
47
47
  * same property the §8.7 "one round in flight" rule relies on.)
48
- * - **On the first message after a wake**, the socket has a serialized
49
- * attachment (`ws.serializeAttachment` — `{clientId, actorId, partition}`,
50
- * written at accept time) but no live session. We reconstruct the session
51
- * via `hub.connect(...)`, which reloads the registration list from the
48
+ * - **On the first serialized operation after a wake** (a socket frame, an
49
+ * HTTP sync round, a command, a wake), every accepted socket has a
50
+ * serialized attachment (`ws.serializeAttachment`, `{clientId, actorId,
51
+ * partition}`, written at accept time) but no live session. The host
52
+ * reconstructs the session of every socket in `getWebSockets()`, so
53
+ * sockets that stayed quiet through the hibernation keep receiving
54
+ * deltas. Each session is rebuilt via `hub.connect(...)`, which reloads the registration list from the
52
55
  * client record in D1 (the §8.1 load-at-upgrade rule — exactly what a
53
56
  * fresh upgrade does), then dispatch the message into it. Rehydration is
54
57
  * transparent to the client: it saw `hello` once at the real upgrade, so
@@ -62,12 +65,13 @@
62
65
  *
63
66
  * ## The wake path (external-command fan-out)
64
67
  *
65
- * Ordinary HTTP `/sync` is forwarded into this DO and fans out in-process. An
68
+ * Ordinary HTTP `/sync` and `/operations` (with `RealtimeDOConfig.operations`)
69
+ * are forwarded into this DO and fan out in-process. An
66
70
  * external authoritative command host that already provides equivalent D1
67
71
  * partition serialization may call `/__wake` after its own commit so sockets
68
72
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
69
73
  */
70
- import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, errorBody, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
74
+ import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, errorBody, handleRemoteOperation, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
71
75
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
72
76
  function isAttachment(value) {
73
77
  return (typeof value === 'object' &&
@@ -80,6 +84,9 @@ function isAttachment(value) {
80
84
  export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
81
85
  export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
82
86
  export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
87
+ export const OPERATIONS_DO_REQUEST_PATH = '/__syncular_realtime/operations';
88
+ /** The remote operation protocol content type (REMOTE.md §5). */
89
+ export const OPERATIONS_CONTENT_TYPE = 'application/vnd.syncular.operations.v1+json';
83
90
  /** Prefix of forwarded admin routes; the admin route path follows it. */
84
91
  export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
85
92
  /**
@@ -112,11 +119,17 @@ export class SyncularRealtimeHost {
112
119
  #hub;
113
120
  #admin;
114
121
  /** Live sessions, keyed by their socket. Empty after a hibernation wake;
115
- * lazily rehydrated on the first message per socket (see the class doc). */
122
+ * rehydrated for every socket before the first serialized operation (see
123
+ * the class doc). */
116
124
  #sessions = new Map();
117
125
  /** Sockets whose rehydration `hello` must be swallowed (already greeted at
118
126
  * the real upgrade — rehydration is transparent to the client). */
119
127
  #swallowHello = new Set();
128
+ #closedSockets = new WeakSet();
129
+ /** Accepted sockets whose upgrade is still building their session. */
130
+ #upgrading = new WeakSet();
131
+ /** Set once this instance rebuilt the sessions of hibernated sockets. */
132
+ #rehydrated = false;
120
133
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
121
134
  #partitionTail = Promise.resolve();
122
135
  constructor(state, db, config) {
@@ -165,8 +178,11 @@ export class SyncularRealtimeHost {
165
178
  if (url.pathname === SYNC_DO_REQUEST_PATH) {
166
179
  return this.#serializePartition(() => this.#handleSync(request));
167
180
  }
181
+ if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
182
+ return this.#serializePartition(() => this.#handleOperation(request));
183
+ }
168
184
  if (url.pathname === REALTIME_DO_WAKE_PATH) {
169
- return this.#handleWake(request);
185
+ return this.#serializePartition(() => this.#handleWake(request));
170
186
  }
171
187
  if (url.pathname === REALTIME_DO_UPGRADE_PATH) {
172
188
  return this.#handleUpgrade(request);
@@ -184,10 +200,76 @@ export class SyncularRealtimeHost {
184
200
  });
185
201
  }
186
202
  #serializePartition(operation) {
187
- const result = this.#partitionTail.then(operation, operation);
203
+ const run = async () => {
204
+ await this.#rehydrateSockets();
205
+ return operation();
206
+ };
207
+ const result = this.#partitionTail.then(run, run);
188
208
  this.#partitionTail = result.then(() => undefined, () => undefined);
189
209
  return result;
190
210
  }
211
+ /**
212
+ * After a hibernation wake the session map is empty while sockets stay
213
+ * open. Rebuild every socket's session before the first serialized
214
+ * operation, so a commit fans out to sockets that stayed quiet through
215
+ * the hibernation. A socket whose session cannot be rebuilt is closed;
216
+ * its client reconnects and catches up (§8.4).
217
+ */
218
+ async #rehydrateSockets() {
219
+ if (this.#rehydrated)
220
+ return;
221
+ this.#rehydrated = true;
222
+ for (const ws of this.#state.getWebSockets()) {
223
+ if (this.#upgrading.has(ws))
224
+ continue;
225
+ try {
226
+ await this.#sessionFor(ws);
227
+ }
228
+ catch (error) {
229
+ ws.close(1011, 'realtime rehydration failed');
230
+ this.#syncError(error, 'realtime');
231
+ }
232
+ }
233
+ }
234
+ /**
235
+ * Map a host failure to its catalog error. The reporters are read inside
236
+ * the callbacks so a failing accessor stays inside `adapterSyncError`.
237
+ */
238
+ #syncError(error, route) {
239
+ return adapterSyncError(error, (error, context) => this.#getHub().onError?.(error, context), route, (error, context) => this.#getHub().mapError?.(error, context));
240
+ }
241
+ async #handleOperation(request) {
242
+ const contentType = request.headers
243
+ .get('content-type')
244
+ ?.split(';')[0]
245
+ ?.trim();
246
+ if (contentType !== OPERATIONS_CONTENT_TYPE) {
247
+ const error = new SyncError('operation.invalid_request');
248
+ return Response.json(errorBody(error), { status: 415 });
249
+ }
250
+ const registry = this.#config.operations;
251
+ if (registry === undefined) {
252
+ const error = new SyncError('operation.unknown');
253
+ return Response.json(errorBody(error), { status: error.httpStatus });
254
+ }
255
+ const identity = readRequestIdentityHeaders(request);
256
+ if (identity === undefined) {
257
+ const error = new SyncError('sync.auth_required');
258
+ return Response.json(errorBody(error), { status: error.httpStatus });
259
+ }
260
+ try {
261
+ const bytes = new Uint8Array(await request.arrayBuffer());
262
+ const out = await handleRemoteOperation(bytes, this.#getHub().requestContextFor(identity), registry);
263
+ return new Response(out.slice().buffer, {
264
+ status: 200,
265
+ headers: { 'content-type': OPERATIONS_CONTENT_TYPE },
266
+ });
267
+ }
268
+ catch (error) {
269
+ const sync = this.#syncError(error, 'operations');
270
+ return Response.json(errorBody(sync), { status: sync.httpStatus });
271
+ }
272
+ }
191
273
  async #handleSync(request) {
192
274
  const contentType = request.headers
193
275
  .get('content-type')
@@ -211,7 +293,7 @@ export class SyncularRealtimeHost {
211
293
  });
212
294
  }
213
295
  catch (error) {
214
- const sync = adapterSyncError(error, (error, context) => this.#getHub().onError?.(error, context), 'sync', (error, context) => this.#getHub().mapError?.(error, context));
296
+ const sync = this.#syncError(error, 'sync');
215
297
  return Response.json(errorBody(sync), { status: sync.httpStatus });
216
298
  }
217
299
  }
@@ -221,7 +303,7 @@ export class SyncularRealtimeHost {
221
303
  * Actions share the partition FIFO with sync rounds.
222
304
  */
223
305
  async #handleAdmin(request, url) {
224
- this.#getHub();
306
+ const hub = this.#getHub();
225
307
  const partition = request.headers.get(REALTIME_ID_HEADER.partition);
226
308
  if (this.#admin === undefined || partition === null || partition === '') {
227
309
  const error = new SyncError('sync.invalid_request', 'forwarded admin request names no partition');
@@ -232,6 +314,8 @@ export class SyncularRealtimeHost {
232
314
  ...(request.headers.get(ADMIN_ACTIONS_HEADER) === '1'
233
315
  ? { authorizeActions: () => true }
234
316
  : {}),
317
+ ...(hub.onError !== undefined ? { onError: hub.onError } : {}),
318
+ ...(hub.mapError !== undefined ? { mapError: hub.mapError } : {}),
235
319
  });
236
320
  url.pathname = url.pathname.slice(ADMIN_DO_PATH.length);
237
321
  url.searchParams.set('partition', partition);
@@ -273,16 +357,19 @@ export class SyncularRealtimeHost {
273
357
  clientId: identity.clientId,
274
358
  };
275
359
  server.serializeAttachment(attachment);
360
+ this.#upgrading.add(server);
276
361
  this.#state.acceptWebSocket(server);
277
362
  // Build the session now (first connect: hello IS delivered). Any failure
278
363
  // closes the socket loudly — never a half-open realtime connection.
279
364
  try {
280
365
  const session = await this.#connectSession(server, attachment, false);
281
366
  this.#sessions.set(server, session);
367
+ this.#upgrading.delete(server);
282
368
  }
283
369
  catch (error) {
370
+ this.#upgrading.delete(server);
284
371
  server.close(1011, 'realtime connect failed');
285
- const sync = adapterSyncError(error, (error, context) => this.#getHub().onError?.(error, context), 'realtime', (error, context) => this.#getHub().mapError?.(error, context));
372
+ const sync = this.#syncError(error, 'realtime');
286
373
  return Response.json(errorBody(sync), { status: sync.httpStatus });
287
374
  }
288
375
  // `webSocket` is a workerd-only ResponseInit field (the 101 upgrade
@@ -317,6 +404,8 @@ export class SyncularRealtimeHost {
317
404
  * the DO woke from hibernation and lost its in-memory map.
318
405
  */
319
406
  async #sessionFor(ws) {
407
+ if (this.#closedSockets.has(ws))
408
+ return undefined;
320
409
  const existing = this.#sessions.get(ws);
321
410
  if (existing !== undefined)
322
411
  return existing;
@@ -324,6 +413,11 @@ export class SyncularRealtimeHost {
324
413
  if (!isAttachment(attachment))
325
414
  return undefined;
326
415
  const session = await this.#connectSession(ws, attachment, true);
416
+ if (this.#closedSockets.has(ws)) {
417
+ session.close();
418
+ this.#swallowHello.delete(ws);
419
+ return undefined;
420
+ }
327
421
  this.#sessions.set(ws, session);
328
422
  return session;
329
423
  }
@@ -348,6 +442,7 @@ export class SyncularRealtimeHost {
348
442
  }
349
443
  /** Hibernation callback: the socket closed. */
350
444
  async webSocketClose(ws) {
445
+ this.#closedSockets.add(ws);
351
446
  const session = this.#sessions.get(ws);
352
447
  if (session !== undefined) {
353
448
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.32.0",
3
+ "version": "0.33.0",
4
4
  "description": "Cloudflare Workers adapter for the Syncular sync server",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -45,11 +45,11 @@
45
45
  "!dist/**/*.test.d.ts"
46
46
  ],
47
47
  "dependencies": {
48
- "@syncular/server": "0.32.0",
49
- "@syncular/server-hono": "0.32.0"
48
+ "@syncular/server": "0.33.0",
49
+ "@syncular/server-hono": "0.33.0"
50
50
  },
51
51
  "devDependencies": {
52
- "@syncular/core": "0.32.0",
52
+ "@syncular/core": "0.33.0",
53
53
  "miniflare": "4.20260701.0"
54
54
  }
55
55
  }
package/src/index.ts CHANGED
@@ -9,9 +9,13 @@
9
9
  *
10
10
  * - **D1** → `D1ServerStorage` (the sqlite-family storage over the D1
11
11
  * binding, §4.2);
12
- * - **R2 / secrets** → the segment store, blob store, and signed-URL
13
- * config the host assembles from `env` (R2-as-S3 via `S3SegmentStore` +
14
- * `s3PresignedUrls`, or a memory store for tests);
12
+ * - **R2 / segments and blobs** → the segment store, blob store, and
13
+ * signed-URL config the host assembles from `env`. With a bucket binding
14
+ * (`env.BUCKET`), `R2SegmentStore` and `R2BlobStore` (`r2-stores.ts`) put
15
+ * the durable bytes in the same key layout as the S3 stores, with no S3
16
+ * credentials and no presign (bytes are served inline). With R2's S3
17
+ * endpoint, the S3 stores plus `s3PresignedUrls` give delegated presign
18
+ * (§5.4); a memory store serves tests;
15
19
  * - **secrets** → whatever `authenticate` needs.
16
20
  *
17
21
  * ## Realtime (§8): the Durable Object
@@ -43,6 +47,7 @@ import {
43
47
  } from '@syncular/server-hono';
44
48
  import {
45
49
  adminRequestForDurableObject,
50
+ OPERATIONS_DO_REQUEST_PATH,
46
51
  REALTIME_DO_UPGRADE_PATH,
47
52
  REALTIME_DO_WAKE_PATH,
48
53
  type RealtimeUpgradeIdentity,
@@ -52,6 +57,7 @@ import {
52
57
  } from './realtime-do';
53
58
 
54
59
  export { type D1Database, D1ServerStorage } from '@syncular/server';
60
+ export * from './r2-stores';
55
61
  export * from './realtime-do';
56
62
 
57
63
  /**
@@ -231,13 +237,30 @@ export function createWorkersFetchHandler<Env = unknown>(
231
237
  options.coordinator !== undefined
232
238
  ? await options.coordinator(env, ctx)
233
239
  : realtime;
234
- if (coordinator !== undefined && isSyncPost(request)) {
240
+ const partitionPath =
241
+ coordinator !== undefined ? partitionRequestPath(request) : undefined;
242
+ if (coordinator !== undefined && partitionPath !== undefined) {
243
+ if (
244
+ partitionPath === OPERATIONS_DO_REQUEST_PATH &&
245
+ honoOptions.operations !== undefined
246
+ ) {
247
+ // Commands must apply on the partition FIFO; a registry in the
248
+ // Worker would run them beside it.
249
+ throw new Error(
250
+ 'createWorkersFetchHandler: pass operations to the Durable Object config (RealtimeDOConfig.operations), not to the Worker config',
251
+ );
252
+ }
235
253
  const auth = await honoOptions.authenticate(request);
236
254
  if (auth === null) {
237
255
  const error = new SyncError('sync.auth_required');
238
256
  return Response.json(errorBody(error), { status: error.httpStatus });
239
257
  }
240
- return forwardSyncRequest(request, coordinator.namespace, auth);
258
+ return forwardSyncRequest(
259
+ request,
260
+ coordinator.namespace,
261
+ auth,
262
+ partitionPath,
263
+ );
241
264
  }
242
265
  if (options.admin !== undefined) {
243
266
  const admin = await options.admin(env, ctx);
@@ -283,34 +306,41 @@ export function createWorkersFetchHandler<Env = unknown>(
283
306
  };
284
307
  }
285
308
 
286
- function isSyncPost(request: Request): boolean {
287
- if (request.method !== 'POST') return false;
309
+ /**
310
+ * The Durable Object path for a request that must run on the partition FIFO:
311
+ * `POST /sync` with the SSP2 content type and `POST /operations` (the DO
312
+ * checks the operations content type). Exactly the routes
313
+ * `createSyncularHono` mounts at the app root; any other path, such as
314
+ * `/admin/sync`, stays with Hono routing.
315
+ */
316
+ function partitionRequestPath(request: Request): string | undefined {
317
+ if (request.method !== 'POST') return undefined;
318
+ const pathname = new URL(request.url).pathname;
319
+ if (pathname === '/operations') return OPERATIONS_DO_REQUEST_PATH;
288
320
  const contentType = request.headers
289
321
  .get('content-type')
290
322
  ?.split(';')[0]
291
323
  ?.trim();
292
- if (contentType !== SSP2_CONTENT_TYPE) return false;
293
- // Exactly the route `createSyncularHono` mounts (`POST /sync` at the app
294
- // root, which is where this handler serves the Hono app). Any other path —
295
- // e.g. `/admin/sync` — stays with Hono routing.
296
- return new URL(request.url).pathname === '/sync';
324
+ if (pathname === '/sync' && contentType === SSP2_CONTENT_TYPE)
325
+ return SYNC_DO_REQUEST_PATH;
326
+ return undefined;
297
327
  }
298
328
 
299
329
  /**
300
- * Forward an authenticated HTTP sync round to the partition's Durable Object.
301
- * Pulls and pushes share this path so client-record updates and push apply use
302
- * one ordered partition boundary. Other HTTP routes remain direct.
330
+ * Forward an authenticated HTTP sync round (or, with
331
+ * `OPERATIONS_DO_REQUEST_PATH`, a remote operation) to the partition's
332
+ * Durable Object. Pulls, pushes and commands share this boundary so
333
+ * client-record updates and commit apply use one ordered partition FIFO.
334
+ * Other HTTP routes remain direct.
303
335
  */
304
336
  export function forwardSyncRequest(
305
337
  request: Request,
306
338
  namespace: DurableObjectNamespaceLike,
307
339
  identity: { readonly partition: string; readonly actorId: string },
340
+ path: string = SYNC_DO_REQUEST_PATH,
308
341
  ): Promise<Response> {
309
342
  const stub = namespace.get(namespace.idFromName(identity.partition));
310
- const forwarded = new Request(
311
- new URL(SYNC_DO_REQUEST_PATH, request.url),
312
- request,
313
- );
343
+ const forwarded = new Request(new URL(path, request.url), request);
314
344
  writeRequestIdentityHeaders(forwarded.headers, identity);
315
345
  return stub.fetch(forwarded);
316
346
  }
@@ -0,0 +1,195 @@
1
+ /**
2
+ * R2-binding segment and blob stores (SPEC.md §5.1, §5.9.2) for Cloudflare
3
+ * Workers.
4
+ *
5
+ * `R2SegmentStore` and `R2BlobStore` run the same bucket-generic store logic
6
+ * as `S3SegmentStore` and `S3BlobStore` (`BucketSegmentStore` /
7
+ * `BucketBlobStore` in `@syncular/server`) over the Worker's `env.BUCKET`
8
+ * binding instead of the S3 REST API. No S3 credentials, no SigV4 signing, and
9
+ * no outbound request: every read and write is a binding call, which works the
10
+ * same under `wrangler dev --local`.
11
+ *
12
+ * The object key layout is identical to the S3 stores, so one bucket serves
13
+ * both access paths: a Bun or Node host can publish segments and blobs through
14
+ * the S3 API while the Worker reads them through the binding.
15
+ *
16
+ * There are no `presign*` methods here. A binding cannot mint a provider URL,
17
+ * so segments and blobs are served inline through `GET /segments/:id` and
18
+ * `GET /blobs/:id` (the `open` path streams them without buffering the object
19
+ * in the isolate). Configure no `signedUrls` / `blobSignedUrls` for a binding
20
+ * deployment; the core falls back to inline delivery.
21
+ *
22
+ * The binding surface is declared structurally below, so this package keeps
23
+ * taking no `@cloudflare/workers-types` dependency. Cloudflare's `R2Bucket`
24
+ * is assignable to `R2BucketLike`.
25
+ */
26
+ import {
27
+ BucketBlobStore,
28
+ type BucketBlobStoreOptions,
29
+ BucketSegmentStore,
30
+ type BucketSegmentStoreOptions,
31
+ type ObjectBucket,
32
+ } from '@syncular/server';
33
+
34
+ // -- R2 bindings (structural; no @cloudflare/workers-types dep) -------------
35
+
36
+ /** `R2Conditional`: the precondition R2 evaluates before it writes. */
37
+ export interface R2ConditionLike {
38
+ /** Write only if the stored ETag equals this one. */
39
+ readonly etagMatches?: string;
40
+ /** Write only if the stored ETag differs; `*` means "only when absent". */
41
+ readonly etagDoesNotMatch?: string;
42
+ }
43
+
44
+ /** `R2Object`: one stored object's description. */
45
+ export interface R2ObjectLike {
46
+ readonly key: string;
47
+ /** Unquoted object ETag (the CAS token; R2 also reports `httpEtag`). */
48
+ readonly etag: string;
49
+ readonly size: number;
50
+ readonly customMetadata?: Readonly<Record<string, string>>;
51
+ }
52
+
53
+ /** `R2ObjectBody`: the object plus its bytes. */
54
+ export interface R2ObjectBodyLike extends R2ObjectLike {
55
+ readonly body: ReadableStream<Uint8Array<ArrayBuffer>>;
56
+ arrayBuffer(): Promise<ArrayBuffer>;
57
+ text(): Promise<string>;
58
+ }
59
+
60
+ /** `R2Objects`: one page of a `list`. */
61
+ export interface R2ObjectsLike {
62
+ readonly objects: readonly R2ObjectLike[];
63
+ readonly truncated: boolean;
64
+ readonly cursor?: string;
65
+ }
66
+
67
+ /** `R2PutOptions`: the subset the stores set. */
68
+ export interface R2PutOptionsLike {
69
+ readonly onlyIf?: R2ConditionLike;
70
+ readonly httpMetadata?: { readonly contentType?: string };
71
+ readonly customMetadata?: Record<string, string>;
72
+ }
73
+
74
+ /** `R2GetOptions`: declared for structural parity; the stores read plainly. */
75
+ export interface R2GetOptionsLike {
76
+ readonly onlyIf?: R2ConditionLike;
77
+ }
78
+
79
+ /**
80
+ * The `R2Bucket` binding surface the stores use
81
+ * (`wrangler [[r2_buckets]] binding = "BUCKET"` → `env.BUCKET`).
82
+ */
83
+ export interface R2BucketLike {
84
+ get(
85
+ key: string,
86
+ options?: R2GetOptionsLike,
87
+ ): Promise<R2ObjectBodyLike | null>;
88
+ head(key: string): Promise<R2ObjectLike | null>;
89
+ /** `null` when `onlyIf` failed, exactly as the platform reports it. */
90
+ put(
91
+ key: string,
92
+ value: Uint8Array,
93
+ options?: R2PutOptionsLike,
94
+ ): Promise<R2ObjectLike | null>;
95
+ delete(key: string): Promise<void>;
96
+ list(options: {
97
+ readonly prefix: string;
98
+ readonly cursor?: string;
99
+ readonly limit?: number;
100
+ }): Promise<R2ObjectsLike>;
101
+ }
102
+
103
+ function metadataOf(object: R2ObjectLike): Readonly<Record<string, string>> {
104
+ return object.customMetadata ?? {};
105
+ }
106
+
107
+ /**
108
+ * The `ObjectBucket` seam over one R2 binding. `etagMatches` /
109
+ * `etagDoesNotMatch: '*'` are the binding's spelling of the `If-Match` /
110
+ * `If-None-Match: *` preconditions the record and stats CAS depend on; a
111
+ * failed precondition is a `null` put result.
112
+ */
113
+ function r2ObjectBucket(bucket: R2BucketLike): ObjectBucket {
114
+ return {
115
+ async get(key) {
116
+ const object = await bucket.get(key);
117
+ if (object === null) return undefined;
118
+ return {
119
+ body: object.body,
120
+ etag: object.etag,
121
+ size: object.size,
122
+ metadata: metadataOf(object),
123
+ arrayBuffer: () => object.arrayBuffer(),
124
+ text: () => object.text(),
125
+ };
126
+ },
127
+ async head(key) {
128
+ const object = await bucket.head(key);
129
+ if (object === null) return undefined;
130
+ return {
131
+ etag: object.etag,
132
+ size: object.size,
133
+ metadata: metadataOf(object),
134
+ };
135
+ },
136
+ async put(key, options) {
137
+ const onlyIf: R2ConditionLike | undefined =
138
+ options.createOnly === true
139
+ ? { etagDoesNotMatch: '*' }
140
+ : options.ifMatch !== undefined
141
+ ? { etagMatches: options.ifMatch }
142
+ : undefined;
143
+ const written = await bucket.put(key, options.body, {
144
+ ...(onlyIf !== undefined ? { onlyIf } : {}),
145
+ httpMetadata: { contentType: options.contentType },
146
+ ...(options.metadata !== undefined
147
+ ? { customMetadata: { ...options.metadata } }
148
+ : {}),
149
+ });
150
+ return written !== null;
151
+ },
152
+ async delete(key) {
153
+ await bucket.delete(key);
154
+ },
155
+ async list(prefix, cursor) {
156
+ const page = await bucket.list({
157
+ prefix,
158
+ ...(cursor !== undefined ? { cursor } : {}),
159
+ });
160
+ return {
161
+ keys: page.objects.map((object) => object.key),
162
+ cursor: page.truncated ? page.cursor : undefined,
163
+ };
164
+ },
165
+ };
166
+ }
167
+
168
+ /**
169
+ * Segment store over an R2 binding. Same key layout, record CAS, reuse
170
+ * pointers, and approximate stats accumulator as `S3SegmentStore`.
171
+ *
172
+ * ```ts
173
+ * const segments = new R2SegmentStore(env.BUCKET);
174
+ * ```
175
+ */
176
+ export class R2SegmentStore extends BucketSegmentStore {
177
+ constructor(bucket: R2BucketLike, options?: BucketSegmentStoreOptions) {
178
+ super(r2ObjectBucket(bucket), options);
179
+ }
180
+ }
181
+
182
+ /**
183
+ * Blob store over an R2 binding. Same key layout, idempotent re-put, orphan
184
+ * sweep, and approximate stats accumulator as `S3BlobStore`. The sweep pages
185
+ * the binding's `list`, so no S3 credentials are needed for GC either.
186
+ *
187
+ * ```ts
188
+ * const blobs = new R2BlobStore(env.BUCKET);
189
+ * ```
190
+ */
191
+ export class R2BlobStore extends BucketBlobStore {
192
+ constructor(bucket: R2BucketLike, options?: BucketBlobStoreOptions) {
193
+ super(r2ObjectBucket(bucket), options);
194
+ }
195
+ }