@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/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.js
CHANGED
package/dist/worker-host.d.ts
CHANGED
|
@@ -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>;
|
package/dist/worker-host.js
CHANGED
|
@@ -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:
|
|
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.
|
|
3
|
+
"version": "0.50.0",
|
|
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.
|
|
100
|
+
"@syncular/core": "0.50.0"
|
|
101
101
|
},
|
|
102
102
|
"devDependencies": {
|
|
103
|
-
"@syncular/server": "0.
|
|
103
|
+
"@syncular/server": "0.50.0",
|
|
104
104
|
"playwright": "1.63.0",
|
|
105
105
|
"@electric-sql/pglite": "^0.5.4"
|
|
106
106
|
}
|
package/src/availability.ts
CHANGED
|
@@ -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:
|
|
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
|
|
package/src/leader-lock.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
|
|
|
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
|
-
|
|
54
|
-
|
|
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
|
}
|