@syncular/client 0.58.0 → 0.59.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.
Files changed (82) hide show
  1. package/README.md +7 -7
  2. package/dist/apply.d.ts +20 -11
  3. package/dist/apply.js +67 -45
  4. package/dist/blob.d.ts +17 -9
  5. package/dist/blob.js +5 -6
  6. package/dist/bun-database.d.ts +1 -0
  7. package/dist/bun-database.js +28 -0
  8. package/dist/client.d.ts +27 -10
  9. package/dist/client.js +357 -190
  10. package/dist/database.d.ts +5 -0
  11. package/dist/encryption.d.ts +2 -2
  12. package/dist/encryption.js +8 -2
  13. package/dist/errors.d.ts +2 -0
  14. package/dist/errors.js +4 -0
  15. package/dist/failed-overlay.d.ts +0 -1
  16. package/dist/failed-overlay.js +3 -6
  17. package/dist/http.d.ts +4 -1
  18. package/dist/http.js +61 -39
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/invalidation.d.ts +11 -10
  22. package/dist/invalidation.js +15 -26
  23. package/dist/local-purge.js +9 -12
  24. package/dist/local-rebootstrap.js +2 -2
  25. package/dist/multi-tab.d.ts +89 -1
  26. package/dist/multi-tab.js +70 -31
  27. package/dist/native-bridge.d.ts +235 -0
  28. package/dist/native-bridge.js +789 -0
  29. package/dist/node-database.d.ts +1 -0
  30. package/dist/node-database.js +29 -0
  31. package/dist/outbox.d.ts +9 -12
  32. package/dist/outbox.js +19 -36
  33. package/dist/outcomes.js +3 -3
  34. package/dist/previous-version.js +96 -114
  35. package/dist/query-guard.d.ts +25 -24
  36. package/dist/query-guard.js +34 -191
  37. package/dist/reactive-store.js +53 -11
  38. package/dist/realtime-supervisor.d.ts +9 -2
  39. package/dist/realtime-supervisor.js +31 -7
  40. package/dist/remote.js +11 -15
  41. package/dist/schema.js +15 -10
  42. package/dist/sync-scheduler.js +28 -2
  43. package/dist/transport.d.ts +19 -4
  44. package/dist/wasm-database.js +58 -21
  45. package/dist/worker-core.d.ts +5 -0
  46. package/dist/worker-core.js +80 -72
  47. package/dist/worker-host.d.ts +10 -5
  48. package/dist/worker-host.js +64 -7
  49. package/dist/worker-local-authority.js +2 -2
  50. package/dist/worker-protocol.d.ts +6 -2
  51. package/package.json +11 -3
  52. package/src/apply.ts +91 -55
  53. package/src/blob.ts +27 -15
  54. package/src/bun-database.ts +29 -0
  55. package/src/client.ts +477 -261
  56. package/src/database.ts +5 -0
  57. package/src/encryption.ts +10 -5
  58. package/src/errors.ts +8 -0
  59. package/src/failed-overlay.ts +3 -7
  60. package/src/http.ts +90 -79
  61. package/src/index.ts +1 -1
  62. package/src/invalidation.ts +17 -32
  63. package/src/local-purge.ts +11 -13
  64. package/src/local-rebootstrap.ts +2 -3
  65. package/src/multi-tab.ts +88 -30
  66. package/src/native-bridge.ts +1189 -0
  67. package/src/node-database.ts +32 -0
  68. package/src/outbox.ts +19 -41
  69. package/src/outcomes.ts +3 -5
  70. package/src/previous-version.ts +103 -114
  71. package/src/query-guard.ts +43 -180
  72. package/src/reactive-store.ts +50 -10
  73. package/src/realtime-supervisor.ts +37 -12
  74. package/src/remote.ts +12 -16
  75. package/src/schema.ts +19 -12
  76. package/src/sync-scheduler.ts +31 -1
  77. package/src/transport.ts +21 -2
  78. package/src/wasm-database.ts +76 -27
  79. package/src/worker-core.ts +94 -74
  80. package/src/worker-host.ts +63 -16
  81. package/src/worker-local-authority.ts +2 -5
  82. package/src/worker-protocol.ts +6 -2
package/src/multi-tab.ts CHANGED
@@ -19,7 +19,9 @@
19
19
  * announce {t,epoch,clientId,protocol,schemaVersion}
20
20
  * — "I am the leader, this epoch";
21
21
  * the answer to every hello
22
- * res {t,epoch,reqId,ok,value|error} — reply to one req
22
+ * res {t,epoch,to,reqId,ok,value|error}
23
+ * — reply to one req, for the
24
+ * follower `to` that sent it
23
25
  * event {t,epoch,event,to?} — fan-out (invalidate/presence/…),
24
26
  * or one tab's event when `to` is set
25
27
  *
@@ -29,17 +31,21 @@
29
31
  * from a stale epoch, and a follower discards any `res`/`event` that does not
