@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.
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
@@ -1,198 +1,61 @@
1
1
  /**
2
- * The raw-query guard. `client.query()` and the React
3
- * `useRawSql` hook are the untrusted raw-SQL tier: an app hands us a SQL
4
- * string and we run it against the local database. Two rules make that safe
5
- * to expose, enforced HERE in the core (previously they lived in the
6
- * now-removed `@syncular/kysely` read-only driver):
2
+ * The raw-query guard behind `client.query()`, `querySnapshot()` and
3
+ * `snapshotRead()`, the untrusted raw-SQL tier. Each `ClientDatabase` adapter
4
+ * prepares only the first statement and reports what SQLite knows about it:
7
5
  *
8
- * 1. READ-ONLY. Only `select / with / explain / pragma / values` are
9
- * allowed. A write (`insert/update/delete/…`) against the local mirror
10
- * bypasses the outbox (SPEC §7.1) and silently diverges from the
11
- * server — writes MUST go through `client.mutate([...])`.
12
- * 2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
13
- * multi-statement string (`SELECT 1; DROP TABLE t`), while the native
14
- * SQLite adapters prepare only the first. We unify on the strict
15
- * behaviour: exactly one statement per `query()`.
6
+ * 1. READ-ONLY. SQLite decides (`sqlite3_stmt_readonly`) and the statement
7
+ * returns columns, which refuses `BEGIN`, `ATTACH` and the other
8
+ * read-only statements that change the connection. A write against the
9
+ * local mirror bypasses the outbox (SPEC §7.1); writes go through
10
+ * `client.mutate([...])`.
11
+ * 2. NO PRAGMA, refused before SQLite compiles anything: SQLite applies a
12
+ * flag pragma such as `query_only` while it compiles the statement, even
13
+ * under `EXPLAIN`. Read a pragma through its table-valued function
14
+ * (`SELECT * FROM pragma_table_info('tasks')`).
15
+ * 3. ONE STATEMENT. Anything but whitespace, comments and semicolons after
16
+ * the first statement is refused, because sqlite-wasm's `exec` runs
17
+ * every statement in the string. The tail is never compiled.
16
18
  *
17
- * The guard only fronts the PUBLIC `client.query()` — engine-internal reads
18
- * call the `ClientDatabase` directly and are trusted, so they are never
19
- * routed through here.
20
- *
21
- * RFC 0005 previously added a third rule here, denying reads of its container
22
- * table by root page. That table now lives in its own database file and is not
23
- * on the connection `query()` uses, so there is nothing left to guard and the
24
- * rule was removed with its EXPLAIN plumbing.
19
+ * Engine-internal reads call the `ClientDatabase` directly and never route
20
+ * here.
25
21
  */
26
22
 
27
- /** Verbs a read-only query may begin with (lowercased). */
28
- const READ_ONLY_VERBS = new Set([
29
- 'select',
30
- 'with',
31
- 'explain',
32
- 'pragma',
33
- 'values',
34
- ]);
35
-
36
23
  /** Raised when `client.query()` is handed SQL it will not run. */
37
24
  export class RawSqlError extends Error {
38
25
  override readonly name = 'RawSqlError';
39
26
  }
40
27
 
41
- /**
42
- * Split `sql` into top-level statements at unquoted `;`, skipping over
43
- * string literals ('…'), quoted/bracketed identifiers ("…", `…`, […]) and
44
- * comments (-- …, /* … *​/) so a `;` inside any of them is not a boundary.
45
- * Returns the non-empty statements (comment/whitespace-only trailers drop).
46
- */
47
- function splitStatements(sql: string): string[] {
48
- const statements: string[] = [];
49
- let start = 0;
50
- let i = 0;
51
- const n = sql.length;
52
-
53
- const pushIfNonEmpty = (end: number) => {
54
- const stripped = stripLeading(sql.slice(start, end));
55
- if (stripped.length > 0) statements.push(sql.slice(start, end));
56
- start = end + 1;
57
- };
28
+ /** Leading whitespace, comments and empty statements. */
29
+ export const SQL_BLANK =
30
+ /^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$))*/;
58
31
 
