@syncular/client 0.49.1 → 0.50.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.
@@ -83,8 +83,11 @@ import {
83
83
  import {
84
84
  type CrossTabChannel,
85
85
  createTabCoordinator,
86
+ type LeaderUnreachableEvent,
86
87
  type LeadershipState,
87
88
  multiTabChannelName,
89
+ TAKEOVER_REFUSED_CODE,
90
+ type TabClock,
88
91
  type TabCoordinator,
89
92
  } from './multi-tab';
90
93
  import type { OutboxCommit } from './outbox';
@@ -235,6 +238,15 @@ export interface SyncClientHandleConfig {
235
238
  * `blocked` when the probe stays unanswered for the rest. Default 10 s.
236
239
  */
237
240
  readonly followerCallTimeoutMs?: number;
241
+ /**
242
+ * How long a follower must have been `leader-unreachable` before
243
+ * `takeOver()` is allowed. Default twice `followerCallTimeoutMs`.
244
+ */
245
+ readonly takeOverAfterMs?: number;
246
+ /** Start and end of every `leader-unreachable` period, for host telemetry. */
247
+ readonly onLeaderUnreachable?: (event: LeaderUnreachableEvent) => void;
248
+ /** Time source for the follower timers; injectable for tests. */
249
+ readonly tabClock?: TabClock;
238
250
  /** Fires when this handle's role changes (follower → leader on promotion). */
239
251
  readonly onRoleChange?: (role: HandleRole) => void;
240
252
  /** Fires when reachability or ownership changes without replacing the handle. */
@@ -323,6 +335,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
323
335
  readonly #diagnostics: ClientDiagnosticsEmitter;
324
336
  readonly #roleListeners: Set<(role: HandleRole) => void>;
325
337
  readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
338
+ readonly #unreachableListeners: Set<(event: LeaderUnreachableEvent) => void>;
326
339
  readonly #devtoolsUnregister: () => void;
327
340
  #closed = false;
328
341
 
@@ -339,6 +352,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
339
352
  diagnostics: ClientDiagnosticsEmitter;
340
353
  roleListeners?: Set<(role: HandleRole) => void>;
341
354
  leadershipListeners?: Set<(state: LeadershipState) => void>;
355
+ unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
342
356
  leadership?: LeadershipState;
343
357
  }) {
344
358
  this.#role = internals.role;
@@ -363,6 +377,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
363
377
  this.#diagnostics = internals.diagnostics;
364
378
  this.#roleListeners = internals.roleListeners ?? new Set();
365
379
  this.#leadershipListeners = internals.leadershipListeners ?? new Set();
380
+ this.#unreachableListeners = internals.unreachableListeners ?? new Set();
366
381
  // Console introspection is a no-op outside a dev page.
367
382
  this.#devtoolsUnregister = registerDevtools({
368
383
  kind: 'handle',
@@ -484,6 +499,44 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
484
499
  };
485
500
  }
486
501
 
502
+ /** Start and end of every `leader-unreachable` period, with its duration. */
503
+ onLeaderUnreachable(
504
+ listener: (event: LeaderUnreachableEvent) => void,
505
+ ): () => void {
506
+ this.#unreachableListeners.add(listener);
507
+ return () => {
508
+ this.#unreachableListeners.delete(listener);
509
+ };
510
+ }
511
+
512
+ /**
513
+ * Take the database from a leader tab that has been `leader-unreachable`
514
+ * for `takeOverAfterMs`, and run the worker in this tab. Call it from an
515
+ * explicit user action. The old leader's worker refuses every statement
516
+ * from then on (`client.storage_fenced`) and its tab reports
517
+ * `leadership-taken`. Rejects with `client.takeover_refused` when the
518
+ * conditions do not hold, and with `client.storage_busy` when the old
519
+ * worker still holds the database files.
520
+ */
521
+ takeOver(): Promise<void> {
522
+ if (this.#closed) {
523
+ return Promise.reject(
524
+ new ClientSyncError(WORKER_FAILED_CODE, 'the handle is closed'),
525
+ );
526
+ }
527
+ if (this.#tabs === undefined) {
528
+ return Promise.reject(
529
+ new ClientSyncError(
530
+ TAKEOVER_REFUSED_CODE,
531
+ 'takeOver() requires a multi-tab handle',
532
+ false,
533
+ { reason: 'unsupported' },
534
+ ),
535
+ );
536
+ }
537
+ return this.#tabs.takeOver();
538
+ }
539
+
487
540
  #call<M extends WorkerMethod>(
