@syncular/server-workers 0.79.3 → 0.80.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 CHANGED
@@ -250,6 +250,8 @@ holds no socket: shards register with it and it relays every commit to them,
250
250
  retrying a shard whose relay failed from its alarm. Call
251
251
  `durableObjectRealtimeNotifier(env.REALTIME, { waitUntil }).refreshScopes(partition, actorId)`
252
252
  after a grant changes; it reaches the sessions in every shard.
253
+ `announceScopes(partition, actorIds)` on the same notifier tells those actors'
254
+ sessions in every shard that their grants grew (SPEC §8.7).
253
255
  A scope resolver reads its grants under `prepareReadTransaction`, so a pull
254
256
  never waits on a push. The setup, its costs and its Wrangler configuration are
255
257
  on the docs page (`apps/docs/src/content/server-workers.md`).
@@ -106,7 +106,7 @@
106
106
  * (`RealtimeHubConfig.fanout`) sends the commits of its own rounds through the
107
107
  * partition's object too, so every shard, the shard itself included, receives
108
108
  * each commit once. A host scope refresh (`refreshScopes` on the notifier)
109
- * takes the same path. A relay that fails leaves a record of what the shard
109
+ * and a host announcement (`announceScopes`) take the same path. A relay that fails leaves a record of what the shard
110
110
  * owes in the partition object's storage, and the alarm retries it every
111
111
  * second until the shard answers or is removed.
112
112
  */
