@syncular/client 0.58.0 → 0.59.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 +7 -7
- package/dist/apply.d.ts +20 -11
- package/dist/apply.js +67 -45
- package/dist/blob.d.ts +17 -9
- package/dist/blob.js +5 -6
- package/dist/bun-database.d.ts +1 -0
- package/dist/bun-database.js +28 -0
- package/dist/client.d.ts +27 -10
- package/dist/client.js +357 -190
- package/dist/database.d.ts +5 -0
- package/dist/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +2 -0
- package/dist/errors.js +4 -0
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +3 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +61 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +11 -10
- package/dist/invalidation.js +15 -26
- package/dist/local-purge.js +9 -12
- package/dist/local-rebootstrap.js +2 -2
- package/dist/multi-tab.d.ts +89 -1
- package/dist/multi-tab.js +70 -31
- package/dist/native-bridge.d.ts +235 -0
- package/dist/native-bridge.js +789 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +29 -0
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +19 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/query-guard.d.ts +25 -24
- package/dist/query-guard.js +34 -191
- package/dist/reactive-store.js +53 -11
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +11 -15
- package/dist/schema.js +15 -10
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +80 -72
- package/dist/worker-host.d.ts +10 -5
- package/dist/worker-host.js +64 -7
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +6 -2
- package/package.json +11 -3
- package/src/apply.ts +91 -55
- package/src/blob.ts +27 -15
- package/src/bun-database.ts +29 -0
- package/src/client.ts +477 -261
- package/src/database.ts +5 -0
- package/src/encryption.ts +10 -5
- package/src/errors.ts +8 -0
- package/src/failed-overlay.ts +3 -7
- package/src/http.ts +90 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +17 -32
- package/src/local-purge.ts +11 -13
- package/src/local-rebootstrap.ts +2 -3
- package/src/multi-tab.ts +88 -30
- package/src/native-bridge.ts +1189 -0
- package/src/node-database.ts +32 -0
- package/src/outbox.ts +19 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/query-guard.ts +43 -180
- package/src/reactive-store.ts +50 -10
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +12 -16
- package/src/schema.ts +19 -12
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/worker-core.ts +94 -74
- package/src/worker-host.ts +63 -16
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +6 -2
package/dist/multi-tab.d.ts
CHANGED
|
@@ -1,3 +1,76 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Multi-tab followers: one core per origin, N tabs.
|
|
3
|
+
*
|
|
4
|
+
* The leader tab holds the Web Locks lease and runs the worker core (the
|
|
5
|
+
* existing worker-host path, unchanged). Every OTHER tab is a FOLLOWER: it
|
|
6
|
+
* loses the lock election and, instead of a dead not-leader handle, opens a
|
|
7
|
+
* BroadcastChannel to the leader and proxies the whole logical API over it —
|
|
8
|
+
* one sync loop, one WebSocket, one DB, N tabs.
|
|
9
|
+
*
|
|
10
|
+
* Wire (all messages structured-clone-safe; `Set`/`Uint8Array`/`ArrayBuffer`
|
|
11
|
+
* survive `postMessage` on a BroadcastChannel):
|
|
12
|
+
*
|
|
13
|
+
* follower → leader
|
|
14
|
+
* hello {t,epoch?,fromId,protocol,schemaVersion}
|
|
15
|
+
* — "who's the leader?" on join,
|
|
16
|
+
* and the follower's liveness probe
|
|
17
|
+
* req {t,epoch,fromId,reqId,method,args,protocol,schemaVersion}
|
|
18
|
+
* leader → all
|
|
19
|
+
* announce {t,epoch,clientId,protocol,schemaVersion}
|
|
20
|
+
* — "I am the leader, this epoch";
|
|
21
|
+
* the answer to every hello
|
|
22
|
+
* res {t,epoch,to,reqId,ok,value|error}
|
|
23
|
+
* — reply to one req, for the
|
|
24
|
+
* follower `to` that sent it
|
|
25
|
+
* event {t,epoch,event,to?} — fan-out (invalidate/presence/…),
|
|
26
|
+
* or one tab's event when `to` is set
|
|
27
|
+
*
|
|
28
|
+
* Epoch (leader generation token): a monotonic counter carried in a shared
|
|
29
|
+
* BroadcastChannel and bumped by every promotion. Followers stamp requests
|
|
30
|
+
* with the epoch they last heard in an `announce`; a leader ignores requests
|
|
31
|
+
* from a stale epoch, and a follower discards any `res`/`event` that does not
|
|
32
|
+
* match its current epoch — so a late reply from a tab that has since died
|
|
33
|
+
* (or a duplicate from a previous leader) can never be mistaken for a live
|
|
34
|
+
* one. Every follower counts its `reqId`s from 1, so a follower also discards
|
|
35
|
+
* a `res` whose `to` names another tab. Epoch is derived deterministically
|
|
36
|
+
* from a per-origin clock: each promoter reads the highest epoch it has seen
|
|
37
|
+
* and adds one, so successive leaders always strictly increase it even across
|
|
38
|
+
* the lock-handover gap.
|
|
39
|
+
*
|
|
40
|
+
* Identity: every hello, req, and announce carries the sender's
|
|
41
|
+
* {@link MULTI_TAB_PROTOCOL_VERSION} and application schema version. A leader
|
|
42
|
+
* serves only requests with its own identity. A follower whose leader has a
|
|
43
|
+
* different identity goes `blocked` with `leader-incompatible` and sends it
|
|
44
|
+
* nothing. A leader that hears a hello from a newer tab closes its core and
|
|
45
|
+
* releases the lock, so the newer tab takes over. A newer follower sends one
|
|
46
|
+
* hello to every older leader it hears announce, so an older tab that promotes
|
|
47
|
+
* after the first one stepped down steps down as well. Tabs from before
|
|
48
|
+
* protocol 1 send no identity and count as older.
|
|
49
|
+
*
|
|
50
|
+
* Liveness is follower-driven: the leader runs no timer. Browsers throttle
|
|
51
|
+
* the timers of a hidden tab (Chrome's intensive throttling wakes them about
|
|
52
|
+
* once a minute) but still dispatch its BroadcastChannel messages, so a leader
|
|
53
|
+
* heartbeat misses its schedule in a background leader tab while that tab is
|
|
54
|
+
* alive. Instead, a bound follower that has heard no `announce` for a third of
|
|
55
|
+
* its call timeout posts a `hello`, and goes `blocked` only when that probe
|
|
56
|
+
* stays unanswered for the rest of the timeout. A leader tab whose main thread
|
|
57
|
+
* processes no messages (hung or frozen) therefore still blocks its followers
|
|
58
|
+
* within `callTimeoutMs`, and a closed leader hands over through the lock.
|
|
59
|
+
* A forwarded call has no deadline of its own: a live leader may run it behind
|
|
60
|
+
* a long sync round, exactly as it runs its own tab's calls. It rejects when
|
|
61
|
+
* the link blocks, when another leader announces, or when the link closes.
|
|
62
|
+
*
|
|
63
|
+
* Presence identity: all tabs share the leader's one connection, so a device
|
|
64
|
+
* is exactly ONE presence peer collectively — `(actorId, leaderClientId)`.
|
|
65
|
+
* A follower's `setPresence` forwards to the leader's single publisher; there
|
|
66
|
+
* is no per-tab presence peer (documented in the web-client README).
|
|
67
|
+
*
|
|
68
|
+
* Tab lifetime: every tab of a {@link TabCoordinator} holds an exclusive Web
|
|
69
|
+
* Lock named for its tab id until it closes. A leader whose core keeps per-tab
|
|
70
|
+
* state waits on that lock for each tab that called it; the grant means the
|
|
71
|
+
* tab is gone.
|
|
72
|
+
*/
|
|
73
|
+
import { ClientSyncError } from './errors.js';
|
|
1
74
|
import { type LeaderLease, type LeaderLock } from './leader-lock.js';
|
|
2
75
|
import type { SyncWorkerEvent } from './worker-protocol.js';
|
|
3
76
|
/** Client-local: a follower call could not reach a leader before its deadline. */
|
|
@@ -15,7 +88,7 @@ export declare const TAKEOVER_REFUSED_CODE = "client.takeover_refused";
|
|
|
15
88
|
* with every change to a message shape or to a forwarded method's arguments
|
|
16
89
|
* or result, so tabs of different builds never serve each other.
|
|
17
90
|
*/
|
|
18
|
-
export declare const MULTI_TAB_PROTOCOL_VERSION =
|
|
91
|
+
export declare const MULTI_TAB_PROTOCOL_VERSION = 3;
|
|
19
92
|
/** What a tab must share with its leader to be served by it. */
|
|
20
93
|
export interface TabIdentity {
|
|
21
94
|
readonly protocol: number;
|
|
@@ -43,6 +116,19 @@ export type LeadershipState = {
|
|
|
43
116
|
} | {
|
|
44
117
|
readonly state: 'waiting';
|
|
45
118
|
readonly reason: 'handover' | 'leader-announcement';
|
|
119
|
+
} | {
|
|
120
|
+
/**
|
|
121
|
+
* This tab won the lock after the leader left and its core failed to
|
|
122
|
+
* start. It released the lock and, while `retrying`, asks for it again
|
|
123
|
+
* behind every other waiting tab; after the third failed start it stops
|
|
124
|
+
* contesting and binds to whichever tab leads next.
|
|
125
|
+
*/
|
|
126
|
+
readonly state: 'waiting';
|
|
127
|
+
readonly reason: 'leader-start-failed';
|
|
128
|
+
readonly error: ClientSyncError;
|
|
129
|
+
/** Failed starts of this tab's core so far. */
|
|
130
|
+
readonly attempt: number;
|
|
131
|
+
readonly retrying: boolean;
|
|
46
132
|
} | {
|
|
47
133
|
readonly state: 'blocked';
|
|
48
134
|
readonly reason: 'leader-unreachable';
|
|
@@ -89,6 +175,8 @@ interface AnnounceMessage extends IdentityFields {
|
|
|
89
175
|
interface ResMessage {
|
|
90
176
|
readonly t: 'res';
|
|
91
177
|
readonly epoch: number;
|
|
178
|
+
/** The follower that sent the request. */
|
|
179
|
+
readonly to: string;
|
|
92
180
|
readonly reqId: number;
|
|
93
181
|
readonly ok: boolean;
|
|
94
182
|
readonly value?: unknown;
|
package/dist/multi-tab.js
CHANGED
|
@@ -19,7 +19,9 @@
|
|
|
19
19
|
* announce {t,epoch,clientId,protocol,schemaVersion}
|
|
20
20
|
* — "I am the leader, this epoch";
|
|
21
21
|
* the answer to every hello
|
|
22
|
-
* res {t,epoch,reqId,ok,value|error}
|
|
22
|
+
* res {t,epoch,to,reqId,ok,value|error}
|
|
23
|
+
* — reply to one req, for the
|
|
24
|
+
* follower `to` that sent it
|
|
23
25
|
* event {t,epoch,event,to?} — fan-out (invalidate/presence/…),
|
|
24
26
|
* or one tab's event when `to` is set
|
|
25
27
|
*
|
|
@@ -29,17 +31,21 @@
|
|
|
29
31
|
* from a stale epoch, and a follower discards any `res`/`event` that does not
|
|
30
32
|
* match its current epoch — so a late reply from a tab that has since died
|
|
31
33
|
* (or a duplicate from a previous leader) can never be mistaken for a live
|
|
32
|
-
* one.
|
|
33
|
-
*
|
|
34
|
-
*
|
|
34
|
+
* one. Every follower counts its `reqId`s from 1, so a follower also discards
|
|
35
|
+
* a `res` whose `to` names another tab. Epoch is derived deterministically
|
|
36
|
+
* from a per-origin clock: each promoter reads the highest epoch it has seen
|
|
37
|
+
* and adds one, so successive leaders always strictly increase it even across
|
|
38
|
+
* the lock-handover gap.
|
|
35
39
|
*
|
|
36
40
|
* Identity: every hello, req, and announce carries the sender's
|
|
37
41
|
* {@link MULTI_TAB_PROTOCOL_VERSION} and application schema version. A leader
|
|
38
42
|
* serves only requests with its own identity. A follower whose leader has a
|
|
39
43
|
* different identity goes `blocked` with `leader-incompatible` and sends it
|
|
40
44
|
* nothing. A leader that hears a hello from a newer tab closes its core and
|
|
41
|
-
* releases the lock, so the newer tab takes over.
|
|
42
|
-
*
|
|
45
|
+
* releases the lock, so the newer tab takes over. A newer follower sends one
|
|
46
|
+
* hello to every older leader it hears announce, so an older tab that promotes
|
|
47
|
+
* after the first one stepped down steps down as well. Tabs from before
|
|
48
|
+
* protocol 1 send no identity and count as older.
|
|
43
49
|
*
|
|
44
50
|
* Liveness is follower-driven: the leader runs no timer. Browsers throttle
|
|
45
51
|
* the timers of a hidden tab (Chrome's intensive throttling wakes them about
|
|
@@ -82,7 +88,7 @@ export const TAKEOVER_REFUSED_CODE = 'client.takeover_refused';
|
|
|
82
88
|
* with every change to a message shape or to a forwarded method's arguments
|
|
83
89
|
* or result, so tabs of different builds never serve each other.
|
|
84
90
|
*/
|
|
85
|
-
export const MULTI_TAB_PROTOCOL_VERSION =
|
|
91
|
+
export const MULTI_TAB_PROTOCOL_VERSION = 3;
|
|
86
92
|
/**
|
|
87
93
|
* Order a peer's identity against our own: -1 older, 0 same, 1 newer. A peer
|
|
88
94
|
* from before protocol 1 sends no identity and is older.
|
|
@@ -202,6 +208,7 @@ export class LeaderBridge {
|
|
|
202
208
|
this.#channel.postMessage({
|
|
203
209
|
t: 'res',
|
|
204
210
|
epoch: this.#epoch,
|
|
211
|
+
to: fromId,
|
|
205
212
|
reqId,
|
|
206
213
|
ok: false,
|
|
207
214
|
error: {
|
|
@@ -223,6 +230,7 @@ export class LeaderBridge {
|
|
|
223
230
|
this.#channel.postMessage({
|
|
224
231
|
t: 'res',
|
|
225
232
|
epoch: this.#epoch,
|
|
233
|
+
to: fromId,
|
|
226
234
|
reqId,
|
|
227
235
|
ok: true,
|
|
228
236
|
value,
|
|
@@ -247,6 +255,7 @@ export class LeaderBridge {
|
|
|
247
255
|
this.#channel.postMessage({
|
|
248
256
|
t: 'res',
|
|
249
257
|
epoch: this.#epoch,
|
|
258
|
+
to: fromId,
|
|
250
259
|
reqId,
|
|
251
260
|
ok: false,
|
|
252
261
|
error: shape,
|
|
@@ -292,6 +301,8 @@ export class FollowerLink {
|
|
|
292
301
|
#nextReqId = 1;
|
|
293
302
|
#inFlight = new Map();
|
|
294
303
|
#replayOnHandover;
|
|
304
|
+
/** `epoch:clientId` of every older leader this tab asked to step down. */
|
|
305
|
+
#deposed = new Set();
|
|
295
306
|
#queue = [];
|
|
296
307
|
#closed = false;
|
|
297
308
|
#state = {
|
|
@@ -481,6 +492,13 @@ export class FollowerLink {
|
|
|
481
492
|
return;
|
|
482
493
|
const relation = compareTabIdentity(message, this.#identity);
|
|
483
494
|
if (relation !== 0) {
|
|
495
|
+
// An older leader steps down for this tab's hello. Each one hears it
|
|
496
|
+
// once: an older tab that promotes later is another leader.
|
|
497
|
+
const leader = `${message.epoch}:${message.clientId}`;
|
|
498
|
+
if (relation < 0 && !this.#deposed.has(leader)) {
|
|
499
|
+
this.#deposed.add(leader);
|
|
500
|
+
this.#probe();
|
|
501
|
+
}
|
|
484
502
|
this.#setIncompatible(relation < 0 ? 'older' : 'newer');
|
|
485
503
|
return;
|
|
486
504
|
}
|
|
@@ -509,8 +527,9 @@ export class FollowerLink {
|
|
|
509
527
|
}
|
|
510
528
|
if (message.t === 'res') {
|
|
511
529
|
// Discard a reply for a stale epoch — the leader that produced it is
|
|
512
|
-
// gone; the request (if still pending) is being retried elsewhere.
|
|
513
|
-
|
|
530
|
+
// gone; the request (if still pending) is being retried elsewhere. A
|
|
531
|
+
// reply for another follower carries a `reqId` of that tab's counter.
|
|
532
|
+
if (message.epoch !== this.#epoch || message.to !== this.#fromId)
|
|
514
533
|
return;
|
|
515
534
|
const inflight = this.#inFlight.get(message.reqId);
|
|
516
535
|
if (inflight === undefined)
|
|
@@ -631,9 +650,9 @@ export class FollowerLink {
|
|
|
631
650
|
});
|
|
632
651
|
}
|
|
633
652
|
/**
|
|
634
|
-
* The leader runs another build. Send it nothing
|
|
635
|
-
* leader
|
|
636
|
-
*
|
|
653
|
+
* The leader runs another build. Send it nothing but the one step-down
|
|
654
|
+
* hello for an older leader, and stay unbound until a leader with this
|
|
655
|
+
* tab's identity announces (see the module comment).
|
|
637
656
|
*/
|
|
638
657
|
#setIncompatible(leader) {
|
|
639
658
|
this.#clearReachabilityTimers();
|
|
@@ -996,27 +1015,47 @@ export async function createTabCoordinator(config) {
|
|
|
996
1015
|
: {}),
|
|
997
1016
|
});
|
|
998
1017
|
follower = link;
|
|
1018
|
+
let failedStarts = 0;
|
|
999
1019
|
// Granted only when the lock is released: the leader's tab closed, or this
|
|
1000
1020
|
// tab's own failed takeover let go of it.
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1021
|
+
const contest = () => {
|
|
1022
|
+
void lock.acquire(config.name).then(async (promoted) => {
|
|
1023
|
+
if (closed || follower !== link) {
|
|
1024
|
+
// Closed, or this tab already leads through takeOver(): promoting
|
|
1025
|
+
// would hold the lock forever.
|
|
1026
|
+
await promoted.release();
|
|
1027
|
+
return;
|
|
1028
|
+
}
|
|
1029
|
+
// The new leader must exceed every epoch this tab saw, so stale replies
|
|
1030
|
+
// and events are discarded everywhere.
|
|
1031
|
+
const epoch = link.maxEpochSeen + 1;
|
|
1032
|
+
link.unbind();
|
|
1033
|
+
try {
|
|
1034
|
+
await lead(promoted, epoch, false);
|
|
1035
|
+
}
|
|
1036
|
+
catch (error) {
|
|
1037
|
+
// Release so the next waiting tab tries, then queue behind it. Three
|
|
1038
|
+
// failed starts stop the contest: a core that fails the same way each
|
|
1039
|
+
// time (a changed worker bundle, an unreadable database) would
|
|
1040
|
+
// otherwise take and drop the lock in a loop while this tab is alone.
|
|
1041
|
+
await promoted.release();
|
|
1042
|
+
failedStarts += 1;
|
|
1043
|
+
const retrying = failedStarts < 3 && !closed;
|
|
1044
|
+
setState({
|
|
1045
|
+
state: 'waiting',
|
|
1046
|
+
reason: 'leader-start-failed',
|
|
1047
|
+
error: error instanceof ClientSyncError
|
|
1048
|
+
? error
|
|
1049
|
+
: new ClientSyncError(WORKER_FAILED_CODE, 'the core failed to start'),
|
|
1050
|
+
attempt: failedStarts,
|
|
1051
|
+
retrying,
|
|
1052
|
+
});
|
|
1053
|
+
if (retrying)
|
|
1054
|
+
contest();
|
|
1055
|
+
}
|
|
1056
|
+
});
|
|
1057
|
+
};
|
|
1058
|
+
contest();
|
|
1020
1059
|
// Return bound: an event the leader fans out before binding is dropped.
|
|
1021
1060
|
try {
|
|
1022
1061
|
await link.waitUntilBound();
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The command bridge shared by the native hosts: `@syncular/tauri` (the Tauri
|
|
3
|
+
* plugin over IPC) and the React Native binding (the C-ABI core behind a
|
|
4
|
+
* TurboModule). Both drive one Rust core through the driver-protocol command
|
|
5
|
+
* envelope `{method, params}`, so the codec, the security preflight gate, the
|
|
6
|
+
* event fanout, and every command method live here. A host subclass supplies
|
|
7
|
+
* the transport: the generic command, the query fast path, the snapshot read,
|
|
8
|
+
* header replacement, and shutdown.
|
|
9
|
+
*
|
|
10
|
+
* Bytes cross as `{$bytes: hex}` and unsafe SQLite integers as
|
|
11
|
+
* `{$bigint: decimal}`, the convention of the Rust command router. The browser
|
|
12
|
+
* client and worker entries never import this module.
|
|
13
|
+
*/
|
|
14
|
+
import { type ClientSnapshotMethods, type CurrentBaseProof, type MutationInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClientConfig, type WindowState } from './client.js';
|
|
15
|
+
import type { SqlRow, SqlValue } from './database.js';
|
|
16
|
+
import type { PresenceErrorCode } from '@syncular/core';
|
|
17
|
+
import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
|
|
18
|
+
import type { EncryptionKeyringConfig } from './encryption.js';
|
|
19
|
+
import type { ClientChangeListener, InvalidationListener, SyncStatusSnapshot } from './invalidation.js';
|
|
20
|
+
import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
|
|
21
|
+
import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
|
|
22
|
+
import type { CommitOutcome, CommitOutcomeQuery, ConflictRecord, RejectionRecord, ResolveCommitOutcomeInput } from './outcomes.js';
|
|
23
|
+
import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
|
|
24
|
+
import { type SyncProgress, type SyncProgressListener } from './progress.js';
|
|
25
|
+
import type { WindowBase } from './window.js';
|
|
26
|
+
/** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
|
|
27
|
+
export interface NativeReply {
|
|
28
|
+
readonly result?: unknown;
|
|
29
|
+
readonly error?: {
|
|
30
|
+
readonly code: string;
|
|
31
|
+
readonly message: string;
|
|
32
|
+
readonly details?: Readonly<Record<string, unknown>> | null;
|
|
33
|
+
readonly retryable?: boolean;
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
/** One event the native core pushes (the derived client-observable set). */
|
|
37
|
+
export interface SyncularEvent {
|
|
38
|
+
readonly type: string;
|
|
39
|
+
readonly [key: string]: unknown;
|
|
40
|
+
}
|
|
41
|
+
/** The bytes envelope both sides share. */
|
|
42
|
+
export type BytesEnvelope = {
|
|
43
|
+
readonly $bytes: string;
|
|
44
|
+
};
|
|
45
|
+
/** The `create` options every native host forwards to the Rust core. */
|
|
46
|
+
export interface NativeCreateConfig {
|
|
47
|
+
/** The generated schema JSON (the app passes `schema` from typegen). */
|
|
48
|
+
readonly schema: unknown;
|
|
49
|
+
/**
|
|
50
|
+
* Client id for this device or actor. If omitted, the native core generates
|
|
51
|
+
* one and persists it in the database. Supplying a different id when opening
|
|
52
|
+
* an existing database fails with `client.identity_mismatch`.
|
|
53
|
+
*/
|
|
54
|
+
readonly clientId?: string;
|
|
55
|
+
/** §4.2 client limits. */
|
|
56
|
+
readonly limits?: Record<string, unknown>;
|
|
57
|
+
/**
|
|
58
|
+
* SPEC §8.8 realtime policy. Absent ⇒ `optional`. `required` refuses a sync
|
|
59
|
+
* round while the socket is not connected instead of falling back to HTTP.
|
|
60
|
+
*/
|
|
61
|
+
readonly realtimePolicy?: SyncClientConfig['realtimePolicy'];
|
|
62
|
+
/**
|
|
63
|
+
* Portable E2EE keys and declarative per-row key-id columns, installed in
|
|
64
|
+
* the Rust core. Raw keys are never sent to the server.
|
|
65
|
+
*/
|
|
66
|
+
readonly encryption?: EncryptionKeyringConfig;
|
|
67
|
+
/** Open the native replica behind the fail-closed security gate. */
|
|
68
|
+
readonly securityPreflight?: boolean;
|
|
69
|
+
/** RFC 0005 previous-version context (default off). */
|
|
70
|
+
readonly previousVersionContext?: SyncClientConfig['previousVersionContext'];
|
|
71
|
+
}
|
|
72
|
+
/** The error a native `{error}` reply surfaces (mirrors `ClientSyncError`). */
|
|
73
|
+
export declare class NativeSyncError extends Error {
|
|
74
|
+
readonly code: string;
|
|
75
|
+
readonly details: Readonly<Record<string, unknown>> | undefined;
|
|
76
|
+
readonly retryable: boolean;
|
|
77
|
+
constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>, retryable?: boolean);
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The `create` params every native host sends. Keys cannot be installed
|
|
81
|
+
* before a security preflight; that combination fails before the host is
|
|
82
|
+
* touched.
|
|
83
|
+
*/
|
|
84
|
+
export declare function nativeCreateParams(config: NativeCreateConfig, ErrorType: typeof NativeSyncError): Record<string, unknown>;
|
|
85
|
+
/**
|
|
86
|
+
* The `SyncClientLike` proxy over a native core. Every snapshot method
|
|
87
|
+
* returns a promise from one host round trip; React hooks accept the
|
|
88
|
+
* canonical snapshot interface directly.
|
|
89
|
+
*/
|
|
90
|
+
export declare abstract class NativeBridgeClient implements PromiseMethods<ClientSnapshotMethods> {
|
|
91
|
+
#private;
|
|
92
|
+
/**
|
|
93
|
+
* `release` detaches the host event listener; the bridge calls it once,
|
|
94
|
+
* after shutdown or after a failed `create`.
|
|
95
|
+
*/
|
|
96
|
+
constructor(kind: 'tauri' | 'react-native', ErrorType: typeof NativeSyncError, release: () => void, securityLifecycle: SecurityLifecycle);
|
|
97
|
+
/** Run one `{method, params}` command on the native core. */
|
|
98
|
+
protected abstract send(method: string, params: Record<string, unknown>): Promise<NativeReply>;
|
|
99
|
+
/** The read-only SQL fast path; `params` are already envelope-encoded. */
|
|
100
|
+
protected abstract sendQuery(sql: string, params: unknown): Promise<NativeReply>;
|
|
101
|
+
/** The atomic `querySnapshot` read. */
|
|
102
|
+
protected abstract sendQuerySnapshot(params: Record<string, unknown>): Promise<NativeReply>;
|
|
103
|
+
/** Replace the native transport's full header set. */
|
|
104
|
+
protected abstract sendHeaders(headers: Readonly<Record<string, string>>): Promise<NativeReply>;
|
|
105
|
+
/** Stop the native core. `close()` detaches listeners once it settles. */
|
|
106
|
+
protected abstract shutdown(): Promise<void>;
|
|
107
|
+
/** @internal Settle the native `create`; a failure detaches the listener. */
|
|
108
|
+
__open(create: () => Promise<NativeReply>): Promise<void>;
|
|
109
|
+
/** Dispatch a command through the closed check and the preflight gate. */
|
|
110
|
+
protected command(method: string, params: Record<string, unknown>): Promise<unknown>;
|
|
111
|
+
/** Additional preflight operations a host subclass permits. */
|
|
112
|
+
protected allowPreflightCommand(_method: string): boolean;
|
|
113
|
+
protected get closed(): boolean;
|
|
114
|
+
protected get preflight(): boolean;
|
|
115
|
+
protected requireOpen(): void;
|
|
116
|
+
/** Decode a native row. Reserved `_sync_*` columns stay engine-internal,
|
|
117
|
+
* so a `SELECT *` row round-trips into `mutate()` values. */
|
|
118
|
+
protected decodeRow(row: Readonly<Record<string, unknown>>): SqlRow;
|
|
119
|
+
/** @internal Fan an incoming native event out to the local listeners. */
|
|
120
|
+
__dispatchEvent(event: SyncularEvent): void;
|
|
121
|
+
securityLifecycle(): Promise<SecurityLifecycle>;
|
|
122
|
+
beginSecurityPreflight(): Promise<void>;
|
|
123
|
+
/**
|
|
124
|
+
* Complete the security preflight. `headers` optionally carries a fresh
|
|
125
|
+
* FULL transport header set that the native host applies atomically with
|
|
126
|
+
* the activation, before the startup sync it enqueues, so a preflight that
|
|
127
|
+
* outlives the boot token starts its first round with valid credentials
|
|
128
|
+
* (the direct `setHeaders` path stays refused while gated).
|
|
129
|
+
*/
|
|
130
|
+
activateSecurity(options?: {
|
|
131
|
+
readonly encryption?: EncryptionKeyringConfig;
|
|
132
|
+
readonly headers?: Readonly<Record<string, string>>;
|
|
133
|
+
}): Promise<void>;
|
|
134
|
+
onInvalidate(listener: InvalidationListener): () => void;
|
|
135
|
+
onProgress(listener: SyncProgressListener): () => void;
|
|
136
|
+
progressSnapshot(): SyncProgress | undefined;
|
|
137
|
+
onChange(listener: ClientChangeListener): () => void;
|
|
138
|
+
onDiagnostics(listener: ClientDiagnosticsListener): () => void;
|
|
139
|
+
onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
|
|
140
|
+
query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
|
|
141
|
+
querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
|
|
142
|
+
/**
|
|
143
|
+
* §7.5: one atomic read. Every statement and every catch-up and delivery
|
|
144
|
+
* read shares one revision and one read transaction.
|
|
145
|
+
*/
|
|
146
|
+
snapshotRead(request: SnapshotReadRequest): Promise<SnapshotRead>;
|
|
147
|
+
localRevision(): Promise<bigint>;
|
|
148
|
+
statusSnapshot(): Promise<SyncStatusSnapshot>;
|
|
149
|
+
diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
|
|
150
|
+
mutate(mutations: readonly MutationInput[]): Promise<string>;
|
|
151
|
+
patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
|
|
152
|
+
readonly baseVersion?: number;
|
|
153
|
+
}): Promise<string>;
|
|
154
|
+
purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
|
|
155
|
+
rebootstrapLocalData(input: LocalDataRebootstrapInput): Promise<LocalDataRebootstrapResult>;
|
|
156
|
+
previousVersionSnapshot(spec: PreviousVersionReadSpec): Promise<PreviousVersionSnapshot>;
|
|
157
|
+
previousVersionAudit(): Promise<PreviousVersionAudit | undefined>;
|
|
158
|
+
previousVersionDiscard(): Promise<{
|
|
159
|
+
present: boolean;
|
|
160
|
+
discarded: boolean;
|
|
161
|
+
}>;
|
|
162
|
+
/**
|
|
163
|
+
* Replace the native transport's request headers at runtime, the auth
|
|
164
|
+
* rotation path. Pass the FULL header set: it replaces the current set.
|
|
165
|
+
* HTTP requests use the new set from the next call; the realtime socket
|
|
166
|
+
* applies it on its next (re)connect.
|
|
167
|
+
*/
|
|
168
|
+
setHeaders(headers: Readonly<Record<string, string>>): Promise<void>;
|
|
169
|
+
/** Materialize a `crdt` column's collaborative text from the stored
|
|
170
|
+
* (server-merged) Yjs bytes. `name` selects the shared text (default
|
|
171
|
+
* `"text"`). An absent row or NULL column is the empty document. */
|
|
172
|
+
crdtText(table: string, rowId: string, column: string, name?: string): Promise<string>;
|
|
173
|
+
/** Insert `value` at UTF-16 offset `index` in a `crdt` column's text and
|
|
174
|
+
* push the resulting Yjs update (baseVersion-less). Returns the commit id. */
|
|
175
|
+
crdtInsertText(table: string, rowId: string, column: string, index: number, value: string, name?: string): Promise<string>;
|
|
176
|
+
/** Delete `len` UTF-16 code units at `index` in a `crdt` column's text. */
|
|
177
|
+
crdtDeleteText(table: string, rowId: string, column: string, index: number, len: number, name?: string): Promise<string>;
|
|
178
|
+
/** Apply an arbitrary Yjs update onto a `crdt` column. */
|
|
179
|
+
crdtApplyUpdate(table: string, rowId: string, column: string, update: Uint8Array): Promise<string>;
|
|
180
|
+
/**
|
|
181
|
+
* Stage a blob for attachment (§5.9.7) and return the canonical `BlobRef`
|
|
182
|
+
* string to store in a `blob_ref` column. The native core owns the upload
|
|
183
|
+
* queue; write the referencing row after this resolves (§5.9.3).
|
|
184
|
+
*/
|
|
185
|
+
uploadBlob(bytes: Uint8Array, options?: {
|
|
186
|
+
readonly mediaType?: string;
|
|
187
|
+
readonly name?: string;
|
|
188
|
+
}): Promise<string>;
|
|
189
|
+
/**
|
|
190
|
+
* Resolve blob bytes for a `blob_ref` column value or a bare `blobId`
|
|
191
|
+
* (§5.9.7): the native core serves a local cache hit and otherwise
|
|
192
|
+
* downloads and verifies the content address.
|
|
193
|
+
*/
|
|
194
|
+
fetchBlob(ref: string): Promise<{
|
|
195
|
+
readonly blobId: string;
|
|
196
|
+
readonly byteLength: number;
|
|
197
|
+
readonly bytes: Uint8Array;
|
|
198
|
+
readonly mediaType?: string;
|
|
199
|
+
}>;
|
|
200
|
+
subscribe(input: {
|
|
201
|
+
readonly id: string;
|
|
202
|
+
readonly table: string;
|
|
203
|
+
readonly scopes?: Record<string, readonly string[]>;
|
|
204
|
+
readonly params?: string;
|
|
205
|
+
}): Promise<void>;
|
|
206
|
+
/** Register several subscriptions in one local transaction. */
|
|
207
|
+
subscribeMany(inputs: readonly {
|
|
208
|
+
readonly id: string;
|
|
209
|
+
readonly table: string;
|
|
210
|
+
readonly scopes?: Record<string, readonly string[]>;
|
|
211
|
+
readonly params?: string;
|
|
212
|
+
}[]): Promise<void>;
|
|
213
|
+
unsubscribe(id: string): Promise<void>;
|
|
214
|
+
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
215
|
+
windowState(base: WindowBase): Promise<WindowState>;
|
|
216
|
+
sync(): Promise<unknown>;
|
|
217
|
+
syncUntilIdle(maxRounds?: number, timeoutMs?: number): Promise<unknown>;
|
|
218
|
+
proveCurrentBase(outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>, maxRounds?: number): Promise<CurrentBaseProof>;
|
|
219
|
+
conflicts(): Promise<readonly ConflictRecord[]>;
|
|
220
|
+
rejections(): Promise<readonly RejectionRecord[]>;
|
|
221
|
+
commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
|
|
222
|
+
commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
|
|
223
|
+
resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
|
|
224
|
+
pendingCommits(): Promise<unknown[]>;
|
|
225
|
+
presence(scopeKey: string): Promise<readonly PresencePeer[]>;
|
|
226
|
+
setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
|
|
227
|
+
connectRealtime(): Promise<void>;
|
|
228
|
+
disconnectRealtime(): Promise<void>;
|
|
229
|
+
/**
|
|
230
|
+
* Shut down the native core, then detach listeners. Every call returns the
|
|
231
|
+
* same promise, so a concurrent or repeated close settles only when the one
|
|
232
|
+
* native shutdown settles, with its outcome.
|
|
233
|
+
*/
|
|
234
|
+
close(): Promise<void>;
|
|
235
|
+
}
|