@syncular/client 0.55.1 → 0.56.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/dist/multi-tab.d.ts +11 -2
- package/dist/multi-tab.js +36 -10
- package/dist/worker-host.js +3 -0
- package/package.json +3 -3
- package/src/multi-tab.ts +51 -22
- package/src/worker-host.ts +3 -0
package/dist/multi-tab.d.ts
CHANGED
|
@@ -181,6 +181,7 @@ export declare class FollowerLink<E = SyncWorkerEvent> {
|
|
|
181
181
|
callTimeoutMs?: number;
|
|
182
182
|
queueLimit?: number;
|
|
183
183
|
schedule?: FollowerSchedule;
|
|
184
|
+
replayOnHandover?: readonly string[];
|
|
184
185
|
});
|
|
185
186
|
get epoch(): number;
|
|
186
187
|
get maxEpochSeen(): number;
|
|
@@ -204,8 +205,9 @@ export declare class FollowerLink<E = SyncWorkerEvent> {
|
|
|
204
205
|
/**
|
|
205
206
|
* The leader we were bound to went away (its lock released). Un-bind so new
|
|
206
207
|
* calls queue again; re-request an announce so the next leader finds us.
|
|
207
|
-
* Calls in flight to the departed leader reject
|
|
208
|
-
* flushes the queued
|
|
208
|
+
* Calls in flight to the departed leader reject, except `replayOnHandover`
|
|
209
|
+
* methods, which queue again; the winner's announce flushes the queued
|
|
210
|
+
* ones.
|
|
209
211
|
*/
|
|
210
212
|
unbind(): void;
|
|
211
213
|
/**
|
|
@@ -304,6 +306,13 @@ export interface TabCoordinatorConfig<E> {
|
|
|
304
306
|
readonly channelFactory?: (name: string) => CrossTabChannel<E>;
|
|
305
307
|
/** Liveness and handover-queue deadline; defaults to 10 s. */
|
|
306
308
|
readonly callTimeoutMs?: number;
|
|
309
|
+
/**
|
|
310
|
+
* Methods whose follower call, in flight when the leader changes, runs again
|
|
311
|
+
* on the next leader instead of rejecting with `client.leader_handover`.
|
|
312
|
+
* List only methods whose result does not depend on whether the departed
|
|
313
|
+
* core ran them.
|
|
314
|
+
*/
|
|
315
|
+
readonly replayOnHandover?: readonly string[];
|
|
307
316
|
/**
|
|
308
317
|
* How long a follower must have been `leader-unreachable` before
|
|
309
318
|
* `takeOver()` is allowed; defaults to twice `callTimeoutMs`.
|
package/dist/multi-tab.js
CHANGED
|
@@ -291,6 +291,7 @@ export class FollowerLink {
|
|
|
291
291
|
#leaderClientId = '';
|
|
292
292
|
#nextReqId = 1;
|
|
293
293
|
#inFlight = new Map();
|
|
294
|
+
#replayOnHandover;
|
|
294
295
|
#queue = [];
|
|
295
296
|
#closed = false;
|
|
296
297
|
#state = {
|
|
@@ -312,6 +313,7 @@ export class FollowerLink {
|
|
|
312
313
|
options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
|
|
313
314
|
this.#probeAfterMs = Math.max(1, Math.floor(this.#callTimeoutMs / 3));
|
|
314
315
|
this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
|
|
316
|
+
this.#replayOnHandover = new Set(options.replayOnHandover);
|
|
315
317
|
this.#schedule =
|
|
316
318
|
options.schedule ??
|
|
317
319
|
((callback, delayMs) => {
|
|
@@ -420,10 +422,7 @@ export class FollowerLink {
|
|
|
420
422
|
const reqId = this.#nextReqId++;
|
|
421
423
|
// No deadline: a live leader may queue the call behind a long sync round.
|
|
422
424
|
// The liveness probe, a leader change, or close settles it otherwise.
|
|
423
|
-
this.#inFlight.set(reqId,
|
|
424
|
-
resolve: queued.resolve,
|
|
425
|
-
reject: queued.reject,
|
|
426
|
-
});
|
|
425
|
+
this.#inFlight.set(reqId, queued);
|
|
427
426
|
this.#channel.postMessage({
|
|
428
427
|
t: 'req',
|
|
429
428
|
epoch: this.#epoch,
|
|
@@ -448,6 +447,23 @@ export class FollowerLink {
|
|
|
448
447
|
for (const inflight of pending)
|
|
449
448
|
inflight.reject(error);
|
|
450
449
|
}
|
|
450
|
+
/**
|
|
451
|
+
* The leader changed before it answered. Calls to `replayOnHandover`
|
|
452
|
+
* methods return for replay on the next leader. Every other call rejects
|
|
453
|
+
* with `error`: the follower cannot tell whether the old core applied it.
|
|
454
|
+
*/
|
|
455
|
+
#handOverInFlight(error) {
|
|
456
|
+
const pending = [...this.#inFlight.values()];
|
|
457
|
+
this.#inFlight.clear();
|
|
458
|
+
const replay = [];
|
|
459
|
+
for (const inflight of pending) {
|
|
460
|
+
if (this.#replayOnHandover.has(inflight.method))
|
|
461
|
+
replay.push(inflight);
|
|
462
|
+
else
|
|
463
|
+
inflight.reject(error);
|
|
464
|
+
}
|
|
465
|
+
return replay;
|
|
466
|
+
}
|
|
451
467
|
#dropQueued(queued) {
|
|
452
468
|
const index = this.#queue.indexOf(queued);
|
|
453
469
|
if (index >= 0)
|
|
@@ -471,9 +487,9 @@ export class FollowerLink {
|
|
|
471
487
|
const changed = message.epoch !== this.#epoch ||
|
|
472
488
|
message.clientId !== this.#leaderClientId;
|
|
473
489
|
// Calls sent to the previous leader get no answer from this one.
|
|
474
|
-
|
|
475
|
-
this.#
|
|
476
|
-
|
|
490
|
+
const replay = changed && this.#epoch >= 0
|
|
491
|
+
? this.#handOverInFlight(new ClientSyncError(LEADER_HANDOVER_CODE, 'the leader changed before it answered the call', true))
|
|
492
|
+
: [];
|
|
477
493
|
this.#epoch = message.epoch;
|
|
478
494
|
this.#leaderClientId = message.clientId;
|
|
479
495
|
if (changed)
|
|
@@ -486,6 +502,9 @@ export class FollowerLink {
|
|
|
486
502
|
this.#armLivenessProbe();
|
|
487
503
|
this.#resolveBindWaiters();
|
|
488
504
|
this.#flushQueue();
|
|
505
|
+
for (const call of replay) {
|
|
506
|
+
this.call(call.method, call.args).then(call.resolve, call.reject);
|
|
507
|
+
}
|
|
489
508
|
return;
|
|
490
509
|
}
|
|
491
510
|
if (message.t === 'res') {
|
|
@@ -528,17 +547,21 @@ export class FollowerLink {
|
|
|
528
547
|
/**
|
|
529
548
|
* The leader we were bound to went away (its lock released). Un-bind so new
|
|
530
549
|
* calls queue again; re-request an announce so the next leader finds us.
|
|
531
|
-
* Calls in flight to the departed leader reject
|
|
532
|
-
* flushes the queued
|
|
550
|
+
* Calls in flight to the departed leader reject, except `replayOnHandover`
|
|
551
|
+
* methods, which queue again; the winner's announce flushes the queued
|
|
552
|
+
* ones.
|
|
533
553
|
*/
|
|
534
554
|
unbind() {
|
|
535
555
|
if (this.#closed)
|
|
536
556
|
return;
|
|
537
|
-
this.#
|
|
557
|
+
const replay = this.#handOverInFlight(new ClientSyncError(LEADER_HANDOVER_CODE, 'the leader released the database before it answered the call', true));
|
|
538
558
|
this.#epoch = -1;
|
|
539
559
|
this.#leaderClientId = '';
|
|
540
560
|
this.#setState({ state: 'waiting', reason: 'handover' });
|
|
541
561
|
this.#armUnboundDeadline();
|
|
562
|
+
for (const call of replay) {
|
|
563
|
+
this.call(call.method, call.args).then(call.resolve, call.reject);
|
|
564
|
+
}
|
|
542
565
|
this.#probe();
|
|
543
566
|
}
|
|
544
567
|
/**
|
|
@@ -968,6 +991,9 @@ export async function createTabCoordinator(config) {
|
|
|
968
991
|
onStateChange: setState,
|
|
969
992
|
callTimeoutMs,
|
|
970
993
|
schedule: clock.schedule,
|
|
994
|
+
...(config.replayOnHandover !== undefined
|
|
995
|
+
? { replayOnHandover: config.replayOnHandover }
|
|
996
|
+
: {}),
|
|
971
997
|
});
|
|
972
998
|
follower = link;
|
|
973
999
|
// Granted only when the lock is released: the leader's tab closed, or this
|
package/dist/worker-host.js
CHANGED
|
@@ -701,6 +701,9 @@ export async function createSyncClientHandle(config) {
|
|
|
701
701
|
name: lockName,
|
|
702
702
|
version: resolvedConfig.schema.version,
|
|
703
703
|
lock,
|
|
704
|
+
// A promoted leader starts a fresh core, so the realtime state a follower
|
|
705
|
+
// set on the departed core is gone either way.
|
|
706
|
+
replayOnHandover: ['connectRealtime', 'disconnectRealtime'],
|
|
704
707
|
...(resolvedConfig.channelFactory !== undefined
|
|
705
708
|
? { channelFactory: resolvedConfig.channelFactory }
|
|
706
709
|
: {}),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.56.0",
|
|
4
4
|
"description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -105,11 +105,11 @@
|
|
|
105
105
|
},
|
|
106
106
|
"dependencies": {
|
|
107
107
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
108
|
-
"@syncular/core": "0.
|
|
108
|
+
"@syncular/core": "0.56.0"
|
|
109
109
|
},
|
|
110
110
|
"devDependencies": {
|
|
111
111
|
"@electric-sql/pglite": "^0.5.4",
|
|
112
|
-
"@syncular/server": "0.
|
|
112
|
+
"@syncular/server": "0.56.0",
|
|
113
113
|
"playwright": "1.63.0",
|
|
114
114
|
"vite": "8.3.4"
|
|
115
115
|
}
|
package/src/multi-tab.ts
CHANGED
|
@@ -439,11 +439,6 @@ interface QueuedCall {
|
|
|
439
439
|
cancelTimer: (() => void) | undefined;
|
|
440
440
|
}
|
|
441
441
|
|
|
442
|
-
interface InFlight {
|
|
443
|
-
readonly resolve: (value: unknown) => void;
|
|
444
|
-
readonly reject: (error: unknown) => void;
|
|
445
|
-
}
|
|
446
|
-
|
|
447
442
|
/**
|
|
448
443
|
* Runs on a follower tab. Sends `req`s to the leader and settles them on the
|
|
449
444
|
* matching `res`; queues calls (bounded, timed) while no leader is bound (the
|
|
@@ -474,7 +469,8 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
474
469
|
#maxEpochSeen = -1;
|
|
475
470
|
#leaderClientId = '';
|
|
476
471
|
#nextReqId = 1;
|
|
477
|
-
readonly #inFlight = new Map<number,
|
|
472
|
+
readonly #inFlight = new Map<number, QueuedCall>();
|
|
473
|
+
readonly #replayOnHandover: ReadonlySet<string>;
|
|
478
474
|
#queue: QueuedCall[] = [];
|
|
479
475
|
#closed = false;
|
|
480
476
|
#state: LeadershipState = {
|
|
@@ -496,6 +492,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
496
492
|
callTimeoutMs?: number;
|
|
497
493
|
queueLimit?: number;
|
|
498
494
|
schedule?: FollowerSchedule;
|
|
495
|
+
replayOnHandover?: readonly string[];
|
|
499
496
|
}) {
|
|
500
497
|
this.#channel = options.channel;
|
|
501
498
|
this.#fromId = options.fromId;
|
|
@@ -507,6 +504,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
507
504
|
options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
|
|
508
505
|
this.#probeAfterMs = Math.max(1, Math.floor(this.#callTimeoutMs / 3));
|
|
509
506
|
this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
|
|
507
|
+
this.#replayOnHandover = new Set(options.replayOnHandover);
|
|
510
508
|
this.#schedule =
|
|
511
509
|
options.schedule ??
|
|
512
510
|
((callback, delayMs) => {
|
|
@@ -643,10 +641,7 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
643
641
|
const reqId = this.#nextReqId++;
|
|
644
642
|
// No deadline: a live leader may queue the call behind a long sync round.
|
|
645
643
|
// The liveness probe, a leader change, or close settles it otherwise.
|
|
646
|
-
this.#inFlight.set(reqId,
|
|
647
|
-
resolve: queued.resolve,
|
|
648
|
-
reject: queued.reject,
|
|
649
|
-
});
|
|
644
|
+
this.#inFlight.set(reqId, queued);
|
|
650
645
|
this.#channel.postMessage({
|
|
651
646
|
t: 'req',
|
|
652
647
|
epoch: this.#epoch,
|
|
@@ -681,6 +676,22 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
681
676
|
for (const inflight of pending) inflight.reject(error);
|
|
682
677
|
}
|
|
683
678
|
|
|
679
|
+
/**
|
|
680
|
+
* The leader changed before it answered. Calls to `replayOnHandover`
|
|
681
|
+
* methods return for replay on the next leader. Every other call rejects
|
|
682
|
+
* with `error`: the follower cannot tell whether the old core applied it.
|
|
683
|
+
*/
|
|
684
|
+
#handOverInFlight(error: ClientSyncError): QueuedCall[] {
|
|
685
|
+
const pending = [...this.#inFlight.values()];
|
|
686
|
+
this.#inFlight.clear();
|
|
687
|
+
const replay: QueuedCall[] = [];
|
|
688
|
+
for (const inflight of pending) {
|
|
689
|
+
if (this.#replayOnHandover.has(inflight.method)) replay.push(inflight);
|
|
690
|
+
else inflight.reject(error);
|
|
691
|
+
}
|
|
692
|
+
return replay;
|
|
693
|
+
}
|
|
694
|
+
|
|
684
695
|
#dropQueued(queued: QueuedCall): void {
|
|
685
696
|
const index = this.#queue.indexOf(queued);
|
|
686
697
|
if (index >= 0) this.#queue.splice(index, 1);
|
|
@@ -703,15 +714,16 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
703
714
|
message.epoch !== this.#epoch ||
|
|
704
715
|
message.clientId !== this.#leaderClientId;
|
|
705
716
|
// Calls sent to the previous leader get no answer from this one.
|
|
706
|
-
|
|
707
|
-
this.#
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
717
|
+
const replay =
|
|
718
|
+
changed && this.#epoch >= 0
|
|
719
|
+
? this.#handOverInFlight(
|
|
720
|
+
new ClientSyncError(
|
|
721
|
+
LEADER_HANDOVER_CODE,
|
|
722
|
+
'the leader changed before it answered the call',
|
|
723
|
+
true,
|
|
724
|
+
),
|
|
725
|
+
)
|
|
726
|
+
: [];
|
|
715
727
|
this.#epoch = message.epoch;
|
|
716
728
|
this.#leaderClientId = message.clientId;
|
|
717
729
|
if (changed) this.#onLeaderChange(message.clientId);
|
|
@@ -723,6 +735,9 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
723
735
|
this.#armLivenessProbe();
|
|
724
736
|
this.#resolveBindWaiters();
|
|
725
737
|
this.#flushQueue();
|
|
738
|
+
for (const call of replay) {
|
|
739
|
+
this.call(call.method, call.args).then(call.resolve, call.reject);
|
|
740
|
+
}
|
|
726
741
|
return;
|
|
727
742
|
}
|
|
728
743
|
if (message.t === 'res') {
|
|
@@ -769,12 +784,13 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
769
784
|
/**
|
|
770
785
|
* The leader we were bound to went away (its lock released). Un-bind so new
|
|
771
786
|
* calls queue again; re-request an announce so the next leader finds us.
|
|
772
|
-
* Calls in flight to the departed leader reject
|
|
773
|
-
* flushes the queued
|
|
787
|
+
* Calls in flight to the departed leader reject, except `replayOnHandover`
|
|
788
|
+
* methods, which queue again; the winner's announce flushes the queued
|
|
789
|
+
* ones.
|
|
774
790
|
*/
|
|
775
791
|
unbind(): void {
|
|
776
792
|
if (this.#closed) return;
|
|
777
|
-
this.#
|
|
793
|
+
const replay = this.#handOverInFlight(
|
|
778
794
|
new ClientSyncError(
|
|
779
795
|
LEADER_HANDOVER_CODE,
|
|
780
796
|
'the leader released the database before it answered the call',
|
|
@@ -785,6 +801,9 @@ export class FollowerLink<E = SyncWorkerEvent> {
|
|
|
785
801
|
this.#leaderClientId = '';
|
|
786
802
|
this.#setState({ state: 'waiting', reason: 'handover' });
|
|
787
803
|
this.#armUnboundDeadline();
|
|
804
|
+
for (const call of replay) {
|
|
805
|
+
this.call(call.method, call.args).then(call.resolve, call.reject);
|
|
806
|
+
}
|
|
788
807
|
this.#probe();
|
|
789
808
|
}
|
|
790
809
|
|
|
@@ -1054,6 +1073,13 @@ export interface TabCoordinatorConfig<E> {
|
|
|
1054
1073
|
readonly channelFactory?: (name: string) => CrossTabChannel<E>;
|
|
1055
1074
|
/** Liveness and handover-queue deadline; defaults to 10 s. */
|
|
1056
1075
|
readonly callTimeoutMs?: number;
|
|
1076
|
+
/**
|
|
1077
|
+
* Methods whose follower call, in flight when the leader changes, runs again
|
|
1078
|
+
* on the next leader instead of rejecting with `client.leader_handover`.
|
|
1079
|
+
* List only methods whose result does not depend on whether the departed
|
|
1080
|
+
* core ran them.
|
|
1081
|
+
*/
|
|
1082
|
+
readonly replayOnHandover?: readonly string[];
|
|
1057
1083
|
/**
|
|
1058
1084
|
* How long a follower must have been `leader-unreachable` before
|
|
1059
1085
|
* `takeOver()` is allowed; defaults to twice `callTimeoutMs`.
|
|
@@ -1407,6 +1433,9 @@ export async function createTabCoordinator<E>(
|
|
|
1407
1433
|
onStateChange: setState,
|
|
1408
1434
|
callTimeoutMs,
|
|
1409
1435
|
schedule: clock.schedule,
|
|
1436
|
+
...(config.replayOnHandover !== undefined
|
|
1437
|
+
? { replayOnHandover: config.replayOnHandover }
|
|
1438
|
+
: {}),
|
|
1410
1439
|
});
|
|
1411
1440
|
follower = link;
|
|
1412
1441
|
// Granted only when the lock is released: the leader's tab closed, or this
|
package/src/worker-host.ts
CHANGED
|
@@ -1125,6 +1125,9 @@ export async function createSyncClientHandle(
|
|
|
1125
1125
|
name: lockName,
|
|
1126
1126
|
version: resolvedConfig.schema.version,
|
|
1127
1127
|
lock,
|
|
1128
|
+
// A promoted leader starts a fresh core, so the realtime state a follower
|
|
1129
|
+
// set on the departed core is gone either way.
|
|
1130
|
+
replayOnHandover: ['connectRealtime', 'disconnectRealtime'],
|
|
1128
1131
|
...(resolvedConfig.channelFactory !== undefined
|
|
1129
1132
|
? { channelFactory: resolvedConfig.channelFactory }
|
|
1130
1133
|
: {}),
|