@syncular/client 0.48.0 → 0.49.2
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 +50 -1
- package/dist/availability.d.ts +1 -1
- package/dist/availability.js +1 -1
- package/dist/client.js +18 -3
- package/dist/errors.d.ts +5 -0
- package/dist/errors.js +5 -0
- package/dist/leader-lock.d.ts +18 -7
- package/dist/leader-lock.js +40 -22
- package/dist/multi-tab.d.ts +158 -22
- package/dist/multi-tab.js +361 -10
- package/dist/outbox.d.ts +5 -0
- package/dist/outbox.js +11 -3
- package/dist/outcomes.js +6 -2
- package/dist/previous-version.d.ts +3 -1
- package/dist/previous-version.js +24 -5
- package/dist/reactive-store.js +2 -1
- package/dist/wasm-database.d.ts +6 -0
- package/dist/wasm-database.js +36 -6
- package/dist/worker-entry.d.ts +17 -1
- package/dist/worker-entry.js +74 -4
- package/dist/worker-host.d.ts +45 -26
- package/dist/worker-host.js +172 -310
- package/dist/worker-protocol.d.ts +22 -0
- package/dist/worker-protocol.js +2 -0
- package/package.json +3 -3
- package/src/availability.ts +3 -2
- package/src/client.ts +26 -3
- package/src/errors.ts +6 -0
- package/src/leader-lock.ts +64 -34
- package/src/multi-tab.ts +576 -34
- package/src/outbox.ts +16 -2
- package/src/outcomes.ts +6 -2
- package/src/previous-version.ts +32 -5
- package/src/reactive-store.ts +2 -1
- package/src/wasm-database.ts +64 -6
- package/src/worker-entry.ts +124 -4
- package/src/worker-host.ts +219 -379
- package/src/worker-protocol.ts +24 -0
package/src/multi-tab.ts
CHANGED
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
* — "I am the leader, this epoch";
|
|
21
21
|
* the answer to every hello
|
|
22
22
|
* res {t,epoch,reqId,ok,value|error} — reply to one req
|
|
23
|
-
* event {t,epoch,event}
|
|
23
|
+
* event {t,epoch,event,to?} — fan-out (invalidate/presence/…),
|
|
24
|
+
* or one tab's event when `to` is set
|
|
24
25
|
*
|
|
25
26
|
* Epoch (leader generation token): a monotonic counter carried in a shared
|
|
26
27
|
* BroadcastChannel and bumped by every promotion. Followers stamp requests
|
|
@@ -57,8 +58,18 @@
|
|
|
57
58
|
* is exactly ONE presence peer collectively — `(actorId, leaderClientId)`.
|
|
58
59
|
* A follower's `setPresence` forwards to the leader's single publisher; there
|
|
59
60
|
* is no per-tab presence peer (documented in the web-client README).
|
|
61
|
+
*
|
|
62
|
+
* Tab lifetime: every tab of a {@link TabCoordinator} holds an exclusive Web
|
|
63
|
+
* Lock named for its tab id until it closes. A leader whose core keeps per-tab
|
|
64
|
+
* state waits on that lock for each tab that called it; the grant means the
|
|
65
|
+
* tab is gone.
|
|
60
66
|
*/
|
|
61
67
|
import { ClientSyncError } from './errors';
|
|
68
|
+
import {
|
|
69
|
+
type LeaderLease,
|
|
70
|
+
type LeaderLock,
|
|
71
|
+
webLocksLeaderLock,
|
|
72
|
+
} from './leader-lock';
|
|
62
73
|
import type { SyncWorkerEvent } from './worker-protocol';
|
|
63
74
|
import { WORKER_FAILED_CODE } from './worker-protocol';
|
|
64
75
|
|
|
@@ -71,12 +82,18 @@ export const LEADER_INCOMPATIBLE_CODE = 'client.leader_incompatible';
|
|
|
71
82
|
/** Client-local: the leader that received a call stopped leading before it answered. */
|
|
72
83
|
export const LEADER_HANDOVER_CODE = 'client.leader_handover';
|
|
73
84
|
|
|
85
|
+
/** Client-local: another tab took this tab's leadership with `takeOver()`. */
|
|
86
|
+
export const LEADERSHIP_TAKEN_CODE = 'client.leadership_taken';
|
|
87
|
+
|
|
88
|
+
/** Client-local: `takeOver()` was called while its conditions do not hold. */
|
|
89
|
+
export const TAKEOVER_REFUSED_CODE = 'client.takeover_refused';
|
|
90
|
+
|
|
74
91
|
/**
|
|
75
92
|
* Version of the leader/follower wire and the forwarded handle API. Bump it
|
|
76
93
|
* with every change to a message shape or to a forwarded method's arguments
|
|
77
94
|
* or result, so tabs of different builds never serve each other.
|
|
78
95
|
*/
|
|
79
|
-
export const MULTI_TAB_PROTOCOL_VERSION =
|
|
96
|
+
export const MULTI_TAB_PROTOCOL_VERSION = 2;
|
|
80
97
|
|
|
81
98
|
/** What a tab must share with its leader to be served by it. */
|
|
82
99
|
export interface TabIdentity {
|
|
@@ -130,6 +147,12 @@ export type LeadershipState =
|
|
|
130
147
|
/** Whether the tab holding the database runs an older or a newer build. */
|
|
131
148
|
readonly leader: 'older' | 'newer';
|
|
132
149
|
readonly retryable: true;
|
|
150
|
+
}
|
|
151
|
+
| {
|
|
152
|
+
readonly state: 'blocked';
|
|
153
|
+
readonly reason: 'leadership-taken';
|
|
154
|
+
readonly code: typeof LEADERSHIP_TAKEN_CODE;
|
|
155
|
+
readonly retryable: true;
|
|
133
156
|
};
|
|
134
157
|
|
|
135
158
|
// ---------------------------------------------------------------------------
|
|
@@ -179,39 +202,43 @@ interface ResMessage {
|
|
|
179
202
|
};
|
|
180
203
|
}
|
|
181
204
|
|
|
182
|
-
interface EventMessage {
|
|
205
|
+
interface EventMessage<E> {
|
|
183
206
|
readonly t: 'event';
|
|
184
207
|
readonly epoch: number;
|
|
185
|
-
readonly event:
|
|
208
|
+
readonly event: E;
|
|
209
|
+
/** The one tab this event is for; absent for a fan-out to every tab. */
|
|
210
|
+
readonly to?: string;
|
|
186
211
|
}
|
|
187
212
|
|
|
188
|
-
export type MultiTabMessage =
|
|
213
|
+
export type MultiTabMessage<E = SyncWorkerEvent> =
|
|
189
214
|
| HelloMessage
|
|
190
215
|
| ReqMessage
|
|
191
216
|
| AnnounceMessage
|
|
192
217
|
| ResMessage
|
|
193
|
-
| EventMessage
|
|
218
|
+
| EventMessage<E>;
|
|
194
219
|
|
|
195
220
|
/**
|
|
196
221
|
* The tiny cross-tab channel surface we depend on — the DOM `BroadcastChannel`
|
|
197
222
|
* satisfies it. Injectable so bun tests can pair two instances by name.
|
|
198
223
|
*/
|
|
199
|
-
export interface CrossTabChannel {
|
|
200
|
-
postMessage(message: MultiTabMessage): void;
|
|
224
|
+
export interface CrossTabChannel<E = SyncWorkerEvent> {
|
|
225
|
+
postMessage(message: MultiTabMessage<E>): void;
|
|
201
226
|
addEventListener(
|
|
202
227
|
type: 'message',
|
|
203
|
-
listener: (event: { data: MultiTabMessage }) => void,
|
|
228
|
+
listener: (event: { data: MultiTabMessage<E> }) => void,
|
|
204
229
|
): void;
|
|
205
230
|
removeEventListener(
|
|
206
231
|
type: 'message',
|
|
207
|
-
listener: (event: { data: MultiTabMessage }) => void,
|
|
232
|
+
listener: (event: { data: MultiTabMessage<E> }) => void,
|
|
208
233
|
): void;
|
|
209
234
|
close(): void;
|
|
210
235
|
}
|
|
211
236
|
|
|
212
237
|
/** Default channel factory: a real `BroadcastChannel` named per lock. */
|
|
213
|
-
export function broadcastChannelFactory(): (
|
|
214
|
-
|
|
238
|
+
export function broadcastChannelFactory<E = SyncWorkerEvent>(): (
|
|
239
|
+
name: string,
|
|
240
|
+
) => CrossTabChannel<E> {
|
|
241
|
+
return (name) => new BroadcastChannel(name) as unknown as CrossTabChannel<E>;
|
|
215
242
|
}
|
|
216
243
|
|
|
217
244
|
/** The channel name a leader and its followers rendezvous on. */
|
|
@@ -235,31 +262,39 @@ export function newTabId(): string {
|
|
|
235
262
|
|
|
236
263
|
/**
|
|
237
264
|
* Runs on the leader tab. Announces leadership, answers follower `req`s by
|
|
238
|
-
* invoking the (already-running)
|
|
239
|
-
*
|
|
240
|
-
*
|
|
241
|
-
* newer tab calls `onNewerTab`, whose owner closes the core and
|
|
242
|
-
* lock.
|
|
265
|
+
* invoking the (already-running) core via `invoke` with the calling tab's id,
|
|
266
|
+
* and relays core events to followers. Owns nothing about the core lifecycle;
|
|
267
|
+
* this is a relay. `onFirstCall` runs once per tab, at its first request. A
|
|
268
|
+
* hello from a newer tab calls `onNewerTab`, whose owner closes the core and
|
|
269
|
+
* releases the lock.
|
|
243
270
|
*/
|
|
244
|
-
export class LeaderBridge {
|
|
245
|
-
readonly #channel: CrossTabChannel
|
|
271
|
+
export class LeaderBridge<E = SyncWorkerEvent> {
|
|
272
|
+
readonly #channel: CrossTabChannel<E>;
|
|
246
273
|
readonly #epoch: number;
|
|
247
274
|
readonly #clientId: string;
|
|
248
275
|
readonly #identity: TabIdentity;
|
|
249
276
|
readonly #invoke: (
|
|
277
|
+
tabId: string,
|
|
250
278
|
method: string,
|
|
251
279
|
args: readonly unknown[],
|
|
252
280
|
) => Promise<unknown>;
|
|
281
|
+
readonly #onFirstCall: ((tabId: string) => void) | undefined;
|
|
253
282
|
readonly #onNewerTab: () => void;
|
|
254
|
-
readonly #onMessage: (event: { data: MultiTabMessage }) => void;
|
|
283
|
+
readonly #onMessage: (event: { data: MultiTabMessage<E> }) => void;
|
|
284
|
+
readonly #callers = new Set<string>();
|
|
255
285
|
#closed = false;
|
|
256
286
|
|
|
257
287
|
constructor(options: {
|
|
258
|
-
channel: CrossTabChannel
|
|
288
|
+
channel: CrossTabChannel<E>;
|
|
259
289
|
epoch: number;
|
|
260
290
|
clientId: string;
|
|
261
291
|
identity: TabIdentity;
|
|
262
|
-
invoke: (
|
|
292
|
+
invoke: (
|
|
293
|
+
tabId: string,
|
|
294
|
+
method: string,
|
|
295
|
+
args: readonly unknown[],
|
|
296
|
+
) => Promise<unknown>;
|
|
297
|
+
onFirstCall?: (tabId: string) => void;
|
|
263
298
|
onNewerTab: () => void;
|
|
264
299
|
}) {
|
|
265
300
|
this.#channel = options.channel;
|
|
@@ -267,6 +302,7 @@ export class LeaderBridge {
|
|
|
267
302
|
this.#clientId = options.clientId;
|
|
268
303
|
this.#identity = options.identity;
|
|
269
304
|
this.#invoke = options.invoke;
|
|
305
|
+
this.#onFirstCall = options.onFirstCall;
|
|
270
306
|
this.#onNewerTab = options.onNewerTab;
|
|
271
307
|
this.#onMessage = (event) => this.#handle(event.data);
|
|
272
308
|
this.#channel.addEventListener('message', this.#onMessage);
|
|
@@ -284,13 +320,24 @@ export class LeaderBridge {
|
|
|
284
320
|
});
|
|
285
321
|
}
|
|
286
322
|
|
|
287
|
-
/** Fan
|
|
288
|
-
broadcastEvent(event:
|
|
323
|
+
/** Fan an event out to all followers on the current epoch. */
|
|
324
|
+
broadcastEvent(event: E): void {
|
|
289
325
|
if (this.#closed) return;
|
|
290
326
|
this.#channel.postMessage({ t: 'event', epoch: this.#epoch, event });
|
|
291
327
|
}
|
|
292
328
|
|
|
293
|
-
|
|
329
|
+
/** Post an event that only the follower `tabId` delivers. */
|
|
330
|
+
sendEvent(tabId: string, event: E): void {
|
|
331
|
+
if (this.#closed) return;
|
|
332
|
+
this.#channel.postMessage({
|
|
333
|
+
t: 'event',
|
|
334
|
+
epoch: this.#epoch,
|
|
335
|
+
event,
|
|
336
|
+
to: tabId,
|
|
337
|
+
});
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
#handle(message: MultiTabMessage<E>): void {
|
|
294
341
|
if (this.#closed) return;
|
|
295
342
|
if (message.t === 'hello') {
|
|
296
343
|
// A newer tab takes over; any other follower learns who leads.
|
|
@@ -306,7 +353,7 @@ export class LeaderBridge {
|
|
|
306
353
|
// Ignore requests stamped for a different (dead/older) leader; that
|
|
307
354
|
// follower will re-stamp once it sees our announce.
|
|
308
355
|
if (message.epoch !== this.#epoch) return;
|
|
309
|
-
const { reqId, method, args } = message;
|
|
356
|
+
const { reqId, method, args, fromId } = message;
|
|
310
357
|
if (compareTabIdentity(message, this.#identity) !== 0) {
|
|
311
358
|
this.#channel.postMessage({
|
|
312
359
|
t: 'res',
|
|
@@ -321,8 +368,12 @@ export class LeaderBridge {
|
|
|
321
368
|
});
|
|
322
369
|
return;
|
|
323
370
|
}
|
|
371
|
+
if (!this.#callers.has(fromId)) {
|
|
372
|
+
this.#callers.add(fromId);
|
|
373
|
+
this.#onFirstCall?.(fromId);
|
|
374
|
+
}
|
|
324
375
|
// A call can outlive close(); a closed BroadcastChannel throws on post.
|
|
325
|
-
this.#invoke(method, args).then(
|
|
376
|
+
this.#invoke(fromId, method, args).then(
|
|
326
377
|
(value) => {
|
|
327
378
|
if (this.#closed) return;
|
|
328
379
|
this.#channel.postMessage({
|
|
@@ -403,11 +454,11 @@ interface InFlight {
|
|
|
403
454
|
* when a probe goes unanswered, or when the leader's identity differs from
|
|
404
455
|
* this tab's (see the module comment).
|
|
405
456
|
*/
|
|
406
|
-
export class FollowerLink {
|
|
407
|
-
readonly #channel: CrossTabChannel
|
|
457
|
+
export class FollowerLink<E = SyncWorkerEvent> {
|
|
458
|
+
readonly #channel: CrossTabChannel<E>;
|
|
408
459
|
readonly #fromId: string;
|
|
409
460
|
readonly #identity: TabIdentity;
|
|
410
|
-
readonly #onEvent: (event:
|
|
461
|
+
readonly #onEvent: (event: E) => void;
|
|
411
462
|
readonly #onLeaderChange: (clientId: string) => void;
|
|
412
463
|
readonly #onStateChange: (state: LeadershipState) => void;
|
|
413
464
|
readonly #callTimeoutMs: number;
|
|
@@ -415,7 +466,7 @@ export class FollowerLink {
|
|
|
415
466
|
readonly #probeAfterMs: number;
|
|
416
467
|
readonly #queueLimit: number;
|
|
417
468
|
readonly #schedule: FollowerSchedule;
|
|
418
|
-
readonly #onMessage: (event: { data: MultiTabMessage }) => void;
|
|
469
|
+
readonly #onMessage: (event: { data: MultiTabMessage<E> }) => void;
|
|
419
470
|
|
|
420
471
|
/** -1 until the first `announce` binds us to a leader. */
|
|
421
472
|
#epoch = -1;
|
|
@@ -436,10 +487,10 @@ export class FollowerLink {
|
|
|
436
487
|
#bindWaiters: Array<() => void> = [];
|
|
437
488
|
|
|
438
489
|
constructor(options: {
|
|
439
|
-
channel: CrossTabChannel
|
|
490
|
+
channel: CrossTabChannel<E>;
|
|
440
491
|
fromId: string;
|
|
441
492
|
identity: TabIdentity;
|
|
442
|
-
onEvent: (event:
|
|
493
|
+
onEvent: (event: E) => void;
|
|
443
494
|
onLeaderChange: (clientId: string) => void;
|
|
444
495
|
onStateChange?: (state: LeadershipState) => void;
|
|
445
496
|
callTimeoutMs?: number;
|
|
@@ -635,7 +686,7 @@ export class FollowerLink {
|
|
|
635
686
|
if (index >= 0) this.#queue.splice(index, 1);
|
|
636
687
|
}
|
|
637
688
|
|
|
638
|
-
#handle(message: MultiTabMessage): void {
|
|
689
|
+
#handle(message: MultiTabMessage<E>): void {
|
|
639
690
|
if (this.#closed) return;
|
|
640
691
|
if (message.t === 'announce') {
|
|
641
692
|
if (message.epoch > this.#maxEpochSeen) {
|
|
@@ -698,6 +749,7 @@ export class FollowerLink {
|
|
|
698
749
|
}
|
|
699
750
|
if (message.t === 'event') {
|
|
700
751
|
if (message.epoch !== this.#epoch) return;
|
|
752
|
+
if (message.to !== undefined && message.to !== this.#fromId) return;
|
|
701
753
|
this.#onEvent(message.event);
|
|
702
754
|
return;
|
|
703
755
|
}
|
|
@@ -893,3 +945,493 @@ export class FollowerLink {
|
|
|
893
945
|
this.#cancelBlocked = undefined;
|
|
894
946
|
}
|
|
895
947
|
}
|
|
948
|
+
|
|
949
|
+
// ---------------------------------------------------------------------------
|
|
950
|
+
// Tab coordinator: the whole leader/follower lifecycle around any core
|
|
951
|
+
// ---------------------------------------------------------------------------
|
|
952
|
+
|
|
953
|
+
/** What a leader's core receives when this tab wins or promotes. */
|
|
954
|
+
export interface TabLeaderContext<E> {
|
|
955
|
+
/** This leadership's epoch; a promotion runs on a higher one. */
|
|
956
|
+
readonly epoch: number;
|
|
957
|
+
/** This tab's id. The leader's own calls arrive under it. */
|
|
958
|
+
readonly tabId: string;
|
|
959
|
+
/**
|
|
960
|
+
* True when this tab took the lock from an unreachable leader with
|
|
961
|
+
* `takeOver()`. That leader's worker can still hold the database files;
|
|
962
|
+
* the core must take over its storage lock and retry opening until the
|
|
963
|
+
* old worker releases them.
|
|
964
|
+
*/
|
|
965
|
+
readonly takeover: boolean;
|
|
966
|
+
/**
|
|
967
|
+
* The leader lock. The coordinator releases it after {@link TabLeader.close}
|
|
968
|
+
* resolves. Release it earlier only when the core is already gone, such as a
|
|
969
|
+
* worker terminated on `pagehide`.
|
|
970
|
+
*/
|
|
971
|
+
readonly lease: LeaderLease;
|
|
972
|
+
/** Deliver an event to every tab, this one included. */
|
|
973
|
+
broadcast(event: E): void;
|
|
974
|
+
/** Deliver an event to the tab `tabId` only. */
|
|
975
|
+
send(tabId: string, event: E): void;
|
|
976
|
+
}
|
|
977
|
+
|
|
978
|
+
/** The core a leader tab runs for every tab of the coordinator. */
|
|
979
|
+
export interface TabLeader {
|
|
980
|
+
/** Announced to followers as `LeadershipState.leaderClientId`. */
|
|
981
|
+
readonly clientId: string;
|
|
982
|
+
/** Serve one call from the tab `tabId`. */
|
|
983
|
+
call(
|
|
984
|
+
tabId: string,
|
|
985
|
+
method: string,
|
|
986
|
+
args: readonly unknown[],
|
|
987
|
+
): Promise<unknown>;
|
|
988
|
+
/**
|
|
989
|
+
* The tab `tabId`, which called this leader, closed. Defined only by cores
|
|
990
|
+
* that keep per-tab state; the coordinator then waits on each caller's tab
|
|
991
|
+
* lock.
|
|
992
|
+
*/
|
|
993
|
+
tabClosed?(tabId: string): void;
|
|
994
|
+
/**
|
|
995
|
+
* Stop the core. The coordinator releases the leader lock afterwards. It
|
|
996
|
+
* also runs when another tab took the lock: the core must not write again.
|
|
997
|
+
*/
|
|
998
|
+
close(): Promise<void>;
|
|
999
|
+
}
|
|
1000
|
+
|
|
1001
|
+
/**
|
|
1002
|
+
* A follower's link to its leader went `leader-unreachable`, or left that
|
|
1003
|
+
* state. Times are `clock.now()` milliseconds (wall-clock by default).
|
|
1004
|
+
*/
|
|
1005
|
+
export type LeaderUnreachableEvent =
|
|
1006
|
+
| {
|
|
1007
|
+
readonly phase: 'started';
|
|
1008
|
+
readonly at: number;
|
|
1009
|
+
/** The earliest time `takeOver()` is allowed. */
|
|
1010
|
+
readonly takeOverAt: number;
|
|
1011
|
+
}
|
|
1012
|
+
| {
|
|
1013
|
+
readonly phase: 'ended';
|
|
1014
|
+
readonly at: number;
|
|
1015
|
+
readonly durationMs: number;
|
|
1016
|
+
/**
|
|
1017
|
+
* `rebound`: the leader answered again. `promoted`: its lock passed to
|
|
1018
|
+
* this tab. `taken-over`: this tab's `takeOver()` succeeded.
|
|
1019
|
+
* `incompatible`: a leader of another build answered. `closed`: this
|
|
1020
|
+
* tab closed first.
|
|
1021
|
+
*/
|
|
1022
|
+
readonly outcome:
|
|
1023
|
+
| 'rebound'
|
|
1024
|
+
| 'promoted'
|
|
1025
|
+
| 'taken-over'
|
|
1026
|
+
| 'incompatible'
|
|
1027
|
+
| 'closed';
|
|
1028
|
+
};
|
|
1029
|
+
|
|
1030
|
+
/** Time source and timer seam; tests inject a manual clock. */
|
|
1031
|
+
export interface TabClock {
|
|
1032
|
+
now(): number;
|
|
1033
|
+
schedule(callback: () => void, delayMs: number): () => void;
|
|
1034
|
+
}
|
|
1035
|
+
|
|
1036
|
+
export interface TabCoordinatorConfig<E> {
|
|
1037
|
+
/** Web Lock name of the leadership; the channel and tab locks derive from it. */
|
|
1038
|
+
readonly name: string;
|
|
1039
|
+
/**
|
|
1040
|
+
* The application build. Tabs of different versions never serve each other:
|
|
1041
|
+
* a leader steps down for a higher version, and a tab next to a leader of
|
|
1042
|
+
* another version is `blocked` with reason `leader-incompatible`.
|
|
1043
|
+
*/
|
|
1044
|
+
readonly version: number;
|
|
1045
|
+
/** Start the core. Runs when this tab wins the lock, and on every promotion. */
|
|
1046
|
+
lead(context: TabLeaderContext<E>): Promise<TabLeader>;
|
|
1047
|
+
/** Events the leader broadcast, or sent to this tab. */
|
|
1048
|
+
onEvent?(event: E): void;
|
|
1049
|
+
onStateChange?(state: LeadershipState): void;
|
|
1050
|
+
/** Start and end of every `leader-unreachable` period, for host telemetry. */
|
|
1051
|
+
onLeaderUnreachable?(event: LeaderUnreachableEvent): void;
|
|
1052
|
+
/** Defaults to Web Locks; tests inject a name-keyed exclusive lock. */
|
|
1053
|
+
readonly lock?: LeaderLock;
|
|
1054
|
+
readonly channelFactory?: (name: string) => CrossTabChannel<E>;
|
|
1055
|
+
/** Liveness and handover-queue deadline; defaults to 10 s. */
|
|
1056
|
+
readonly callTimeoutMs?: number;
|
|
1057
|
+
/**
|
|
1058
|
+
* How long a follower must have been `leader-unreachable` before
|
|
1059
|
+
* `takeOver()` is allowed; defaults to twice `callTimeoutMs`.
|
|
1060
|
+
*/
|
|
1061
|
+
readonly takeOverAfterMs?: number;
|
|
1062
|
+
readonly clock?: TabClock;
|
|
1063
|
+
}
|
|
1064
|
+
|
|
1065
|
+
/** One tab's end of the coordinator, the same in leader and follower tabs. */
|
|
1066
|
+
export interface TabCoordinator {
|
|
1067
|
+
readonly tabId: string;
|
|
1068
|
+
readonly state: LeadershipState;
|
|
1069
|
+
/** Run a call on the leader's core, in this tab or over the channel. */
|
|
1070
|
+
call(method: string, args: readonly unknown[]): Promise<unknown>;
|
|
1071
|
+
/**
|
|
1072
|
+
* Take the lock from a leader that has been `leader-unreachable` for
|
|
1073
|
+
* `takeOverAfterMs`, and start the core in this tab. The old leader reports
|
|
1074
|
+
* `leadership-taken` and closes its core once it runs again. Rejects with
|
|
1075
|
+
* `client.takeover_refused` (`details.reason`: `not-unreachable`,
|
|
1076
|
+
* `too-early`, `in-progress` or `unsupported`) when the conditions do not
|
|
1077
|
+
* hold, and with the core's start error when the core cannot start.
|
|
1078
|
+
*/
|
|
1079
|
+
takeOver(): Promise<void>;
|
|
1080
|
+
/** Stop the core (leader) or the link (follower), and release this tab's locks. */
|
|
1081
|
+
close(): Promise<void>;
|
|
1082
|
+
}
|
|
1083
|
+
|
|
1084
|
+
function tabLockName(name: string, tabId: string): string {
|
|
1085
|
+
return `${name}:tab:${tabId}`;
|
|
1086
|
+
}
|
|
1087
|
+
|
|
1088
|
+
function takeOverRefused(
|
|
1089
|
+
reason: 'not-unreachable' | 'too-early' | 'in-progress' | 'unsupported',
|
|
1090
|
+
takeOverAt?: number,
|
|
1091
|
+
): ClientSyncError {
|
|
1092
|
+
return new ClientSyncError(
|
|
1093
|
+
TAKEOVER_REFUSED_CODE,
|
|
1094
|
+
'takeOver() requires a leader that has been unreachable for takeOverAfterMs',
|
|
1095
|
+
reason === 'too-early' || reason === 'in-progress',
|
|
1096
|
+
{ reason, ...(takeOverAt !== undefined ? { takeOverAt } : {}) },
|
|
1097
|
+
);
|
|
1098
|
+
}
|
|
1099
|
+
|
|
1100
|
+
/**
|
|
1101
|
+
* Elect one leader tab per `name` and run `lead` there; every other tab
|
|
1102
|
+
* forwards its calls to that core and receives its events. When the leader
|
|
1103
|
+
* tab closes, one follower promotes in place on a higher epoch and runs
|
|
1104
|
+
* `lead` itself. Resolves once this tab leads or is bound to a leader.
|
|
1105
|
+
*/
|
|
1106
|
+
export async function createTabCoordinator<E>(
|
|
1107
|
+
config: TabCoordinatorConfig<E>,
|
|
1108
|
+
): Promise<TabCoordinator> {
|
|
1109
|
+
const lock = config.lock ?? webLocksLeaderLock();
|
|
1110
|
+
const clock: TabClock = config.clock ?? {
|
|
1111
|
+
now: () => Date.now(),
|
|
1112
|
+
schedule: (callback, delayMs) => {
|
|
1113
|
+
const timer = setTimeout(callback, delayMs);
|
|
1114
|
+
return () => clearTimeout(timer);
|
|
1115
|
+
},
|
|
1116
|
+
};
|
|
1117
|
+
const callTimeoutMs =
|
|
1118
|
+
config.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
|
|
1119
|
+
const takeOverAfterMs = config.takeOverAfterMs ?? 2 * callTimeoutMs;
|
|
1120
|
+
const openChannel = config.channelFactory ?? broadcastChannelFactory<E>();
|
|
1121
|
+
const channelName = multiTabChannelName(config.name);
|
|
1122
|
+
const identity: TabIdentity = {
|
|
1123
|
+
protocol: MULTI_TAB_PROTOCOL_VERSION,
|
|
1124
|
+
schemaVersion: config.version,
|
|
1125
|
+
};
|
|
1126
|
+
const tabId = newTabId();
|
|
1127
|
+
let state: LeadershipState = {
|
|
1128
|
+
state: 'waiting',
|
|
1129
|
+
reason: 'leader-announcement',
|
|
1130
|
+
};
|
|
1131
|
+
let leading:
|
|
1132
|
+
| { leader: TabLeader; lease: LeaderLease; end(): void }
|
|
1133
|
+
| undefined;
|
|
1134
|
+
let follower: FollowerLink<E> | undefined;
|
|
1135
|
+
let closed = false;
|
|
1136
|
+
let takingOver = false;
|
|
1137
|
+
/** Start of the current `leader-unreachable` period. */
|
|
1138
|
+
let unreachableSince: number | undefined;
|
|
1139
|
+
|
|
1140
|
+
const report = (event: LeaderUnreachableEvent): void => {
|
|
1141
|
+
try {
|
|
1142
|
+
config.onLeaderUnreachable?.(event);
|
|
1143
|
+
} catch {
|
|
1144
|
+
// A telemetry listener must never break cross-tab coordination.
|
|
1145
|
+
}
|
|
1146
|
+
};
|
|
1147
|
+
const endUnreachable = (
|
|
1148
|
+
outcome: Extract<LeaderUnreachableEvent, { phase: 'ended' }>['outcome'],
|
|
1149
|
+
): void => {
|
|
1150
|
+
if (unreachableSince === undefined) return;
|
|
1151
|
+
const at = clock.now();
|
|
1152
|
+
report({ phase: 'ended', at, durationMs: at - unreachableSince, outcome });
|
|
1153
|
+
unreachableSince = undefined;
|
|
1154
|
+
};
|
|
1155
|
+
const setState = (next: LeadershipState): void => {
|
|
1156
|
+
state = next;
|
|
1157
|
+
if (next.state === 'blocked' && next.reason === 'leader-unreachable') {
|
|
1158
|
+
if (unreachableSince === undefined) {
|
|
1159
|
+
unreachableSince = clock.now();
|
|
1160
|
+
report({
|
|
1161
|
+
phase: 'started',
|
|
1162
|
+
at: unreachableSince,
|
|
1163
|
+
takeOverAt: unreachableSince + takeOverAfterMs,
|
|
1164
|
+
});
|
|
1165
|
+
}
|
|
1166
|
+
} else if (next.state === 'follower') {
|
|
1167
|
+
endUnreachable('rebound');
|
|
1168
|
+
} else if (next.state === 'leader') {
|
|
1169
|
+
endUnreachable(takingOver ? 'taken-over' : 'promoted');
|
|
1170
|
+
} else if (next.state === 'blocked') {
|
|
1171
|
+
endUnreachable('incompatible');
|
|
1172
|
+
}
|
|
1173
|
+
try {
|
|
1174
|
+
config.onStateChange?.(next);
|
|
1175
|
+
} catch {
|
|
1176
|
+
// A status listener must never break cross-tab coordination.
|
|
1177
|
+
}
|
|
1178
|
+
};
|
|
1179
|
+
|
|
1180
|
+
// Held until close: a leader waits on it to learn this tab is gone.
|
|
1181
|
+
const tabLease = await lock.acquire(tabLockName(config.name, tabId));
|
|
1182
|
+
|
|
1183
|
+
const lead = async (
|
|
1184
|
+
lease: LeaderLease,
|
|
1185
|
+
epoch: number,
|
|
1186
|
+
takeover: boolean,
|
|
1187
|
+
): Promise<void> => {
|
|
1188
|
+
let bridge: LeaderBridge<E> | undefined;
|
|
1189
|
+
let current = true;
|
|
1190
|
+
let stepDown: ((next: LeadershipState) => void) | undefined;
|
|
1191
|
+
let lostWhileStarting = false;
|
|
1192
|
+
const taken: LeadershipState = {
|
|
1193
|
+
state: 'blocked',
|
|
1194
|
+
reason: 'leadership-taken',
|
|
1195
|
+
code: LEADERSHIP_TAKEN_CODE,
|
|
1196
|
+
retryable: true,
|
|
1197
|
+
};
|
|
1198
|
+
void lease.lost?.then(() => {
|
|
1199
|
+
if (stepDown !== undefined) stepDown(taken);
|
|
1200
|
+
else lostWhileStarting = true;
|
|
1201
|
+
});
|
|
1202
|
+
const leader = await config.lead({
|
|
1203
|
+
epoch,
|
|
1204
|
+
tabId,
|
|
1205
|
+
takeover,
|
|
1206
|
+
lease,
|
|
1207
|
+
broadcast: (event) => {
|
|
1208
|
+
if (!current) return;
|
|
1209
|
+
bridge?.broadcastEvent(event);
|
|
1210
|
+
config.onEvent?.(event);
|
|
1211
|
+
},
|
|
1212
|
+
send: (to, event) => {
|
|
1213
|
+
if (!current) return;
|
|
1214
|
+
if (to === tabId) config.onEvent?.(event);
|
|
1215
|
+
else bridge?.sendEvent(to, event);
|
|
1216
|
+
},
|
|
1217
|
+
});
|
|
1218
|
+
if (closed || lostWhileStarting) {
|
|
1219
|
+
// Closed while the core was starting, or another tab took the lock: a
|
|
1220
|
+
// follower link, if any, binds to that tab's announcement.
|
|
1221
|
+
current = false;
|
|
1222
|
+
await leader.close();
|
|
1223
|
+
await lease.release();
|
|
1224
|
+
return;
|
|
1225
|
+
}
|
|
1226
|
+
const ending = {
|
|
1227
|
+
leader,
|
|
1228
|
+
lease,
|
|
1229
|
+
end: () => {
|
|
1230
|
+
current = false;
|
|
1231
|
+
bridge?.close();
|
|
1232
|
+
},
|
|
1233
|
+
};
|
|
1234
|
+
leading = ending;
|
|
1235
|
+
stepDown = (next) => {
|
|
1236
|
+
// Stop the core and release the lock; this tab stays blocked until it
|
|
1237
|
+
// reloads.
|
|
1238
|
+
if (leading !== ending) return;
|
|
1239
|
+
leading = undefined;
|
|
1240
|
+
ending.end();
|
|
1241
|
+
setState(next);
|
|
1242
|
+
void leader.close().finally(() => lease.release());
|
|
1243
|
+
};
|
|
1244
|
+
bridge = new LeaderBridge<E>({
|
|
1245
|
+
channel: openChannel(channelName),
|
|
1246
|
+
epoch,
|
|
1247
|
+
clientId: leader.clientId,
|
|
1248
|
+
identity,
|
|
1249
|
+
invoke: (from, method, args) => leader.call(from, method, args),
|
|
1250
|
+
...(leader.tabClosed !== undefined
|
|
1251
|
+
? {
|
|
1252
|
+
onFirstCall: (from: string) => {
|
|
1253
|
+
void lock
|
|
1254
|
+
.acquire(tabLockName(config.name, from))
|
|
1255
|
+
.then(async (gone) => {
|
|
1256
|
+
await gone.release();
|
|
1257
|
+
if (current) leader.tabClosed?.(from);
|
|
1258
|
+
});
|
|
1259
|
+
},
|
|
1260
|
+
}
|
|
1261
|
+
: {}),
|
|
1262
|
+
// A newer build asked for the core.
|
|
1263
|
+
onNewerTab: () =>
|
|
1264
|
+
stepDown?.({
|
|
1265
|
+
state: 'blocked',
|
|
1266
|
+
reason: 'leader-incompatible',
|
|
1267
|
+
code: LEADER_INCOMPATIBLE_CODE,
|
|
1268
|
+
leader: 'newer',
|
|
1269
|
+
retryable: true,
|
|
1270
|
+
}),
|
|
1271
|
+
});
|
|
1272
|
+
// Calls queued for the next leader run on this tab's own core.
|
|
1273
|
+
follower?.handOver((method, args) => leader.call(tabId, method, args));
|
|
1274
|
+
follower = undefined;
|
|
1275
|
+
setState({ state: 'leader', clientId: leader.clientId });
|
|
1276
|
+
};
|
|
1277
|
+
|
|
1278
|
+
const coordinator: TabCoordinator = {
|
|
1279
|
+
tabId,
|
|
1280
|
+
get state() {
|
|
1281
|
+
return state;
|
|
1282
|
+
},
|
|
1283
|
+
call: (method, args) => {
|
|
1284
|
+
if (closed) {
|
|
1285
|
+
return Promise.reject(
|
|
1286
|
+
new ClientSyncError(
|
|
1287
|
+
WORKER_FAILED_CODE,
|
|
1288
|
+
'the tab coordinator is closed',
|
|
1289
|
+
),
|
|
1290
|
+
);
|
|
1291
|
+
}
|
|
1292
|
+
if (leading !== undefined)
|
|
1293
|
+
return leading.leader.call(tabId, method, args);
|
|
1294
|
+
if (follower !== undefined) return follower.call(method, args);
|
|
1295
|
+
if (state.state === 'blocked' && state.reason === 'leadership-taken') {
|
|
1296
|
+
return Promise.reject(
|
|
1297
|
+
new ClientSyncError(
|
|
1298
|
+
LEADERSHIP_TAKEN_CODE,
|
|
1299
|
+
'another tab took over the core this tab ran',
|
|
1300
|
+
true,
|
|
1301
|
+
),
|
|
1302
|
+
);
|
|
1303
|
+
}
|
|
1304
|
+
if (state.state === 'blocked' && state.reason === 'leader-incompatible') {
|
|
1305
|
+
return Promise.reject(
|
|
1306
|
+
new ClientSyncError(
|
|
1307
|
+
LEADER_INCOMPATIBLE_CODE,
|
|
1308
|
+
'the tab that owns the database runs a different protocol or schema version',
|
|
1309
|
+
true,
|
|
1310
|
+
),
|
|
1311
|
+
);
|
|
1312
|
+
}
|
|
1313
|
+
return Promise.reject(
|
|
1314
|
+
new ClientSyncError(WORKER_FAILED_CODE, 'no core serves this tab'),
|
|
1315
|
+
);
|
|
1316
|
+
},
|
|
1317
|
+
takeOver: async () => {
|
|
1318
|
+
if (closed) {
|
|
1319
|
+
throw new ClientSyncError(
|
|
1320
|
+
WORKER_FAILED_CODE,
|
|
1321
|
+
'the tab coordinator is closed',
|
|
1322
|
+
);
|
|
1323
|
+
}
|
|
1324
|
+
const link = follower;
|
|
1325
|
+
if (
|
|
1326
|
+
link === undefined ||
|
|
1327
|
+
unreachableSince === undefined ||
|
|
1328
|
+
state.state !== 'blocked' ||
|
|
1329
|
+
state.reason !== 'leader-unreachable'
|
|
1330
|
+
) {
|
|
1331
|
+
throw takeOverRefused('not-unreachable');
|
|
1332
|
+
}
|
|
1333
|
+
if (takingOver) throw takeOverRefused('in-progress');
|
|
1334
|
+
const takeOverAt = unreachableSince + takeOverAfterMs;
|
|
1335
|
+
if (clock.now() < takeOverAt)
|
|
1336
|
+
throw takeOverRefused('too-early', takeOverAt);
|
|
1337
|
+
if (lock.steal === undefined) throw takeOverRefused('unsupported');
|
|
1338
|
+
takingOver = true;
|
|
1339
|
+
try {
|
|
1340
|
+
const lease = await lock.steal(config.name);
|
|
1341
|
+
if (closed) {
|
|
1342
|
+
await lease.release();
|
|
1343
|
+
return;
|
|
1344
|
+
}
|
|
1345
|
+
try {
|
|
1346
|
+
// Exceed every epoch this tab saw, so the old leader's late replies
|
|
1347
|
+
// and events are discarded everywhere.
|
|
1348
|
+
await lead(lease, link.maxEpochSeen + 1, true);
|
|
1349
|
+
} catch (error) {
|
|
1350
|
+
await lease.release();
|
|
1351
|
+
throw error;
|
|
1352
|
+
}
|
|
1353
|
+
if (!closed && leading === undefined) {
|
|
1354
|
+
// A third tab took the lock while this tab's core was starting.
|
|
1355
|
+
throw new ClientSyncError(
|
|
1356
|
+
LEADERSHIP_TAKEN_CODE,
|
|
1357
|
+
'another tab took over the core this tab ran',
|
|
1358
|
+
true,
|
|
1359
|
+
);
|
|
1360
|
+
}
|
|
1361
|
+
} finally {
|
|
1362
|
+
takingOver = false;
|
|
1363
|
+
}
|
|
1364
|
+
},
|
|
1365
|
+
close: async () => {
|
|
1366
|
+
if (closed) return;
|
|
1367
|
+
closed = true;
|
|
1368
|
+
endUnreachable('closed');
|
|
1369
|
+
follower?.close();
|
|
1370
|
+
follower = undefined;
|
|
1371
|
+
const ending = leading;
|
|
1372
|
+
leading = undefined;
|
|
1373
|
+
if (ending !== undefined) {
|
|
1374
|
+
ending.end();
|
|
1375
|
+
await ending.leader.close();
|
|
1376
|
+
await ending.lease.release();
|
|
1377
|
+
}
|
|
1378
|
+
await tabLease.release();
|
|
1379
|
+
},
|
|
1380
|
+
};
|
|
1381
|
+
|
|
1382
|
+
// Leadership before any core exists: a losing tab never starts one.
|
|
1383
|
+
const lease =
|
|
1384
|
+
lock.tryAcquire !== undefined
|
|
1385
|
+
? await lock.tryAcquire(config.name)
|
|
1386
|
+
: await lock.acquire(config.name);
|
|
1387
|
+
if (lease !== undefined) {
|
|
1388
|
+
try {
|
|
1389
|
+
await lead(lease, 0, false);
|
|
1390
|
+
} catch (error) {
|
|
1391
|
+
await lease.release();
|
|
1392
|
+
await tabLease.release();
|
|
1393
|
+
throw error;
|
|
1394
|
+
}
|
|
1395
|
+
return coordinator;
|
|
1396
|
+
}
|
|
1397
|
+
|
|
1398
|
+
const link = new FollowerLink<E>({
|
|
1399
|
+
channel: openChannel(channelName),
|
|
1400
|
+
fromId: tabId,
|
|
1401
|
+
identity,
|
|
1402
|
+
onEvent: (event) => config.onEvent?.(event),
|
|
1403
|
+
onLeaderChange: () => {},
|
|
1404
|
+
onStateChange: setState,
|
|
1405
|
+
callTimeoutMs,
|
|
1406
|
+
schedule: clock.schedule,
|
|
1407
|
+
});
|
|
1408
|
+
follower = link;
|
|
1409
|
+
// Granted only when the lock is released: the leader's tab closed, or this
|
|
1410
|
+
// tab's own failed takeover let go of it.
|
|
1411
|
+
void lock.acquire(config.name).then(async (promoted) => {
|
|
1412
|
+
if (closed || follower !== link) {
|
|
1413
|
+
// Closed, or this tab already leads through takeOver(): promoting would
|
|
1414
|
+
// hold the lock forever.
|
|
1415
|
+
await promoted.release();
|
|
1416
|
+
return;
|
|
1417
|
+
}
|
|
1418
|
+
// The new leader must exceed every epoch this tab saw, so stale replies
|
|
1419
|
+
// and events are discarded everywhere.
|
|
1420
|
+
const epoch = link.maxEpochSeen + 1;
|
|
1421
|
+
link.unbind();
|
|
1422
|
+
try {
|
|
1423
|
+
await lead(promoted, epoch, false);
|
|
1424
|
+
} catch {
|
|
1425
|
+
// The core failed to start: release so the next tab tries.
|
|
1426
|
+
await promoted.release();
|
|
1427
|
+
}
|
|
1428
|
+
});
|
|
1429
|
+
// Return bound: an event the leader fans out before binding is dropped.
|
|
1430
|
+
try {
|
|
1431
|
+
await link.waitUntilBound();
|
|
1432
|
+
} catch {
|
|
1433
|
+
// Bind timed out: the link keeps probing, queued calls flush on the next
|
|
1434
|
+
// announce, and the state says `blocked`.
|
|
1435
|
+
}
|
|
1436
|
+
return coordinator;
|
|
1437
|
+
}
|