@syncular/client 0.59.0 → 0.60.1
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 +27 -27
- package/dist/apply.d.ts +6 -5
- package/dist/apply.js +52 -25
- package/dist/authority.js +21 -16
- package/dist/blob.d.ts +4 -4
- package/dist/bun-database.js +3 -16
- package/dist/client.d.ts +57 -66
- package/dist/client.js +701 -796
- package/dist/devtools.d.ts +2 -2
- package/dist/devtools.js +3 -3
- package/dist/diagnostics.d.ts +17 -28
- package/dist/diagnostics.js +1 -2
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +1 -1
- package/dist/failed-overlay.js +4 -1
- package/dist/http.js +19 -5
- package/dist/invalidation.d.ts +3 -4
- package/dist/invalidation.js +9 -22
- package/dist/native-bridge.d.ts +7 -16
- package/dist/native-bridge.js +16 -41
- package/dist/node-database.js +16 -25
- package/dist/outbox.js +1 -0
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +15 -6
- package/dist/query-guard.js +38 -6
- package/dist/reactive-store.js +2 -2
- package/dist/remote.js +9 -9
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +28 -12
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +2 -2
- package/dist/transport.d.ts +2 -2
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.js +6 -6
- package/dist/worker-host.d.ts +9 -8
- package/dist/worker-host.js +23 -14
- package/dist/worker-protocol.d.ts +9 -8
- package/package.json +3 -3
- package/src/apply.ts +87 -33
- package/src/authority.ts +31 -17
- package/src/blob.ts +4 -3
- package/src/bun-database.ts +9 -14
- package/src/client.ts +886 -1037
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/errors.ts +1 -1
- package/src/failed-overlay.ts +6 -1
- package/src/http.ts +22 -9
- package/src/invalidation.ts +9 -29
- package/src/native-bridge.ts +22 -58
- package/src/node-database.ts +26 -27
- package/src/outbox.ts +1 -0
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +45 -8
- package/src/reactive-store.ts +2 -2
- package/src/remote.ts +12 -16
- package/src/schema.ts +48 -13
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +2 -2
- package/src/transport.ts +2 -2
- package/src/window.ts +55 -134
- package/src/worker-core.ts +6 -6
- package/src/worker-host.ts +27 -19
- package/src/worker-protocol.ts +8 -8
package/src/devtools.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
*
|
|
7
7
|
* __SYNCULAR__.clients // the live entries
|
|
8
8
|
* await __SYNCULAR__.snapshot() // one plain object per client:
|
|
9
|
-
* // outbox depth,
|
|
9
|
+
* // outbox depth, units,
|
|
10
10
|
* // conflicts, syncNeeded, upgrading,
|
|
11
11
|
* // last invalidation
|
|
12
12
|
* __SYNCULAR__.clients[0].ref // the client itself — full API
|
|
@@ -26,7 +26,7 @@ export interface DevtoolsRegistration {
|
|
|
26
26
|
readonly clientId: () => string;
|
|
27
27
|
readonly role: () => string;
|
|
28
28
|
readonly outbox: () => Promise<number>;
|
|
29
|
-
readonly
|
|
29
|
+
readonly units: () => Promise<readonly unknown[]>;
|
|
30
30
|
readonly conflicts: () => Promise<number>;
|
|
31
31
|
readonly rejections: () => Promise<number>;
|
|
32
32
|
readonly syncNeeded: () => Promise<boolean>;
|
|
@@ -87,9 +87,9 @@ function registryOn(host: Record<string, unknown>): DevtoolsRegistry {
|
|
|
87
87
|
clientId: entry.clientId(),
|
|
88
88
|
role: entry.role(),
|
|
89
89
|
outbox: await entry.outbox().catch(() => 'unavailable'),
|
|
90
|
-
|
|
91
|
-
.
|
|
92
|
-
.then((
|
|
90
|
+
units: await entry
|
|
91
|
+
.units()
|
|
92
|
+
.then((units) => units.length)
|
|
93
93
|
.catch(() => 'unavailable'),
|
|
94
94
|
conflicts: await entry.conflicts().catch(() => 'unavailable'),
|
|
95
95
|
rejections: await entry.rejections().catch(() => 'unavailable'),
|
package/src/diagnostics.ts
CHANGED
|
@@ -7,8 +7,7 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import type { SecurityLifecycle } from './client';
|
|
9
9
|
|
|
10
|
-
export const CLIENT_DIAGNOSTICS_VERSION =
|
|
11
|
-
export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
|
|
10
|
+
export const CLIENT_DIAGNOSTICS_VERSION = 2 as const;
|
|
12
11
|
export const MAX_DIAGNOSTIC_DOMAINS = 256;
|
|
13
12
|
export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
|
|
14
13
|
|
|
@@ -66,38 +65,15 @@ export interface ClientDiagnosticsHost {
|
|
|
66
65
|
readonly realtimeRetryDelayMs?: number;
|
|
67
66
|
}
|
|
68
67
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
readonly
|
|
72
|
-
|
|
73
|
-
readonly
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
* Optional bounded intent list. Missing registrations are returned as
|
|
79
|
-
* `unregistered`, allowing a zero-row security scope to fail closed without
|
|
80
|
-
* reading private Syncular tables. Values/scopes are intentionally absent.
|
|
81
|
-
*/
|
|
82
|
-
readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
export type DiagnosticSubscriptionState =
|
|
86
|
-
| 'unregistered'
|
|
87
|
-
| 'bootstrapping'
|
|
88
|
-
| 'complete'
|
|
89
|
-
| 'reset'
|
|
90
|
-
| 'revoked'
|
|
91
|
-
| 'failed';
|
|
92
|
-
|
|
93
|
-
export interface DiagnosticSubscription {
|
|
94
|
-
readonly id: string;
|
|
95
|
-
readonly table: string;
|
|
96
|
-
readonly state: DiagnosticSubscriptionState;
|
|
97
|
-
readonly complete: boolean;
|
|
98
|
-
/** Last fully applied local commit sequence; absent when unregistered. */
|
|
99
|
-
readonly cursor?: number;
|
|
100
|
-
readonly reasonCode?: string;
|
|
68
|
+
/** §7.6: registered units per state; a unit id never enters diagnostics. */
|
|
69
|
+
export interface DiagnosticUnits {
|
|
70
|
+
readonly bootstrapping: number;
|
|
71
|
+
readonly complete: number;
|
|
72
|
+
readonly reset: number;
|
|
73
|
+
readonly revoked: number;
|
|
74
|
+
readonly failed: number;
|
|
75
|
+
/** Distinct stable reason codes of registered units, ascending. */
|
|
76
|
+
readonly reasonCodes: readonly string[];
|
|
101
77
|
}
|
|
102
78
|
|
|
103
79
|
export interface DiagnosticRoundCounters {
|
|
@@ -140,7 +116,8 @@ export interface DiagnosticLastChange {
|
|
|
140
116
|
readonly recordedAtMs: number;
|
|
141
117
|
/** Generated table names only; no scope keys or row ids. */
|
|
142
118
|
readonly tables: readonly string[];
|
|
143
|
-
/**
|
|
119
|
+
/** Selected variables of window bases whose registration or completeness
|
|
120
|
+
* changed. */
|
|
144
121
|
readonly windows: readonly string[];
|
|
145
122
|
readonly domainsTruncated: boolean;
|
|
146
123
|
readonly statusChanged: boolean;
|
|
@@ -201,8 +178,11 @@ export interface ClientDiagnosticsSnapshot {
|
|
|
201
178
|
readonly expiresAtMs?: number;
|
|
202
179
|
readonly errorCode?: string;
|
|
203
180
|
};
|
|
204
|
-
readonly
|
|
205
|
-
|
|
181
|
+
readonly units: DiagnosticUnits;
|
|
182
|
+
/** Units the next registration list carries; the server limit counts these (SPEC §4.1). */
|
|
183
|
+
readonly activeUnits: number;
|
|
184
|
+
/** §4.5 replica cursor; `-1` while no unit is live. */
|
|
185
|
+
readonly replicaCursor: number;
|
|
206
186
|
readonly lastRound?: DiagnosticLastRound;
|
|
207
187
|
readonly lastChange?: DiagnosticLastChange;
|
|
208
188
|
readonly storage: ClientDiagnosticsStorage;
|
package/src/errors.ts
CHANGED
|
@@ -9,7 +9,7 @@ export const STORAGE_BUSY_CODE = 'client.storage_busy';
|
|
|
9
9
|
*/
|
|
10
10
|
export const STORAGE_FENCED_CODE = 'client.storage_fenced';
|
|
11
11
|
|
|
12
|
-
/** The
|
|
12
|
+
/** The runtime cannot provide the storage APIs Syncular requires. */
|
|
13
13
|
export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
|
|
14
14
|
|
|
15
15
|
/** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
|
package/src/failed-overlay.ts
CHANGED
|
@@ -37,6 +37,9 @@ export function ensureFailedOverlaySchema(db: ClientDatabase): void {
|
|
|
37
37
|
for (const column of ['unique_conflicts TEXT', 'commit_seq INTEGER'])
|
|
38
38
|
if (!columns.some((row) => row.name === column.split(' ')[0]))
|
|
39
39
|
db.exec(`ALTER TABLE ${RETAINED_ROWS} ADD COLUMN ${column}`);
|
|
40
|
+
db.exec(
|
|
41
|
+
`CREATE INDEX IF NOT EXISTS ${RETAINED_ROWS}_row ON ${RETAINED_ROWS}(tbl,id)`,
|
|
42
|
+
);
|
|
40
43
|
}
|
|
41
44
|
|
|
42
45
|
export function retainedBaseWrite(
|
|
@@ -176,8 +179,10 @@ function retainedRows(
|
|
|
176
179
|
scope?: OverlayScope,
|
|
177
180
|
acknowledged?: boolean,
|
|
178
181
|
) {
|
|
182
|
+
// A scope joins through the (tbl, id) index; a scan per applied commit
|
|
183
|
+
// would make a drained batch quadratic.
|
|
179
184
|
return db.query(
|
|
180
|
-
`SELECT * FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR
|
|
185
|
+
`SELECT * FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
|
|
181
186
|
[scope ? JSON.stringify(scope) : null],
|
|
182
187
|
);
|
|
183
188
|
}
|
package/src/http.ts
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
import type { BlobTransport } from './blob';
|
|
8
8
|
import { SSP2_CONTENT_TYPE } from './content-type';
|
|
9
9
|
import { ClientSyncError, transportFailed } from './errors';
|
|
10
|
+
import { hexToBytes } from './schema';
|
|
10
11
|
import type {
|
|
11
12
|
RealtimeConnector,
|
|
12
13
|
RemoteOperationTransport,
|
|
@@ -272,7 +273,15 @@ async function readBody(
|
|
|
272
273
|
}
|
|
273
274
|
}
|
|
274
275
|
if (received !== reported) onProgress?.(received);
|
|
275
|
-
|
|
276
|
+
// One allocation of the body's size. A Blob of the chunks and its
|
|
277
|
+
// arrayBuffer() kept one more full copy resident until garbage collection.
|
|
278
|
+
const bytes = new Uint8Array(received);
|
|
279
|
+
let offset = 0;
|
|
280
|
+
for (const chunk of chunks) {
|
|
281
|
+
bytes.set(chunk, offset);
|
|
282
|
+
offset += chunk.byteLength;
|
|
283
|
+
}
|
|
284
|
+
return bytes;
|
|
276
285
|
}
|
|
277
286
|
|
|
278
287
|
export function httpSegmentDownloader(
|
|
@@ -470,15 +479,19 @@ export function httpBlobTransport(
|
|
|
470
479
|
return { kind: 'none' };
|
|
471
480
|
},
|
|
472
481
|
// §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
|
|
473
|
-
uploadToUrl: async (url, bytes, mediaType, signal) => {
|
|
482
|
+
uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
|
|
483
|
+
// The grant signs content-length (set by fetch from the body) and the
|
|
484
|
+
// checksum, the blob id's digest, so the object store rejects any other
|
|
485
|
+
// bytes without the client hashing the body again (§5.9.3).
|
|
486
|
+
const hex = /^sha256:([0-9a-f]{64})$/.exec(blobId)?.[1];
|
|
487
|
+
if (hex === undefined) {
|
|
488
|
+
throw new ClientSyncError(
|
|
489
|
+
'sync.invalid_request',
|
|
490
|
+
'the blob id is not a sha256 blob id (§5.9.1)',
|
|
491
|
+
);
|
|
492
|
+
}
|
|
493
|
+
const checksum = btoa(String.fromCharCode(...hexToBytes(hex)));
|
|
474
494
|
const body = bytes.slice().buffer as ArrayBuffer;
|
|
475
|
-
// The grant signs content-length (set by fetch from the body) and this
|
|
476
|
-
// checksum, so the object store rejects any other bytes (§5.9.3).
|
|
477
|
-
const checksum = btoa(
|
|
478
|
-
String.fromCharCode(
|
|
479
|
-
...new Uint8Array(await crypto.subtle.digest('SHA-256', body)),
|
|
480
|
-
),
|
|
481
|
-
);
|
|
482
495
|
const response = await transfer('signed blob upload failed', () =>
|
|
483
496
|
doFetch(url, {
|
|
484
497
|
method: 'PUT',
|
package/src/invalidation.ts
CHANGED
|
@@ -19,7 +19,7 @@ export interface TableChange {
|
|
|
19
19
|
|
|
20
20
|
export interface WindowChange {
|
|
21
21
|
readonly baseKey: string;
|
|
22
|
-
|
|
22
|
+
/** Changed values of the base. */
|
|
23
23
|
readonly units: ReadonlySet<string>;
|
|
24
24
|
}
|
|
25
25
|
|
|
@@ -51,7 +51,6 @@ export interface ClientChangeBatch {
|
|
|
51
51
|
readonly outcomesChanged: boolean;
|
|
52
52
|
/** Server COMMIT frames applied by this transaction, when present. */
|
|
53
53
|
readonly appliedCommits?: readonly {
|
|
54
|
-
readonly subscriptionId: string;
|
|
55
54
|
readonly table: string;
|
|
56
55
|
readonly commitSeq: number;
|
|
57
56
|
readonly source: 'delta' | 'pull';
|
|
@@ -84,18 +83,13 @@ interface MutableTableChange {
|
|
|
84
83
|
scopeKeys: Set<string> | undefined;
|
|
85
84
|
}
|
|
86
85
|
|
|
87
|
-
interface MutableWindowChange {
|
|
88
|
-
table: string;
|
|
89
|
-
units: Set<string>;
|
|
90
|
-
}
|
|
91
|
-
|
|
92
86
|
/**
|
|
93
87
|
* Per-observer-transaction accumulator. It contains no revision itself: the
|
|
94
88
|
* transaction wrapper assigns the revision only after all writes succeeded.
|
|
95
89
|
*/
|
|
96
90
|
export class ChangeAccumulator {
|
|
97
91
|
readonly #tables = new Map<string, MutableTableChange>();
|
|
98
|
-
readonly #windows = new Map<string,
|
|
92
|
+
readonly #windows = new Map<string, Set<string>>();
|
|
99
93
|
#status = false;
|
|
100
94
|
#conflicts = false;
|
|
101
95
|
#rejections = false;
|
|
@@ -129,17 +123,11 @@ export class ChangeAccumulator {
|
|
|
129
123
|
current.scopeKeys?.add(key);
|
|
130
124
|
}
|
|
131
125
|
|
|
132
|
-
/** Record registration/completeness change for one window
|
|
133
|
-
window(baseKey: string,
|
|
126
|
+
/** Record registration/completeness change for one window value. */
|
|
127
|
+
window(baseKey: string, value: string): void {
|
|
134
128
|
const current = this.#windows.get(baseKey);
|
|
135
|
-
if (current === undefined)
|
|
136
|
-
|
|
137
|
-
return;
|
|
138
|
-
}
|
|
139
|
-
if (current.table !== table) {
|
|
140
|
-
throw new Error(`window base ${JSON.stringify(baseKey)} changed tables`);
|
|
141
|
-
}
|
|
142
|
-
current.units.add(unit);
|
|
129
|
+
if (current === undefined) this.#windows.set(baseKey, new Set([value]));
|
|
130
|
+
else current.add(value);
|
|
143
131
|
}
|
|
144
132
|
|
|
145
133
|
status(): void {
|
|
@@ -222,13 +210,8 @@ export class ChangeAccumulator {
|
|
|
222
210
|
);
|
|
223
211
|
}
|
|
224
212
|
const windows: WindowChange[] = [];
|
|
225
|
-
for (const [baseKey,
|
|
226
|
-
windows.push({
|
|
227
|
-
baseKey,
|
|
228
|
-
table: change.table,
|
|
229
|
-
units: change.units,
|
|
230
|
-
});
|
|
231
|
-
}
|
|
213
|
+
for (const [baseKey, units] of this.#windows)
|
|
214
|
+
windows.push({ baseKey, units });
|
|
232
215
|
return {
|
|
233
216
|
revision,
|
|
234
217
|
tables,
|
|
@@ -289,16 +272,13 @@ export type InvalidationListener = (event: InvalidationEvent) => void;
|
|
|
289
272
|
export function invalidationFromChange(
|
|
290
273
|
batch: ClientChangeBatch,
|
|
291
274
|
): InvalidationEvent | undefined {
|
|
292
|
-
if (batch.tables.length === 0
|
|
275
|
+
if (batch.tables.length === 0) return undefined;
|
|
293
276
|
const tables = new Set<string>();
|
|
294
277
|
const scopeKeys = new Set<string>();
|
|
295
278
|
for (const change of batch.tables) {
|
|
296
279
|
tables.add(change.table);
|
|
297
280
|
for (const key of change.scopeKeys ?? []) scopeKeys.add(key);
|
|
298
281
|
}
|
|
299
|
-
// Window-only changes project the table for old completeness consumers.
|
|
300
|
-
// The exact API still keeps this distinct, so new table-only reads do not run.
|
|
301
|
-
for (const change of batch.windows) tables.add(change.table);
|
|
302
282
|
return { tables, scopeKeys };
|
|
303
283
|
}
|
|
304
284
|
|
package/src/native-bridge.ts
CHANGED
|
@@ -27,10 +27,10 @@ import {
|
|
|
27
27
|
type WindowState,
|
|
28
28
|
} from './client';
|
|
29
29
|
import type { SqlRow, SqlValue } from './database';
|
|
30
|
-
import type { PresenceErrorCode } from '@syncular/core';
|
|
30
|
+
import type { PresenceErrorCode, UnitScopes } from '@syncular/core';
|
|
31
31
|
import {
|
|
32
|
+
CLIENT_DIAGNOSTICS_VERSION,
|
|
32
33
|
type ClientDiagnosticsListener,
|
|
33
|
-
type ClientDiagnosticsRequest,
|
|
34
34
|
type ClientDiagnosticsSnapshot,
|
|
35
35
|
withClientDiagnosticsHost,
|
|
36
36
|
} from './diagnostics';
|
|
@@ -206,19 +206,8 @@ function decodeChangeBatch(value: unknown): ClientChangeBatch | undefined {
|
|
|
206
206
|
? raw.windows.flatMap((entry) => {
|
|
207
207
|
if (entry === null || typeof entry !== 'object') return [];
|
|
208
208
|
const item = entry as Record<string, unknown>;
|
|
209
|
-
if (
|
|
210
|
-
|
|
211
|
-
typeof item.table !== 'string'
|
|
212
|
-
) {
|
|
213
|
-
return [];
|
|
214
|
-
}
|
|
215
|
-
return [
|
|
216
|
-
{
|
|
217
|
-
baseKey: item.baseKey,
|
|
218
|
-
table: item.table,
|
|
219
|
-
units: toStringSet(item.units),
|
|
220
|
-
},
|
|
221
|
-
];
|
|
209
|
+
if (typeof item.baseKey !== 'string') return [];
|
|
210
|
+
return [{ baseKey: item.baseKey, units: toStringSet(item.units) }];
|
|
222
211
|
})
|
|
223
212
|
: [];
|
|
224
213
|
const appliedCommits: NonNullable<
|
|
@@ -230,7 +219,6 @@ function decodeChangeBatch(value: unknown): ClientChangeBatch | undefined {
|
|
|
230
219
|
if (entry === null || typeof entry !== 'object') return undefined;
|
|
231
220
|
const item = entry as Record<string, unknown>;
|
|
232
221
|
if (
|
|
233
|
-
typeof item.subscriptionId !== 'string' ||
|
|
234
222
|
typeof item.table !== 'string' ||
|
|
235
223
|
typeof item.commitSeq !== 'number' ||
|
|
236
224
|
!Number.isSafeInteger(item.commitSeq) ||
|
|
@@ -239,7 +227,6 @@ function decodeChangeBatch(value: unknown): ClientChangeBatch | undefined {
|
|
|
239
227
|
)
|
|
240
228
|
return undefined;
|
|
241
229
|
appliedCommits.push({
|
|
242
|
-
subscriptionId: item.subscriptionId,
|
|
243
230
|
table: item.table,
|
|
244
231
|
commitSeq: item.commitSeq,
|
|
245
232
|
source: item.source,
|
|
@@ -558,14 +545,13 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
|
|
|
558
545
|
const batch = decodeChangeBatch(event.batch);
|
|
559
546
|
if (batch === undefined) break;
|
|
560
547
|
fanOut(this.#changeListeners, batch);
|
|
561
|
-
if (batch.tables.length === 0
|
|
548
|
+
if (batch.tables.length === 0) break;
|
|
562
549
|
const tables = new Set<string>();
|
|
563
550
|
const scopeKeys = new Set<string>();
|
|
564
551
|
for (const table of batch.tables) {
|
|
565
552
|
tables.add(table.table);
|
|
566
553
|
for (const key of table.scopeKeys ?? []) scopeKeys.add(key);
|
|
567
554
|
}
|
|
568
|
-
for (const window of batch.windows) tables.add(window.table);
|
|
569
555
|
fanOut(this.#invalidationListeners, { tables, scopeKeys });
|
|
570
556
|
break;
|
|
571
557
|
}
|
|
@@ -581,7 +567,7 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
|
|
|
581
567
|
if (
|
|
582
568
|
snapshot === null ||
|
|
583
569
|
typeof snapshot !== 'object' ||
|
|
584
|
-
snapshot.version !==
|
|
570
|
+
snapshot.version !== CLIENT_DIAGNOSTICS_VERSION ||
|
|
585
571
|
snapshot.host === undefined
|
|
586
572
|
)
|
|
587
573
|
break;
|
|
@@ -738,14 +724,14 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
|
|
|
738
724
|
params: encodeValue(statement.params ?? []),
|
|
739
725
|
})),
|
|
740
726
|
coverage: request.coverage ?? [],
|
|
741
|
-
|
|
727
|
+
units: request.units ?? [],
|
|
742
728
|
commitIds: request.commitIds ?? [],
|
|
743
729
|
...(request.owner !== undefined ? { owner: request.owner } : {}),
|
|
744
730
|
})) as {
|
|
745
731
|
revision: string;
|
|
746
732
|
queries: readonly (readonly Record<string, unknown>[])[];
|
|
747
733
|
coverage: SnapshotRead['coverage'];
|
|
748
|
-
|
|
734
|
+
units: SnapshotRead['units'];
|
|
749
735
|
deliveries: SnapshotRead['deliveries'];
|
|
750
736
|
};
|
|
751
737
|
return {
|
|
@@ -754,7 +740,7 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
|
|
|
754
740
|
rows.map((row) => this.decodeRow(row)),
|
|
755
741
|
),
|
|
756
742
|
coverage: result.coverage,
|
|
757
|
-
|
|
743
|
+
units: result.units,
|
|
758
744
|
deliveries: result.deliveries.map((delivery) =>
|
|
759
745
|
delivery.status === 'known'
|
|
760
746
|
? { ...delivery, outcome: this.#commitOutcome(delivery.outcome) }
|
|
@@ -774,12 +760,11 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
|
|
|
774
760
|
return (await this.command('statusSnapshot', {})) as SyncStatusSnapshot;
|
|
775
761
|
}
|
|
776
762
|
|
|
777
|
-
async diagnosticsSnapshot(
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
})) as ClientDiagnosticsSnapshot;
|
|
763
|
+
async diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot> {
|
|
764
|
+
const snapshot = (await this.command(
|
|
765
|
+
'diagnosticsSnapshot',
|
|
766
|
+
{},
|
|
767
|
+
)) as ClientDiagnosticsSnapshot;
|
|
783
768
|
return withClientDiagnosticsHost(snapshot, {
|
|
784
769
|
...snapshot.host,
|
|
785
770
|
kind: this.#kind,
|
|
@@ -1007,37 +992,16 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
|
|
|
1007
992
|
};
|
|
1008
993
|
}
|
|
1009
994
|
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
readonly scopes?: Record<string, readonly string[]>;
|
|
1014
|
-
readonly params?: string;
|
|
1015
|
-
}): Promise<void> {
|
|
1016
|
-
await this.command('subscribe', {
|
|
1017
|
-
id: input.id,
|
|
1018
|
-
table: input.table,
|
|
1019
|
-
scopes: input.scopes ?? {},
|
|
1020
|
-
...(input.params !== undefined ? { params: input.params } : {}),
|
|
1021
|
-
});
|
|
995
|
+
/** §4.1: register one unit; returns its id. */
|
|
996
|
+
async subscribe(scopes: UnitScopes): Promise<string> {
|
|
997
|
+
return ((await this.command('subscribe', { scopes })) as { id: string }).id;
|
|
1022
998
|
}
|
|
1023
999
|
|
|
1024
|
-
/** Register several
|
|
1025
|
-
async subscribeMany(
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
readonly scopes?: Record<string, readonly string[]>;
|
|
1030
|
-
readonly params?: string;
|
|
1031
|
-
}[],
|
|
1032
|
-
): Promise<void> {
|
|
1033
|
-
await this.command('subscribeMany', {
|
|
1034
|
-
subscriptions: inputs.map((input) => ({
|
|
1035
|
-
id: input.id,
|
|
1036
|
-
table: input.table,
|
|
1037
|
-
scopes: input.scopes ?? {},
|
|
1038
|
-
...(input.params !== undefined ? { params: input.params } : {}),
|
|
1039
|
-
})),
|
|
1040
|
-
});
|
|
1000
|
+
/** Register several units in one local transaction; returns their ids. */
|
|
1001
|
+
async subscribeMany(units: readonly UnitScopes[]): Promise<string[]> {
|
|
1002
|
+
return (
|
|
1003
|
+
(await this.command('subscribeMany', { units })) as { ids: string[] }
|
|
1004
|
+
).ids;
|
|
1041
1005
|
}
|
|
1042
1006
|
|
|
1043
1007
|
async unsubscribe(id: string): Promise<void> {
|
package/src/node-database.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* `ClientDatabase` on Node's built-in `node:sqlite`. Semantics mirror the Bun
|
|
3
3
|
* adapter: synchronous queries, nested transactions, and SQLite image attach.
|
|
4
4
|
*/
|
|
5
|
-
import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
|
|
5
|
+
import { DatabaseSync, type SQLInputValue, StatementSync } from 'node:sqlite';
|
|
6
6
|
import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
|
|
7
7
|
import { tmpdir } from 'node:os';
|
|
8
8
|
import { join } from 'node:path';
|
|
@@ -14,7 +14,8 @@ import {
|
|
|
14
14
|
type SqlRow,
|
|
15
15
|
type SqlValue,
|
|
16
16
|
} from './database';
|
|
17
|
-
import {
|
|
17
|
+
import { ClientSyncError, STORAGE_UNAVAILABLE_CODE } from './errors';
|
|
18
|
+
import { prepareReadOnly, runReadOnly } from './query-guard';
|
|
18
19
|
|
|
19
20
|
function coerceParams(params: readonly SqlValue[]): SQLInputValue[] {
|
|
20
21
|
return params.map((value): SQLInputValue => {
|
|
@@ -39,9 +40,19 @@ function normalizeRow(row: Record<string, unknown>): SqlRow {
|
|
|
39
40
|
export class NodeClientDatabase implements ClientDatabase {
|
|
40
41
|
readonly db: DatabaseSync;
|
|
41
42
|
readonly #path: string;
|
|
43
|
+
readonly #proven = new Set<string>();
|
|
42
44
|
#tx = { depth: 0 };
|
|
43
45
|
|
|
44
46
|
constructor(path = ':memory:') {
|
|
47
|
+
// The raw-SQL tier reads result columns through `columns()` (Node 22.16).
|
|
48
|
+
if (typeof StatementSync.prototype.columns !== 'function') {
|
|
49
|
+
throw new ClientSyncError(
|
|
50
|
+
STORAGE_UNAVAILABLE_CODE,
|
|
51
|
+
'The node:sqlite adapter needs Node 22.16 or newer.',
|
|
52
|
+
false,
|
|
53
|
+
{ runtime: 'node', version: process.versions.node, minimum: '22.16.0' },
|
|
54
|
+
);
|
|
55
|
+
}
|
|
45
56
|
this.#path = path;
|
|
46
57
|
this.db = new DatabaseSync(path);
|
|
47
58
|
try {
|
|
@@ -65,32 +76,20 @@ export class NodeClientDatabase implements ClientDatabase {
|
|
|
65
76
|
queryReadOnly(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
|
|
66
77
|
const statement = prepareReadOnly(sql, () => {
|
|
67
78
|
const prepared = this.db.prepare(sql);
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
const verb = /^[a-z]+/i.exec(body)?.[0].toLowerCase();
|
|
74
|
-
let reads = verb === 'select' || verb === 'values' || verb === 'explain';
|
|
75
|
-
if (verb === 'with') {
|
|
76
|
-
let depth = 0;
|
|
77
|
-
for (const [token] of body.matchAll(
|
|
78
|
-
/'[^']*'|"[^"]*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|[\w$\u0080-\uffff]+|[\s\S]/g,
|
|
79
|
-
)) {
|
|
80
|
-
if (token === '(') depth += 1;
|
|
81
|
-
else if (token === ')') depth -= 1;
|
|
82
|
-
else if (
|
|
83
|
-
depth === 0 &&
|
|
84
|
-
/^(?:select|values|insert|update|delete|replace)$/i.test(token)
|
|
85
|
-
) {
|
|
86
|
-
reads = /^(?:select|values)$/i.test(token);
|
|
87
|
-
break;
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
}
|
|
91
|
-
return [prepared, prepared.sourceSQL, reads] as const;
|
|
79
|
+
return [
|
|
80
|
+
prepared,
|
|
81
|
+
prepared.sourceSQL,
|
|
82
|
+
prepared.columns().length > 0,
|
|
83
|
+
] as const;
|
|
92
84
|
});
|
|
93
|
-
return
|
|
85
|
+
return runReadOnly(
|
|
86
|
+
this.#proven,
|
|
87
|
+
sql,
|
|
88
|
+
(pragma) => this.db.exec(pragma),
|
|
89
|
+
// SQLITE_READONLY
|
|
90
|
+
(error) => (error as { errcode?: unknown }).errcode === 8,
|
|
91
|
+
() => statement.all(...coerceParams(params)).map(normalizeRow),
|
|
92
|
+
);
|
|
94
93
|
}
|
|
95
94
|
|
|
96
95
|
/** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
|
package/src/outbox.ts
CHANGED
package/src/progress.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import type { TransportCauseKind } from './diagnostics';
|
|
2
2
|
|
|
3
|
-
/** Ephemeral sync work, independent of committed change notifications (SPEC §7.
|
|
3
|
+
/** Ephemeral sync work, independent of committed change notifications (SPEC §7.7). */
|
|
4
4
|
export interface SyncProgress {
|
|
5
5
|
readonly attempt: number;
|
|
6
6
|
readonly state: 'running' | 'complete' | 'failed';
|
|
7
7
|
readonly phase: 'request' | 'download' | 'import';
|
|
8
|
-
readonly
|
|
8
|
+
readonly unitId?: string;
|
|
9
9
|
readonly table?: string;
|
|
10
10
|
readonly segmentId?: string | undefined;
|
|
11
11
|
readonly bytesReceived: number;
|
package/src/query-guard.ts
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
* `snapshotRead()`, the untrusted raw-SQL tier. Each `ClientDatabase` adapter
|
|
4
4
|
* prepares only the first statement and reports what SQLite knows about it:
|
|
5
5
|
*
|
|
6
|
-
* 1. READ-ONLY. SQLite decides (`sqlite3_stmt_readonly
|
|
7
|
-
*
|
|
6
|
+
* 1. READ-ONLY. SQLite decides (`sqlite3_stmt_readonly`, or `query_only`
|
|
7
|
+
* on the first run of a text, `runReadOnly`) and the statement returns
|
|
8
|
+
* columns, which refuses `BEGIN`, `ATTACH` and the other
|
|
8
9
|
* read-only statements that change the connection. A write against the
|
|
9
10
|
* local mirror bypasses the outbox (SPEC §7.1); writes go through
|
|
10
11
|
* `client.mutate([...])`.
|
|
@@ -25,12 +26,8 @@ export class RawSqlError extends Error {
|
|
|
25
26
|
override readonly name = 'RawSqlError';
|
|
26
27
|
}
|
|
27
28
|
|
|
28
|
-
/** Leading whitespace, comments and empty statements. */
|
|
29
|
-
export const SQL_BLANK =
|
|
30
|
-
/^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$))*/;
|
|
31
|
-
|
|
32
29
|
/** Refuse a statement the raw-SQL tier does not run. */
|
|
33
|
-
|
|
30
|
+
function refuseRawSql(): never {
|
|
34
31
|
throw new RawSqlError(
|
|
35
32
|
'client.query() runs read-only statements and no PRAGMA; write through client.mutate() so the outbox records it (SPEC §7.1).',
|
|
36
33
|
);
|
|
@@ -53,9 +50,49 @@ export function prepareReadOnly<S>(
|
|
|
53
50
|
refuseRawSql();
|
|
54
51
|
}
|
|
55
52
|
const [statement, first, reads] = prepare();
|
|
56
|
-
if (
|
|
53
|
+
if (
|
|
54
|
+
sql
|
|
55
|
+
.slice(first.length)
|
|
56
|
+
.replace(
|
|
57
|
+
/^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$))*/,
|
|
58
|
+
'',
|
|
59
|
+
) !== ''
|
|
60
|
+
) {
|
|
57
61
|
throw new RawSqlError('client.query() runs one statement per call.');
|
|
58
62
|
}
|
|
59
63
|
if (!reads) refuseRawSql();
|
|
60
64
|
return statement;
|
|
61
65
|
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Run a statement `prepareReadOnly` accepted on an adapter without
|
|
69
|
+
* `sqlite3_stmt_readonly` (bun:sqlite before 1.4.4, node:sqlite). SQLite
|
|
70
|
+
* refuses a write when it runs: under `query_only` a write transaction fails
|
|
71
|
+
* before it changes anything, and `refused` recognizes that error. The
|
|
72
|
+
* verdict depends on the text alone, since a write fails at its write
|
|
73
|
+
* transaction whether or not it touches a row, so a text that completed
|
|
74
|
+
* under `query_only` joins `proven` and later runs skip the pragma: a flag
|
|
75
|
+
* pragma expires every prepared statement of the connection. `proven` is per
|
|
76
|
+
* connection and cleared at 512 texts, so dynamic SQL cannot grow it.
|
|
77
|
+
*/
|
|
78
|
+
export function runReadOnly<R>(
|
|
79
|
+
proven: Set<string>,
|
|
80
|
+
sql: string,
|
|
81
|
+
pragma: (sql: string) => void,
|
|
82
|
+
refused: (error: unknown) => boolean,
|
|
83
|
+
run: () => R,
|
|
84
|
+
): R {
|
|
85
|
+
if (proven.has(sql)) return run();
|
|
86
|
+
pragma('PRAGMA query_only = ON');
|
|
87
|
+
try {
|
|
88
|
+
const result = run();
|
|
89
|
+
if (proven.size >= 512) proven.clear();
|
|
90
|
+
proven.add(sql);
|
|
91
|
+
return result;
|
|
92
|
+
} catch (error) {
|
|
93
|
+
if (refused(error)) refuseRawSql();
|
|
94
|
+
throw error;
|
|
95
|
+
} finally {
|
|
96
|
+
pragma('PRAGMA query_only = OFF');
|
|
97
|
+
}
|
|
98
|
+
}
|
package/src/reactive-store.ts
CHANGED
|
@@ -545,7 +545,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
|
|
|
545
545
|
this.reset();
|
|
546
546
|
}
|
|
547
547
|
|
|
548
|
-
/** SPEC §7.
|
|
548
|
+
/** SPEC §7.8: a rejected claim is claimed again; its stored error would
|
|
549
549
|
* fail every read until the last subscriber leaves. */
|
|
550
550
|
reclaim(): void {
|
|
551
551
|
if (this.#delegate !== undefined || this.#claimError === undefined) return;
|
|
@@ -1231,7 +1231,7 @@ export class ReactiveClientStore {
|
|
|
1231
1231
|
>;
|
|
1232
1232
|
let claimedAttempt: number | undefined;
|
|
1233
1233
|
this.#offProgress = this.client.onProgress((progress) => {
|
|
1234
|
-
// A new sync attempt is the client's retry schedule (§7.
|
|
1234
|
+
// A new sync attempt is the client's retry schedule (§7.7): window
|
|
1235
1235
|
// claims that failed are claimed again once per attempt.
|
|
1236
1236
|
if (progress.state === 'running' && progress.attempt !== claimedAttempt) {
|
|
1237
1237
|
claimedAttempt = progress.attempt;
|