488
541
  method: M,
489
542
  args: Parameters<WorkerApi[M]>,
@@ -993,6 +1046,12 @@ export async function createSyncClientHandle(
993
1046
  if (resolvedConfig.onLeadershipChange !== undefined) {
994
1047
  leadershipListeners.add(resolvedConfig.onLeadershipChange);
995
1048
  }
1049
+ const unreachableListeners = new Set<
1050
+ (event: LeaderUnreachableEvent) => void
1051
+ >();
1052
+ if (resolvedConfig.onLeaderUnreachable !== undefined) {
1053
+ unreachableListeners.add(resolvedConfig.onLeaderUnreachable);
1054
+ }
996
1055
 
997
1056
  const handleRef: { handle: SyncClientHandle | undefined } = {
998
1057
  handle: undefined,
@@ -1005,6 +1064,7 @@ export async function createSyncClientHandle(
1005
1064
  diagnostics,
1006
1065
  roleListeners,
1007
1066
  leadershipListeners,
1067
+ unreachableListeners,
1008
1068
  };
1009
1069
 
1010
1070
  if (resolvedConfig.multiTab === false) {
@@ -1048,14 +1108,32 @@ export async function createSyncClientHandle(
1048
1108
  ...(resolvedConfig.followerCallTimeoutMs !== undefined
1049
1109
  ? { callTimeoutMs: resolvedConfig.followerCallTimeoutMs }
1050
1110
  : {}),
1111
+ ...(resolvedConfig.takeOverAfterMs !== undefined
1112
+ ? { takeOverAfterMs: resolvedConfig.takeOverAfterMs }
1113
+ : {}),
1114
+ ...(resolvedConfig.tabClock !== undefined
1115
+ ? { clock: resolvedConfig.tabClock }
1116
+ : {}),
1117
+ onLeaderUnreachable: (event) => {
1118
+ for (const listener of unreachableListeners) {
1119
+ try {
1120
+ listener(event);
1121
+ } catch {
1122
+ /* a telemetry listener must never break cross-tab coordination */
1123
+ }
1124
+ }
1125
+ },
1051
1126
  lead: async (context) => {
1052
1127
  const core = await startWorkerCore({
1053
1128
  config: resolvedConfig,
1054
1129
  // A promoted tab carries the latest `setHeaders` set.
1055
- initConfig: buildInitConfig(
1056
- resolvedConfig,
1057
- handleRef.handle?.__headers ?? resolvedConfig.headers,
1058
- ),
1130
+ initConfig: {
1131
+ ...buildInitConfig(
1132
+ resolvedConfig,
1133
+ handleRef.handle?.__headers ?? resolvedConfig.headers,
1134
+ ),
1135
+ ...(context.takeover ? { takeOverStorage: true } : {}),
1136
+ },
1059
1137
  lease: context.lease,
1060
1138
  dispatchEvent: (event) => {
1061
1139
  fireConfigCallbacks(resolvedConfig, event);
@@ -118,6 +118,12 @@ export interface WorkerInitConfig {
118
118
  readonly headers?: Readonly<Record<string, string>>;
119
119
  /** Portable raw keyring installed inside the worker-owned client core. */
120
120
  readonly encryption?: EncryptionKeyringConfig;
121
+ /**
122
+ * This tab took the lock from an unreachable leader: take the storage lock
123
+ * from that leader's worker, which fences its database, and retry the open
124
+ * while its OPFS handles drain.
125
+ */
126
+ readonly takeOverStorage?: boolean;
121
127
  /** Open the worker-owned replica behind the fail-closed security gate. */
122
128
  readonly authorityReads?: readonly import('./authority').AuthorityReadDeclaration[];
123
129
  readonly securityPreflight?: boolean;