@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.
@@ -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();
@@ -16,7 +16,8 @@
16
16
  import type { defineAuthorityReads } from './authority.js';
17
17
  import type { ClientDatabase } from './database.js';
18
18
  import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
19
- import { type WorkerInitConfig } from './worker-protocol.js';
19
+ import type { ClientSchema } from './schema.js';
20
+ import { type LocalAuthorityState, type WorkerInitConfig } from './worker-protocol.js';
20
21
  export interface SyncWorkerOverrides {
21
22
  /** Explicit authority reader factory. Required when init declares authorityReads. */
22
23
  readonly createAuthorityReads?: typeof defineAuthorityReads;
@@ -31,6 +32,21 @@ export interface SyncWorkerOverrides {
31
32
  * connection attempt. `headers` reads the current host auth set.
32
33
  */
33
34
  readonly createRealtime?: (config: WorkerInitConfig, clientId: string, headers: () => Readonly<Record<string, string>>) => RealtimeConnector | undefined;
35
+ /**
36
+ * SPEC §12 local authority, required by init's `localAuthority: true`:
37
+ * `(database, schema) => openLocalAuthority({ database:
38
+ * clientSqliteDatabase(database), schema })` from `@syncular/server`. Only
39
+ * a worker entry that passes it bundles the server code.
40
+ */
41
+ readonly openLocalAuthority?: (database: ClientDatabase, schema: ClientSchema) => Promise<WorkerLocalAuthority>;
42
+ }
43
+ /** The `LocalAuthority` surface of `@syncular/server` the worker drives (§12). */
44
+ export interface WorkerLocalAuthority {
45
+ readonly state: LocalAuthorityState;
46
+ readonly sync: SyncTransport;
47
+ readonly downloadSegment: SegmentDownloader;
48
+ readonly attach: (transport: SyncTransport) => Promise<void>;
49
+ readonly abandonAttach: (transport?: SyncTransport) => Promise<void>;
34
50
  }
35
51
  /**
36
52
  * Register the RPC server on the current worker scope. Call this once
@@ -4,7 +4,9 @@ import { encryptionConfigFromKeyring } from './encryption.js';
4
4
  import { classifySqliteFailure, ClientSyncError, STORAGE_BUSY_CODE, } from './errors.js';
5
5
  import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
6
6
  import { openPersistentWasmDatabase } from './wasm-database.js';
7
- import { WORKER_FAILED_CODE, } from './worker-protocol.js';
7
+ import { LOCAL_AUTHORITY_UNCONFIGURED_CODE, WORKER_FAILED_CODE, } from './worker-protocol.js';
8
+ /** §12: the worker's sibling file for the local authority. */
9
+ const LOCAL_AUTHORITY_SIBLING = 'local-authority';
8
10
  function toErrorShape(caught) {
9
11
  const error = classifySqliteFailure(caught).error;
10
12
  if (error instanceof ClientSyncError) {
@@ -60,6 +62,9 @@ export function startSyncWorker(overrides = {}) {
60
62
  };
61
63
  let client;
62
64
  let database;
65
+ let authority;
66
+ let authoritySibling;
67
+ let remoteTransport;
63
68
  let offline = false;
64
69
  let headers = {};
65
70
  let closed = false;
@@ -145,6 +150,40 @@ export function startSyncWorker(overrides = {}) {
145
150
  autoSyncScheduled = true;
146
151
  queueMicrotask(runAutoSync);
147
152
  }
153
+ /**
154
+ * §12.3: attach or abandon with the client's rounds held, so no round
155
+ * reaches the authority while it uploads or rolls back.
156
+ */
157
+ async function driveLocalAuthority(run) {
158
+ const running = requireClient();
159
+ const local = authority;
160
+ const remote = remoteTransport;
161
+ if (local === undefined || remote === undefined) {
162
+ throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'init did not enable the local authority');
163
+ }
164
+ running.setTransportEnabled(false);
165
+ try {
166
+ await serializedSync(() => run(local, remote));
167
+ }
168
+ catch (error) {
169
+ // `sync.attach_rejected` keeps its code and details across the RPC.
170
+ if (error instanceof Error &&
171
+ !(error instanceof ClientSyncError) &&
172
+ 'code' in error &&
173
+ typeof error.code === 'string') {
174
+ throw new ClientSyncError(error.code, error.message, false, 'details' in error &&
175
+ typeof error.details === 'object' &&
176
+ error.details !== null
177
+ ? { ...error.details }
178
+ : undefined);
179
+ }
180
+ throw error;
181
+ }
182
+ finally {
183
+ running.setTransportEnabled(!offline);
184
+ }
185
+ consumeSyncIntent({ kind: 'interactive' });
186
+ }
148
187
  function requireClient() {
149
188
  if (client === undefined) {
150
189
  throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker received a call before init completed');
@@ -187,14 +226,39 @@ export function startSyncWorker(overrides = {}) {
187
226
  }
188
227
  }
189
228
  }
190
- const transport = overrides.createTransport !== undefined
229
+ const remote = overrides.createTransport !== undefined
191
230
  ? overrides.createTransport(config)
192
231
  : httpSyncTransport(config.endpoints.syncUrl, http);
193
- const segments = overrides.createSegments !== undefined
232
+ remoteTransport = remote;
233
+ const remoteSegments = overrides.createSegments !== undefined
194
234
  ? overrides.createSegments(config)
195
235
  : config.endpoints.segmentsUrl !== undefined
196
236
  ? httpSegmentDownloader(config.endpoints.segmentsUrl, http)
197
237
  : undefined;
238
+ if (config.localAuthority === true) {
239
+ if (overrides.openLocalAuthority === undefined) {
240
+ throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'localAuthority requires startSyncWorker({ openLocalAuthority })');
241
+ }
242
+ authoritySibling = database.openSibling?.(LOCAL_AUTHORITY_SIBLING);
243
+ if (authoritySibling === undefined) {
244
+ throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'localAuthority requires a database with sibling files');
245
+ }
246
+ authority = await overrides.openLocalAuthority(authoritySibling.database, config.schema);
247
+ }
248
+ // §12.4: rounds reach the local authority until attach completes, then
249
+ // the remote server; the replica rebinds through the §2.1 epoch reset.
250
+ const localActive = () => authority !== undefined && authority.state !== 'attached';
251
+ const transport = (request) => localActive() ? authority.sync(request) : remote(request);
252
+ const segments = authority === undefined
253
+ ? remoteSegments
254
+ : (request) => {
255
+ if (localActive())
256
+ return authority.downloadSegment(request);
257
+ if (remoteSegments === undefined) {
258
+ throw new ClientSyncError('sync.invalid_request', 'no segment endpoint configured');
259
+ }
260
+ return remoteSegments(request);
261
+ };
198
262
  // §5.9 blob transport: only when a blobs URL is configured.