30
32
  * match its current epoch — so a late reply from a tab that has since died
31
33
  * (or a duplicate from a previous leader) can never be mistaken for a live
32
- * one. Epoch is derived deterministically from a per-origin clock: each
33
- * promoter reads the highest epoch it has seen and adds one, so successive
34
- * leaders always strictly increase it even across the lock-handover gap.
34
+ * one. Every follower counts its `reqId`s from 1, so a follower also discards
35
+ * a `res` whose `to` names another tab. Epoch is derived deterministically
36
+ * from a per-origin clock: each promoter reads the highest epoch it has seen
37
+ * and adds one, so successive leaders always strictly increase it even across
38
+ * the lock-handover gap.
35
39
  *
36
40
  * Identity: every hello, req, and announce carries the sender's
37
41
  * {@link MULTI_TAB_PROTOCOL_VERSION} and application schema version. A leader
38
42
  * serves only requests with its own identity. A follower whose leader has a
39
43
  * different identity goes `blocked` with `leader-incompatible` and sends it
40
44
  * nothing. A leader that hears a hello from a newer tab closes its core and
41
- * releases the lock, so the newer tab takes over. Tabs from before protocol 1
42
- * send no identity and count as older.
45
+ * releases the lock, so the newer tab takes over. A newer follower sends one
46
+ * hello to every older leader it hears announce, so an older tab that promotes
47
+ * after the first one stepped down steps down as well. Tabs from before
48
+ * protocol 1 send no identity and count as older.
43
49
  *
44
50
  * Liveness is follower-driven: the leader runs no timer. Browsers throttle
