@syncular/client 0.58.0 → 0.59.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -7
- package/dist/apply.d.ts +20 -11
- package/dist/apply.js +67 -45
- package/dist/blob.d.ts +17 -9
- package/dist/blob.js +5 -6
- package/dist/bun-database.d.ts +1 -0
- package/dist/bun-database.js +28 -0
- package/dist/client.d.ts +27 -10
- package/dist/client.js +357 -190
- package/dist/database.d.ts +5 -0
- package/dist/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +2 -0
- package/dist/errors.js +4 -0
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +3 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +61 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +11 -10
- package/dist/invalidation.js +15 -26
- package/dist/local-purge.js +9 -12
- package/dist/local-rebootstrap.js +2 -2
- package/dist/multi-tab.d.ts +89 -1
- package/dist/multi-tab.js +70 -31
- package/dist/native-bridge.d.ts +235 -0
- package/dist/native-bridge.js +789 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +29 -0
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +19 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/query-guard.d.ts +25 -24
- package/dist/query-guard.js +34 -191
- package/dist/reactive-store.js +53 -11
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +11 -15
- package/dist/schema.js +15 -10
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +80 -72
- package/dist/worker-host.d.ts +10 -5
- package/dist/worker-host.js +64 -7
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +6 -2
- package/package.json +11 -3
- package/src/apply.ts +91 -55
- package/src/blob.ts +27 -15
- package/src/bun-database.ts +29 -0
- package/src/client.ts +477 -261
- package/src/database.ts +5 -0
- package/src/encryption.ts +10 -5
- package/src/errors.ts +8 -0
- package/src/failed-overlay.ts +3 -7
- package/src/http.ts +90 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +17 -32
- package/src/local-purge.ts +11 -13
- package/src/local-rebootstrap.ts +2 -3
- package/src/multi-tab.ts +88 -30
- package/src/native-bridge.ts +1189 -0
- package/src/node-database.ts +32 -0
- package/src/outbox.ts +19 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/query-guard.ts +43 -180
- package/src/reactive-store.ts +50 -10
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +12 -16
- package/src/schema.ts +19 -12
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/worker-core.ts +94 -74
- package/src/worker-host.ts +63 -16
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +6 -2
package/src/query-guard.ts
CHANGED
|
@@ -1,198 +1,61 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The raw-query guard
|
|
3
|
-
* `
|
|
4
|
-
*
|
|
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.
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
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
|
-
*
|
|
18
|
-
*
|
|
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
|
-
|
|
43
|
-
|
|
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
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
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
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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
|
|
182
|
-
|
|
183
|
-
|
|
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
|
}
|
package/src/reactive-store.ts
CHANGED
|
@@ -315,8 +315,10 @@ function reconcileRows<Row>(
|
|
|
315
315
|
|
|
316
316
|
interface CachedObservation {
|
|
317
317
|
onChange(batch: ClientChangeBatch): void;
|
|
318
|
-
/**
|
|
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
|
-
|
|
776
|
-
void this
|
|
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 (
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
338
|
-
|
|
339
|
-
|
|
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)
|
|
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
|
|
239
|
+
throw invalidRequest('SyncRemoteClient clientId must be non-empty');
|
|
243
240
|
}
|
|
244
241
|
if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
|
|
245
|
-
throw
|
|
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
|
|
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
|
|
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
|
|
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
|
|
360
|
+
throw invalidRequest('remote upsert requires a non-empty primary key');
|
|
365
361
|
}
|
|
366
|
-
if (
|
|
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
|
|
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
|
|
170
|
-
if (
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
.
|
|
606
|
-
|
|
607
|
-
|
|
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",
|
package/src/sync-scheduler.ts
CHANGED
|
@@ -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 (
|
|
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;
|