199
263
  const blobs = config.endpoints.blobsUrl !== undefined
200
264
  ? httpBlobTransport(config.endpoints.blobsUrl, http)
@@ -212,7 +276,8 @@ export function startSyncWorker(overrides = {}) {
212
276
  ...(segments !== undefined ? { segments } : {}),
213
277
  ...(blobs !== undefined ? { blobs } : {}),
214
278
  realtime: (handlers) => {
215
- if (realtimeConnector === undefined) {
279
+ // §12.2: a local authority has no realtime channel.
280
+ if (realtimeConnector === undefined || localActive()) {
216
281
  throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
217
282
  }
218
283
  return realtimeConnector(handlers);
@@ -410,11 +475,15 @@ export function startSyncWorker(overrides = {}) {
410
475
  });
411
476
  }
412
477
  },
478
+ localAuthorityState: () => authority?.state,
479
+ attachLocalAuthority: () => driveLocalAuthority((local, remote) => local.attach(remote)),
480
+ abandonLocalAuthorityAttach: () => driveLocalAuthority((local, remote) => local.abandonAttach(remote)),
413
481
  close: async () => {
414
482
  closed = true;
415
483
  if (backgroundTimer !== undefined)
416
484
  clearTimeout(backgroundTimer);
417
485
  await client?.close();
486
+ authoritySibling?.close();
418
487
  database?.close();
419
488
  client = undefined;
420
489
  database = undefined;
@@ -477,5 +546,6 @@ async function defaultOpenDatabase(config) {
477
546
  ...(config.database.directory !== undefined
478
547
  ? { directory: config.database.directory }
479
548
  : {}),
549
+ ...(config.takeOverStorage === true ? { takeOver: true } : {}),
480
550
  });
481
551
  }
@@ -31,17 +31,17 @@ import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDi
31
31
  import type { EncryptionKeyringConfig } from './encryption.js';
32
32
  import { ClientSyncError } from './errors.js';
33
33
  import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
34
- import { type LeaderLease, type LeaderLock } from './leader-lock.js';
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, FollowerLink, LeaderBridge, type LeadershipState } 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';
41
41
  import type { ClientSchema } from './schema.js';
42
42
  import type { SubscriptionRecord } from './state.js';
43
43
  import type { WindowBase } from './window.js';