45
51
  * the timers of a hidden tab (Chrome's intensive throttling wakes them about
@@ -93,7 +99,7 @@ export const TAKEOVER_REFUSED_CODE = 'client.takeover_refused';
93
99
  * with every change to a message shape or to a forwarded method's arguments
94
100
  * or result, so tabs of different builds never serve each other.
95
101
  */
96
- export const MULTI_TAB_PROTOCOL_VERSION = 2;
102
+ export const MULTI_TAB_PROTOCOL_VERSION = 3;
97
103
 
98
104
  /** What a tab must share with its leader to be served by it. */
99
105
  export interface TabIdentity {
@@ -134,6 +140,20 @@ export type LeadershipState =
134
140
  readonly state: 'waiting';
135
141
  readonly reason: 'handover' | 'leader-announcement';
136
142
  }
143
+ | {
144
+ /**
145
+ * This tab won the lock after the leader left and its core failed to
146
+ * start. It released the lock and, while `retrying`, asks for it again
147
+ * behind every other waiting tab; after the third failed start it stops
148
+ * contesting and binds to whichever tab leads next.
149
+ */
150
+ readonly state: 'waiting';
151
+ readonly reason: 'leader-start-failed';
152
+ readonly error: ClientSyncError;
153
+ /** Failed starts of this tab's core so far. */
154
+ readonly attempt: number;
155
+ readonly retrying: boolean;
156
+ }
137
157
  | {
138
158
  readonly state: 'blocked';
139
159
  readonly reason: 'leader-unreachable';
@@ -191,6 +211,8 @@ interface AnnounceMessage extends IdentityFields {
191
211
  interface ResMessage {
192
212
  readonly t: 'res';
193
213
  readonly epoch: number;
214
+ /** The follower that sent the request. */
215
+ readonly to: string;
194
216
  readonly reqId: number;
195
217
  readonly ok: boolean;
196
218
  readonly value?: unknown;
@@ -358,6 +380,7 @@ export class LeaderBridge<E = SyncWorkerEvent> {
358
380
  this.#channel.postMessage({
359
381
  t: 'res',
360
382
  epoch: this.#epoch,
383
+ to: fromId,
361
384
  reqId,
362
385
  ok: false,
363
386
  error: {
@@ -379,6 +402,7 @@ export class LeaderBridge<E = SyncWorkerEvent> {
379
402
  this.#channel.postMessage({
380
403
  t: 'res',
381
404
  epoch: this.#epoch,
405
+ to: fromId,
382
406
  reqId,
383
407
  ok: true,
384
408
  value,
@@ -405,6 +429,7 @@ export class LeaderBridge<E = SyncWorkerEvent> {
405
429
  this.#channel.postMessage({
406
430
  t: 'res',
407
431
  epoch: this.#epoch,
432
+ to: fromId,
408
433
  reqId,
409
434
  ok: false,
410
435
  error: shape,
@@ -471,6 +496,8 @@ export class FollowerLink<E = SyncWorkerEvent> {
471
496
  #nextReqId = 1;
472
497
  readonly #inFlight = new Map<number, QueuedCall>();
473
498
  readonly #replayOnHandover: ReadonlySet<string>;
499
+ /** `epoch:clientId` of every older leader this tab asked to step down. */
500
+ readonly #deposed = new Set<string>();
474
501
  #queue: QueuedCall[] = [];
475
502
  #closed = false;
476
503
  #state: LeadershipState = {
@@ -707,6 +734,13 @@ export class FollowerLink<E = SyncWorkerEvent> {
707
734
  if (message.epoch < this.#epoch) return;
708
735
  const relation = compareTabIdentity(message, this.#identity);
709
736
  if (relation !== 0) {
737
+ // An older leader steps down for this tab's hello. Each one hears it
738
+ // once: an older tab that promotes later is another leader.
739
+ const leader = `${message.epoch}:${message.clientId}`;
740
+ if (relation < 0 && !this.#deposed.has(leader)) {
741
+ this.#deposed.add(leader);
742
+ this.#probe();
743
+ }
710
744
  this.#setIncompatible(relation < 0 ? 'older' : 'newer');
711
745
  return;
712
746
  }
@@ -742,8 +776,9 @@ export class FollowerLink<E = SyncWorkerEvent> {
742
776
  }
743
777
  if (message.t === 'res') {
744
778
  // Discard a reply for a stale epoch — the leader that produced it is
745
- // gone; the request (if still pending) is being retried elsewhere.
746
- if (message.epoch !== this.#epoch) return;
779
+ // gone; the request (if still pending) is being retried elsewhere. A
780
+ // reply for another follower carries a `reqId` of that tab's counter.
781
+ if (message.epoch !== this.#epoch || message.to !== this.#fromId) return;
747
782
  const inflight = this.#inFlight.get(message.reqId);
748
783
  if (inflight === undefined) return;
749
784
  this.#inFlight.delete(message.reqId);
@@ -883,9 +918,9 @@ export class FollowerLink<E = SyncWorkerEvent> {
883
918
  }
884
919
 
885
920
  /**
886
- * The leader runs another build. Send it nothing and stay unbound until a
887
- * leader with this tab's identity announces (a newer leader's own hello
888
- * already asked an older one to step down; see the module comment).
921
+ * The leader runs another build. Send it nothing but the one step-down
922
+ * hello for an older leader, and stay unbound until a leader with this
923
+ * tab's identity announces (see the module comment).
889
924
  */
890
925
  #setIncompatible(leader: 'older' | 'newer'): void {
891
926
  this.#clearReachabilityTimers();
@@ -1438,26 +1473,49 @@ export async function createTabCoordinator<E>(
1438
1473
  : {}),
1439
1474
  });
1440
1475
  follower = link;
1476
+ let failedStarts = 0;
1441
1477
  // Granted only when the lock is released: the leader's tab closed, or this
1442
1478
  // tab's own failed takeover let go of it.
1443
- void lock.acquire(config.name).then(async (promoted) => {
1444
- if (closed || follower !== link) {
1445
- // Closed, or this tab already leads through takeOver(): promoting would
1446
- // hold the lock forever.
1447
- await promoted.release();
1448
- return;
1449
- }
1450
- // The new leader must exceed every epoch this tab saw, so stale replies
1451
- // and events are discarded everywhere.
1452
- const epoch = link.maxEpochSeen + 1;
1453
- link.unbind();
1454
- try {
1455
- await lead(promoted, epoch, false);
1456
- } catch {
1457
- // The core failed to start: release so the next tab tries.
1458
- await promoted.release();
1459
- }
1460
- });
1479
+ const contest = (): void => {
1480
+ void lock.acquire(config.name).then(async (promoted) => {
1481
+ if (closed || follower !== link) {
1482
+ // Closed, or this tab already leads through takeOver(): promoting
1483
+ // would hold the lock forever.
1484
+ await promoted.release();
1485
+ return;
1486
+ }
1487
+ // The new leader must exceed every epoch this tab saw, so stale replies
1488
+ // and events are discarded everywhere.
1489
+ const epoch = link.maxEpochSeen + 1;
1490
+ link.unbind();
1491
+ try {
1492
+ await lead(promoted, epoch, false);
1493
+ } catch (error) {
1494
+ // Release so the next waiting tab tries, then queue behind it. Three
1495
+ // failed starts stop the contest: a core that fails the same way each
1496
+ // time (a changed worker bundle, an unreadable database) would
1497
+ // otherwise take and drop the lock in a loop while this tab is alone.
1498
+ await promoted.release();
1499
+ failedStarts += 1;
1500
+ const retrying = failedStarts < 3 && !closed;
1501
+ setState({
1502
+ state: 'waiting',
1503
+ reason: 'leader-start-failed',
1504
+ error:
1505
+ error instanceof ClientSyncError
1506
+ ? error
1507
+ : new ClientSyncError(
1508
+ WORKER_FAILED_CODE,
1509
+ 'the core failed to start',
1510
+ ),
1511
+ attempt: failedStarts,
1512
+ retrying,
1513
+ });
1514
+ if (retrying) contest();
1515
+ }
1516
+ });
1517
+ };
1518
+ contest();
1461
1519
  // Return bound: an event the leader fans out before binding is dropped.
1462
1520
  try {
1463
1521
  await link.waitUntilBound();