@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/dist/wasm-database.js
CHANGED
|
@@ -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: () =>
|
|
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
|
|
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();
|
package/dist/worker-entry.d.ts
CHANGED
|
@@ -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 {
|
|
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
|
package/dist/worker-entry.js
CHANGED
|
@@ -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
|
|
229
|
+
const remote = overrides.createTransport !== undefined
|
|
191
230
|
? overrides.createTransport(config)
|
|
192
231
|
: httpSyncTransport(config.endpoints.syncUrl, http);
|
|
193
|
-
|
|
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
|
-
|
|
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
|
}
|
package/dist/worker-host.d.ts
CHANGED
|
@@ -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
|
|
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,
|
|
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
|
|
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
|
-
|
|
154
|
-
|
|
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
|
-
|
|
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 —
|
|
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
|
-
/**
|
|
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
|
/**
|