@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/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} — fan-out (invalidate/presence/…)
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 = 1;
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: SyncWorkerEvent;
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(): (name: string) => CrossTabChannel {
214
- return (name) => new BroadcastChannel(name) as unknown as CrossTabChannel;
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) worker via `invoke`, and rebroadcasts every
239
- * worker event to followers. Owns nothing about the worker lifecycle — the
240
- * worker-host stays the single core owner; this is a relay. A hello from a
241
- * newer tab calls `onNewerTab`, whose owner closes the core and releases the
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: (method: string, args: readonly unknown[]) => Promise<unknown>;
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 a worker event out to all followers on the current epoch. */
288
- broadcastEvent(event: SyncWorkerEvent): void {
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
- #handle(message: MultiTabMessage): void {
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: SyncWorkerEvent) => void;
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: SyncWorkerEvent) => void;
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
+ }