@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,34 +1,35 @@
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
  /** Raised when `client.query()` is handed SQL it will not run. */
27
23
  export declare class RawSqlError extends Error {
28
24
  readonly name = "RawSqlError";
29
25
  }
26
+ /** Leading whitespace, comments and empty statements. */
27
+ export declare const SQL_BLANK: RegExp;
28
+ /** Refuse a statement the raw-SQL tier does not run. */
29
+ export declare function refuseRawSql(): never;
30
30
  /**
31
- * Assert `sql` is a single read-only statement, or throw `RawSqlError`.
32
- * Called by `client.query()` before the string reaches the database.
31
+ * Prepare `sql` for the raw-SQL tier or throw `RawSqlError`. `prepare`
32
+ * compiles the first statement only and returns it, the text SQLite compiled
33
+ * for it, and whether SQLite reports it read-only with result columns.
33
34
  */
34
- export declare function assertReadOnlyQuery(sql: string): void;
35
+ export declare function prepareReadOnly<S>(sql: string, prepare: () => readonly [statement: S, first: string, reads: boolean]): S;
@@ -1,205 +1,48 @@
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
- /** Verbs a read-only query may begin with (lowercased). */
27
- const READ_ONLY_VERBS = new Set([
28
- 'select',
29
- 'with',
30
- 'explain',
31
- 'pragma',
32
- 'values',
33
- ]);
34
22
  /** Raised when `client.query()` is handed SQL it will not run. */
35
23
  export class RawSqlError extends Error {
36
24
  name = 'RawSqlError';
37
25
  }
38
- /**
39
- * Split `sql` into top-level statements at unquoted `;`, skipping over
40
- * string literals ('…'), quoted/bracketed identifiers ("…", `…`, […]) and
41
- * comments (-- …, /* … *​/) so a `;` inside any of them is not a boundary.
42
- * Returns the non-empty statements (comment/whitespace-only trailers drop).
43
- */
44
- function splitStatements(sql) {
45
- const statements = [];
46
- let start = 0;
47
- let i = 0;
48
- const n = sql.length;
49
- const pushIfNonEmpty = (end) => {
50
- const stripped = stripLeading(sql.slice(start, end));
51
- if (stripped.length > 0)
52
- statements.push(sql.slice(start, end));
53
- start = end + 1;
54
- };
55
- while (i < n) {
56
- const c = sql[i];
57
- if (c === '-' && sql[i + 1] === '-') {
58
- const nl = sql.indexOf('\n', i + 2);
59
- i = nl === -1 ? n : nl + 1;
60
- }
61
- else if (c === '/' && sql[i + 1] === '*') {
62
- const close = sql.indexOf('*/', i + 2);
63
- i = close === -1 ? n : close + 2;
64
- }
65
- else if (c === "'" || c === '"' || c === '`') {
66
- i = skipQuoted(sql, i, c);
67
- }
68
- else if (c === '[') {
69
- const close = sql.indexOf(']', i + 1);
70
- i = close === -1 ? n : close + 1;
71
- }
72
- else if (c === ';') {
73
- pushIfNonEmpty(i);
74
- i += 1;
75
- }
76
- else {
77
- i += 1;
78
- }
79
- }
80
- pushIfNonEmpty(n);
81
- return statements;
82
- }
83
- /** Advance past a quoted run opened at `open`; SQL doubles the quote to escape it. */
84
- function skipQuoted(sql, open, quote) {
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)
90
- i += 2;
91
- else
92
- return i + 1;
93
- }
94
- else {
95
- i += 1;
96
- }
97
- }
98
- return n;
99
- }
100
- /** Strip leading whitespace and comments, returning the remainder. */
101
- function stripLeading(sql) {
102
- return sql
103
- .replace(/^\s*(?:--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/|\s)+/, '')
104
- .trimStart();
105
- }
106
- function firstWords(sql) {
107
- const trimmed = sql.trim().replace(/\s+/g, ' ');
108
- return trimmed.length > 72 ? `${trimmed.slice(0, 72)}…` : trimmed;
109
- }
110
- /**
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.
116
- */
117
- function mainVerbAfterWith(sql) {
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];
132
- if (c === '-' && sql[i + 1] === '-') {
133
- const nl = sql.indexOf('\n', i + 2);
134
- i = nl === -1 ? n : nl + 1;
135
- }
136
- else if (c === '/' && sql[i + 1] === '*') {
137
- const close = sql.indexOf('*/', i + 2);
138
- i = close === -1 ? n : close + 2;
139
- }
140
- else if (c === "'" || c === '"' || c === '`') {
141
- i = skipQuoted(sql, i, c);
142
- }
143
- else if (c === '[') {
144
- const close = sql.indexOf(']', i + 1);
145
- i = close === -1 ? n : close + 1;
146
- }
147
- else if (c === '(') {
148
- depth += 1;
149
- i += 1;
150
- }
151
- else if (c === ')') {
152
- depth -= 1;
153
- i += 1;
154
- }
155
- else if (/[A-Za-z_]/.test(c)) {
156
- let j = i + 1;
157
- while (j < n && /[A-Za-z0-9_]/.test(sql[j]))
158
- j += 1;
159
- const word = sql.slice(i, j).toLowerCase();
160
- if (depth === 0) {
161
- if (!sawWith && word === 'with')
162
- sawWith = true;
163
- else if (sawWith && MAIN_VERBS.has(word))
164
- return word;
165
- }
166
- i = j;
167
- }
168
- else {
169
- i += 1;
170
- }
171
- }
172
- return undefined;
26
+ /** Leading whitespace, comments and empty statements. */
27
+ export const SQL_BLANK = /^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$))*/;
28
+ /** Refuse a statement the raw-SQL tier does not run. */
29
+ export function refuseRawSql() {
30
+ throw new RawSqlError('client.query() runs read-only statements and no PRAGMA; write through client.mutate() so the outbox records it (SPEC §7.1).');
173
31
  }
