@syncular/client 0.57.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.
Files changed (82) hide show
  1. package/README.md +7 -7
  2. package/dist/apply.d.ts +20 -11
  3. package/dist/apply.js +67 -45
  4. package/dist/blob.d.ts +17 -9
  5. package/dist/blob.js +5 -6
  6. package/dist/bun-database.d.ts +1 -0
  7. package/dist/bun-database.js +28 -0
  8. package/dist/client.d.ts +27 -10
  9. package/dist/client.js +357 -190
  10. package/dist/database.d.ts +5 -0
  11. package/dist/encryption.d.ts +2 -2
  12. package/dist/encryption.js +8 -2
  13. package/dist/errors.d.ts +2 -0
  14. package/dist/errors.js +4 -0
  15. package/dist/failed-overlay.d.ts +0 -1
  16. package/dist/failed-overlay.js +3 -6
  17. package/dist/http.d.ts +4 -1
  18. package/dist/http.js +61 -39
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/invalidation.d.ts +11 -10
  22. package/dist/invalidation.js +15 -26
  23. package/dist/local-purge.js +9 -12
  24. package/dist/local-rebootstrap.js +2 -2
  25. package/dist/multi-tab.d.ts +89 -1
  26. package/dist/multi-tab.js +70 -31
  27. package/dist/native-bridge.d.ts +235 -0
  28. package/dist/native-bridge.js +789 -0
  29. package/dist/node-database.d.ts +1 -0
  30. package/dist/node-database.js +29 -0
  31. package/dist/outbox.d.ts +9 -12
  32. package/dist/outbox.js +19 -36
  33. package/dist/outcomes.js +3 -3
  34. package/dist/previous-version.js +96 -114
  35. package/dist/query-guard.d.ts +25 -24
  36. package/dist/query-guard.js +34 -191
  37. package/dist/reactive-store.js +53 -11
  38. package/dist/realtime-supervisor.d.ts +9 -2
  39. package/dist/realtime-supervisor.js +31 -7
  40. package/dist/remote.js +11 -15
  41. package/dist/schema.js +15 -10
  42. package/dist/sync-scheduler.js +28 -2
  43. package/dist/transport.d.ts +19 -4
  44. package/dist/wasm-database.js +58 -21
  45. package/dist/worker-core.d.ts +5 -0
  46. package/dist/worker-core.js +80 -72
  47. package/dist/worker-host.d.ts +10 -5
  48. package/dist/worker-host.js +64 -7
  49. package/dist/worker-local-authority.js +2 -2
  50. package/dist/worker-protocol.d.ts +6 -2
  51. package/package.json +11 -3
  52. package/src/apply.ts +91 -55
  53. package/src/blob.ts +27 -15
  54. package/src/bun-database.ts +29 -0
  55. package/src/client.ts +477 -261
  56. package/src/database.ts +5 -0
  57. package/src/encryption.ts +10 -5
  58. package/src/errors.ts +8 -0
  59. package/src/failed-overlay.ts +3 -7
  60. package/src/http.ts +90 -79
  61. package/src/index.ts +1 -1
  62. package/src/invalidation.ts +17 -32
  63. package/src/local-purge.ts +11 -13
  64. package/src/local-rebootstrap.ts +2 -3
  65. package/src/multi-tab.ts +88 -30
  66. package/src/native-bridge.ts +1189 -0
  67. package/src/node-database.ts +32 -0
  68. package/src/outbox.ts +19 -41
  69. package/src/outcomes.ts +3 -5
  70. package/src/previous-version.ts +103 -114
  71. package/src/query-guard.ts +43 -180
  72. package/src/reactive-store.ts +50 -10
  73. package/src/realtime-supervisor.ts +37 -12
  74. package/src/remote.ts +12 -16
  75. package/src/schema.ts +19 -12
  76. package/src/sync-scheduler.ts +31 -1
  77. package/src/transport.ts +21 -2
  78. package/src/wasm-database.ts +76 -27
  79. package/src/worker-core.ts +94 -74
  80. package/src/worker-host.ts +63 -16
  81. package/src/worker-local-authority.ts +2 -5
  82. 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 match = PATTERN_RE.exec(pattern);
69
- if (match === null || match[1] === undefined || match[2] === undefined) {
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
- if (!columnIndex.has(column)) {
76
- invalidSchema(`${tableLabel}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`);
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
- if (!db
410
- .query(`PRAGMA table_info(${OUTBOX_IMAGES})`)
411
- .some((row) => row.name === 'delivery_seq'))
412
- db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN delivery_seq INTEGER`);
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.
@@ -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 (!stopped)
68
- report(error);
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;
@@ -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
- /** One combined push+pull round trip: SSP2 request bytes → response bytes. */
8
- export type SyncTransport = (request: Uint8Array) => Promise<Uint8Array>;
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) => Promise<Uint8Array>;
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) => Promise<RealtimeSocket> | RealtimeSocket;
69
+ export type RealtimeConnector = (handlers: RealtimeHandlers,
70
+ /** The client's id; the client passes it on every connect. */
71
+ clientId?: string) => Promise<RealtimeSocket> | RealtimeSocket;
@@ -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.#assertOwned();
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
- const resultRows = [];
79
- this.#db.exec({
80
- sql,
81
- ...(params.length > 0 ? { bind: coerceParams(params) } : {}),
82
- rowMode: 'object',
83
- resultRows,
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 resultRows;
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?.siblings.add(db);
146
+ const database = new WasmClientDatabase(db, this.#sqlite3, undefined, this.#fence);
147
+ this.#fence?.siblings.add(database);
112
148
  return {
113
- database: new WasmClientDatabase(db, this.#sqlite3, undefined, this.#fence),
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.
@@ -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
  /**
@@ -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 backgroundTimer;
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 (!closed) {
102
- post({
103
- t: 'event',
104
- event: { kind: 'synced', error: toErrorShape(error) },
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 (backgroundTimer !== undefined && due >= backgroundDue)
166
+ if (cancelBackground !== undefined && due >= backgroundDue)
123
167
  return;
124
- if (backgroundTimer !== undefined)
125
- clearTimeout(backgroundTimer);
168
+ cancelBackground?.();
126
169
  backgroundDue = due;
127
- backgroundTimer = setTimeout(() => {
128
- backgroundTimer = undefined;
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
- if (backgroundTimer !== undefined) {
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 new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
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.replace('{clientId}', encodeURIComponent(started.clientId)))
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
- if (backgroundTimer !== undefined)
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 snapshot = requireClient().diagnosticsSnapshot(request);
397
- return withClientDiagnosticsHost(snapshot, {
398
- kind: 'worker',
399
- role: 'leader',
400
- connectivity: offline ? 'offline' : snapshot.host.connectivity,
401
- realtime: snapshot.host.realtime,
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
- if (backgroundTimer !== undefined)
412
- clearTimeout(backgroundTimer);
413
- backgroundTimer = undefined;
414
- backgroundDue = Number.POSITIVE_INFINITY;
435
+ stopBackground();
415
436
  }
416
- else if (client !== undefined) {
417
- const snapshot = client.diagnosticsSnapshot();
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
- if (backgroundTimer !== undefined)
436
- clearTimeout(backgroundTimer);
444
+ cancelBackground?.();
437
445
  await client?.close();
438
446
  local?.close();
439
447
  database?.close();
@@ -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 { WakeReason } from '@syncular/core';
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
- readonly onPresence?: (scopeKey: string) => void;
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;