44
- import { type SyncWorkerEvent, type WorkerApi, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
44
+ import { type LocalAuthorityState, type SyncWorkerEvent, type WorkerApi, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
45
45
  /** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
46
46
  export declare function workerStartupError(message: unknown): ClientSyncError;
47
47
  export type HandleRole = 'leader' | 'follower';
@@ -88,6 +88,8 @@ export interface SyncClientHandleConfig {
88
88
  /** Open the worker-owned replica behind the fail-closed security gate. */
89
89
  readonly securityPreflight?: boolean;
90
90
  readonly transportEnabled?: boolean;
91
+ /** SPEC §12: start against the worker's local authority (`WorkerInitConfig`). */
92
+ readonly localAuthority?: boolean;
91
93
  readonly clientId?: string;
92
94
  readonly limits?: SyncClientLimits;
93
95
  readonly retainFailedCommits?: boolean;
@@ -124,6 +126,15 @@ export interface SyncClientHandleConfig {
124
126
  * `blocked` when the probe stays unanswered for the rest. Default 10 s.
125
127
  */
126
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;
127
138
  /** Fires when this handle's role changes (follower → leader on promotion). */
128
139
  readonly onRoleChange?: (role: HandleRole) => void;
129
140
  /** Fires when reachability or ownership changes without replacing the handle. */
@@ -143,16 +154,14 @@ export interface SyncClientHandleConfig {
143
154
  readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
144
155
  }
145
156
  /**
146
- * A running worker core owned by THIS tab (the leader). Wraps the worker,
147
- * the RPC pending map, and (in multi-tab mode) the `LeaderBridge` relaying
148
- * follower requests. Torn down on `close()` or on a graceful demotion.
157
+ * A running worker core owned by THIS tab (the leader). Wraps the worker and
158
+ * the RPC pending map. Torn down on `close()` or on a graceful demotion.
149
159
  */
150
160
  interface LeaderCore {
151
161
  readonly clientId: string;
152
162
  readonly invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
153
- readonly bridge: LeaderBridge | undefined;
154
- readonly lease: LeaderLease;
155
- close(terminate: boolean): Promise<void>;
163
+ /** Close the core, terminate the worker, and release the lease. */
164
+ close(): Promise<void>;
156
165
  }
157
166
  /**
158
167
  * The main-thread proxy: the same logical API as `SyncClient`, every method a
@@ -175,32 +184,20 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
175
184
  clientId: string;
176
185
  currentSchemaVersion: number;
177
186
  core?: LeaderCore;
178
- follower?: FollowerLink;
187
+ tabs?: TabCoordinator;
179
188
  invalidation: InvalidationEmitter;
180
189
  changes: ChangeEmitter;
181
190
  presence: Set<(scopeKey: string) => void>;
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
  /**
188
- * @internal — whether `close()` has run.
189
- *
190
- * A follower keeps a blocking `acquire` outstanding for the whole time it is a
191
- * follower, so its promotion can fire long after the application has discarded
192
- * the handle. The promotion path consults this before opening anything.
193
- */
194
- get __isClosed(): boolean;
195
- /** @internal — swap this handle from follower to leader (promotion). */
196
- __becomeLeader(core: LeaderCore): void;
197
- /**
198
- * @internal — a newer tab asked for the database: close the core and
199
- * release the lock so that tab promotes. This tab stays blocked until it
200
- * reloads with the newer build.
198
+ * @internal — apply a leadership snapshot in place: a promotion flips the
199
+ * role to `'leader'`, stepping down for a newer tab flips it back.
201
200
  */
202
- __yieldToNewerTab(): void;
203
- /** @internal — apply a follower reachability snapshot in place. */
204
201
  __setLeadership(state: LeadershipState): void;
205
202
  /** @internal — dispatch a worker/relayed event to handle-local listeners. */
206
203
  __dispatchEvent(event: SyncWorkerEvent): void;
@@ -223,6 +220,18 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
223
220
  /** Subscribe to role transitions (follower → leader on promotion). */
224
221
  onRoleChange(listener: (role: HandleRole) => void): () => void;
225
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>;
226
235
  subscribe(input: SubscribeInput): Promise<void>;
227
236
  subscribeMany(inputs: readonly SubscribeInput[]): Promise<void>;
228
237
  securityLifecycle(): Promise<SecurityLifecycle>;
@@ -289,7 +298,17 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
289
298
  __headers: Readonly<Record<string, string>> | undefined;
290
299
  /** Sever/restore transport + realtime inside the worker (demos). */
291
300
  setOffline(offline: boolean): Promise<void>;
292
- /** Close the core (leader) or unbind the link (follower), release leadership. */
301
+ /** SPEC §12.3 local-authority state; `undefined` without `localAuthority`. */
302
+ localAuthorityState(): Promise<LocalAuthorityState | undefined>;
303
+ /**
304
+ * SPEC §12.3: upload the local authority's rows to `endpoints.syncUrl`,
305
+ * then sync with that server. Rejects with `sync.attach_rejected` when the
306
+ * server refuses an upload commit.
307
+ */
308
+ attachLocalAuthority(): Promise<void>;
309
+ /** SPEC §12.3: delete the rows a stopped attach uploaded, then sync locally. */
310
+ abandonLocalAuthorityAttach(): Promise<void>;
311
+ /** Close the core (leader) or the link (follower), release leadership. */
293
312
  close(): Promise<void>;
294
313
  }
295
314
  /**