@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/schema.js
CHANGED
|
@@ -65,15 +65,16 @@ export function compileClientSchema(schema) {
|
|
|
65
65
|
const scopePrefixByVariable = new Map();
|
|
66
66
|
for (const spec of table.scopes) {
|
|
67
67
|
const pattern = typeof spec === 'string' ? spec : spec.pattern;
|
|
68
|
-
const
|
|
69
|
-
if (
|
|
68
|
+
const [, prefix, variable] = PATTERN_RE.exec(pattern) ?? [];
|
|
69
|
+
if (!prefix || !variable) {
|
|
70
70
|
invalidSchema(`${tableLabel}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`);
|
|
71
71
|
}
|
|
72
|
-
const prefix = match[1];
|
|
73
|
-
const variable = match[2];
|
|
74
72
|
const column = typeof spec === 'string' ? variable : spec.column;
|
|
75
|
-
|
|
76
|
-
|
|
73
|
+
// §3.1: a scope value is an authorization key; only these two types
|
|
74
|
+
// render identically in every implementation.
|
|
75
|
+
const type = table.columns[columnIndex.get(column) ?? -1]?.type;
|
|
76
|
+
if (type !== 'string' && type !== 'integer') {
|
|
77
|
+
invalidSchema(`${tableLabel}: scope column ${JSON.stringify(column)} must be string or integer (§3.1)`);
|
|
77
78
|
}
|
|
78
79
|
const existing = scopeColumnByVariable.get(variable);
|
|
79
80
|
if (existing !== undefined && existing !== column) {
|
|
@@ -406,10 +407,14 @@ export function ensureLocalBookkeepingSchema(db) {
|
|
|
406
407
|
db.exec(`INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`);
|
|
407
408
|
createTable(OUTBOX_TABLE, 'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL');
|
|
408
409
|
createTable(OUTBOX_IMAGES, 'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)');
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
.some((row) => row.name === '
|
|
412
|
-
|
|
410
|
+
const imageColumns = db.query(`PRAGMA table_info(${OUTBOX_IMAGES})`);
|
|
411
|
+
for (const column of ['delivery_seq INTEGER', 'tbl TEXT', 'row_id TEXT'])
|
|
412
|
+
if (!imageColumns.some((row) => row.name === column.split(' ')[0]))
|
|
413
|
+
db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN ${column}`);
|
|
414
|
+
// Images written before the row key existed take it from their operation.
|
|
415
|
+
if (!imageColumns.some((row) => row.name === 'row_id'))
|
|
416
|
+
db.exec(`UPDATE ${OUTBOX_IMAGES} SET (tbl,row_id)=(SELECT json_extract(operations,'$['||op_index||'].table'),json_extract(operations,'$['||op_index||'].rowId') FROM ${OUTBOX_TABLE} WHERE client_commit_id=${OUTBOX_IMAGES}.client_commit_id)`);
|
|
417
|
+
db.exec(`CREATE INDEX IF NOT EXISTS ${OUTBOX_IMAGES}_row ON ${OUTBOX_IMAGES}(tbl,row_id)`);
|
|
413
418
|
createTable(OUTCOMES_TABLE, "seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,status TEXT NOT NULL CHECK(status IN ('applied','cached','conflict','rejected')),recorded_at_ms INTEGER NOT NULL,results TEXT NOT NULL,operations TEXT,resolution TEXT NOT NULL DEFAULT 'active' CHECK(resolution IN ('active','resolved_keep_server','superseded','dismissed')),resolved_at_ms INTEGER,replacement_client_commit_id TEXT");
|
|
414
419
|
// Outcomes created before durable aggregate recovery retain no commit
|
|
415
420
|
// envelope. New failed outcomes store it in the protected client DB.
|
package/dist/sync-scheduler.js
CHANGED
|
@@ -14,6 +14,8 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
14
14
|
let backgroundReady = false;
|
|
15
15
|
let backgroundDue = Number.POSITIVE_INFINITY;
|
|
16
16
|
let cancelBackground;
|
|
17
|
+
// §7.6 backoff for drives that end without a client retry intent.
|
|
18
|
+
let retryDelayMs = 250;
|
|
17
19
|
const report = (error) => {
|
|
18
20
|
if (options.onError !== undefined) {
|
|
19
21
|
options.onError(error);
|
|
@@ -56,6 +58,7 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
56
58
|
void client
|
|
57
59
|
.syncUntilIdle(options.maxRounds)
|
|
58
60
|
.then((result) => {
|
|
61
|
+
retryDelayMs = 250;
|
|
59
62
|
if (result !== null &&
|
|
60
63
|
typeof result === 'object' &&
|
|
61
64
|
'budgetExhausted' in result &&
|
|
@@ -64,8 +67,31 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
64
67
|
}
|
|
65
68
|
})
|
|
66
69
|
.catch((error) => {
|
|
67
|
-
if (
|
|
68
|
-
|
|
70
|
+
if (stopped)
|
|
71
|
+
return;
|
|
72
|
+
report(error);
|
|
73
|
+
// §7.7: a retryable drive rejection owes another drive. A retryable
|
|
74
|
+
// round failure already handed this loop its background intent; the
|
|
75
|
+
// drive deadline did not. An unreachable endpoint waits for the
|
|
76
|
+
// host's connectivity resume (§1.8).
|
|
77
|
+
const details = error instanceof Error && 'details' in error
|
|
78
|
+
? error.details
|
|
79
|
+
: undefined;
|
|
80
|
+
const causeKind = typeof details === 'object' &&
|
|
81
|
+
details !== null &&
|
|
82
|
+
'causeKind' in details
|
|
83
|
+
? details.causeKind
|
|
84
|
+
: undefined;
|
|
85
|
+
if (error instanceof Error &&
|
|
86
|
+
'retryable' in error &&
|
|
87
|
+
error.retryable === true &&
|
|
88
|
+
causeKind !== 'network' &&
|
|
89
|
+
causeKind !== 'connect' &&
|
|
90
|
+
cancelBackground === undefined &&
|
|
91
|
+
!immediatePending) {
|
|
92
|
+
consume({ kind: 'background', delayMs: retryDelayMs });
|
|
93
|
+
retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
|
|
94
|
+
}
|
|
69
95
|
})
|
|
70
96
|
.finally(() => {
|
|
71
97
|
running = false;
|
package/dist/transport.d.ts
CHANGED
|
@@ -4,8 +4,12 @@
|
|
|
4
4
|
* loopback implementations that call the server library directly — the
|
|
5
5
|
* loopback doctrine; HTTP/WebSocket bindings live in `./http`.
|
|
6
6
|
*/
|
|
7
|
-
/**
|
|
8
|
-
|
|
7
|
+
/**
|
|
8
|
+
* One combined push+pull round trip: SSP2 request bytes → response bytes.
|
|
9
|
+
* `signal` aborts when the `syncUntilIdle` deadline elapses (§7.7); a
|
|
10
|
+
* transport that honors it releases the round instead of holding it open.
|
|
11
|
+
*/
|
|
12
|
+
export type SyncTransport = (request: Uint8Array, signal?: AbortSignal) => Promise<Uint8Array>;
|
|
9
13
|
/** One registered authoritative query or command request. */
|
|
10
14
|
export type RemoteOperationTransport = (request: Uint8Array) => Promise<Uint8Array>;
|
|
11
15
|
export interface RemoteOperationRealtimeHandlers {
|
|
@@ -22,7 +26,14 @@ export interface SegmentFetchRequest {
|
|
|
22
26
|
readonly table: string;
|
|
23
27
|
/** Canonical JSON (§11.2) of the requested scope map (§5.5 header). */
|
|
24
28
|
readonly requestedScopesJson: string;
|
|
29
|
+
/**
|
|
30
|
+
* The descriptor's `byteLength` (§5.4): the downloader stops reading once
|
|
31
|
+
* the body exceeds it, and the client core rejects the result.
|
|
32
|
+
*/
|
|
33
|
+
readonly byteLength?: number;
|
|
25
34
|
readonly onProgress?: (bytesReceived: number) => void;
|
|
35
|
+
/** Aborts with the round when the `syncUntilIdle` deadline elapses (§7.7). */
|
|
36
|
+
readonly signal?: AbortSignal;
|
|
26
37
|
}
|
|
27
38
|
/**
|
|
28
39
|
* Fetch segment bytes from the direct endpoint (§5.5). `fetchUrl`, when
|
|
@@ -34,7 +45,9 @@ export interface SegmentFetchRequest {
|
|
|
34
45
|
*/
|
|
35
46
|
export interface SegmentDownloader {
|
|
36
47
|
(request: SegmentFetchRequest): Promise<Uint8Array>;
|
|
37
|
-
readonly fetchUrl?: (url: string, onProgress?: (bytesReceived: number) => void
|
|
48
|
+
readonly fetchUrl?: (url: string, onProgress?: (bytesReceived: number) => void, signal?: AbortSignal,
|
|
49
|
+
/** The descriptor's `byteLength`; reading stops once the body exceeds it. */
|
|
50
|
+
byteLength?: number) => Promise<Uint8Array>;
|
|
38
51
|
}
|
|
39
52
|
export interface RealtimeHandlers {
|
|
40
53
|
/** JSON control frame (§8.1): hello / sync / heartbeat / unknown. */
|
|
@@ -53,4 +66,6 @@ export interface RealtimeSocket {
|
|
|
53
66
|
sendBytes(bytes: Uint8Array): void;
|
|
54
67
|
close(): void;
|
|
55
68
|
}
|
|
56
|
-
export type RealtimeConnector = (handlers: RealtimeHandlers
|
|
69
|
+
export type RealtimeConnector = (handlers: RealtimeHandlers,
|
|
70
|
+
/** The client's id; the client passes it on every connect. */
|
|
71
|
+
clientId?: string) => Promise<RealtimeSocket> | RealtimeSocket;
|
package/dist/wasm-database.js
CHANGED
|
@@ -26,6 +26,9 @@ import { webLocksLeaderLock } from './leader-lock.js';
|
|
|
26
26
|
import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
|
|
27
27
|
import { assertImageAlias, runTransaction, } from './database.js';
|
|
28
28
|
import { ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, STORAGE_FENCED_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
|
|
29
|
+
import { prepareReadOnly } from './query-guard.js';
|
|
30
|
+
/** Compiled statements one database keeps; a full cache is finalized and cleared. */
|
|
31
|
+
const STATEMENT_CACHE_LIMIT = 128;
|
|
29
32
|
function coerceParams(params) {
|
|
30
33
|
return params.map((value) => {
|
|
31
34
|
if (typeof value === 'boolean')
|
|
@@ -39,6 +42,7 @@ class WasmClientDatabase {
|
|
|
39
42
|
/** RFC 0005: present only for a persistent OPFS database. */
|
|
40
43
|
#sah;
|
|
41
44
|
#fence;
|
|
45
|
+
#statements = new Map();
|
|
42
46
|
#closed = false;
|
|
43
47
|
#tx = { depth: 0 };
|
|
44
48
|
constructor(db, sqlite3, sah, fence) {
|
|
@@ -55,7 +59,6 @@ class WasmClientDatabase {
|
|
|
55
59
|
fence.fenced = true;
|
|
56
60
|
for (const sibling of fence.siblings)
|
|
57
61
|
sibling.close();
|
|
58
|
-
fence.siblings.clear();
|
|
59
62
|
this.close();
|
|
60
63
|
});
|
|
61
64
|
}
|
|
@@ -65,24 +68,56 @@ class WasmClientDatabase {
|
|
|
65
68
|
}
|
|
66
69
|
}
|
|
67
70
|
exec(sql, params = []) {
|
|
68
|
-
this
|
|
69
|
-
this.#db.exec({
|
|
70
|
-
sql,
|
|
71
|
-
...(params.length > 0 ? { bind: coerceParams(params) } : {}),
|
|
72
|
-
rowMode: 'object',
|
|
73
|
-
resultRows: [],
|
|
74
|
-
});
|
|
71
|
+
this.query(sql, params);
|
|
75
72
|
}
|
|
73
|
+
/**
|
|
74
|
+
* Parameterized SQL (one statement per call, the `ClientDatabase` contract)
|
|
75
|
+
* runs through a compiled statement cached by its SQL text. SQL without
|
|
76
|
+
* parameters may hold several statements and compiles through `exec`.
|
|
77
|
+
*/
|
|
76
78
|
query(sql, params = []) {
|
|
77
79
|
this.#assertOwned();
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
sql,
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
80
|
+
if (params.length === 0) {
|
|
81
|
+
const resultRows = [];
|
|
82
|
+
this.#db.exec({ sql, rowMode: 'object', resultRows });
|
|
83
|
+
return resultRows;
|
|
84
|
+
}
|
|
85
|
+
let statement = this.#statements.get(sql);
|
|
86
|
+
if (statement === undefined) {
|
|
87
|
+
statement = this.#db.prepare(sql);
|
|
88
|
+
if (this.#statements.size === STATEMENT_CACHE_LIMIT) {
|
|
89
|
+
this.#statements.forEach((evicted) => evicted.finalize());
|
|
90
|
+
this.#statements.clear();
|
|
91
|
+
}
|
|
92
|
+
this.#statements.set(sql, statement);
|
|
93
|
+
}
|
|
94
|
+
const rows = [];
|
|
95
|
+
try {
|
|
96
|
+
statement.bind(coerceParams(params));
|
|
97
|
+
while (statement.step())
|
|
98
|
+
rows.push(statement.get({}));
|
|
99
|
+
}
|
|
100
|
+
finally {
|
|
101
|
+
statement.reset(true);
|
|
102
|
+
}
|
|
103
|
+
return rows;
|
|
104
|
+
}
|
|
105
|
+
queryReadOnly(sql, params = []) {
|
|
106
|
+
this.#assertOwned();
|
|
107
|
+
prepareReadOnly(sql, () => {
|
|
108
|
+
const statement = this.#db.prepare(sql);
|
|
109
|
+
try {
|
|
110
|
+
return [
|
|
111
|
+
undefined,
|
|
112
|
+
this.#sqlite3.capi.sqlite3_sql(statement.pointer),
|
|
113
|
+
statement.isReadOnly() && statement.columnCount > 0,
|
|
114
|
+
];
|
|
115
|
+
}
|
|
116
|
+
finally {
|
|
117
|
+
statement.finalize();
|
|
118
|
+
}
|
|
84
119
|
});
|
|
85
|
-
return
|
|
120
|
+
return this.query(sql, params);
|
|
86
121
|
}
|
|
87
122
|
transaction(fn) {
|
|
88
123
|
this.#assertOwned();
|
|
@@ -108,13 +143,11 @@ class WasmClientDatabase {
|
|
|
108
143
|
db.close();
|
|
109
144
|
throw error;
|
|
110
145
|
}
|
|
111
|
-
this.#fence
|
|
146
|
+
const database = new WasmClientDatabase(db, this.#sqlite3, undefined, this.#fence);
|
|
147
|
+
this.#fence?.siblings.add(database);
|
|
112
148
|
return {
|
|
113
|
-
database
|
|
114
|
-
close: () =>
|
|
115
|
-
this.#fence?.siblings.delete(db);
|
|
116
|
-
db.close();
|
|
117
|
-
},
|
|
149
|
+
database,
|
|
150
|
+
close: () => database.close(),
|
|
118
151
|
removeFile: () => {
|
|
119
152
|
sah.util.unlink(fileName);
|
|
120
153
|
},
|
|
@@ -158,6 +191,10 @@ class WasmClientDatabase {
|
|
|
158
191
|
close() {
|
|
159
192
|
if (this.#closed)
|
|
160
193
|
return;
|
|
194
|
+
this.#fence?.siblings.delete(this);
|
|
195
|
+
// oo1 DB.close() does not finalize prepared statements, and an open one
|
|
196
|
+
// keeps the database file open, so pauseVfs() below would throw.
|
|
197
|
+
this.#statements.forEach((statement) => statement.finalize());
|
|
161
198
|
this.#db.close();
|
|
162
199
|
// DB.close() leaves the SAH pool live. Close siblings first, then pause the
|
|
163
200
|
// VFS without deleting files, before releasing this worker's physical lock.
|
package/dist/worker-core.d.ts
CHANGED
|
@@ -26,6 +26,11 @@ export interface SyncWorkerOverrides {
|
|
|
26
26
|
readonly openDatabase?: (config: WorkerInitConfig) => Promise<ClientDatabase> | ClientDatabase;
|
|
27
27
|
/** Retry deadline indirection for deterministic worker-host tests. */
|
|
28
28
|
readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
|
|
29
|
+
/**
|
|
30
|
+
* Timer indirection for deterministic worker-host tests: background-intent
|
|
31
|
+
* deadlines and the client's §8.5 heartbeat watchdog.
|
|
32
|
+
*/
|
|
33
|
+
readonly scheduleBackground?: (callback: () => void, delayMs: number) => () => void;
|
|
29
34
|
readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
|
|
30
35
|
readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
|
|
31
36
|
/**
|
package/dist/worker-core.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { SyncClient } from './client.js';
|
|
2
2
|
import { withClientDiagnosticsHost, } from './diagnostics.js';
|
|
3
3
|
import { encryptionConfigFromKeyring } from './encryption.js';
|
|
4
|
-
import { classifySqliteFailure, ClientSyncError, STORAGE_BUSY_CODE, } from './errors.js';
|
|
4
|
+
import { classifySqliteFailure, ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, } from './errors.js';
|
|
5
5
|
import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
|
|
6
6
|
import { openPersistentWasmDatabase } from './wasm-database.js';
|
|
7
7
|
import { LOCAL_AUTHORITY_UNCONFIGURED_CODE, WORKER_FAILED_CODE, WORKER_METHOD_UNAVAILABLE_CODE, } from './worker-protocol.js';
|
|
@@ -63,6 +63,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
63
63
|
let offline = false;
|
|
64
64
|
let headers = {};
|
|
65
65
|
let closed = false;
|
|
66
|
+
let pushingDiagnostics = false;
|
|
66
67
|
// -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
|
|
67
68
|
let syncChain = Promise.resolve();
|
|
68
69
|
function serializedSync(fn) {
|
|
@@ -73,8 +74,29 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
73
74
|
// -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
|
|
74
75
|
let autoSync = true;
|
|
75
76
|
let autoSyncScheduled = false;
|
|
76
|
-
let
|
|
77
|
+
let cancelBackground;
|
|
77
78
|
let backgroundDue = Number.POSITIVE_INFINITY;
|
|
79
|
+
// §7.6 backoff for drives that end without a client retry intent.
|
|
80
|
+
let retryDelayMs = 250;
|
|
81
|
+
const scheduleBackground = overrides.scheduleBackground ??
|
|
82
|
+
((callback, delayMs) => {
|
|
83
|
+
const timer = setTimeout(callback, delayMs);
|
|
84
|
+
return () => clearTimeout(timer);
|
|
85
|
+
});
|
|
86
|
+
const workerDiagnostics = (snapshot) => withClientDiagnosticsHost(snapshot, {
|
|
87
|
+
kind: 'worker',
|
|
88
|
+
role: 'leader',
|
|
89
|
+
connectivity: offline ? 'offline' : snapshot.host.connectivity,
|
|
90
|
+
realtime: snapshot.host.realtime,
|
|
91
|
+
});
|
|
92
|
+
const postDiagnostics = (snapshot) => {
|
|
93
|
+
if (!closed) {
|
|
94
|
+
post({
|
|
95
|
+
t: 'event',
|
|
96
|
+
event: { kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) },
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
};
|
|
78
100
|
function runAutoSync() {
|
|
79
101
|
if (closed ||
|
|
80
102
|
client === undefined ||
|
|
@@ -92,20 +114,42 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
92
114
|
return running.syncUntilIdle();
|
|
93
115
|
})
|
|
94
116
|
.then((summary) => {
|
|
117
|
+
retryDelayMs = 250;
|
|
95
118
|
if (!closed)
|
|
96
119
|
post({ t: 'event', event: { kind: 'synced', summary } });
|
|
97
120
|
if (summary.budgetExhausted)
|
|
98
121
|
consumeSyncIntent({ kind: 'interactive' });
|
|
99
122
|
})
|
|
100
123
|
.catch((error) => {
|
|
101
|
-
if (
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
}
|
|
124
|
+
if (closed)
|
|
125
|
+
return;
|
|
126
|
+
post({
|
|
127
|
+
t: 'event',
|
|
128
|
+
event: { kind: 'synced', error: toErrorShape(error) },
|
|
129
|
+
});
|
|
130
|
+
// §7.7: a retryable drive rejection owes another drive. A retryable
|
|
131
|
+
// round failure already handed this loop its background intent; the
|
|
132
|
+
// drive deadline did not. An unreachable endpoint waits for the
|
|
133
|
+
// host's connectivity resume (§1.8).
|
|
134
|
+
const causeKind = error instanceof ClientSyncError
|
|
135
|
+
? error.details?.['causeKind']
|
|
136
|
+
: undefined;
|
|
137
|
+
if (error instanceof ClientSyncError &&
|
|
138
|
+
error.retryable &&
|
|
139
|
+
causeKind !== 'network' &&
|
|
140
|
+
causeKind !== 'connect' &&
|
|
141
|
+
cancelBackground === undefined &&
|
|
142
|
+
!autoSyncScheduled) {
|
|
143
|
+
consumeSyncIntent({ kind: 'background', delayMs: retryDelayMs });
|
|
144
|
+
retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
|
|
106
145
|
}
|
|
107
146
|
});
|
|
108
147
|
}
|
|
148
|
+
function stopBackground() {
|
|
149
|
+
cancelBackground?.();
|
|
150
|
+
cancelBackground = undefined;
|
|
151
|
+
backgroundDue = Number.POSITIVE_INFINITY;
|
|
152
|
+
}
|
|
109
153
|
function consumeSyncIntent(intent) {
|
|
110
154
|
if (!autoSync ||
|
|
111
155
|
closed ||
|
|
@@ -119,13 +163,12 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
119
163
|
if (autoSyncScheduled)
|
|
120
164
|
return;
|
|
121
165
|
const due = Date.now() + Math.max(0, intent.delayMs);
|
|
122
|
-
if (
|
|
166
|
+
if (cancelBackground !== undefined && due >= backgroundDue)
|
|
123
167
|
return;
|
|
124
|
-
|
|
125
|
-
clearTimeout(backgroundTimer);
|
|
168
|
+
cancelBackground?.();
|
|
126
169
|
backgroundDue = due;
|
|
127
|
-
|
|
128
|
-
|
|
170
|
+
cancelBackground = scheduleBackground(() => {
|
|
171
|
+
cancelBackground = undefined;
|
|
129
172
|
backgroundDue = Number.POSITIVE_INFINITY;
|
|
130
173
|
if (!autoSyncScheduled) {
|
|
131
174
|
autoSyncScheduled = true;
|
|
@@ -134,11 +177,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
134
177
|
}, Math.max(0, due - Date.now()));
|
|
135
178
|
return;
|
|
136
179
|
}
|
|
137
|
-
|
|
138
|
-
clearTimeout(backgroundTimer);
|
|
139
|
-
backgroundTimer = undefined;
|
|
140
|
-
backgroundDue = Number.POSITIVE_INFINITY;
|
|
141
|
-
}
|
|
180
|
+
stopBackground();
|
|
142
181
|
if (!autoSync || autoSyncScheduled || closed || client === undefined) {
|
|
143
182
|
return;
|
|
144
183
|
}
|
|
@@ -225,12 +264,12 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
225
264
|
? { segments: bindings.segments }
|
|
226
265
|
: {}),
|
|
227
266
|
...(blobs !== undefined ? { blobs } : {}),
|
|
228
|
-
realtime: (handlers) => {
|
|
267
|
+
realtime: (handlers, clientId) => {
|
|
229
268
|
// §12.2: a local authority has no realtime channel.
|
|
230
269
|
if (realtimeConnector === undefined || local?.active()) {
|
|
231
|
-
throw
|
|
270
|
+
throw invalidRequest('no realtime connector configured');
|
|
232
271
|
}
|
|
233
|
-
return realtimeConnector(handlers);
|
|
272
|
+
return realtimeConnector(handlers, clientId);
|
|
234
273
|
},
|
|
235
274
|
...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
|
|
236
275
|
...(config.limits !== undefined ? { limits: config.limits } : {}),
|
|
@@ -240,6 +279,10 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
240
279
|
...(config.realtimePolicy !== undefined
|
|
241
280
|
? { realtimePolicy: config.realtimePolicy }
|
|
242
281
|
: {}),
|
|
282
|
+
...(config.realtimeHeartbeatMs !== undefined
|
|
283
|
+
? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
|
|
284
|
+
: {}),
|
|
285
|
+
schedule: scheduleBackground,
|
|
243
286
|
...(config.encryption !== undefined
|
|
244
287
|
? { encryption: encryptionConfigFromKeyring(config.encryption) }
|
|
245
288
|
: {}),
|
|
@@ -266,9 +309,9 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
266
309
|
// §7.4.5: surface the schema-bump reset + completion to the UI thread.
|
|
267
310
|
post({ t: 'event', event: { kind: 'upgrading', upgrading } });
|
|
268
311
|
},
|
|
269
|
-
onPresence: (scopeKey) => {
|
|
270
|
-
// §8.6: surface a presence change to the UI thread.
|
|
271
|
-
post({ t: 'event', event: { kind: 'presence', scopeKey } });
|
|
312
|
+
onPresence: (scopeKey, error) => {
|
|
313
|
+
// §8.6: surface a presence change or rejection to the UI thread.
|
|
314
|
+
post({ t: 'event', event: { kind: 'presence', scopeKey, error } });
|
|
272
315
|
},
|
|
273
316
|
});
|
|
274
317
|
started.onProgress((progress) => {
|
|
@@ -279,29 +322,12 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
279
322
|
if (!closed)
|
|
280
323
|
post({ t: 'event', event: { kind: 'change', batch } });
|
|
281
324
|
});
|
|
282
|
-
const postDiagnostics = (snapshot) => {
|
|
283
|
-
if (closed)
|
|
284
|
-
return;
|
|
285
|
-
post({
|
|
286
|
-
t: 'event',
|
|
287
|
-
event: {
|
|
288
|
-
kind: 'diagnostics',
|
|
289
|
-
snapshot: withClientDiagnosticsHost(snapshot, {
|
|
290
|
-
kind: 'worker',
|
|
291
|
-
role: 'leader',
|
|
292
|
-
connectivity: offline ? 'offline' : snapshot.host.connectivity,
|
|
293
|
-
realtime: snapshot.host.realtime,
|
|
294
|
-
}),
|
|
295
|
-
},
|
|
296
|
-
});
|
|
297
|
-
};
|
|
298
|
-
started.onDiagnostics(postDiagnostics);
|
|
299
325
|
await started.start();
|
|
300
326
|
realtimeConnector =
|
|
301
327
|
overrides.createRealtime !== undefined
|
|
302
328
|
? overrides.createRealtime(config, started.clientId, http.headers)
|
|
303
329
|
: config.endpoints.realtimeUrl !== undefined
|
|
304
|
-
? webSocketRealtimeConnector(config.endpoints.realtimeUrl
|
|
330
|
+
? webSocketRealtimeConnector(config.endpoints.realtimeUrl)
|
|
305
331
|
: undefined;
|
|
306
332
|
client = started;
|
|
307
333
|
// `start()` may discover persisted subscriptions/outbox work. Its callback
|
|
@@ -352,10 +378,7 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
352
378
|
},
|
|
353
379
|
])),
|
|
354
380
|
beginSecurityPreflight: async () => {
|
|
355
|
-
|
|
356
|
-
clearTimeout(backgroundTimer);
|
|
357
|
-
backgroundTimer = undefined;
|
|
358
|
-
backgroundDue = Number.POSITIVE_INFINITY;
|
|
381
|
+
stopBackground();
|
|
359
382
|
autoSyncScheduled = false;
|
|
360
383
|
await requireClient().beginSecurityPreflight();
|
|
361
384
|
},
|
|
@@ -393,13 +416,14 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
393
416
|
resetClientId: () => requireClient().resetClientId(),
|
|
394
417
|
localRevision: () => requireClient().localRevision,
|
|
395
418
|
diagnosticsSnapshot: (request) => {
|
|
396
|
-
const
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
}
|
|
419
|
+
const running = requireClient();
|
|
420
|
+
// The first pull makes the worker a push source: no tab has asked for
|
|
421
|
+
// diagnostics before it, so no snapshot is built per revision until then.
|
|
422
|
+
if (!pushingDiagnostics) {
|
|
423
|
+
pushingDiagnostics = true;
|
|
424
|
+
running.onDiagnostics(postDiagnostics);
|
|
425
|
+
}
|
|
426
|
+
return workerDiagnostics(running.diagnosticsSnapshot(request));
|
|
403
427
|
},
|
|
404
428
|
setHeaders: (next) => {
|
|
405
429
|
headers = next;
|
|
@@ -408,32 +432,16 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
408
432
|
offline = value;
|
|
409
433
|
requireClient().setTransportEnabled(!value);
|
|
410
434
|
if (offline) {
|
|
411
|
-
|
|
412
|
-
clearTimeout(backgroundTimer);
|
|
413
|
-
backgroundTimer = undefined;
|
|
414
|
-
backgroundDue = Number.POSITIVE_INFINITY;
|
|
435
|
+
stopBackground();
|
|
415
436
|
}
|
|
416
|
-
else if (client !== undefined) {
|
|
417
|
-
|
|
418
|
-
post({
|
|
419
|
-
t: 'event',
|
|
420
|
-
event: {
|
|
421
|
-
kind: 'diagnostics',
|
|
422
|
-
snapshot: withClientDiagnosticsHost(snapshot, {
|
|
423
|
-
kind: 'worker',
|
|
424
|
-
role: 'leader',
|
|
425
|
-
connectivity: snapshot.host.connectivity,
|
|
426
|
-
realtime: snapshot.host.realtime,
|
|
427
|
-
}),
|
|
428
|
-
},
|
|
429
|
-
});
|
|
437
|
+
else if (client !== undefined && pushingDiagnostics) {
|
|
438
|
+
postDiagnostics(client.diagnosticsSnapshot());
|
|
430
439
|
}
|
|
431
440
|
},
|
|
432
441
|
...local?.methods,
|
|
433
442
|
close: async () => {
|
|
434
443
|
closed = true;
|
|
435
|
-
|
|
436
|
-
clearTimeout(backgroundTimer);
|
|
444
|
+
cancelBackground?.();
|
|
437
445
|
await client?.close();
|
|
438
446
|
local?.close();
|
|
439
447
|
database?.close();
|
package/dist/worker-host.d.ts
CHANGED
|
@@ -23,7 +23,7 @@ import type { PromiseMethods } from './client.js';
|
|
|
23
23
|
* With `multiTab: false`, the loser is an `isLeader === false` handle whose
|
|
24
24
|
* calls reject with `client.not_leader` (the single-tab contract).
|
|
25
25
|
*/
|
|
26
|
-
import type
|
|
26
|
+
import { type PresenceErrorCode, type WakeReason } from '@syncular/core';
|
|
27
27
|
import type { BlobRef, CachedBlob } from './blob.js';
|
|
28
28
|
import type { ConflictRecord, CurrentBaseProof, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SnapshotRead, SnapshotReadRequest, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
|
|
29
29
|
import type { SqlRow, SqlValue } from './database.js';
|
|
@@ -101,6 +101,8 @@ export interface SyncClientHandleConfig {
|
|
|
101
101
|
* `WorkerInitConfig`. Absent ⇒ `optional`.
|
|
102
102
|
*/
|
|
103
103
|
readonly realtimePolicy?: RealtimePolicy;
|
|
104
|
+
/** SPEC §8.5 heartbeat interval, forwarded into `WorkerInitConfig`. */
|
|
105
|
+
readonly realtimeHeartbeatMs?: number;
|
|
104
106
|
/**
|
|
105
107
|
* RFC 0005 previous-version context, forwarded into the worker's
|
|
106
108
|
* `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
|
|
@@ -151,8 +153,9 @@ export interface SyncClientHandleConfig {
|
|
|
151
153
|
}) => void;
|
|
152
154
|
/** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
|
|
153
155
|
readonly onUpgrading?: (upgrading: boolean) => void;
|
|
154
|
-
/** §8.6: presence on a scope key changed
|
|
155
|
-
|
|
156
|
+
/** §8.6: presence on a scope key changed, or the server refused this
|
|
157
|
+
* client's publish on it (`error`, §8.6.2). */
|
|
158
|
+
readonly onPresence?: (scopeKey: string, error?: PresenceErrorCode) => void;
|
|
156
159
|
/** Atomic privacy-safe diagnostics changed. */
|
|
157
160
|
readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
|
|
158
161
|
}
|
|
@@ -190,7 +193,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
190
193
|
tabs?: TabCoordinator;
|
|
191
194
|
invalidation: InvalidationEmitter;
|
|
192
195
|
changes: ChangeEmitter;
|
|
193
|
-
presence: Set<(scopeKey: string) => void>;
|
|
196
|
+
presence: Set<(scopeKey: string, error?: PresenceErrorCode) => void>;
|
|
194
197
|
diagnostics: ClientDiagnosticsEmitter;
|
|
195
198
|
roleListeners?: Set<(role: HandleRole) => void>;
|
|
196
199
|
leadershipListeners?: Set<(state: LeadershipState) => void>;
|
|
@@ -220,7 +223,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
220
223
|
* §8.6: subscribe to presence changes — the identical surface as
|
|
221
224
|
* `SyncClient.onPresence`. Returns an unsubscribe function.
|
|
222
225
|
*/
|
|
223
|
-
onPresence(listener: (scopeKey: string) => void): () => void;
|
|
226
|
+
onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
|
|
224
227
|
/** Subscribe to role transitions (follower → leader on promotion). */
|
|
225
228
|
onRoleChange(listener: (role: HandleRole) => void): () => void;
|
|
226
229
|
onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
|
|
@@ -292,6 +295,8 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
292
295
|
readonly mediaType?: string;
|
|
293
296
|
readonly name?: string;
|
|
294
297
|
}): Promise<BlobRef>;
|
|
298
|
+
/** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
|
|
299
|
+
blobRefString(ref: BlobRef): string;
|
|
295
300
|
fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
|
|
296
301
|
/**
|
|
297
302
|
* Replace the full host auth header set. The next HTTP request uses it;
|