@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.
- 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/README.md
CHANGED
|
@@ -252,7 +252,24 @@ worker still holds the OPFS database and may be mid-commit, so a transfer
|
|
|
252
252
|
needs a cooperative close-and-release handshake, and every focus change
|
|
253
253
|
between tabs would restart the worker, reopen the database, and reconnect the
|
|
254
254
|
realtime socket. A hidden leader answers its followers from its message
|
|
255
|
-
handler, so leadership moves only when the leader tab closes
|
|
255
|
+
handler, so leadership moves only when the leader tab closes, or when the
|
|
256
|
+
user takes over from an unresponsive one.
|
|
257
|
+
|
|
258
|
+
**Taking over from an unresponsive leader.** A leader whose main thread runs
|
|
259
|
+
no task (a frozen background tab, a hung window) blocks its followers with
|
|
260
|
+
`leader-unreachable`. Once that has lasted `takeOverAfterMs` (default twice
|
|
261
|
+
`followerCallTimeoutMs`), `handle.takeOver()`, called from a user action, steals
|
|
262
|
+
the leader's Web Lock, starts the worker in this tab on a higher epoch, and
|
|
263
|
+
steals the old worker's OPFS storage lock. OPFS sync access handles are
|
|
264
|
+
exclusive, so the new worker opens the database only after the old one closed
|
|
265
|
+
it. The old worker's database refuses every statement once its storage lock is
|
|
266
|
+
gone (`client.storage_fenced`) and closes its handles, and the old tab becomes
|
|
267
|
+
`blocked` with reason `leadership-taken` when it runs again. `takeOver()`
|
|
268
|
+
rejects with `client.takeover_refused` (`details.reason`: `not-unreachable`,
|
|
269
|
+
`too-early`, `in-progress`, `unsupported`) and with `client.storage_busy` while a
|
|
270
|
+
frozen worker still holds the files. `onLeaderUnreachable` reports the start of
|
|
271
|
+
each unreachable period with `takeOverAt`, and its end with `durationMs` and
|
|
272
|
+
the outcome.
|
|
256
273
|
|
|
257
274
|
**Presence semantics — one device, one peer.** All tabs share the leader's
|
|
258
275
|
single connection, so a device is exactly ONE presence peer collectively:
|
package/dist/availability.d.ts
CHANGED
|
@@ -7,7 +7,7 @@ export type SyncAvailability = {
|
|
|
7
7
|
readonly currentSchemaVersion: number;
|
|
8
8
|
} | {
|
|
9
9
|
readonly state: 'blocked';
|
|
10
|
-
readonly reason: 'client-upgrade-required' | 'server-behind' | 'incompatible-schema' | 'leader-unreachable' | 'leader-incompatible';
|
|
10
|
+
readonly reason: 'client-upgrade-required' | 'server-behind' | 'incompatible-schema' | 'leader-unreachable' | 'leader-incompatible' | 'leadership-taken';
|
|
11
11
|
readonly currentSchemaVersion: number;
|
|
12
12
|
/** `leader-incompatible`: whether the tab holding the database runs an
|
|
13
13
|
* older or a newer build than this one. */
|
package/dist/availability.js
CHANGED
package/dist/errors.d.ts
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import type { RealtimeState } from './diagnostics.js';
|
|
2
2
|
/** A persistent local store is temporarily owned by another live engine. */
|
|
3
3
|
export declare const STORAGE_BUSY_CODE = "client.storage_busy";
|
|
4
|
+
/**
|
|
5
|
+
* Another tab took this engine's persistent store with `takeOver()`; the
|
|
6
|
+
* engine closed the store and refuses every further statement.
|
|
7
|
+
*/
|
|
8
|
+
export declare const STORAGE_FENCED_CODE = "client.storage_fenced";
|
|
4
9
|
/** The browser cannot provide the persistent storage APIs Syncular requires. */
|
|
5
10
|
export declare const STORAGE_UNAVAILABLE_CODE = "client.storage_unavailable";
|
|
6
11
|
/** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
|
package/dist/errors.js
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
/** A persistent local store is temporarily owned by another live engine. */
|
|
2
2
|
export const STORAGE_BUSY_CODE = 'client.storage_busy';
|
|
3
|
+
/**
|
|
4
|
+
* Another tab took this engine's persistent store with `takeOver()`; the
|
|
5
|
+
* engine closed the store and refuses every further statement.
|
|
6
|
+
*/
|
|
7
|
+
export const STORAGE_FENCED_CODE = 'client.storage_fenced';
|
|
3
8
|
/** The browser cannot provide the persistent storage APIs Syncular requires. */
|
|
4
9
|
export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
|
|
5
10
|
/** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
|
package/dist/leader-lock.d.ts
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Multi-tab ownership seam: exactly one core instance owns the
|
|
3
|
-
* local database.
|
|
4
|
-
*
|
|
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
|
export interface LeaderLock {
|
|
11
16
|
/** Resolves when this instance holds leadership for `name`. */
|
|
@@ -13,16 +18,22 @@ export interface LeaderLock {
|
|
|
13
18
|
/**
|
|
14
19
|
* Resolves immediately: the lease when leadership was free, `undefined`
|
|
15
20
|
* when another owner holds it. The worker handle uses this so a second
|
|
16
|
-
* tab gets a clear not-leader state instead of blocking forever
|
|
17
|
-
* (followers are post-gate).
|
|
21
|
+
* tab gets a clear not-leader state instead of blocking forever.
|
|
18
22
|
*/
|
|
19
23
|
tryAcquire?(name: string): Promise<LeaderLease | undefined>;
|
|
24
|
+
/**
|
|
25
|
+
* Takes `name` from its current holder at once; the holder's lease reports
|
|
26
|
+
* `lost`. Waiting requests stay queued behind the new holder.
|
|
27
|
+
*/
|
|
28
|
+
steal?(name: string): Promise<LeaderLease>;
|
|
20
29
|
}
|
|
21
30
|
/** Single-owner environments (tests, dedicated workers): always leader. */
|
|
22
31
|
export declare function singleOwnerLock(): LeaderLock;
|
|
23
32
|
/**
|
|
24
33
|
* Web Locks leader election: resolves once the exclusive lock is granted
|
|
25
34
|
* and holds it until the lease is released (tab close releases it
|
|
26
|
-
* implicitly, letting the next tab take over).
|
|
35
|
+
* implicitly, letting the next tab take over). A `steal` from another
|
|
36
|
+
* context rejects the holder's request with `AbortError`, which resolves the
|
|
37
|
+
* holder's `lost`.
|
|
27
38
|
*/
|
|
28
|
-
export declare function webLocksLeaderLock(locks?: LockManager): LeaderLock
|
|
39
|
+
export declare function webLocksLeaderLock(locks?: LockManager): Required<LeaderLock>;
|
package/dist/leader-lock.js
CHANGED
|
@@ -8,31 +8,49 @@ export function singleOwnerLock() {
|
|
|
8
8
|
/**
|
|
9
9
|
* Web Locks leader election: resolves once the exclusive lock is granted
|
|
10
10
|
* and holds it until the lease is released (tab close releases it
|
|
11
|
-
* implicitly, letting the next tab take over).
|
|
11
|
+
* implicitly, letting the next tab take over). A `steal` from another
|
|
12
|
+
* context rejects the holder's request with `AbortError`, which resolves the
|
|
13
|
+
* holder's `lost`.
|
|
12
14
|
*/
|
|
13
15
|
export function webLocksLeaderLock(locks) {
|
|
14
16
|
const manager = locks ?? navigator.locks;
|
|
17
|
+
const request = (name, options) => new Promise((resolveRequest, rejectRequest) => {
|
|
18
|
+
let granted = false;
|
|
19
|
+
let markLost = () => { };
|
|
20
|
+
const lost = new Promise((resolve) => {
|
|
21
|
+
markLost = resolve;
|
|
22
|
+
});
|
|
23
|
+
manager
|
|
24
|
+
.request(name, options, (lock) => {
|
|
25
|
+
// `ifAvailable` grants `null` instead of waiting (Web Locks).
|
|
26
|
+
if (lock === null) {
|
|
27
|
+
resolveRequest(undefined);
|
|
28
|
+
return undefined;
|
|
29
|
+
}
|
|
30
|
+
granted = true;
|
|
31
|
+
return new Promise((resolveHold) => {
|
|
32
|
+
resolveRequest({ release: () => resolveHold(), lost });
|
|
33
|
+
});
|
|
34
|
+
})
|
|
35
|
+
.catch((error) => {
|
|
36
|
+
if (granted &&
|
|
37
|
+
error instanceof DOMException &&
|
|
38
|
+
error.name === 'AbortError') {
|
|
39
|
+
markLost();
|
|
40
|
+
return;
|
|
41
|
+
}
|
|
42
|
+
rejectRequest(error);
|
|
43
|
+
});
|
|
44
|
+
});
|
|
45
|
+
const held = async (name, options) => {
|
|
46
|
+
const lease = await request(name, options);
|
|
47
|
+
if (lease === undefined)
|
|
48
|
+
throw new Error('a waiting lock request returned no lock');
|
|
49
|
+
return lease;
|
|
50
|
+
};
|
|
15
51
|
return {
|
|
16
|
-
acquire: (name) =>
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
resolveAcquire({ release: () => resolveHold() });
|
|
20
|
-
}))
|
|
21
|
-
.catch((error) => rejectAcquire(error));
|
|
22
|
-
}),
|
|
23
|
-
tryAcquire: (name) => new Promise((resolveTry, rejectTry) => {
|
|
24
|
-
manager
|
|
25
|
-
.request(name, { mode: 'exclusive', ifAvailable: true }, (lock) => {
|
|
26
|
-
// `ifAvailable` grants `null` instead of waiting (Web Locks).
|
|
27
|
-
if (lock === null) {
|
|
28
|
-
resolveTry(undefined);
|
|
29
|
-
return undefined;
|
|
30
|
-
}
|
|
31
|
-
return new Promise((resolveHold) => {
|
|
32
|
-
resolveTry({ release: () => resolveHold() });
|
|
33
|
-
});
|
|
34
|
-
})
|
|
35
|
-
.catch((error) => rejectTry(error));
|
|
36
|
-
}),
|
|
52
|
+
acquire: (name) => held(name, { mode: 'exclusive' }),
|
|
53
|
+
tryAcquire: (name) => request(name, { mode: 'exclusive', ifAvailable: true }),
|
|
54
|
+
steal: (name) => held(name, { mode: 'exclusive', steal: true }),
|
|
37
55
|
};
|
|
38
56
|
}
|
package/dist/multi-tab.d.ts
CHANGED
|
@@ -6,6 +6,10 @@ export declare const FOLLOWER_TIMEOUT_CODE = "client.follower_timeout";
|
|
|
6
6
|
export declare const LEADER_INCOMPATIBLE_CODE = "client.leader_incompatible";
|
|
7
7
|
/** Client-local: the leader that received a call stopped leading before it answered. */
|
|
8
8
|
export declare const LEADER_HANDOVER_CODE = "client.leader_handover";
|
|
9
|
+
/** Client-local: another tab took this tab's leadership with `takeOver()`. */
|
|
10
|
+
export declare const LEADERSHIP_TAKEN_CODE = "client.leadership_taken";
|
|
11
|
+
/** Client-local: `takeOver()` was called while its conditions do not hold. */
|
|
12
|
+
export declare const TAKEOVER_REFUSED_CODE = "client.takeover_refused";
|
|
9
13
|
/**
|
|
10
14
|
* Version of the leader/follower wire and the forwarded handle API. Bump it
|
|
11
15
|
* with every change to a message shape or to a forwarded method's arguments
|
|
@@ -51,6 +55,11 @@ export type LeadershipState = {
|
|
|
51
55
|
/** Whether the tab holding the database runs an older or a newer build. */
|
|
52
56
|
readonly leader: 'older' | 'newer';
|
|
53
57
|
readonly retryable: true;
|
|
58
|
+
} | {
|
|
59
|
+
readonly state: 'blocked';
|
|
60
|
+
readonly reason: 'leadership-taken';
|
|
61
|
+
readonly code: typeof LEADERSHIP_TAKEN_CODE;
|
|
62
|
+
readonly retryable: true;
|
|
54
63
|
};
|
|
55
64
|
/** Identity fields; absent in messages from tabs before protocol 1. */
|
|
56
65
|
interface IdentityFields {
|
|
@@ -212,6 +221,13 @@ export interface TabLeaderContext<E> {
|
|
|
212
221
|
readonly epoch: number;
|
|
213
222
|
/** This tab's id. The leader's own calls arrive under it. */
|
|
214
223
|
readonly tabId: string;
|
|
224
|
+
/**
|
|
225
|
+
* True when this tab took the lock from an unreachable leader with
|
|
226
|
+
* `takeOver()`. That leader's worker can still hold the database files;
|
|
227
|
+
* the core must take over its storage lock and retry opening until the
|
|
228
|
+
* old worker releases them.
|
|
229
|
+
*/
|
|
230
|
+
readonly takeover: boolean;
|
|
215
231
|
/**
|
|
216
232
|
* The leader lock. The coordinator releases it after {@link TabLeader.close}
|
|
217
233
|
* resolves. Release it earlier only when the core is already gone, such as a
|
|
@@ -235,9 +251,38 @@ export interface TabLeader {
|
|
|
235
251
|
* lock.
|
|
236
252
|
*/
|
|
237
253
|
tabClosed?(tabId: string): void;
|
|
238
|
-
/**
|
|
254
|
+
/**
|
|
255
|
+
* Stop the core. The coordinator releases the leader lock afterwards. It
|
|
256
|
+
* also runs when another tab took the lock: the core must not write again.
|
|
257
|
+
*/
|
|
239
258
|
close(): Promise<void>;
|
|
240
259
|
}
|
|
260
|
+
/**
|
|
261
|
+
* A follower's link to its leader went `leader-unreachable`, or left that
|
|
262
|
+
* state. Times are `clock.now()` milliseconds (wall-clock by default).
|
|
263
|
+
*/
|
|
264
|
+
export type LeaderUnreachableEvent = {
|
|
265
|
+
readonly phase: 'started';
|
|
266
|
+
readonly at: number;
|
|
267
|
+
/** The earliest time `takeOver()` is allowed. */
|
|
268
|
+
readonly takeOverAt: number;
|
|
269
|
+
} | {
|
|
270
|
+
readonly phase: 'ended';
|
|
271
|
+
readonly at: number;
|
|
272
|
+
readonly durationMs: number;
|
|
273
|
+
/**
|
|
274
|
+
* `rebound`: the leader answered again. `promoted`: its lock passed to
|
|
275
|
+
* this tab. `taken-over`: this tab's `takeOver()` succeeded.
|
|
276
|
+
* `incompatible`: a leader of another build answered. `closed`: this
|
|
277
|
+
* tab closed first.
|
|
278
|
+
*/
|
|
279
|
+
readonly outcome: 'rebound' | 'promoted' | 'taken-over' | 'incompatible' | 'closed';
|
|
280
|
+
};
|
|
281
|
+
/** Time source and timer seam; tests inject a manual clock. */
|
|
282
|
+
export interface TabClock {
|
|
283
|
+
now(): number;
|
|
284
|
+
schedule(callback: () => void, delayMs: number): () => void;
|
|
285
|
+
}
|
|
241
286
|
export interface TabCoordinatorConfig<E> {
|
|
242
287
|
/** Web Lock name of the leadership; the channel and tab locks derive from it. */
|
|
243
288
|
readonly name: string;
|
|
@@ -252,11 +297,19 @@ export interface TabCoordinatorConfig<E> {
|
|
|
252
297
|
/** Events the leader broadcast, or sent to this tab. */
|
|
253
298
|
onEvent?(event: E): void;
|
|
254
299
|
onStateChange?(state: LeadershipState): void;
|
|
300
|
+
/** Start and end of every `leader-unreachable` period, for host telemetry. */
|
|
301
|
+
onLeaderUnreachable?(event: LeaderUnreachableEvent): void;
|
|
255
302
|
/** Defaults to Web Locks; tests inject a name-keyed exclusive lock. */
|
|
256
303
|
readonly lock?: LeaderLock;
|
|
257
304
|
readonly channelFactory?: (name: string) => CrossTabChannel<E>;
|
|
258
305
|
/** Liveness and handover-queue deadline; defaults to 10 s. */
|
|
259
306
|
readonly callTimeoutMs?: number;
|
|
307
|
+
/**
|
|
308
|
+
* How long a follower must have been `leader-unreachable` before
|
|
309
|
+
* `takeOver()` is allowed; defaults to twice `callTimeoutMs`.
|
|
310
|
+
*/
|
|
311
|
+
readonly takeOverAfterMs?: number;
|
|
312
|
+
readonly clock?: TabClock;
|
|
260
313
|
}
|
|
261
314
|
/** One tab's end of the coordinator, the same in leader and follower tabs. */
|
|
262
315
|
export interface TabCoordinator {
|
|
@@ -264,6 +317,15 @@ export interface TabCoordinator {
|
|
|
264
317
|
readonly state: LeadershipState;
|
|
265
318
|
/** Run a call on the leader's core, in this tab or over the channel. */
|
|
266
319
|
call(method: string, args: readonly unknown[]): Promise<unknown>;
|
|
320
|
+
/**
|
|
321
|
+
* Take the lock from a leader that has been `leader-unreachable` for
|
|
322
|
+
* `takeOverAfterMs`, and start the core in this tab. The old leader reports
|
|
323
|
+
* `leadership-taken` and closes its core once it runs again. Rejects with
|
|
324
|
+
* `client.takeover_refused` (`details.reason`: `not-unreachable`,
|
|
325
|
+
* `too-early`, `in-progress` or `unsupported`) when the conditions do not
|
|
326
|
+
* hold, and with the core's start error when the core cannot start.
|
|
327
|
+
*/
|
|
328
|
+
takeOver(): Promise<void>;
|
|
267
329
|
/** Stop the core (leader) or the link (follower), and release this tab's locks. */
|
|
268
330
|
close(): Promise<void>;
|
|
269
331
|
}
|
package/dist/multi-tab.js
CHANGED
|
@@ -73,6 +73,10 @@ export const FOLLOWER_TIMEOUT_CODE = 'client.follower_timeout';
|
|
|
73
73
|
export const LEADER_INCOMPATIBLE_CODE = 'client.leader_incompatible';
|
|
74
74
|
/** Client-local: the leader that received a call stopped leading before it answered. */
|
|
75
75
|
export const LEADER_HANDOVER_CODE = 'client.leader_handover';
|
|
76
|
+
/** Client-local: another tab took this tab's leadership with `takeOver()`. */
|
|
77
|
+
export const LEADERSHIP_TAKEN_CODE = 'client.leadership_taken';
|
|
78
|
+
/** Client-local: `takeOver()` was called while its conditions do not hold. */
|
|
79
|
+
export const TAKEOVER_REFUSED_CODE = 'client.takeover_refused';
|
|
76
80
|
/**
|
|
77
81
|
* Version of the leader/follower wire and the forwarded handle API. Bump it
|
|
78
82
|
* with every change to a message shape or to a forwarded method's arguments
|
|
@@ -678,6 +682,9 @@ export class FollowerLink {
|
|
|
678
682
|
function tabLockName(name, tabId) {
|
|
679
683
|
return `${name}:tab:${tabId}`;
|
|
680
684
|
}
|
|
685
|
+
function takeOverRefused(reason, takeOverAt) {
|
|
686
|
+
return new ClientSyncError(TAKEOVER_REFUSED_CODE, 'takeOver() requires a leader that has been unreachable for takeOverAfterMs', reason === 'too-early' || reason === 'in-progress', { reason, ...(takeOverAt !== undefined ? { takeOverAt } : {}) });
|
|
687
|
+
}
|
|
681
688
|
/**
|
|
682
689
|
* Elect one leader tab per `name` and run `lead` there; every other tab
|
|
683
690
|
* forwards its calls to that core and receives its events. When the leader
|
|
@@ -686,6 +693,15 @@ function tabLockName(name, tabId) {
|
|
|
686
693
|
*/
|
|
687
694
|
export async function createTabCoordinator(config) {
|
|
688
695
|
const lock = config.lock ?? webLocksLeaderLock();
|
|
696
|
+
const clock = config.clock ?? {
|
|
697
|
+
now: () => Date.now(),
|
|
698
|
+
schedule: (callback, delayMs) => {
|
|
699
|
+
const timer = setTimeout(callback, delayMs);
|
|
700
|
+
return () => clearTimeout(timer);
|
|
701
|
+
},
|
|
702
|
+
};
|
|
703
|
+
const callTimeoutMs = config.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
|
|
704
|
+
const takeOverAfterMs = config.takeOverAfterMs ?? 2 * callTimeoutMs;
|
|
689
705
|
const openChannel = config.channelFactory ?? broadcastChannelFactory();
|
|
690
706
|
const channelName = multiTabChannelName(config.name);
|
|
691
707
|
const identity = {
|
|
@@ -700,8 +716,45 @@ export async function createTabCoordinator(config) {
|
|
|
700
716
|
let leading;
|
|
701
717
|
let follower;
|
|
702
718
|
let closed = false;
|
|
719
|
+
let takingOver = false;
|
|
720
|
+
/** Start of the current `leader-unreachable` period. */
|
|
721
|
+
let unreachableSince;
|
|
722
|
+
const report = (event) => {
|
|
723
|
+
try {
|
|
724
|
+
config.onLeaderUnreachable?.(event);
|
|
725
|
+
}
|
|
726
|
+
catch {
|
|
727
|
+
// A telemetry listener must never break cross-tab coordination.
|
|
728
|
+
}
|
|
729
|
+
};
|
|
730
|
+
const endUnreachable = (outcome) => {
|
|
731
|
+
if (unreachableSince === undefined)
|
|
732
|
+
return;
|
|
733
|
+
const at = clock.now();
|
|
734
|
+
report({ phase: 'ended', at, durationMs: at - unreachableSince, outcome });
|
|
735
|
+
unreachableSince = undefined;
|
|
736
|
+
};
|
|
703
737
|
const setState = (next) => {
|
|
704
738
|
state = next;
|
|
739
|
+
if (next.state === 'blocked' && next.reason === 'leader-unreachable') {
|
|
740
|
+
if (unreachableSince === undefined) {
|
|
741
|
+
unreachableSince = clock.now();
|
|
742
|
+
report({
|
|
743
|
+
phase: 'started',
|
|
744
|
+
at: unreachableSince,
|
|
745
|
+
takeOverAt: unreachableSince + takeOverAfterMs,
|
|
746
|
+
});
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
else if (next.state === 'follower') {
|
|
750
|
+
endUnreachable('rebound');
|
|
751
|
+
}
|
|
752
|
+
else if (next.state === 'leader') {
|
|
753
|
+
endUnreachable(takingOver ? 'taken-over' : 'promoted');
|
|
754
|
+
}
|
|
755
|
+
else if (next.state === 'blocked') {
|
|
756
|
+
endUnreachable('incompatible');
|
|
757
|
+
}
|
|
705
758
|
try {
|
|
706
759
|
config.onStateChange?.(next);
|
|
707
760
|
}
|
|
@@ -711,12 +764,27 @@ export async function createTabCoordinator(config) {
|
|
|
711
764
|
};
|
|
712
765
|
// Held until close: a leader waits on it to learn this tab is gone.
|
|
713
766
|
const tabLease = await lock.acquire(tabLockName(config.name, tabId));
|
|
714
|
-
const lead = async (lease, epoch) => {
|
|
767
|
+
const lead = async (lease, epoch, takeover) => {
|
|
715
768
|
let bridge;
|
|
716
769
|
let current = true;
|
|
770
|
+
let stepDown;
|
|
771
|
+
let lostWhileStarting = false;
|
|
772
|
+
const taken = {
|
|
773
|
+
state: 'blocked',
|
|
774
|
+
reason: 'leadership-taken',
|
|
775
|
+
code: LEADERSHIP_TAKEN_CODE,
|
|
776
|
+
retryable: true,
|
|
777
|
+
};
|
|
778
|
+
void lease.lost?.then(() => {
|
|
779
|
+
if (stepDown !== undefined)
|
|
780
|
+
stepDown(taken);
|
|
781
|
+
else
|
|
782
|
+
lostWhileStarting = true;
|
|
783
|
+
});
|
|
717
784
|
const leader = await config.lead({
|
|
718
785
|
epoch,
|
|
719
786
|
tabId,
|
|
787
|
+
takeover,
|
|
720
788
|
lease,
|
|
721
789
|
broadcast: (event) => {
|
|
722
790
|
if (!current)
|
|
@@ -733,8 +801,9 @@ export async function createTabCoordinator(config) {
|
|
|
733
801
|
bridge?.sendEvent(to, event);
|
|
734
802
|
},
|
|
735
803
|
});
|
|
736
|
-
if (closed) {
|
|
737
|
-
// Closed while the core was starting
|
|
804
|
+
if (closed || lostWhileStarting) {
|
|
805
|
+
// Closed while the core was starting, or another tab took the lock: a
|
|
806
|
+
// follower link, if any, binds to that tab's announcement.
|
|
738
807
|
current = false;
|
|
739
808
|
await leader.close();
|
|
740
809
|
await lease.release();
|
|
@@ -749,6 +818,16 @@ export async function createTabCoordinator(config) {
|
|
|
749
818
|
},
|
|
750
819
|
};
|
|
751
820
|
leading = ending;
|
|
821
|
+
stepDown = (next) => {
|
|
822
|
+
// Stop the core and release the lock; this tab stays blocked until it
|
|
823
|
+
// reloads.
|
|
824
|
+
if (leading !== ending)
|
|
825
|
+
return;
|
|
826
|
+
leading = undefined;
|
|
827
|
+
ending.end();
|
|
828
|
+
setState(next);
|
|
829
|
+
void leader.close().finally(() => lease.release());
|
|
830
|
+
};
|
|
752
831
|
bridge = new LeaderBridge({
|
|
753
832
|
channel: openChannel(channelName),
|
|
754
833
|
epoch,
|
|
@@ -768,22 +847,14 @@ export async function createTabCoordinator(config) {
|
|
|
768
847
|
},
|
|
769
848
|
}
|
|
770
849
|
: {}),
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
state: 'blocked',
|
|
780
|
-
reason: 'leader-incompatible',
|
|
781
|
-
code: LEADER_INCOMPATIBLE_CODE,
|
|
782
|
-
leader: 'newer',
|
|
783
|
-
retryable: true,
|
|
784
|
-
});
|
|
785
|
-
void leader.close().finally(() => lease.release());
|
|
786
|
-
},
|
|
850
|
+
// A newer build asked for the core.
|
|
851
|
+
onNewerTab: () => stepDown?.({
|
|
852
|
+
state: 'blocked',
|
|
853
|
+
reason: 'leader-incompatible',
|
|
854
|
+
code: LEADER_INCOMPATIBLE_CODE,
|
|
855
|
+
leader: 'newer',
|
|
856
|
+
retryable: true,
|
|
857
|
+
}),
|
|
787
858
|
});
|
|
788
859
|
// Calls queued for the next leader run on this tab's own core.
|
|
789
860
|
follower?.handOver((method, args) => leader.call(tabId, method, args));
|
|
@@ -801,17 +872,64 @@ export async function createTabCoordinator(config) {
|
|
|
801
872
|
}
|
|
802
873
|
if (leading !== undefined)
|
|
803
874
|
return leading.leader.call(tabId, method, args);
|
|
875
|
+
if (follower !== undefined)
|
|
876
|
+
return follower.call(method, args);
|
|
877
|
+
if (state.state === 'blocked' && state.reason === 'leadership-taken') {
|
|
878
|
+
return Promise.reject(new ClientSyncError(LEADERSHIP_TAKEN_CODE, 'another tab took over the core this tab ran', true));
|
|
879
|
+
}
|
|
804
880
|
if (state.state === 'blocked' && state.reason === 'leader-incompatible') {
|
|
805
881
|
return Promise.reject(new ClientSyncError(LEADER_INCOMPATIBLE_CODE, 'the tab that owns the database runs a different protocol or schema version', true));
|
|
806
882
|
}
|
|
807
|
-
if (follower !== undefined)
|
|
808
|
-
return follower.call(method, args);
|
|
809
883
|
return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'no core serves this tab'));
|
|
810
884
|
},
|
|
885
|
+
takeOver: async () => {
|
|
886
|
+
if (closed) {
|
|
887
|
+
throw new ClientSyncError(WORKER_FAILED_CODE, 'the tab coordinator is closed');
|
|
888
|
+
}
|
|
889
|
+
const link = follower;
|
|
890
|
+
if (link === undefined ||
|
|
891
|
+
unreachableSince === undefined ||
|
|
892
|
+
state.state !== 'blocked' ||
|
|
893
|
+
state.reason !== 'leader-unreachable') {
|
|
894
|
+
throw takeOverRefused('not-unreachable');
|
|
895
|
+
}
|
|
896
|
+
if (takingOver)
|
|
897
|
+
throw takeOverRefused('in-progress');
|
|
898
|
+
const takeOverAt = unreachableSince + takeOverAfterMs;
|
|
899
|
+
if (clock.now() < takeOverAt)
|
|
900
|
+
throw takeOverRefused('too-early', takeOverAt);
|
|
901
|
+
if (lock.steal === undefined)
|
|
902
|
+
throw takeOverRefused('unsupported');
|
|
903
|
+
takingOver = true;
|
|
904
|
+
try {
|
|
905
|
+
const lease = await lock.steal(config.name);
|
|
906
|
+
if (closed) {
|
|
907
|
+
await lease.release();
|
|
908
|
+
return;
|
|
909
|
+
}
|
|
910
|
+
try {
|
|
911
|
+
// Exceed every epoch this tab saw, so the old leader's late replies
|
|
912
|
+
// and events are discarded everywhere.
|
|
913
|
+
await lead(lease, link.maxEpochSeen + 1, true);
|
|
914
|
+
}
|
|
915
|
+
catch (error) {
|
|
916
|
+
await lease.release();
|
|
917
|
+
throw error;
|
|
918
|
+
}
|
|
919
|
+
if (!closed && leading === undefined) {
|
|
920
|
+
// A third tab took the lock while this tab's core was starting.
|
|
921
|
+
throw new ClientSyncError(LEADERSHIP_TAKEN_CODE, 'another tab took over the core this tab ran', true);
|
|
922
|
+
}
|
|
923
|
+
}
|
|
924
|
+
finally {
|
|
925
|
+
takingOver = false;
|
|
926
|
+
}
|
|
927
|
+
},
|
|
811
928
|
close: async () => {
|
|
812
929
|
if (closed)
|
|
813
930
|
return;
|
|
814
931
|
closed = true;
|
|
932
|
+
endUnreachable('closed');
|
|
815
933
|
follower?.close();
|
|
816
934
|
follower = undefined;
|
|
817
935
|
const ending = leading;
|
|
@@ -830,7 +948,7 @@ export async function createTabCoordinator(config) {
|
|
|
830
948
|
: await lock.acquire(config.name);
|
|
831
949
|
if (lease !== undefined) {
|
|
832
950
|
try {
|
|
833
|
-
await lead(lease, 0);
|
|
951
|
+
await lead(lease, 0, false);
|
|
834
952
|
}
|
|
835
953
|
catch (error) {
|
|
836
954
|
await lease.release();
|
|
@@ -846,15 +964,16 @@ export async function createTabCoordinator(config) {
|
|
|
846
964
|
onEvent: (event) => config.onEvent?.(event),
|
|
847
965
|
onLeaderChange: () => { },
|
|
848
966
|
onStateChange: setState,
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
: {}),
|
|
967
|
+
callTimeoutMs,
|
|
968
|
+
schedule: clock.schedule,
|
|
852
969
|
});
|
|
853
970
|
follower = link;
|
|
854
|
-
// Granted only when the
|
|
971
|
+
// Granted only when the lock is released: the leader's tab closed, or this
|
|
972
|
+
// tab's own failed takeover let go of it.
|
|
855
973
|
void lock.acquire(config.name).then(async (promoted) => {
|
|
856
|
-
if (closed) {
|
|
857
|
-
//
|
|
974
|
+
if (closed || follower !== link) {
|
|
975
|
+
// Closed, or this tab already leads through takeOver(): promoting would
|
|
976
|
+
// hold the lock forever.
|
|
858
977
|
await promoted.release();
|
|
859
978
|
return;
|
|
860
979
|
}
|
|
@@ -863,7 +982,7 @@ export async function createTabCoordinator(config) {
|
|
|
863
982
|
const epoch = link.maxEpochSeen + 1;
|
|
864
983
|
link.unbind();
|
|
865
984
|
try {
|
|
866
|
-
await lead(promoted, epoch);
|
|
985
|
+
await lead(promoted, epoch, false);
|
|
867
986
|
}
|
|
868
987
|
catch {
|
|
869
988
|
// The core failed to start: release so the next tab tries.
|
package/dist/reactive-store.js
CHANGED
|
@@ -251,7 +251,8 @@ const unreadQuerySnapshots = new Map();
|
|
|
251
251
|
function localReadsBlocked(availability) {
|
|
252
252
|
return (availability.state === 'blocked' &&
|
|
253
253
|
(availability.reason === 'leader-unreachable' ||
|
|
254
|
-
availability.reason === 'leader-incompatible'
|
|
254
|
+
availability.reason === 'leader-incompatible' ||
|
|
255
|
+
availability.reason === 'leadership-taken'));
|
|
255
256
|
}
|
|
256
257
|
/** One frozen snapshot per phase and availability for entries that have no
|
|
257
258
|
* successful read, so switching between unread entries keeps the snapshot and
|
package/dist/wasm-database.d.ts
CHANGED
|
@@ -16,6 +16,12 @@ export interface PersistentWasmDatabaseOptions {
|
|
|
16
16
|
readonly directory?: string;
|
|
17
17
|
/** Initial SAH pool capacity (sqlite-wasm default: 6). */
|
|
18
18
|
readonly initialCapacity?: number;
|
|
19
|
+
/**
|
|
20
|
+
* Take the storage lock from the worker that holds it, which fences that
|
|
21
|
+
* worker's database. Its SAHs stay held until it runs again, so the open
|
|
22
|
+
* fails with a retryable `client.storage_busy` until then.
|
|
23
|
+
*/
|
|
24
|
+
readonly takeOver?: boolean;
|
|
19
25
|
}
|
|
20
26
|
/**
|
|
21
27
|
* THE reload-persistent browser mode: a named database on OPFS via the
|