@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.
- package/README.md +18 -1
- package/dist/availability.d.ts +1 -1
- package/dist/availability.js +1 -1
- 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 +63 -1
- package/dist/multi-tab.js +148 -29
- 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.js +1 -0
- package/dist/worker-host.d.ts +23 -1
- package/dist/worker-host.js +53 -2
- package/dist/worker-protocol.d.ts +6 -0
- package/package.json +3 -3
- package/src/availability.ts +3 -2
- package/src/errors.ts +6 -0
- package/src/leader-lock.ts +64 -34
- package/src/multi-tab.ts +233 -23
- package/src/reactive-store.ts +2 -1
- package/src/wasm-database.ts +64 -6
- package/src/worker-entry.ts +1 -0
- package/src/worker-host.ts +82 -4
- package/src/worker-protocol.ts +6 -0
package/src/worker-host.ts
CHANGED
|
@@ -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:
|
|
1056
|
-
|
|
1057
|
-
|
|
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);
|
package/src/worker-protocol.ts
CHANGED
|
@@ -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;
|