@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/src/realtime-do.ts
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,7 +65,8 @@
|
|
|
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.
|
|
@@ -73,16 +77,19 @@ import {
|
|
|
73
77
|
createRealtimeHub,
|
|
74
78
|
D1ServerStorage,
|
|
75
79
|
errorBody,
|
|
80
|
+
handleRemoteOperation,
|
|
76
81
|
handleSyncRequest,
|
|
77
82
|
pruneCommitLog,
|
|
78
83
|
type PruneOptions,
|
|
79
84
|
type RealtimeHub,
|
|
80
85
|
type RealtimeHubConfig,
|
|
81
86
|
type RealtimeSession,
|
|
87
|
+
type RemoteOperationRegistry,
|
|
82
88
|
RingBufferEvents,
|
|
83
89
|
SSP2_CONTENT_TYPE,
|
|
84
90
|
SyncError,
|
|
85
91
|
SyncularAdmin,
|
|
92
|
+
type SyncularErrorRoute,
|
|
86
93
|
} from '@syncular/server';
|
|
87
94
|
import { createSyncularAdminRoutes } from '@syncular/server-hono';
|
|
88
95
|
|
|
@@ -139,6 +146,12 @@ export type RealtimeDOConfig = (
|
|
|
139
146
|
* partition's rounds.
|
|
140
147
|
*/
|
|
141
148
|
readonly adminRingCapacity?: number;
|
|
149
|
+
/**
|
|
150
|
+
* Registered remote queries and commands (REMOTE.md). The Worker forwards
|
|
151
|
+
* `POST <mount>/operations` here, so a command applies on the partition
|
|
152
|
+
* FIFO and fans out to the partition's sockets like a pushed commit.
|
|
153
|
+
*/
|
|
154
|
+
readonly operations?: RemoteOperationRegistry;
|
|
142
155
|
};
|
|
143
156
|
|
|
144
157
|
/**
|
|
@@ -175,6 +188,10 @@ export interface RealtimeUpgradeIdentity {
|
|
|
175
188
|
export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
|
|
176
189
|
export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
|
|
177
190
|
export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
|
|
191
|
+
export const OPERATIONS_DO_REQUEST_PATH = '/__syncular_realtime/operations';
|
|
192
|
+
/** The remote operation protocol content type (REMOTE.md §5). */
|
|
193
|
+
export const OPERATIONS_CONTENT_TYPE =
|
|
194
|
+
'application/vnd.syncular.operations.v1+json';
|
|
178
195
|
/** Prefix of forwarded admin routes; the admin route path follows it. */
|
|
179
196
|
export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
|
|
180
197
|
|
|
@@ -208,11 +225,17 @@ export class SyncularRealtimeHost {
|
|
|
208
225
|
#hub: RealtimeHub | undefined;
|
|
209
226
|
#admin: SyncularAdmin | undefined;
|
|
210
227
|
/** Live sessions, keyed by their socket. Empty after a hibernation wake;
|
|
211
|
-
*
|
|
228
|
+
* rehydrated for every socket before the first serialized operation (see
|
|
229
|
+
* the class doc). */
|
|
212
230
|
readonly #sessions = new Map<WebSocketLike, RealtimeSession>();
|
|
213
231
|
/** Sockets whose rehydration `hello` must be swallowed (already greeted at
|
|
214
232
|
* the real upgrade — rehydration is transparent to the client). */
|
|
215
233
|
readonly #swallowHello = new Set<WebSocketLike>();
|
|
234
|
+
readonly #closedSockets = new WeakSet<WebSocketLike>();
|
|
235
|
+
/** Accepted sockets whose upgrade is still building their session. */
|
|
236
|
+
readonly #upgrading = new WeakSet<WebSocketLike>();
|
|
237
|
+
/** Set once this instance rebuilt the sessions of hibernated sockets. */
|
|
238
|
+
#rehydrated = false;
|
|
216
239
|
/** Explicit FIFO: Durable Object events may interleave at `await`. */
|
|
217
240
|
#partitionTail: Promise<void> = Promise.resolve();
|
|
218
241
|
|
|
@@ -277,8 +300,11 @@ export class SyncularRealtimeHost {
|
|
|
277
300
|
if (url.pathname === SYNC_DO_REQUEST_PATH) {
|
|
278
301
|
return this.#serializePartition(() => this.#handleSync(request));
|
|
279
302
|
}
|
|
303
|
+
if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
|
|
304
|
+
return this.#serializePartition(() => this.#handleOperation(request));
|
|
305
|
+
}
|
|
280
306
|
if (url.pathname === REALTIME_DO_WAKE_PATH) {
|
|
281
|
-
return this.#handleWake(request);
|
|
307
|
+
return this.#serializePartition(() => this.#handleWake(request));
|
|
282
308
|
}
|
|
283
309
|
if (url.pathname === REALTIME_DO_UPGRADE_PATH) {
|
|
284
310
|
return this.#handleUpgrade(request);
|
|
@@ -298,7 +324,11 @@ export class SyncularRealtimeHost {
|
|
|
298
324
|
}
|
|
299
325
|
|
|
300
326
|
#serializePartition<T>(operation: () => Promise<T>): Promise<T> {
|
|
301
|
-
const
|
|
327
|
+
const run = async (): Promise<T> => {
|
|
328
|
+
await this.#rehydrateSockets();
|
|
329
|
+
return operation();
|
|
330
|
+
};
|
|
331
|
+
const result = this.#partitionTail.then(run, run);
|
|
302
332
|
this.#partitionTail = result.then(
|
|
303
333
|
() => undefined,
|
|
304
334
|
() => undefined,
|
|
@@ -306,6 +336,76 @@ export class SyncularRealtimeHost {
|
|
|
306
336
|
return result;
|
|
307
337
|
}
|
|
308
338
|
|
|
339
|
+
/**
|
|
340
|
+
* After a hibernation wake the session map is empty while sockets stay
|
|
341
|
+
* open. Rebuild every socket's session before the first serialized
|
|
342
|
+
* operation, so a commit fans out to sockets that stayed quiet through
|
|
343
|
+
* the hibernation. A socket whose session cannot be rebuilt is closed;
|
|
344
|
+
* its client reconnects and catches up (§8.4).
|
|
345
|
+
*/
|
|
346
|
+
async #rehydrateSockets(): Promise<void> {
|
|
347
|
+
if (this.#rehydrated) return;
|
|
348
|
+
this.#rehydrated = true;
|
|
349
|
+
for (const ws of this.#state.getWebSockets()) {
|
|
350
|
+
if (this.#upgrading.has(ws)) continue;
|
|
351
|
+
try {
|
|
352
|
+
await this.#sessionFor(ws);
|
|
353
|
+
} catch (error) {
|
|
354
|
+
ws.close(1011, 'realtime rehydration failed');
|
|
355
|
+
this.#syncError(error, 'realtime');
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* Map a host failure to its catalog error. The reporters are read inside
|
|
362
|
+
* the callbacks so a failing accessor stays inside `adapterSyncError`.
|
|
363
|
+
*/
|
|
364
|
+
#syncError(error: unknown, route: SyncularErrorRoute): SyncError {
|
|
365
|
+
return adapterSyncError(
|
|
366
|
+
error,
|
|
367
|
+
(error, context) => this.#getHub().onError?.(error, context),
|
|
368
|
+
route,
|
|
369
|
+
(error, context) => this.#getHub().mapError?.(error, context),
|
|
370
|
+
);
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
async #handleOperation(request: Request): Promise<Response> {
|
|
374
|
+
const contentType = request.headers
|
|
375
|
+
.get('content-type')
|
|
376
|
+
?.split(';')[0]
|
|
377
|
+
?.trim();
|
|
378
|
+
if (contentType !== OPERATIONS_CONTENT_TYPE) {
|
|
379
|
+
const error = new SyncError('operation.invalid_request');
|
|
380
|
+
return Response.json(errorBody(error), { status: 415 });
|
|
381
|
+
}
|
|
382
|
+
const registry = this.#config.operations;
|
|
383
|
+
if (registry === undefined) {
|
|
384
|
+
const error = new SyncError('operation.unknown');
|
|
385
|
+
return Response.json(errorBody(error), { status: error.httpStatus });
|
|
386
|
+
}
|
|
387
|
+
const identity = readRequestIdentityHeaders(request);
|
|
388
|
+
if (identity === undefined) {
|
|
389
|
+
const error = new SyncError('sync.auth_required');
|
|
390
|
+
return Response.json(errorBody(error), { status: error.httpStatus });
|
|
391
|
+
}
|
|
392
|
+
try {
|
|
393
|
+
const bytes = new Uint8Array(await request.arrayBuffer());
|
|
394
|
+
const out = await handleRemoteOperation(
|
|
395
|
+
bytes,
|
|
396
|
+
this.#getHub().requestContextFor(identity),
|
|
397
|
+
registry,
|
|
398
|
+
);
|
|
399
|
+
return new Response(out.slice().buffer as ArrayBuffer, {
|
|
400
|
+
status: 200,
|
|
401
|
+
headers: { 'content-type': OPERATIONS_CONTENT_TYPE },
|
|
402
|
+
});
|
|
403
|
+
} catch (error) {
|
|
404
|
+
const sync = this.#syncError(error, 'operations');
|
|
405
|
+
return Response.json(errorBody(sync), { status: sync.httpStatus });
|
|
406
|
+
}
|
|
407
|
+
}
|
|
408
|
+
|
|
309
409
|
async #handleSync(request: Request): Promise<Response> {
|
|
310
410
|
const contentType = request.headers
|
|
311
411
|
.get('content-type')
|
|
@@ -334,12 +434,7 @@ export class SyncularRealtimeHost {
|
|
|
334
434
|
headers: { 'content-type': SSP2_CONTENT_TYPE },
|
|
335
435
|
});
|
|
336
436
|
} catch (error) {
|
|
337
|
-
const sync =
|
|
338
|
-
error,
|
|
339
|
-
(error, context) => this.#getHub().onError?.(error, context),
|
|
340
|
-
'sync',
|
|
341
|
-
(error, context) => this.#getHub().mapError?.(error, context),
|
|
342
|
-
);
|
|
437
|
+
const sync = this.#syncError(error, 'sync');
|
|
343
438
|
return Response.json(errorBody(sync), { status: sync.httpStatus });
|
|
344
439
|
}
|
|
345
440
|
}
|
|
@@ -350,7 +445,7 @@ export class SyncularRealtimeHost {
|
|
|
350
445
|
* Actions share the partition FIFO with sync rounds.
|
|
351
446
|
*/
|
|
352
447
|
async #handleAdmin(request: Request, url: URL): Promise<Response> {
|
|
353
|
-
this.#getHub();
|
|
448
|
+
const hub = this.#getHub();
|
|
354
449
|
const partition = request.headers.get(REALTIME_ID_HEADER.partition);
|
|
355
450
|
if (this.#admin === undefined || partition === null || partition === '') {
|
|
356
451
|
const error = new SyncError(
|
|
@@ -364,6 +459,8 @@ export class SyncularRealtimeHost {
|
|
|
364
459
|
...(request.headers.get(ADMIN_ACTIONS_HEADER) === '1'
|
|
365
460
|
? { authorizeActions: () => true }
|
|
366
461
|
: {}),
|
|
462
|
+
...(hub.onError !== undefined ? { onError: hub.onError } : {}),
|
|
463
|
+
...(hub.mapError !== undefined ? { mapError: hub.mapError } : {}),
|
|
367
464
|
});
|
|
368
465
|
url.pathname = url.pathname.slice(ADMIN_DO_PATH.length);
|
|
369
466
|
url.searchParams.set('partition', partition);
|
|
@@ -408,20 +505,18 @@ export class SyncularRealtimeHost {
|
|
|
408
505
|
clientId: identity.clientId,
|
|
409
506
|
};
|
|
410
507
|
server.serializeAttachment(attachment);
|
|
508
|
+
this.#upgrading.add(server);
|
|
411
509
|
this.#state.acceptWebSocket(server);
|
|
412
510
|
// Build the session now (first connect: hello IS delivered). Any failure
|
|
413
511
|
// closes the socket loudly — never a half-open realtime connection.
|
|
414
512
|
try {
|
|
415
513
|
const session = await this.#connectSession(server, attachment, false);
|
|
416
514
|
this.#sessions.set(server, session);
|
|
515
|
+
this.#upgrading.delete(server);
|
|
417
516
|
} catch (error) {
|
|
517
|
+
this.#upgrading.delete(server);
|
|
418
518
|
server.close(1011, 'realtime connect failed');
|
|
419
|
-
const sync =
|
|
420
|
-
error,
|
|
421
|
-
(error, context) => this.#getHub().onError?.(error, context),
|
|
422
|
-
'realtime',
|
|
423
|
-
(error, context) => this.#getHub().mapError?.(error, context),
|
|
424
|
-
);
|
|
519
|
+
const sync = this.#syncError(error, 'realtime');
|
|
425
520
|
return Response.json(errorBody(sync), { status: sync.httpStatus });
|
|
426
521
|
}
|
|
427
522
|
// `webSocket` is a workerd-only ResponseInit field (the 101 upgrade
|
|
@@ -460,11 +555,17 @@ export class SyncularRealtimeHost {
|
|
|
460
555
|
* the DO woke from hibernation and lost its in-memory map.
|
|
461
556
|
*/
|
|
462
557
|
async #sessionFor(ws: WebSocketLike): Promise<RealtimeSession | undefined> {
|
|
558
|
+
if (this.#closedSockets.has(ws)) return undefined;
|
|
463
559
|
const existing = this.#sessions.get(ws);
|
|
464
560
|
if (existing !== undefined) return existing;
|
|
465
561
|
const attachment = ws.deserializeAttachment();
|
|
466
562
|
if (!isAttachment(attachment)) return undefined;
|
|
467
563
|
const session = await this.#connectSession(ws, attachment, true);
|
|
564
|
+
if (this.#closedSockets.has(ws)) {
|
|
565
|
+
session.close();
|
|
566
|
+
this.#swallowHello.delete(ws);
|
|
567
|
+
return undefined;
|
|
568
|
+
}
|
|
468
569
|
this.#sessions.set(ws, session);
|
|
469
570
|
return session;
|
|
470
571
|
}
|
|
@@ -492,6 +593,7 @@ export class SyncularRealtimeHost {
|
|
|
492
593
|
|
|
493
594
|
/** Hibernation callback: the socket closed. */
|
|
494
595
|
async webSocketClose(ws: WebSocketLike): Promise<void> {
|
|
596
|
+
this.#closedSockets.add(ws);
|
|
495
597
|
const session = this.#sessions.get(ws);
|
|
496
598
|
if (session !== undefined) {
|
|
497
599
|
try {
|