174
32
  /**
175
- * Assert `sql` is a single read-only statement, or throw `RawSqlError`.
176
- * Called by `client.query()` before the string reaches the database.
33
+ * Prepare `sql` for the raw-SQL tier or throw `RawSqlError`. `prepare`
34
+ * compiles the first statement only and returns it, the text SQLite compiled
35
+ * for it, and whether SQLite reports it read-only with result columns.
177
36
  */
178
- export function assertReadOnlyQuery(sql) {
179
- const statements = splitStatements(sql);
180
- if (statements.length === 0) {
181
- throw new RawSqlError('client.query() was given an empty statement.');
182
- }
183
- if (statements.length > 1) {
184
- throw new RawSqlError(`client.query() runs a single statement, but ${statements.length} were ` +
185
- 'given. Split them into separate query() calls. ' +
186
- `First: ${firstWords(statements[0] ?? '')}`);
37
+ export function prepareReadOnly(sql, prepare) {
38
+ if (/^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|explain\b|query\b|plan\b)*pragma\b/i.test(sql)) {
39
+ refuseRawSql();
187
40
  }
188
- const statement = stripLeading(statements[0] ?? '');
189
- const verb = statement.match(/^([a-zA-Z]+)/)?.[1]?.toLowerCase();
190
- const rejectWrite = () => {
191
- throw new RawSqlError('client.query() is read-only — this statement writes the local ' +
192
- 'database directly, which bypasses the sync outbox (SPEC §7.1). Use ' +
193
- '`client.mutate([...])` for inserts/updates/deletes. ' +
194
- `Rejected: ${firstWords(sql)}`);
195
- };
196
- if (verb === undefined || !READ_ONLY_VERBS.has(verb))
197
- rejectWrite();
198
- if (verb === 'with') {
199
- // SQLite allows `WITH … DELETE/INSERT/UPDATE`; only a SELECT/VALUES
200
- // main statement is a read.
201
- const main = mainVerbAfterWith(statement);
202
- if (main !== 'select' && main !== 'values')
203
- rejectWrite();
41
+ const [statement, first, reads] = prepare();
42
+ if (sql.slice(first.length).replace(SQL_BLANK, '') !== '') {
43
+ throw new RawSqlError('client.query() runs one statement per call.');
204
44
  }
45
+ if (!reads)
46
+ refuseRawSql();
47
+ return statement;
205
48
  }
@@ -237,6 +237,10 @@ class ObservationCache {
237
237
  for (const entry of this.#active)
238
238
  entry.reclaim?.();
239
239
  }
240
+ reread() {
241
+ for (const entry of this.#active)
242
+ entry.reread();
243
+ }
240
244
  clear() {
241
245
  for (const entry of this.#entries.values())
242
246
  entry.dispose();
@@ -409,6 +413,14 @@ class QueryEntry {
409
413
  this.#claimCoverage();
410
414
  this.#requestRead();
411
415
  }
416
+ /** A read that ran against a departed leader, or failed with it, runs on
417
+ * the leader that serves this tab now. */
418
+ reread() {
419
+ if (this.#claimError !== undefined)
420
+ this.reclaim();
421
+ else
422
+ this.#requestRead();
423
+ }
412
424
  onChange(batch) {
413
425
  if (!batchMatches(batch, this.spec))
414
426
  return;
@@ -608,10 +620,14 @@ class QueryEntry {
608
620
  }
609
621
  }
610
622
  }
623
+ /** A value read in full by `read`. Refreshes requested while a read runs
624
+ * coalesce into one more read after it, whose result alone is published. */
611
625
  class ValueEntry {
612
626
  value;
613
627
  read;
614
628
  #generation = 0;
629
+ #reading = false;
630
+ #stale = false;
615
631
  #listeners = new Set();
616
632
  constructor(value, read) {
617
633
  this.value = value;
@@ -623,14 +639,29 @@ class ValueEntry {
623
639
  return () => this.#listeners.delete(listener);
624
640
  };
625
641
  refresh = () => {
626
- const generation = ++this.#generation;
627
- void this.read().then((next) => {
628
- if (generation === this.#generation)
629
- this.set(next);
630
- });
642
+ this.#stale = true;
643
+ if (!this.#reading)
644
+ void this.#readLoop();
631
645
  };
646
+ async #readLoop() {
647
+ this.#reading = true;
648
+ try {
649
+ while (this.#stale) {
650
+ this.#stale = false;
651
+ const generation = this.#generation;
652
+ const next = await this.read();
653
+ if (generation === this.#generation && !this.#stale)
654
+ this.set(next);
655
+ }
656
+ }
657
+ finally {
658
+ this.#reading = false;
659
+ }
660
+ }
661
+ /** Discard the running read and every refresh requested before now. */
632
662
  invalidate() {
633
663
  this.#generation += 1;
664
+ this.#stale = false;
634
665
  }
635
666
  set(next) {
636
667
  this.invalidate();
@@ -698,6 +729,9 @@ class WindowEntry {
698
729
  this.#listeners.clear();
699
730
  this.reset();
700
731
  }
732
+ reread() {
733
+ this.refresh();
734
+ }
701
735
  onChange(batch) {
702
736
  if (batch.windows.some((change) => change.baseKey === this.baseKey) &&
703
737
  this.#listeners.size > 0) {
@@ -1034,12 +1068,20 @@ export class ReactiveClientStore {
1034
1068
  ...previous,
1035
1069
  leadership,
1036
1070
  });
1037
- if (previous.isLoading)
1038
- this.status.refresh();
1039
- // Window edits that failed while no leader served this tab apply now;
1040
- // an applied group compares equal and makes no call.
1041
- if (leadership.state === 'leader' || leadership.state === 'follower')
1042
- this.#reclaimWindows();
1071
+ if (leadership.state !== 'leader' && leadership.state !== 'follower') {
1072
+ if (previous.isLoading)
1073
+ this.status.refresh();
1074
+ return;
1075
+ }
1076
+ // A leader serves this tab again. Reads that failed while none did, or
1077
+ // that a handover rejected, run on it; window edits that failed apply
1078
+ // now, and an applied group compares equal and makes no call.
1079
+ this.#reclaimWindows();
1080
+ this.#queries.reread();
1081
+ this.#windows.reread();
1082
+ this.status.refresh();
1083
+ this.conflicts.refresh();
1084
+ this.outcomes.refresh();
1043
1085
  });
1044
1086
  this.status.refresh();
1045
1087
  this.conflicts.refresh();
@@ -25,7 +25,12 @@ export interface RealtimeSupervisorSnapshot {
25
25
  readonly retryDelayMs?: number;
26
26
  }
27
27
  export interface RealtimeSupervisorOptions {
28
- /** Host online/offline evidence. Unknown remains connectable and observable. */
28
+ /**
29
+ * Host online/offline evidence, the only connectivity the supervisor
30
+ * trusts: a failed round does not suspend it. Unknown remains connectable
31
+ * and observable. Each `online` report drives `syncUntilIdle`, so work a
32
+ * failed round left behind resumes without realtime.
33
+ */
29
34
  readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
30
35
  /** Browser/native foreground evidence. Background suspends a tab-owned
31
36
  * socket; with `sharedTransport` it only serves as a resume nudge. */
@@ -71,7 +76,9 @@ export declare function documentLifecycleSignal(options?: DocumentLifecycleSigna
71
76
  * Supported host policy for Syncular's explicit realtime transport. It owns
72
77
  * exactly one connect attempt, runs an explicit catch-up round before claiming
73
78
  * connected, retries transient loss with bounded exponential jitter, and
74
- * suspends across offline, background, or protected-preflight state.
79
+ * suspends across offline, background, or protected-preflight state. A host
80
+ * `online` report also drives `syncUntilIdle` when realtime is unsupported
81
+ * or disabled.
75
82
  */
76
83
  export declare class RealtimeSupervisor {
77
84
  #private;
@@ -104,7 +104,9 @@ export function documentLifecycleSignal(options = {}) {
104
104
  * Supported host policy for Syncular's explicit realtime transport. It owns
105
105
  * exactly one connect attempt, runs an explicit catch-up round before claiming
106
106
  * connected, retries transient loss with bounded exponential jitter, and
107
- * suspends across offline, background, or protected-preflight state.
107
+ * suspends across offline, background, or protected-preflight state. A host
108
+ * `online` report also drives `syncUntilIdle` when realtime is unsupported
109
+ * or disabled.
108
110
  */
109
111
  export class RealtimeSupervisor {
110
112
  #client;
@@ -124,7 +126,8 @@ export class RealtimeSupervisor {
124
126
  #transportConnected = false;
125
127
  #connecting = false;
126
128
  #realtimeSupported = true;
127
- #diagnosticConnectivity = 'unknown';
129
+ /** The client refused a connect with `sync.offline`: its transport gate is closed. */
130
+ #gateClosed = false;
128
131
  #diagnosticSecurity = 'unknown';
129
132
  #attempt = 0;
130
133
  #generation = 0;
@@ -157,7 +160,17 @@ export class RealtimeSupervisor {
157
160
  return;
158
161
  this.#started = true;
159
162
  this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) => this.#observeDiagnostics(snapshot));
160
- this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => this.#reconcileHostState());
163
+ this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => {
164
+ // §1.8: the host's connectivity signal re-arms the drive a failed
165
+ // round left behind. The drive does not wait for the socket, so a
166
+ // socket that cannot connect does not hold back an HTTP round.
167
+ if (this.#connectivity?.current() === 'online' && !this.#hostBlock()) {
168
+ void Promise.resolve()
169
+ .then(() => this.#client.syncUntilIdle())
170
+ .catch(() => undefined);
171
+ }
172
+ this.#reconcileHostState();
173
+ });
161
174
  this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() => this.#reconcileHostState());
162
175
  this.#unsubscribeProtection = this.#protection?.subscribe(() => this.#reconcileHostState());
163
176
  this.#reconcileHostState();
@@ -207,8 +220,9 @@ export class RealtimeSupervisor {
207
220
  (this.#protection !== undefined && protection !== 'active')) {
208
221
  return 'protected';
209
222
  }
210
- if (this.#diagnosticConnectivity === 'offline' ||
211
- this.#connectivity?.current() === 'offline') {
223
+ // Host evidence only: a failed round is not connectivity evidence, and
224
+ // treating it as such would hold the supervisor offline after recovery.
225
+ if (this.#gateClosed || this.#connectivity?.current() === 'offline') {
212
226
  return 'offline';
213
227
  }
214
228
  if (!this.#sharedTransport && this.#lifecycle?.current() === 'background') {
@@ -317,11 +331,15 @@ export class RealtimeSupervisor {
317
331
  }
318
332
  await this.#catchUpConnectedTransport(generation);
319
333
  }
320
- catch {
334
+ catch (error) {
321
335
  if (generation !== this.#generation) {
322
336
  this.#releaseSupersededSocket();
323
337
  return;
324
338
  }
339
+ this.#gateClosed =
340
+ error instanceof Error &&
341
+ 'code' in error &&
342
+ error.code === 'sync.offline';
325
343
  failed = true;
326
344
  this.#connected = false;
327
345
  this.#transportConnected = false;
@@ -382,7 +400,6 @@ export class RealtimeSupervisor {
382
400
  #observeDiagnostics(snapshot, initial = false) {
383
401
  if (this.#stopped)
384
402
  return;
385
- this.#diagnosticConnectivity = snapshot.host.connectivity;
386
403
  this.#diagnosticSecurity = snapshot.securityLifecycle;
387
404
  if (snapshot.host.realtime === 'unsupported' ||
388
405
  snapshot.host.realtime === 'disabled') {
@@ -406,6 +423,13 @@ export class RealtimeSupervisor {
406
423
  return;
407
424
  this.#realtimeSupported = true;
408
425
  }
426
+ if (this.#gateClosed && snapshot.host.connectivity !== 'offline') {
427
+ // A closed transport gate always reports offline, so any other report
428
+ // means the app reopened it.
429
+ this.#gateClosed = false;
430
+ this.#reconcileHostState();
431
+ return;
432
+ }
409
433
  const block = this.#hostBlock();
410
434
  if (block) {
411
435
  this.#suspend(block);
package/dist/remote.js CHANGED
@@ -4,16 +4,13 @@
4
4
  */
5
5
  import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeSparseRow, normalizeRejectionDetails, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
6
6
  import { encryptRowValues } from './encryption.js';
7
- import { ClientSyncError } from './errors.js';
7
+ import { ClientSyncError, invalidRequest } from './errors.js';
8
8
  import { compileClientSchema, recordToRowValues, normalizeRecordKeys, coerceSqlRepresentation, } from './schema.js';
9
9
  export function remoteCommand(id) {
10
10
  if (id.length === 0)
11
- throw invalid('remote command id must be non-empty');
11
+ throw invalidRequest('remote command id must be non-empty');
12
12
  return { id };
13
13
  }
14
- function invalid(message) {
15
- return new ClientSyncError('sync.invalid_request', message);
16
- }
17
14
  function operationResponse(bytes) {
18
15
  let response;
19
16
  try {
@@ -86,10 +83,10 @@ export class SyncRemoteClient {
86
83
  #logEpoch;
87
84
  constructor(config) {
88
85
  if (config.clientId.length === 0) {
89
- throw invalid('SyncRemoteClient clientId must be non-empty');
86
+ throw invalidRequest('SyncRemoteClient clientId must be non-empty');
90
87
  }
91
88
  if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
92
- throw invalid('SyncRemoteClient logEpoch must be non-empty');
89
+ throw invalidRequest('SyncRemoteClient logEpoch must be non-empty');
93
90
  }
94
91
  this.#schema =
95
92
  config.schema === undefined
@@ -108,7 +105,7 @@ export class SyncRemoteClient {
108
105
  throw new ClientSyncError('client.remote_schema_unconfigured', 'SyncRemoteClient needs a schema to prepare ordinary commits');
109
106
  }
110
107
  if (input.requestId.length === 0) {
111
- throw invalid('remote commit requestId must be non-empty');
108
+ throw invalidRequest('remote commit requestId must be non-empty');
112
109
  }
113
110
  if (input.mutations.length === 0) {
114
111
  throw new ClientSyncError('sync.empty_commit', 'a remote commit must carry at least one mutation (§6.1)');
@@ -141,8 +138,7 @@ export class SyncRemoteClient {
141
138
  })));
142
139
  const acquisitionHeader = acquisition.frames[0];
143
140
  if (acquisition.msgKind !== 'response' ||
144
- acquisitionHeader?.type !== 'RESP_HEADER' ||
145
- acquisitionHeader.logEpoch === undefined) {
141
+ acquisitionHeader?.type !== 'RESP_HEADER') {
146
142
  throw new ClientSyncError('client.invalid_host_response', 'remote epoch acquisition returned an invalid response');
147
143
  }
148
144
  logEpoch = acquisitionHeader.logEpoch;
@@ -152,11 +148,11 @@ export class SyncRemoteClient {
152
148
  for (const mutation of input.mutations) {
153
149
  const table = schema.tables.get(mutation.table);
154
150
  if (table === undefined) {
155
- throw invalid('remote commit targets an unknown table');
151
+ throw invalidRequest('remote commit targets an unknown table');
156
152
  }
157
153
  if (mutation.op === 'delete') {
158
154
  if (mutation.rowId.length === 0) {
159
- throw invalid('remote delete rowId must be non-empty');
155
+ throw invalidRequest('remote delete rowId must be non-empty');
160
156
  }
161
157
  operations.push({
162
158
  table: mutation.table,
@@ -182,9 +178,9 @@ export class SyncRemoteClient {
182
178
  ? String(rawRowId)
183
179
  : undefined;
184
180
  if (rowId === undefined) {
185
- throw invalid('remote upsert requires a non-empty primary key');
181
+ throw invalidRequest('remote upsert requires a non-empty primary key');
186
182
  }
187
- if (this.#encryption !== undefined && table.hasEncryptedColumns) {
183
+ if (table.hasEncryptedColumns) {
188
184
  values = await encryptRowValues(this.#encryption, table, rowId, values);
189
185
  }
190
186
  operations.push({
@@ -288,7 +284,7 @@ export class SyncRemoteClient {
288
284
  throw new ClientSyncError('client.remote_operations_unconfigured', 'SyncRemoteClient has no remote operation transport');
289
285
  }
290
286
  if (requestId.length === 0) {
291
- throw invalid('remote command requestId must be non-empty');
287
+ throw invalidRequest('remote command requestId must be non-empty');
292
288
  }
293
289
  const response = operationResponse(await this.#operations(encodeRemoteOperationRequest({
294
290
  revision: 1,