@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.
- package/README.md +30 -25
- package/dist/index.d.ts +14 -7
- package/dist/index.js +40 -19
- package/dist/r2-stores.d.ts +104 -0
- package/dist/r2-stores.js +117 -0
- package/dist/realtime-do.d.ts +19 -6
- package/dist/realtime-do.js +107 -12
- package/package.json +4 -4
- package/src/index.ts +49 -19
- package/src/r2-stores.ts +195 -0
- package/src/realtime-do.ts +123 -21
package/dist/realtime-do.js
CHANGED
|
@@ -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
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
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`
|
|
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
|
-
*
|
|
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
|
|
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 =
|
|
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 =
|
|
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.
|
|
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.
|
|
49
|
-
"@syncular/server-hono": "0.
|
|
48
|
+
"@syncular/server": "0.33.0",
|
|
49
|
+
"@syncular/server-hono": "0.33.0"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
|
-
"@syncular/core": "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 /
|
|
13
|
-
* config the host assembles from `env
|
|
14
|
-
* `
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
287
|
-
|
|
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
|
|
293
|
-
|
|
294
|
-
|
|
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
|
|
301
|
-
*
|
|
302
|
-
*
|
|
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
|
}
|
package/src/r2-stores.ts
ADDED
|
@@ -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
|
+
}
|