@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,7 +65,8 @@
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.
@@ -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
- * lazily rehydrated on the first message per socket (see the class doc). */
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 result = this.#partitionTail.then(operation, operation);
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 = adapterSyncError(
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 = adapterSyncError(
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 {