@syncular/client 0.49.1 → 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.
@@ -25,7 +25,7 @@
25
25
  import { webLocksLeaderLock } from './leader-lock.js';
26
26
  import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
27
27
  import { assertImageAlias, runTransaction, } from './database.js';
28
- import { ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
28
+ import { ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, STORAGE_FENCED_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
29
29
  function coerceParams(params) {
30
30
  return params.map((value) => {
31
31
  if (typeof value === 'boolean')
@@ -38,14 +38,34 @@ class WasmClientDatabase {
38
38
  #sqlite3;
39
39
  /** RFC 0005: present only for a persistent OPFS database. */
40
40
  #sah;
41
+ #fence;
41
42
  #closed = false;
42
43
  #tx = { depth: 0 };
43
- constructor(db, sqlite3, sah) {
44
+ constructor(db, sqlite3, sah, fence) {
44
45
  this.#db = db;
45
46
  this.#sqlite3 = sqlite3;
46
47
  this.#sah = sah;
48
+ this.#fence = fence;
49
+ // A takeover stole the storage lock. The new owner cannot open the pool
50
+ // while these SAHs are held, so close them before any further statement:
51
+ // the lost lease runs as its own task, never inside a transaction.
52
+ void sah?.lease.lost?.then(() => {
53
+ if (fence === undefined || this.#closed)
54
+ return;
55
+ fence.fenced = true;
56
+ for (const sibling of fence.siblings)
57
+ sibling.close();
58
+ fence.siblings.clear();
59
+ this.close();
60
+ });
61
+ }
62
+ #assertOwned() {
63
+ if (this.#fence?.fenced === true) {
64
+ throw new ClientSyncError(STORAGE_FENCED_CODE, 'another tab took over this persistent database');
65
+ }
47
66
  }
48
67
  exec(sql, params = []) {
68
+ this.#assertOwned();
49
69
  this.#db.exec({
50
70
  sql,
51
71
  ...(params.length > 0 ? { bind: coerceParams(params) } : {}),
@@ -54,6 +74,7 @@ class WasmClientDatabase {
54
74
  });
55
75
  }
56
76
  query(sql, params = []) {
77
+ this.#assertOwned();
57
78
  const resultRows = [];
58
79
  this.#db.exec({
59
80
  sql,
@@ -64,6 +85,7 @@ class WasmClientDatabase {
64
85
  return resultRows;
65
86
  }
66
87
  transaction(fn) {
88
+ this.#assertOwned();
67
89
  return runTransaction(this.#tx, (sql) => this.exec(sql), fn);
68
90
  }
69
91
  /**
@@ -86,9 +108,13 @@ class WasmClientDatabase {
86
108
  db.close();
87
109
  throw error;
88
110
  }
111
+ this.#fence?.siblings.add(db);
89
112
  return {
90
- database: new WasmClientDatabase(db, this.#sqlite3),
91
- close: () => db.close(),
113
+ database: new WasmClientDatabase(db, this.#sqlite3, undefined, this.#fence),
114
+ close: () => {
115
+ this.#fence?.siblings.delete(db);
116
+ db.close();
117
+ },
92
118
  removeFile: () => {
93
119
  sah.util.unlink(fileName);
94
120
  },
@@ -264,7 +290,11 @@ export async function openPersistentWasmDatabase(name, options) {
264
290
  const directory = (options?.directory ?? `.syncular/${name}`).replace(/^\/+|\/+$/g, '');
265
291
  // The document's leader lease can end before its worker's SAHs close. This
266
292
  // worker-owned lock has exactly the same lifetime as the physical pool.
267
- const lease = await webLocksLeaderLock().acquire(`syncular-opfs/${directory}`);
293
+ const storageLock = webLocksLeaderLock();
294
+ const lockName = `syncular-opfs/${directory}`;
295
+ const lease = options?.takeOver === true
296
+ ? await storageLock.steal(lockName)
297
+ : await storageLock.acquire(lockName);
268
298
  let util;
269
299
  let db;
270
300
  try {
@@ -288,7 +318,7 @@ export async function openPersistentWasmDatabase(name, options) {
288
318
  await util.unpauseVfs();
289
319
  db = new util.OpfsSAHPoolDb(`/${name}.db`);
290
320
  configureSahCrashRecovery(db, sqlite3);
291
- return new WasmClientDatabase(db, sqlite3, { util, lease });
321
+ return new WasmClientDatabase(db, sqlite3, { util, lease }, { fenced: false, siblings: new Set() });
292
322
  }
293
323
  catch (error) {
294
324
  db?.close();
@@ -546,5 +546,6 @@ async function defaultOpenDatabase(config) {
546
546
  ...(config.database.directory !== undefined
547
547
  ? { directory: config.database.directory }
548
548
  : {}),
549
+ ...(config.takeOverStorage === true ? { takeOver: true } : {}),
549
550
  });
550
551
  }
@@ -34,7 +34,7 @@ import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type Inv
34
34
  import { type LeaderLock } from './leader-lock.js';
35
35
  import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
36
36
  import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
37
- import { type CrossTabChannel, type LeadershipState, type TabCoordinator } from './multi-tab.js';
37
+ import { type CrossTabChannel, type LeaderUnreachableEvent, type LeadershipState, type TabClock, type TabCoordinator } from './multi-tab.js';
38
38
  import type { OutboxCommit } from './outbox.js';
39
39
  import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
40
40
  import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
@@ -126,6 +126,15 @@ export interface SyncClientHandleConfig {
126
126
  * `blocked` when the probe stays unanswered for the rest. Default 10 s.
127
127
  */
128
128
  readonly followerCallTimeoutMs?: number;
129
+ /**
130
+ * How long a follower must have been `leader-unreachable` before
131
+ * `takeOver()` is allowed. Default twice `followerCallTimeoutMs`.
132
+ */
133
+ readonly takeOverAfterMs?: number;
134
+ /** Start and end of every `leader-unreachable` period, for host telemetry. */
135
+ readonly onLeaderUnreachable?: (event: LeaderUnreachableEvent) => void;
136
+ /** Time source for the follower timers; injectable for tests. */
137
+ readonly tabClock?: TabClock;
129
138
  /** Fires when this handle's role changes (follower → leader on promotion). */
130
139
  readonly onRoleChange?: (role: HandleRole) => void;
131
140
  /** Fires when reachability or ownership changes without replacing the handle. */
@@ -182,6 +191,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
182
191
  diagnostics: ClientDiagnosticsEmitter;
183
192
  roleListeners?: Set<(role: HandleRole) => void>;
184
193
  leadershipListeners?: Set<(state: LeadershipState) => void>;
194
+ unreachableListeners?: Set<(event: LeaderUnreachableEvent) => void>;
185
195
  leadership?: LeadershipState;
186
196
  });
187
197
  /**
@@ -210,6 +220,18 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
210
220
  /** Subscribe to role transitions (follower → leader on promotion). */
211
221
  onRoleChange(listener: (role: HandleRole) => void): () => void;
212
222
  onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
223
+ /** Start and end of every `leader-unreachable` period, with its duration. */
224
+ onLeaderUnreachable(listener: (event: LeaderUnreachableEvent) => void): () => void;
225
+ /**
226
+ * Take the database from a leader tab that has been `leader-unreachable`
227
+ * for `takeOverAfterMs`, and run the worker in this tab. Call it from an
228
+ * explicit user action. The old leader's worker refuses every statement
229
+ * from then on (`client.storage_fenced`) and its tab reports
230
+ * `leadership-taken`. Rejects with `client.takeover_refused` when the
231
+ * conditions do not hold, and with `client.storage_busy` when the old
232
+ * worker still holds the database files.
233
+ */
234
+ takeOver(): Promise<void>;
213
235
  subscribe(input: SubscribeInput): Promise<void>;
214
236
  subscribeMany(inputs: readonly SubscribeInput[]): Promise<void>;
215
237
  securityLifecycle(): Promise<SecurityLifecycle>;
@@ -5,7 +5,7 @@ import { ClientSyncError } from './errors.js';
5
5
  import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
6
6
  import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
7
7
  import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
8
- import { createTabCoordinator, multiTabChannelName, } from './multi-tab.js';
8
+ import { createTabCoordinator, multiTabChannelName, TAKEOVER_REFUSED_CODE, } from './multi-tab.js';
9
9
  import { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, } from './previous-version.js';
10
10
  import { NOT_LEADER_CODE, WORKER_FAILED_CODE, WORKER_RESTART_REQUIRED_CODE, } from './worker-protocol.js';
11
11
  const WORKER_BUNDLE_LOAD_FAILURE = /(?:failed to fetch dynamically imported module|error loading dynamically imported module|importing a module script failed|failed to load module script)/iu;
@@ -78,6 +78,7 @@ export class SyncClientHandle {
78
78
  #diagnostics;
79
79
  #roleListeners;
80
80
  #leadershipListeners;
81
+ #unreachableListeners;
81
82
  #devtoolsUnregister;
82
83
  #closed = false;
83
84
  /** @internal — use {@link createSyncClientHandle}. */
@@ -104,6 +105,7 @@ export class SyncClientHandle {
104
105
  this.#diagnostics = internals.diagnostics;
105
106
  this.#roleListeners = internals.roleListeners ?? new Set();
106
107
  this.#leadershipListeners = internals.leadershipListeners ?? new Set();
108
+ this.#unreachableListeners = internals.unreachableListeners ?? new Set();
107
109
  // Console introspection is a no-op outside a dev page.
108
110
  this.#devtoolsUnregister = registerDevtools({
109
111
  kind: 'handle',
@@ -223,6 +225,31 @@ export class SyncClientHandle {
223
225
  this.#leadershipListeners.delete(listener);
224
226
  };
225
227
  }
228
+ /** Start and end of every `leader-unreachable` period, with its duration. */
229
+ onLeaderUnreachable(listener) {
230
+ this.#unreachableListeners.add(listener);
231
+ return () => {
232
+ this.#unreachableListeners.delete(listener);
233
+ };
234
+ }
235
+ /**
236
+ * Take the database from a leader tab that has been `leader-unreachable`
237
+ * for `takeOverAfterMs`, and run the worker in this tab. Call it from an
238
+ * explicit user action. The old leader's worker refuses every statement
239
+ * from then on (`client.storage_fenced`) and its tab reports
240
+ * `leadership-taken`. Rejects with `client.takeover_refused` when the
241
+ * conditions do not hold, and with `client.storage_busy` when the old
242
+ * worker still holds the database files.
243
+ */
244
+ takeOver() {
245
+ if (this.#closed) {
246
+ return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the handle is closed'));
247
+ }
248
+ if (this.#tabs === undefined) {
249
+ return Promise.reject(new ClientSyncError(TAKEOVER_REFUSED_CODE, 'takeOver() requires a multi-tab handle', false, { reason: 'unsupported' }));
250
+ }
251
+ return this.#tabs.takeOver();
252
+ }
226
253
  #call(method, args) {
227
254
  if (this.#closed) {
228
255
  return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the handle is closed'));
@@ -611,6 +638,10 @@ export async function createSyncClientHandle(config) {
611
638
  if (resolvedConfig.onLeadershipChange !== undefined) {
612
639
  leadershipListeners.add(resolvedConfig.onLeadershipChange);
613
640
  }
641
+ const unreachableListeners = new Set();
642
+ if (resolvedConfig.onLeaderUnreachable !== undefined) {
643
+ unreachableListeners.add(resolvedConfig.onLeaderUnreachable);
644
+ }
614
645
  const handleRef = {
615
646
  handle: undefined,
616
647
  };
@@ -622,6 +653,7 @@ export async function createSyncClientHandle(config) {
622
653
  diagnostics,
623
654
  roleListeners,
624
655
  leadershipListeners,
656
+ unreachableListeners,
625
657
  };
626
658
  if (resolvedConfig.multiTab === false) {
627
659
  // Single-tab contract: the leader runs its core with no channel; a losing
@@ -662,11 +694,30 @@ export async function createSyncClientHandle(config) {
662
694
  ...(resolvedConfig.followerCallTimeoutMs !== undefined
663
695
  ? { callTimeoutMs: resolvedConfig.followerCallTimeoutMs }
664
696
  : {}),
697
+ ...(resolvedConfig.takeOverAfterMs !== undefined
698
+ ? { takeOverAfterMs: resolvedConfig.takeOverAfterMs }
699
+ : {}),
700
+ ...(resolvedConfig.tabClock !== undefined
701
+ ? { clock: resolvedConfig.tabClock }
702
+ : {}),
703
+ onLeaderUnreachable: (event) => {
704
+ for (const listener of unreachableListeners) {
705
+ try {
706
+ listener(event);
707
+ }
708
+ catch {
709
+ /* a telemetry listener must never break cross-tab coordination */
710
+ }
711
+ }
712
+ },
665
713
  lead: async (context) => {
666
714
  const core = await startWorkerCore({
667
715
  config: resolvedConfig,
668
716
  // A promoted tab carries the latest `setHeaders` set.
669
- initConfig: buildInitConfig(resolvedConfig, handleRef.handle?.__headers ?? resolvedConfig.headers),
717
+ initConfig: {
718
+ ...buildInitConfig(resolvedConfig, handleRef.handle?.__headers ?? resolvedConfig.headers),
719
+ ...(context.takeover ? { takeOverStorage: true } : {}),
720
+ },
670
721
  lease: context.lease,
671
722
  dispatchEvent: (event) => {
672
723
  fireConfigCallbacks(resolvedConfig, event);
@@ -80,6 +80,12 @@ export interface WorkerInitConfig {
80
80
  readonly headers?: Readonly<Record<string, string>>;
81
81
  /** Portable raw keyring installed inside the worker-owned client core. */
82
82
  readonly encryption?: EncryptionKeyringConfig;
83
+ /**
84
+ * This tab took the lock from an unreachable leader: take the storage lock
85
+ * from that leader's worker, which fences its database, and retry the open
86
+ * while its OPFS handles drain.
87
+ */
88
+ readonly takeOverStorage?: boolean;
83
89
  /** Open the worker-owned replica behind the fail-closed security gate. */
84
90
  readonly authorityReads?: readonly import('./authority.js').AuthorityReadDeclaration[];
85
91
  readonly securityPreflight?: boolean;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.49.1",
3
+ "version": "0.49.2",
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",
@@ -97,10 +97,10 @@
97
97
  },
98
98
  "dependencies": {
99
99
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
100
- "@syncular/core": "0.49.1"
100
+ "@syncular/core": "0.49.2"
101
101
  },
102
102
  "devDependencies": {
103
- "@syncular/server": "0.49.1",
103
+ "@syncular/server": "0.49.2",
104
104
  "playwright": "1.63.0",
105
105
  "@electric-sql/pglite": "^0.5.4"
106
106
  }
@@ -11,7 +11,8 @@ export type SyncAvailability =
11
11
  | 'server-behind'
12
12
  | 'incompatible-schema'
13
13
  | 'leader-unreachable'
14
- | 'leader-incompatible';
14
+ | 'leader-incompatible'
15
+ | 'leadership-taken';
15
16
  readonly currentSchemaVersion: number;
16
17
  /** `leader-incompatible`: whether the tab holding the database runs an
17
18
  * older or a newer build than this one. */
@@ -36,7 +37,7 @@ export function blockedLeadershipAvailability(
36
37
  }
37
38
  : {
38
39
  state: 'blocked',
39
- reason: 'leader-unreachable',
40
+ reason: leadership.reason,
40
41
  currentSchemaVersion,
41
42
  retryable: true,
42
43
  };
package/src/errors.ts CHANGED
@@ -3,6 +3,12 @@ import type { RealtimeState } from './diagnostics';
3
3
  /** A persistent local store is temporarily owned by another live engine. */
4
4
  export const STORAGE_BUSY_CODE = 'client.storage_busy';
5
5
 
6
+ /**
7
+ * Another tab took this engine's persistent store with `takeOver()`; the
8
+ * engine closed the store and refuses every further statement.
9
+ */
10
+ export const STORAGE_FENCED_CODE = 'client.storage_fenced';
11
+
6
12
  /** The browser cannot provide the persistent storage APIs Syncular requires. */
7
13
  export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
8
14
 
@@ -1,11 +1,16 @@
1
1
  /**
2
2
  * Multi-tab ownership seam: exactly one core instance owns the
3
- * local database. The interface is the whole B3 deliverable — cross-tab
4
- * follower fanout is post-gate. Browsers use Web Locks; tests use the
5
- * no-op single-owner lock.
3
+ * local database. Browsers use Web Locks; tests use the no-op single-owner
4
+ * lock or an injected exclusive lock.
6
5
  */
7
6
  export interface LeaderLease {
8
7
  release(): void | Promise<void>;
8
+ /**
9
+ * Resolves when another context took this lease with
10
+ * {@link LeaderLock.steal}. The holder no longer owns the lock and must stop
11
+ * writing. Absent for locks that cannot be stolen.
12
+ */
13
+ readonly lost?: Promise<void>;
9
14
  }
10
15
 
11
16
  export interface LeaderLock {
@@ -14,10 +19,14 @@ export interface LeaderLock {
14
19
  /**
15
20
  * Resolves immediately: the lease when leadership was free, `undefined`
16
21
  * when another owner holds it. The worker handle uses this so a second
17
- * tab gets a clear not-leader state instead of blocking forever
18
- * (followers are post-gate).
22
+ * tab gets a clear not-leader state instead of blocking forever.
19
23
  */
20
24
  tryAcquire?(name: string): Promise<LeaderLease | undefined>;
25
+ /**
26
+ * Takes `name` from its current holder at once; the holder's lease reports
27
+ * `lost`. Waiting requests stay queued behind the new holder.
28
+ */
29
+ steal?(name: string): Promise<LeaderLease>;
21
30
  }
22
31
 
23
32
  /** Single-owner environments (tests, dedicated workers): always leader. */
@@ -31,38 +40,59 @@ export function singleOwnerLock(): LeaderLock {
31
40
  /**
32
41
  * Web Locks leader election: resolves once the exclusive lock is granted
33
42
  * and holds it until the lease is released (tab close releases it
34
- * implicitly, letting the next tab take over).
43
+ * implicitly, letting the next tab take over). A `steal` from another
44
+ * context rejects the holder's request with `AbortError`, which resolves the
45
+ * holder's `lost`.
35
46
  */
36
- export function webLocksLeaderLock(locks?: LockManager): LeaderLock {
47
+ export function webLocksLeaderLock(locks?: LockManager): Required<LeaderLock> {
37
48
  const manager = locks ?? navigator.locks;
49
+ const request = (
50
+ name: string,
51
+ options: LockOptions,
52
+ ): Promise<LeaderLease | undefined> =>
53
+ new Promise((resolveRequest, rejectRequest) => {
54
+ let granted = false;
55
+ let markLost = (): void => {};
56
+ const lost = new Promise<void>((resolve) => {
57
+ markLost = resolve;
58
+ });
59
+ manager
60
+ .request(name, options, (lock) => {
61
+ // `ifAvailable` grants `null` instead of waiting (Web Locks).
62
+ if (lock === null) {
63
+ resolveRequest(undefined);
64
+ return undefined;
65
+ }
66
+ granted = true;
67
+ return new Promise<void>((resolveHold) => {
68
+ resolveRequest({ release: () => resolveHold(), lost });
69
+ });
70
+ })
71
+ .catch((error: unknown) => {
72
+ if (
73
+ granted &&
74
+ error instanceof DOMException &&
75
+ error.name === 'AbortError'
76
+ ) {
77
+ markLost();
78
+ return;
79
+ }
80
+ rejectRequest(error);
81
+ });
82
+ });
83
+ const held = async (
84
+ name: string,
85
+ options: LockOptions,
86
+ ): Promise<LeaderLease> => {
87
+ const lease = await request(name, options);
88
+ if (lease === undefined)
89
+ throw new Error('a waiting lock request returned no lock');
90
+ return lease;
91
+ };
38
92
  return {
39
- acquire: (name) =>
40
- new Promise<LeaderLease>((resolveAcquire, rejectAcquire) => {
41
- manager
42
- .request(
43
- name,
44
- { mode: 'exclusive' },
45
- () =>
46
- new Promise<void>((resolveHold) => {
47
- resolveAcquire({ release: () => resolveHold() });
48
- }),
49
- )
50
- .catch((error: unknown) => rejectAcquire(error));
51
- }),
93
+ acquire: (name) => held(name, { mode: 'exclusive' }),
52
94
  tryAcquire: (name) =>
53
- new Promise<LeaderLease | undefined>((resolveTry, rejectTry) => {
54
- manager
55
- .request(name, { mode: 'exclusive', ifAvailable: true }, (lock) => {
56
- // `ifAvailable` grants `null` instead of waiting (Web Locks).
57
- if (lock === null) {
58
- resolveTry(undefined);
59
- return undefined;
60
- }
61
- return new Promise<void>((resolveHold) => {
62
- resolveTry({ release: () => resolveHold() });
63
- });
64
- })
65
- .catch((error: unknown) => rejectTry(error));
66
- }),
95
+ request(name, { mode: 'exclusive', ifAvailable: true }),
96
+ steal: (name) => held(name, { mode: 'exclusive', steal: true }),
67
97
  };
68
98
  }