@@ -260,9 +260,14 @@ export interface DurableObjectRealtimeNotifierOptions {
260
260
  * `refreshScopes(partition, actorId?)` is `RealtimeHub.refreshScopes` for
261
261
  * every object of the partition: call it after a grant changes. It throws when
262
262
  * the partition's object did not take the refresh.
263
+ *
264
+ * `announceScopes(partition, actorIds)` is `RealtimeHub.announceScopes` for
265
+ * every object of the partition: call it after a grant widened. It throws when
266
+ * the partition's object did not take the announcement.
263
267
  */
264
268
  export declare function durableObjectRealtimeNotifier(namespace: DurableObjectNamespaceLike, options: DurableObjectRealtimeNotifierOptions): RealtimeNotifier & {
265
269
  refreshScopes(partition: string, actorId?: string): Promise<void>;
270
+ announceScopes(partition: string, actorIds: readonly string[]): Promise<void>;
266
271
  };
267
272
  /** The identity the upgrade request must carry (resolved by the Worker). */
268
273
  export interface RealtimeUpgradeIdentity {
@@ -106,7 +106,7 @@
106
106
  * (`RealtimeHubConfig.fanout`) sends the commits of its own rounds through the
107
107
  * partition's object too, so every shard, the shard itself included, receives
108
108
  * each commit once. A host scope refresh (`refreshScopes` on the notifier)
109
- * takes the same path. A relay that fails leaves a record of what the shard
109
+ * and a host announcement (`announceScopes`) take the same path. A relay that fails leaves a record of what the shard
110
110
  * owes in the partition object's storage, and the alarm retries it every
111
111
  * second until the shard answers or is removed.
112
112
  */
@@ -213,6 +213,10 @@ function decodeFanout(bytes) {
213
213
  * `refreshScopes(partition, actorId?)` is `RealtimeHub.refreshScopes` for
214
214
  * every object of the partition: call it after a grant changes. It throws when
215
215
  * the partition's object did not take the refresh.
216
+ *
217
+ * `announceScopes(partition, actorIds)` is `RealtimeHub.announceScopes` for
218
+ * every object of the partition: call it after a grant widened. It throws when
219
+ * the partition's object did not take the announcement.
216
220
  */
217
221
  export function durableObjectRealtimeNotifier(namespace, options) {
218
222
  // A synthetic origin: the DO reads only the path and the body. The partition
@@ -269,6 +273,12 @@ export function durableObjectRealtimeNotifier(namespace, options) {
269
273
  throw new SyncError('sync.internal_error', 'realtime scope refresh failed', JSON.stringify({ status }));
270
274
  }
271
275
  },
276
+ async announceScopes(partition, actorIds) {
277
+ const status = await send({ partition, announce: actorIds });
278
+ if (status !== 204 && status !== 404) {
279
+ throw new SyncError('sync.internal_error', 'realtime scope announcement failed', JSON.stringify({ status }));
280
+ }
281
+ },
272
282
  };
273
283
  }
274
284
  /** Internal control-request paths on the DO stub (never client-facing). */
@@ -657,9 +667,15 @@ export class SyncularRealtimeHost {
657
667
  else if ('refresh' in message) {
658
668
  await hub.refreshScopes(message.partition, message.refresh.actorId);
659
669
  }
670
+ else if ('announce' in message) {
671
+ hub.announceScopes(message.partition, message.announce);
672
+ }
660
673
  else {
661
674
  if (message.owed.refresh)
662
675
  await hub.refreshScopes(message.partition);
676
+ if (message.owed.announce !== undefined) {
677
+ hub.announceScopes(message.partition, message.owed.announce);
678
+ }
663
679
  if (message.owed.registrations) {
664
680
  hub.wake(message.partition, 'catchup-required');
665
681
  }
@@ -674,7 +690,9 @@ export class SyncularRealtimeHost {
674
690
  ? { registrations: true }
675
691
  : 'refresh' in message
676
692
  ? { refresh: true }
677
- : message.owed;
693
+ : 'announce' in message
694
+ ? { announce: message.announce }
695
+ : message.owed;
678
696
  await Promise.all([...shards].map(async ([key, token]) => {
679
697
  const shard = key.slice('shard:'.length);
680
698
  const status = await this.#relay(shard, token, bytes);
@@ -685,8 +703,13 @@ export class SyncularRealtimeHost {
685
703
  ? JSON.parse(stored).owed
686
704
  : {};
687
705
  const commitSeq = Math.max(before.commitSeq ?? -1, owes.commitSeq ?? -1);
706
+ const announce = new Set([
707
+ ...(before.announce ?? []),
708
+ ...(owes.announce ?? []),
709
+ ]);
688
710
  const owed = {
689
711
  ...(commitSeq >= 0 ? { commitSeq } : {}),
712
+ ...(announce.size > 0 ? { announce: [...announce] } : {}),
690
713
  ...(before.refresh || owes.refresh ? { refresh: true } : {}),
691
714
  ...(before.registrations || owes.registrations
692
715
  ? { registrations: true }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.79.3",
3
+ "version": "0.80.0",
4
4
  "description": "Cloudflare Workers adapter for the Syncular sync server",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -45,9 +45,9 @@
45
45
  "!dist/**/*.test.d.ts"
46
46
  ],
47
47
  "dependencies": {
48
- "@syncular/core": "0.79.3",
49
- "@syncular/server": "0.79.3",
50
- "@syncular/server-hono": "0.79.3"
48
+ "@syncular/core": "0.80.0",
49
+ "@syncular/server": "0.80.0",
50
+ "@syncular/server-hono": "0.80.0"
51
51
  },
52
52
  "devDependencies": {
53
53
  "@electric-sql/pglite": "^0.5.4",
@@ -106,7 +106,7 @@
106
106
  * (`RealtimeHubConfig.fanout`) sends the commits of its own rounds through the
107
107
  * partition's object too, so every shard, the shard itself included, receives
108
108
  * each commit once. A host scope refresh (`refreshScopes` on the notifier)
109
- * takes the same path. A relay that fails leaves a record of what the shard
109
+ * and a host announcement (`announceScopes`) take the same path. A relay that fails leaves a record of what the shard
110
110
  * owes in the partition object's storage, and the alarm retries it every
111
111
  * second until the shard answers or is removed.
112
112
  */
@@ -323,16 +323,19 @@ function encodeAttachment(
323
323
  * §8.9: what a shard missed when a relay to it failed, delivered from the
324
324
  * partition object's alarm: the highest commit sequence (sessions behind it get
325
325
  * a `catchup-required` wake), a fail-closed refresh of every session's scopes,
326
- * and changed registrations (a wake, whose round reloads them).
326
+ * changed registrations (a wake, whose round reloads them), and the actors of
327
+ * missed announcements (a `scopes` event, §8.7).
327
328
  */
328
329
  interface Owed {
329
330
  readonly commitSeq?: number;
330
331
  readonly refresh?: true;
331
332
  readonly registrations?: true;
333
+ readonly announce?: readonly string[];
332
334
  }
333
335
 
334
336
  /** A message between objects (§8.9): a commit, a client's changed
335
- * registrations, a host refresh of scopes, or what a failed relay owes. */
337
+ * registrations, a host refresh of scopes, a host announcement, or what a
338
+ * failed relay owes. */
336
339
  type FanoutMessage =
337
340
  | { readonly partition: string; readonly commit: StoredCommit }
338
341
  | { readonly partition: string; readonly clientId: string }
@@ -340,6 +343,7 @@ type FanoutMessage =
340
343
  readonly partition: string;
341
344
  readonly refresh: { readonly actorId?: string };
342
345
  }
346
+ | { readonly partition: string; readonly announce: readonly string[] }
343
347
  | { readonly partition: string; readonly owed: Owed };
344
348
 
345
349
  /**
@@ -437,12 +441,17 @@ export interface DurableObjectRealtimeNotifierOptions {
437
441
  * `refreshScopes(partition, actorId?)` is `RealtimeHub.refreshScopes` for
438
442
  * every object of the partition: call it after a grant changes. It throws when
439
443
  * the partition's object did not take the refresh.
444
+ *
445
+ * `announceScopes(partition, actorIds)` is `RealtimeHub.announceScopes` for
446
+ * every object of the partition: call it after a grant widened. It throws when
447
+ * the partition's object did not take the announcement.
440
448
  */
441
449
  export function durableObjectRealtimeNotifier(
442
450
  namespace: DurableObjectNamespaceLike,
443
451
  options: DurableObjectRealtimeNotifierOptions,
444
452
  ): RealtimeNotifier & {
445
453
  refreshScopes(partition: string, actorId?: string): Promise<void>;
454
+ announceScopes(partition: string, actorIds: readonly string[]): Promise<void>;
446
455
  } {
447
456
  // A synthetic origin: the DO reads only the path and the body. The partition
448
457
  // object answers 204, or 404 when no object of the partition holds a socket.
@@ -509,6 +518,16 @@ export function durableObjectRealtimeNotifier(
509
518
  );
510
519
  }
511
520
  },
521
+ async announceScopes(partition, actorIds) {
522
+ const status = await send({ partition, announce: actorIds });
523
+ if (status !== 204 && status !== 404) {
524
+ throw new SyncError(
525
+ 'sync.internal_error',
526
+ 'realtime scope announcement failed',
527
+ JSON.stringify({ status }),
528
+ );
529
+ }
530
+ },
512
531
  };
513
532
  }
514
533
 
@@ -1006,8 +1025,13 @@ export class SyncularRealtimeHost<
1006
1025
  await hub.notifySubscriptions(message.partition, message.clientId);
1007
1026
  } else if ('refresh' in message) {
1008
1027
  await hub.refreshScopes(message.partition, message.refresh.actorId);
1028
+ } else if ('announce' in message) {
1029
+ hub.announceScopes(message.partition, message.announce);
1009
1030
  } else {
1010
1031
  if (message.owed.refresh) await hub.refreshScopes(message.partition);
1032
+ if (message.owed.announce !== undefined) {
1033
+ hub.announceScopes(message.partition, message.owed.announce);
1034
+ }
1011
1035
  if (message.owed.registrations) {
1012
1036
  hub.wake(message.partition, 'catchup-required');
1013
1037
  }
@@ -1023,7 +1047,9 @@ export class SyncularRealtimeHost<
1023
1047
  ? { registrations: true }
1024
1048
  : 'refresh' in message
1025
1049
  ? { refresh: true }
1026
- : message.owed;
1050
+ : 'announce' in message
1051
+ ? { announce: message.announce }
1052
+ : message.owed;
1027
1053
  await Promise.all(
1028
1054
  [...shards].map(async ([key, token]) => {
1029
1055
  const shard = key.slice('shard:'.length);
@@ -1038,8 +1064,13 @@ export class SyncularRealtimeHost<
1038
1064
  before.commitSeq ?? -1,
1039
1065
  owes.commitSeq ?? -1,
1040
1066
  );
1067
+ const announce = new Set([
1068
+ ...(before.announce ?? []),
1069
+ ...(owes.announce ?? []),
1070
+ ]);
1041
1071
  const owed: Owed = {
1042
1072
  ...(commitSeq >= 0 ? { commitSeq } : {}),
1073
+ ...(announce.size > 0 ? { announce: [...announce] } : {}),
1043
1074
  ...(before.refresh || owes.refresh ? { refresh: true } : {}),
1044
1075
  ...(before.registrations || owes.registrations
1045
1076
  ? { registrations: true }