59
- while (i < n) {
60
- const c = sql[i];
61
- if (c === '-' && sql[i + 1] === '-') {
62
- const nl = sql.indexOf('\n', i + 2);
63
- i = nl === -1 ? n : nl + 1;
64
- } else if (c === '/' && sql[i + 1] === '*') {
65
- const close = sql.indexOf('*/', i + 2);
66
- i = close === -1 ? n : close + 2;
67
- } else if (c === "'" || c === '"' || c === '`') {
68
- i = skipQuoted(sql, i, c as "'" | '"' | '`');
69
- } else if (c === '[') {
70
- const close = sql.indexOf(']', i + 1);
71
- i = close === -1 ? n : close + 1;
72
- } else if (c === ';') {
73
- pushIfNonEmpty(i);
74
- i += 1;
75
- } else {
76
- i += 1;
77
- }
78
- }
79
- pushIfNonEmpty(n);
80
- return statements;
81
- }
82
-
83
- /** Advance past a quoted run opened at `open`; SQL doubles the quote to escape it. */
84
- function skipQuoted(sql: string, open: number, quote: "'" | '"' | '`'): number {
85
- let i = open + 1;
86
- const n = sql.length;
87
- while (i < n) {
88
- if (sql[i] === quote) {
89
- if (sql[i + 1] === quote) i += 2;
90
- else return i + 1;
91
- } else {
92
- i += 1;
93
- }
94
- }
95
- return n;
96
- }
97
-
98
- /** Strip leading whitespace and comments, returning the remainder. */
99
- function stripLeading(sql: string): string {
100
- return sql
101
- .replace(/^\s*(?:--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/|\s)+/, '')
102
- .trimStart();
103
- }
104
-
105
- function firstWords(sql: string): string {
106
- const trimmed = sql.trim().replace(/\s+/g, ' ');
107
- return trimmed.length > 72 ? `${trimmed.slice(0, 72)}…` : trimmed;
32
+ /** Refuse a statement the raw-SQL tier does not run. */
33
+ export function refuseRawSql(): never {
34
+ throw new RawSqlError(
35
+ 'client.query() runs read-only statements and no PRAGMA; write through client.mutate() so the outbox records it (SPEC §7.1).',
36
+ );
108
37
  }
109
38
 
110
39
  /**
111
- * The main verb of a `WITH …` statement: SQLite allows a with-clause before
112
- * SELECT **and before INSERT/UPDATE/DELETE**, so `WITH t AS (…) DELETE …`
113
- * must not slip through the verb allowlist. CTE bodies live inside
114
- * parentheses, and a bare keyword cannot be a CTE name, so the first
115
- * paren-depth-0 keyword after the clause IS the main verb.
40
+ * Prepare `sql` for the raw-SQL tier or throw `RawSqlError`. `prepare`
41
+ * compiles the first statement only and returns it, the text SQLite compiled
42
+ * for it, and whether SQLite reports it read-only with result columns.
116
43
  */
117
- function mainVerbAfterWith(sql: string): string | undefined {
118
- const MAIN_VERBS = new Set([
119
- 'select',
120
- 'values',
121
- 'insert',
122
- 'update',
123
- 'delete',
124
- 'replace',
125
- ]);
126
- let depth = 0;
127
- let i = 0;
128
- const n = sql.length;
129
- let sawWith = false;
130
- while (i < n) {
131
- const c = sql[i] as string;
132
- if (c === '-' && sql[i + 1] === '-') {
133
- const nl = sql.indexOf('\n', i + 2);
134
- i = nl === -1 ? n : nl + 1;
135
- } else if (c === '/' && sql[i + 1] === '*') {
136
- const close = sql.indexOf('*/', i + 2);
137
- i = close === -1 ? n : close + 2;
138
- } else if (c === "'" || c === '"' || c === '`') {
139
- i = skipQuoted(sql, i, c as "'" | '"' | '`');
140
- } else if (c === '[') {
141
- const close = sql.indexOf(']', i + 1);
142
- i = close === -1 ? n : close + 1;
143
- } else if (c === '(') {
144
- depth += 1;
145
- i += 1;
146
- } else if (c === ')') {
147
- depth -= 1;
148
- i += 1;
149
- } else if (/[A-Za-z_]/.test(c)) {
150
- let j = i + 1;
151
- while (j < n && /[A-Za-z0-9_]/.test(sql[j] as string)) j += 1;
152
- const word = sql.slice(i, j).toLowerCase();
153
- if (depth === 0) {
154
- if (!sawWith && word === 'with') sawWith = true;
155
- else if (sawWith && MAIN_VERBS.has(word)) return word;
156
- }
157
- i = j;
158
- } else {
159
- i += 1;
160
- }
161
- }
162
- return undefined;
163
- }
164
-
165
- /**
166
- * Assert `sql` is a single read-only statement, or throw `RawSqlError`.
167
- * Called by `client.query()` before the string reaches the database.
168
- */
169
- export function assertReadOnlyQuery(sql: string): void {
170
- const statements = splitStatements(sql);
171
- if (statements.length === 0) {
172
- throw new RawSqlError('client.query() was given an empty statement.');
173
- }
174
- if (statements.length > 1) {
175
- throw new RawSqlError(
176
- `client.query() runs a single statement, but ${statements.length} were ` +
177
- 'given. Split them into separate query() calls. ' +
178
- `First: ${firstWords(statements[0] ?? '')}`,
179
- );
44
+ export function prepareReadOnly<S>(
45
+ sql: string,
46
+ prepare: () => readonly [statement: S, first: string, reads: boolean],
47
+ ): S {
48
+ if (
49
+ /^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|explain\b|query\b|plan\b)*pragma\b/i.test(
50
+ sql,
51
+ )
52
+ ) {
53
+ refuseRawSql();
180
54
  }
181
- const statement = stripLeading(statements[0] ?? '');
182
- const verb = statement.match(/^([a-zA-Z]+)/)?.[1]?.toLowerCase();
183
- const rejectWrite = (): never => {
184
- throw new RawSqlError(
185
- 'client.query() is read-only — this statement writes the local ' +
186
- 'database directly, which bypasses the sync outbox (SPEC §7.1). Use ' +
187
- '`client.mutate([...])` for inserts/updates/deletes. ' +
188
- `Rejected: ${firstWords(sql)}`,
189
- );
190
- };
191
- if (verb === undefined || !READ_ONLY_VERBS.has(verb)) rejectWrite();
192
- if (verb === 'with') {
193
- // SQLite allows `WITH … DELETE/INSERT/UPDATE`; only a SELECT/VALUES
194
- // main statement is a read.
195
- const main = mainVerbAfterWith(statement);
196
- if (main !== 'select' && main !== 'values') rejectWrite();
55
+ const [statement, first, reads] = prepare();
56
+ if (sql.slice(first.length).replace(SQL_BLANK, '') !== '') {
57
+ throw new RawSqlError('client.query() runs one statement per call.');
197
58
  }
59
+ if (!reads) refuseRawSql();
60
+ return statement;
198
61
  }
@@ -315,8 +315,10 @@ function reconcileRows<Row>(
315
315
 
316
316
  interface CachedObservation {
317
317
  onChange(batch: ClientChangeBatch): void;
318
- /** A leader serves this tab again (it leads or follows a bound leader). */
318
+ /** Claim again after a rejected claim. */
319
319
  reclaim?(): void;
320
+ /** A leader serves this tab again (it leads or follows a bound leader). */
321
+ reread(): void;
320
322
  reset(): void;
321
323
  dispose(): void;
322
324
  }
@@ -361,6 +363,9 @@ class ObservationCache {
361
363
  reclaim(): void {
362
364
  for (const entry of this.#active) entry.reclaim?.();
363
365
  }
366
+ reread(): void {
367
+ for (const entry of this.#active) entry.reread();
368
+ }
364
369
  clear(): void {
365
370
  for (const entry of this.#entries.values()) entry.dispose();
366
371
  this.#entries.clear();
@@ -549,6 +554,13 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
549
554
  this.#requestRead();
550
555
  }
551
556
 
557
+ /** A read that ran against a departed leader, or failed with it, runs on
558
+ * the leader that serves this tab now. */
559
+ reread(): void {
560
+ if (this.#claimError !== undefined) this.reclaim();
561
+ else this.#requestRead();
562
+ }
563
+
552
564
  onChange(batch: ClientChangeBatch): void {
553
565
  if (!batchMatches(batch, this.spec)) return;
554
566
  if (batch.revision > this.#desiredRevision) {
@@ -759,8 +771,12 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
759
771
  }
760
772
  }
761
773
 
774
+ /** A value read in full by `read`. Refreshes requested while a read runs
775
+ * coalesce into one more read after it, whose result alone is published. */
762
776
  class ValueEntry<T> implements ExternalStoreEntry<T> {
763
777
  #generation = 0;
778
+ #reading = false;
779
+ #stale = false;
764
780
  readonly #listeners = new Set<() => void>();
765
781
  constructor(
766
782
  private value: T,
@@ -772,13 +788,26 @@ class ValueEntry<T> implements ExternalStoreEntry<T> {
772
788
  return () => this.#listeners.delete(listener);
773
789
  };
774
790
  refresh = (): void => {
775
- const generation = ++this.#generation;
776
- void this.read().then((next) => {
777
- if (generation === this.#generation) this.set(next);
778
- });
791
+ this.#stale = true;
792
+ if (!this.#reading) void this.#readLoop();
779
793
  };
794
+ async #readLoop(): Promise<void> {
795
+ this.#reading = true;
796
+ try {
797
+ while (this.#stale) {
798
+ this.#stale = false;
799
+ const generation = this.#generation;
800
+ const next = await this.read();
801
+ if (generation === this.#generation && !this.#stale) this.set(next);
802
+ }
803
+ } finally {
804
+ this.#reading = false;
805
+ }
806
+ }
807
+ /** Discard the running read and every refresh requested before now. */
780
808
  invalidate(): void {
781
809
  this.#generation += 1;
810
+ this.#stale = false;
782
811
  }
783
812
  set(next: T): void {
784
813
  this.invalidate();
@@ -855,6 +884,9 @@ class WindowEntry implements ExternalStoreEntry<WindowState> {
855
884
  this.#listeners.clear();
856
885
  this.reset();
857
886
  }
887
+ reread(): void {
888
+ this.refresh();
889
+ }
858
890
  onChange(batch: ClientChangeBatch): void {
859
891
  if (
860
892
  batch.windows.some((change) => change.baseKey === this.baseKey) &&
@@ -1227,11 +1259,19 @@ export class ReactiveClientStore {
1227
1259
  ...previous,
1228
1260
  leadership,
1229
1261
  });
1230
- if (previous.isLoading) this.status.refresh();
1231
- // Window edits that failed while no leader served this tab apply now;
1232
- // an applied group compares equal and makes no call.
1233
- if (leadership.state === 'leader' || leadership.state === 'follower')
1234
- this.#reclaimWindows();
1262
+ if (leadership.state !== 'leader' && leadership.state !== 'follower') {
1263
+ if (previous.isLoading) this.status.refresh();
1264
+ return;
1265
+ }
1266
+ // A leader serves this tab again. Reads that failed while none did, or
1267
+ // that a handover rejected, run on it; window edits that failed apply
1268
+ // now, and an applied group compares equal and makes no call.
1269
+ this.#reclaimWindows();
1270
+ this.#queries.reread();
1271
+ this.#windows.reread();
1272
+ this.status.refresh();
1273
+ this.conflicts.refresh();
1274
+ this.outcomes.refresh();
1235
1275
  });
1236
1276
  this.status.refresh();
1237
1277
  this.conflicts.refresh();
@@ -48,7 +48,12 @@ export interface RealtimeSupervisorSnapshot {
48
48
  }
49
49
 
50
50
  export interface RealtimeSupervisorOptions {
51
- /** Host online/offline evidence. Unknown remains connectable and observable. */
51
+ /**
52
+ * Host online/offline evidence, the only connectivity the supervisor
53
+ * trusts: a failed round does not suspend it. Unknown remains connectable
54
+ * and observable. Each `online` report drives `syncUntilIdle`, so work a
55
+ * failed round left behind resumes without realtime.
56
+ */
52
57
  readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
53
58
  /** Browser/native foreground evidence. Background suspends a tab-owned
54
59
  * socket; with `sharedTransport` it only serves as a resume nudge. */
@@ -209,7 +214,9 @@ export function documentLifecycleSignal(
209
214
  * Supported host policy for Syncular's explicit realtime transport. It owns
210
215
  * exactly one connect attempt, runs an explicit catch-up round before claiming
211
216
  * connected, retries transient loss with bounded exponential jitter, and
212
- * suspends across offline, background, or protected-preflight state.
217
+ * suspends across offline, background, or protected-preflight state. A host
218
+ * `online` report also drives `syncUntilIdle` when realtime is unsupported
219
+ * or disabled.
213
220
  */
214
221
  export class RealtimeSupervisor {
215
222
  readonly #client: RealtimeSupervisorClient;
@@ -230,7 +237,8 @@ export class RealtimeSupervisor {
230
237
  #transportConnected = false;
231
238
  #connecting = false;
232
239
  #realtimeSupported = true;
233
- #diagnosticConnectivity: ClientDiagnosticsConnectivity = 'unknown';
240
+ /** The client refused a connect with `sync.offline`: its transport gate is closed. */
241
+ #gateClosed = false;
234
242
  #diagnosticSecurity: RealtimeSupervisorProtectionState = 'unknown';
235
243
  #attempt = 0;
236
244
  #generation = 0;
@@ -277,9 +285,17 @@ export class RealtimeSupervisor {
277
285
  this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) =>
278
286
  this.#observeDiagnostics(snapshot),
279
287
  );
280
- this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() =>
281
- this.#reconcileHostState(),
282
- );
288
+ this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => {
289
+ // §1.8: the host's connectivity signal re-arms the drive a failed
290
+ // round left behind. The drive does not wait for the socket, so a
291
+ // socket that cannot connect does not hold back an HTTP round.
292
+ if (this.#connectivity?.current() === 'online' && !this.#hostBlock()) {
293
+ void Promise.resolve()
294
+ .then(() => this.#client.syncUntilIdle())
295
+ .catch(() => undefined);
296
+ }
297
+ this.#reconcileHostState();
298
+ });
283
299
  this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() =>
284
300
  this.#reconcileHostState(),
285
301
  );
@@ -334,10 +350,9 @@ export class RealtimeSupervisor {
334
350
  ) {
335
351
  return 'protected';
336
352
  }
337
- if (
338
- this.#diagnosticConnectivity === 'offline' ||
339
- this.#connectivity?.current() === 'offline'
340
- ) {
353
+ // Host evidence only: a failed round is not connectivity evidence, and
354
+ // treating it as such would hold the supervisor offline after recovery.
355
+ if (this.#gateClosed || this.#connectivity?.current() === 'offline') {
341
356
  return 'offline';
342
357
  }
343
358
  if (!this.#sharedTransport && this.#lifecycle?.current() === 'background') {
@@ -464,11 +479,15 @@ export class RealtimeSupervisor {
464
479
  return;
465
480
  }
466
481
  await this.#catchUpConnectedTransport(generation);
467
- } catch {
482
+ } catch (error) {
468
483
  if (generation !== this.#generation) {
469
484
  this.#releaseSupersededSocket();
470
485
  return;
471
486
  }
487
+ this.#gateClosed =
488
+ error instanceof Error &&
489
+ 'code' in error &&
490
+ error.code === 'sync.offline';
472
491
  failed = true;
473
492
  this.#connected = false;
474
493
  this.#transportConnected = false;
@@ -527,7 +546,6 @@ export class RealtimeSupervisor {
527
546
  initial = false,
528
547
  ): void {
529
548
  if (this.#stopped) return;
530
- this.#diagnosticConnectivity = snapshot.host.connectivity;
531
549
  this.#diagnosticSecurity = snapshot.securityLifecycle;
532
550
  if (
533
551
  snapshot.host.realtime === 'unsupported' ||
@@ -552,6 +570,13 @@ export class RealtimeSupervisor {
552
570
  if (snapshot.host.realtime !== 'connected') return;
553
571
  this.#realtimeSupported = true;
554
572
  }
573
+ if (this.#gateClosed && snapshot.host.connectivity !== 'offline') {
574
+ // A closed transport gate always reports offline, so any other report
575
+ // means the app reopened it.
576
+ this.#gateClosed = false;
577
+ this.#reconcileHostState();
578
+ return;
579
+ }
555
580
  const block = this.#hostBlock();
556
581
  if (block) {
557
582
  this.#suspend(block);
package/src/remote.ts CHANGED
@@ -22,7 +22,7 @@ import {
22
22
  import type { MutationInput } from './client';
23
23
  import type { EncryptionConfig } from './encryption';
24
24
  import { encryptRowValues } from './encryption';
25
- import { ClientSyncError } from './errors';
25
+ import { ClientSyncError, invalidRequest } from './errors';
26
26
  import {
27
27
  compileClientSchema,
28
28
  type ClientSchema,
@@ -97,7 +97,8 @@ export interface RemoteCommandDescriptor<Input = undefined> {
97
97
  export function remoteCommand<Input = undefined>(
98
98
  id: string,
99
99
  ): RemoteCommandDescriptor<Input> {
100
- if (id.length === 0) throw invalid('remote command id must be non-empty');
100
+ if (id.length === 0)
101
+ throw invalidRequest('remote command id must be non-empty');
101
102
  return { id };
102
103
  }
103
104
 
@@ -108,10 +109,6 @@ export interface RemoteCommandResult {
108
109
  readonly results: readonly unknown[];
109
110
  }
110
111
 
111
- function invalid(message: string): ClientSyncError {
112
- return new ClientSyncError('sync.invalid_request', message);
113
- }
114
-
115
112
  function operationResponse(bytes: Uint8Array): RemoteOperationResponse {
116
113
  let response: RemoteOperationResponse;
117
114
  try {
@@ -239,10 +236,10 @@ export class SyncRemoteClient {
239
236
 
240
237
  constructor(config: SyncRemoteClientConfig) {
241
238
  if (config.clientId.length === 0) {
242
- throw invalid('SyncRemoteClient clientId must be non-empty');
239
+ throw invalidRequest('SyncRemoteClient clientId must be non-empty');
243
240
  }
244
241
  if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
245
- throw invalid('SyncRemoteClient logEpoch must be non-empty');
242
+ throw invalidRequest('SyncRemoteClient logEpoch must be non-empty');
246
243
  }
247
244
  this.#schema =
248
245
  config.schema === undefined
@@ -265,7 +262,7 @@ export class SyncRemoteClient {
265
262
  );
266
263
  }
267
264
  if (input.requestId.length === 0) {
268
- throw invalid('remote commit requestId must be non-empty');
265
+ throw invalidRequest('remote commit requestId must be non-empty');
269
266
  }
270
267
  if (input.mutations.length === 0) {
271
268
  throw new ClientSyncError(
@@ -309,8 +306,7 @@ export class SyncRemoteClient {
309
306
  const acquisitionHeader = acquisition.frames[0];
310
307
  if (
311
308
  acquisition.msgKind !== 'response' ||
312
- acquisitionHeader?.type !== 'RESP_HEADER' ||
313
- acquisitionHeader.logEpoch === undefined
309
+ acquisitionHeader?.type !== 'RESP_HEADER'
314
310
  ) {
315
311
  throw new ClientSyncError(
316
312
  'client.invalid_host_response',
@@ -324,11 +320,11 @@ export class SyncRemoteClient {
324
320
  for (const mutation of input.mutations) {
325
321
  const table = schema.tables.get(mutation.table);
326
322
  if (table === undefined) {
327
- throw invalid('remote commit targets an unknown table');
323
+ throw invalidRequest('remote commit targets an unknown table');
328
324
  }
329
325
  if (mutation.op === 'delete') {
330
326
  if (mutation.rowId.length === 0) {
331
- throw invalid('remote delete rowId must be non-empty');
327
+ throw invalidRequest('remote delete rowId must be non-empty');
332
328
  }
333
329
  operations.push({
334
330
  table: mutation.table,
@@ -361,9 +357,9 @@ export class SyncRemoteClient {
361
357
  ? String(rawRowId)
362
358
  : undefined;
363
359
  if (rowId === undefined) {
364
- throw invalid('remote upsert requires a non-empty primary key');
360
+ throw invalidRequest('remote upsert requires a non-empty primary key');
365
361
  }
366
- if (this.#encryption !== undefined && table.hasEncryptedColumns) {
362
+ if (table.hasEncryptedColumns) {
367
363
  values = await encryptRowValues(this.#encryption, table, rowId, values);
368
364
  }
369
365
  operations.push({
@@ -510,7 +506,7 @@ export class SyncRemoteClient {
510
506
  );
511
507
  }
512
508
  if (requestId.length === 0) {
513
- throw invalid('remote command requestId must be non-empty');
509
+ throw invalidRequest('remote command requestId must be non-empty');
514
510
  }
515
511
  const response = operationResponse(
516
512
  await this.#operations(
package/src/schema.ts CHANGED
@@ -166,18 +166,19 @@ export function compileClientSchema(
166
166
  const scopePrefixByVariable = new Map<string, string>();
167
167
  for (const spec of table.scopes) {
168
168
  const pattern = typeof spec === 'string' ? spec : spec.pattern;
169
- const match = PATTERN_RE.exec(pattern);
170
- if (match === null || match[1] === undefined || match[2] === undefined) {
169
+ const [, prefix, variable] = PATTERN_RE.exec(pattern) ?? [];
170
+ if (!prefix || !variable) {
171
171
  invalidSchema(
172
172
  `${tableLabel}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`,
173
173
  );
174
174
  }
175
- const prefix = match[1];
176
- const variable = match[2];
177
175
  const column = typeof spec === 'string' ? variable : spec.column;
178
- if (!columnIndex.has(column)) {
176
+ // §3.1: a scope value is an authorization key; only these two types
177
+ // render identically in every implementation.
178
+ const type = table.columns[columnIndex.get(column) ?? -1]?.type;
179
+ if (type !== 'string' && type !== 'integer') {
179
180
  invalidSchema(
180
- `${tableLabel}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`,
181
+ `${tableLabel}: scope column ${JSON.stringify(column)} must be string or integer (§3.1)`,
181
182
  );
182
183
  }
183
184
  const existing = scopeColumnByVariable.get(variable);
@@ -599,12 +600,18 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
599
600
  OUTBOX_IMAGES,
600
601
  '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)',
601
602
  );
602
- if (
603
- !db
604
- .query(`PRAGMA table_info(${OUTBOX_IMAGES})`)
605
- .some((row) => row.name === 'delivery_seq')
606
- )
607
- db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN delivery_seq INTEGER`);
603
+ const imageColumns = db.query(`PRAGMA table_info(${OUTBOX_IMAGES})`);
604
+ for (const column of ['delivery_seq INTEGER', 'tbl TEXT', 'row_id TEXT'])
605
+ if (!imageColumns.some((row) => row.name === column.split(' ')[0]))
606
+ db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN ${column}`);
607
+ // Images written before the row key existed take it from their operation.
608
+ if (!imageColumns.some((row) => row.name === 'row_id'))
609
+ db.exec(
610
+ `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)`,
611
+ );
612
+ db.exec(
613
+ `CREATE INDEX IF NOT EXISTS ${OUTBOX_IMAGES}_row ON ${OUTBOX_IMAGES}(tbl,row_id)`,
614
+ );
608
615
  createTable(
609
616
  OUTCOMES_TABLE,
610
617
  "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",
@@ -45,6 +45,8 @@ export function installSyncScheduler(
45
45
  let backgroundReady = false;
46
46
  let backgroundDue = Number.POSITIVE_INFINITY;
47
47
  let cancelBackground: (() => void) | undefined;
48
+ // §7.6 backoff for drives that end without a client retry intent.
49
+ let retryDelayMs = 250;
48
50
 
49
51
  const report = (error: unknown): void => {
50
52
  if (options.onError !== undefined) {
@@ -88,6 +90,7 @@ export function installSyncScheduler(
88
90
  void client
89
91
  .syncUntilIdle(options.maxRounds)
90
92
  .then((result) => {
93
+ retryDelayMs = 250;
91
94
  if (
92
95
  result !== null &&
93
96
  typeof result === 'object' &&
@@ -98,7 +101,34 @@ export function installSyncScheduler(
98
101
  }
99
102
  })
100
103
  .catch((error: unknown) => {
101
- if (!stopped) report(error);
104
+ if (stopped) return;
105
+ report(error);
106
+ // §7.7: a retryable drive rejection owes another drive. A retryable
107
+ // round failure already handed this loop its background intent; the
108
+ // drive deadline did not. An unreachable endpoint waits for the
109
+ // host's connectivity resume (§1.8).
110
+ const details =
111
+ error instanceof Error && 'details' in error
112
+ ? error.details
113
+ : undefined;
114
+ const causeKind =
115
+ typeof details === 'object' &&
116
+ details !== null &&
117
+ 'causeKind' in details
118
+ ? details.causeKind
119
+ : undefined;
120
+ if (
121
+ error instanceof Error &&
122
+ 'retryable' in error &&
123
+ error.retryable === true &&
124
+ causeKind !== 'network' &&
125
+ causeKind !== 'connect' &&
126
+ cancelBackground === undefined &&
127
+ !immediatePending
128
+ ) {
129
+ consume({ kind: 'background', delayMs: retryDelayMs });
130
+ retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
131
+ }
102
132
  })
103
133
  .finally(() => {
104
134
  running = false;