@syncular/client 0.57.0 → 0.59.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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/dist/worker-host.js
CHANGED
|
@@ -1,6 +1,30 @@
|
|
|
1
1
|
import { ProgressEmitter, } from './progress.js';
|
|
2
|
+
/**
|
|
3
|
+
* Main-thread side of the worker mode and the
|
|
4
|
+
* multi-tab topology.
|
|
5
|
+
*
|
|
6
|
+
* `createSyncClientHandle` acquires the Web Locks leader lock and, when it
|
|
7
|
+
* wins, spawns the worker running the WHOLE core — so exactly one core runs
|
|
8
|
+
* per origin (the lock IS the invariant: a worker is NEVER spawned without
|
|
9
|
+
* holding the lock). The returned {@link SyncClientHandle} is a thin, fully
|
|
10
|
+
* async proxy over the `worker-protocol` RPC.
|
|
11
|
+
*
|
|
12
|
+
* Multi-tab is the DEFAULT. The follower path is
|
|
13
|
+
* conformance-covered): a tab that LOSES the election becomes a FOLLOWER
|
|
14
|
+
* (`role === 'follower'`) that proxies every call to the leader tab over a
|
|
15
|
+
* BroadcastChannel (see `multi-tab.ts`). When the leader tab closes, its
|
|
16
|
+
* lock releases; the followers contest, the winner PROMOTES in place —
|
|
17
|
+
* spawns the worker over the persisted OPFS database and re-announces — and
|
|
18
|
+
* the handle's `role` flips to `'leader'` with `onRoleChange` firing. The
|
|
19
|
+
* same handle object is kept across the transition so React bindings hold a
|
|
20
|
+
* stable reference.
|
|
21
|
+
*
|
|
22
|
+
* With `multiTab: false`, the loser is an `isLeader === false` handle whose
|
|
23
|
+
* calls reject with `client.not_leader` (the single-tab contract).
|
|
24
|
+
*/
|
|
25
|
+
import { serializeBlobRef, } from '@syncular/core';
|
|
2
26
|
import { ClientDiagnosticsEmitter, withClientDiagnosticsHost, } from './diagnostics.js';
|
|
3
|
-
import { ClientSyncError } from './errors.js';
|
|
27
|
+
import { ClientSyncError, invalidRequest } from './errors.js';
|
|
4
28
|
import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
|
|
5
29
|
import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
|
|
6
30
|
import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
|
|
@@ -18,7 +42,7 @@ export function workerStartupError(message) {
|
|
|
18
42
|
/** Derive the complete ownership tuple for an independently owned replica. */
|
|
19
43
|
export function isolatedReplicaNames(options) {
|
|
20
44
|
if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
|
|
21
|
-
throw
|
|
45
|
+
throw invalidRequest('an isolated replica id must contain only letters, numbers, dot, underscore, or dash');
|
|
22
46
|
}
|
|
23
47
|
const suffix = `--replica-${options.replicaId}`;
|
|
24
48
|
const databaseName = `${options.databaseName}${suffix}`;
|
|
@@ -131,6 +155,11 @@ export class SyncClientHandle {
|
|
|
131
155
|
this.#clientId = state.clientId;
|
|
132
156
|
if (state.state === 'follower')
|
|
133
157
|
this.#clientId = state.leaderClientId;
|
|
158
|
+
// A new leader starts a fresh core that no tab has pulled from yet.
|
|
159
|
+
if (this.#diagnostics.observed &&
|
|
160
|
+
(state.state === 'leader' || state.state === 'follower')) {
|
|
161
|
+
this.#pullDiagnostics();
|
|
162
|
+
}
|
|
134
163
|
for (const listener of this.#leadershipListeners) {
|
|
135
164
|
try {
|
|
136
165
|
listener(state);
|
|
@@ -160,7 +189,7 @@ export class SyncClientHandle {
|
|
|
160
189
|
else if (event.kind === 'presence') {
|
|
161
190
|
for (const listener of this.#presence) {
|
|
162
191
|
try {
|
|
163
|
-
listener(event.scopeKey);
|
|
192
|
+
listener(event.scopeKey, event.error);
|
|
164
193
|
}
|
|
165
194
|
catch {
|
|
166
195
|
/* a UI listener must never break event dispatch */
|
|
@@ -200,7 +229,17 @@ export class SyncClientHandle {
|
|
|
200
229
|
return this.#changes.on(listener);
|
|
201
230
|
}
|
|
202
231
|
onDiagnostics(listener) {
|
|
203
|
-
|
|
232
|
+
const off = this.#diagnostics.on(listener);
|
|
233
|
+
this.#pullDiagnostics();
|
|
234
|
+
return off;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* The worker pushes diagnostics only after a consumer pulled once. A handle
|
|
238
|
+
* that cannot reach a core has nothing to observe, so a failed pull is
|
|
239
|
+
* dropped.
|
|
240
|
+
*/
|
|
241
|
+
#pullDiagnostics() {
|
|
242
|
+
void this.diagnosticsSnapshot().catch(() => undefined);
|
|
204
243
|
}
|
|
205
244
|
/**
|
|
206
245
|
* §8.6: subscribe to presence changes — the identical surface as
|
|
@@ -402,6 +441,10 @@ export class SyncClientHandle {
|
|
|
402
441
|
uploadBlob(bytes, options) {
|
|
403
442
|
return this.#call('uploadBlob', [bytes, options]);
|
|
404
443
|
}
|
|
444
|
+
/** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
|
|
445
|
+
blobRefString(ref) {
|
|
446
|
+
return serializeBlobRef(ref);
|
|
447
|
+
}
|
|
405
448
|
fetchBlob(blobIdOrRef) {
|
|
406
449
|
return this.#call('fetchBlob', [blobIdOrRef]);
|
|
407
450
|
}
|
|
@@ -461,7 +504,15 @@ export class SyncClientHandle {
|
|
|
461
504
|
*/
|
|
462
505
|
async function startWorkerCore(options) {
|
|
463
506
|
const { config, initConfig, lease } = options;
|
|
464
|
-
|
|
507
|
+
let worker;
|
|
508
|
+
try {
|
|
509
|
+
worker = config.worker();
|
|
510
|
+
}
|
|
511
|
+
catch (error) {
|
|
512
|
+
// No worker exists to terminate; the lease is the only thing held.
|
|
513
|
+
await lease.release();
|
|
514
|
+
throw error;
|
|
515
|
+
}
|
|
465
516
|
const pending = new Map();
|
|
466
517
|
const nextId = { value: 1 };
|
|
467
518
|
let terminated = false;
|
|
@@ -546,6 +597,9 @@ async function startWorkerCore(options) {
|
|
|
546
597
|
config: initConfig,
|
|
547
598
|
});
|
|
548
599
|
});
|
|
600
|
+
// A config callback is a consumer from the first round.
|
|
601
|
+
if (config.onDiagnostics !== undefined)
|
|
602
|
+
await invoke('diagnosticsSnapshot', []);
|
|
549
603
|
return {
|
|
550
604
|
clientId: initResult.clientId,
|
|
551
605
|
invoke,
|
|
@@ -596,6 +650,9 @@ function buildInitConfig(config, headers = config.headers) {
|
|
|
596
650
|
...(config.realtimePolicy !== undefined
|
|
597
651
|
? { realtimePolicy: config.realtimePolicy }
|
|
598
652
|
: {}),
|
|
653
|
+
...(config.realtimeHeartbeatMs !== undefined
|
|
654
|
+
? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
|
|
655
|
+
: {}),
|
|
599
656
|
...(config.previousVersionContext !== undefined
|
|
600
657
|
? { previousVersionContext: config.previousVersionContext }
|
|
601
658
|
: {}),
|
|
@@ -614,7 +671,7 @@ function fireConfigCallbacks(config, event) {
|
|
|
614
671
|
config.onUpgrading?.(event.upgrading);
|
|
615
672
|
}
|
|
616
673
|
else if (event.kind === 'presence') {
|
|
617
|
-
config.onPresence?.(event.scopeKey);
|
|
674
|
+
config.onPresence?.(event.scopeKey, event.error);
|
|
618
675
|
}
|
|
619
676
|
else if (event.kind === 'synced') {
|
|
620
677
|
config.onSynced?.({
|
|
@@ -783,7 +840,7 @@ function resolveReplicaConfig(config) {
|
|
|
783
840
|
if (config.replica?.mode !== 'isolated')
|
|
784
841
|
return config;
|
|
785
842
|
if (config.database.mode !== 'persistent') {
|
|
786
|
-
throw
|
|
843
|
+
throw invalidRequest('isolated browser replicas require a named persistent database');
|
|
787
844
|
}
|
|
788
845
|
const names = isolatedReplicaNames({
|
|
789
846
|
databaseName: config.database.name,
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ClientSyncError } from './errors.js';
|
|
1
|
+
import { ClientSyncError, invalidRequest } from './errors.js';
|
|
2
2
|
import { LOCAL_AUTHORITY_UNCONFIGURED_CODE } from './worker-protocol.js';
|
|
3
3
|
/** §12 behavior loaded by the authority-enabled worker entry. */
|
|
4
4
|
export const createWorkerLocalAuthority = (context) => {
|
|
@@ -58,7 +58,7 @@ export const createWorkerLocalAuthority = (context) => {
|
|
|
58
58
|
if (active())
|
|
59
59
|
return local.downloadSegment(request);
|
|
60
60
|
if (segments === undefined) {
|
|
61
|
-
throw
|
|
61
|
+
throw invalidRequest('no segment endpoint configured');
|
|
62
62
|
}
|
|
63
63
|
return segments(request);
|
|
64
64
|
},
|
|
@@ -17,7 +17,7 @@ import type { SyncProgress } from './progress.js';
|
|
|
17
17
|
* so the UI thread never has to react to keep data flowing. Events are
|
|
18
18
|
* still forwarded to the handle for visibility.
|
|
19
19
|
*/
|
|
20
|
-
import type { WakeReason } from '@syncular/core';
|
|
20
|
+
import type { PresenceErrorCode, WakeReason } from '@syncular/core';
|
|
21
21
|
import type { BlobRef, CachedBlob } from './blob.js';
|
|
22
22
|
import type { ConflictRecord, CurrentBaseProof, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, SyncIdleOptions, SyncIdleResult, WindowState } from './client.js';
|
|
23
23
|
import type { SqlRow, SqlValue } from './database.js';
|
|
@@ -107,6 +107,8 @@ export interface WorkerInitConfig {
|
|
|
107
107
|
* Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
|
|
108
108
|
*/
|
|
109
109
|
readonly realtimePolicy?: RealtimePolicy;
|
|
110
|
+
/** SPEC §8.5 heartbeat interval for the worker-owned core; forwarded verbatim. */
|
|
111
|
+
readonly realtimeHeartbeatMs?: number;
|
|
110
112
|
/**
|
|
111
113
|
* RFC 0005 previous-version context, forwarded verbatim into the worker's
|
|
112
114
|
* `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
|
|
@@ -231,9 +233,11 @@ export type SyncWorkerEvent = {
|
|
|
231
233
|
readonly kind: 'upgrading';
|
|
232
234
|
readonly upgrading: boolean;
|
|
233
235
|
} | {
|
|
234
|
-
/** §8.6: presence on a scope key changed
|
|
236
|
+
/** §8.6: presence on a scope key changed, or the server refused this
|
|
237
|
+
* client's publish on it (`error`, §8.6.2). */
|
|
235
238
|
readonly kind: 'presence';
|
|
236
239
|
readonly scopeKey: string;
|
|
240
|
+
readonly error?: PresenceErrorCode | undefined;
|
|
237
241
|
} | {
|
|
238
242
|
/** Exact revisioned core transaction; Sets and bigint clone directly. */
|
|
239
243
|
readonly kind: 'change';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.59.0",
|
|
4
4
|
"description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -89,6 +89,14 @@
|
|
|
89
89
|
"types": "./dist/authority.d.ts",
|
|
90
90
|
"default": "./dist/authority.js"
|
|
91
91
|
}
|
|
92
|
+
},
|
|
93
|
+
"./native-bridge": {
|
|
94
|
+
"bun": "./src/native-bridge.ts",
|
|
95
|
+
"browser": "./dist/native-bridge.js",
|
|
96
|
+
"import": {
|
|
97
|
+
"types": "./dist/native-bridge.d.ts",
|
|
98
|
+
"default": "./dist/native-bridge.js"
|
|
99
|
+
}
|
|
92
100
|
}
|
|
93
101
|
},
|
|
94
102
|
"files": [
|
|
@@ -105,11 +113,11 @@
|
|
|
105
113
|
},
|
|
106
114
|
"dependencies": {
|
|
107
115
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
108
|
-
"@syncular/core": "0.
|
|
116
|
+
"@syncular/core": "0.59.0"
|
|
109
117
|
},
|
|
110
118
|
"devDependencies": {
|
|
111
119
|
"@electric-sql/pglite": "^0.5.4",
|
|
112
|
-
"@syncular/server": "0.
|
|
120
|
+
"@syncular/server": "0.59.0",
|
|
113
121
|
"playwright": "1.63.0",
|
|
114
122
|
"vite": "8.3.4"
|
|
115
123
|
}
|
package/src/apply.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { hasUniqueIndex } from './schema';
|
|
2
|
-
import {
|
|
2
|
+
import { OUTBOX_IMAGES, countOutbox } from './outbox';
|
|
3
3
|
import { RETAINED_ROWS, type OverlayScope } from './failed-overlay';
|
|
4
4
|
import { retainedBaseWrite, restoreFailedBases } from './failed-overlay';
|
|
5
5
|
/**
|
|
@@ -132,7 +132,7 @@ export async function applyCommitFrame(
|
|
|
132
132
|
throw invalidRequest('upsert change without row payload');
|
|
133
133
|
}
|
|
134
134
|
let values = decodeRow(table.columns, change.row);
|
|
135
|
-
if (
|
|
135
|
+
if (table.hasEncryptedColumns) {
|
|
136
136
|
const { decryptRowValues } = await import('./encryption');
|
|
137
137
|
values = await decryptRowValues(encryption, table, values);
|
|
138
138
|
}
|
|
@@ -144,18 +144,19 @@ export async function applyCommitFrame(
|
|
|
144
144
|
});
|
|
145
145
|
}
|
|
146
146
|
transaction(() => {
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
147
|
+
// Exact keys name the rows this frame rebases; unique-key peers widen the
|
|
148
|
+
// replay to the table.
|
|
149
|
+
const scope = resolved.flatMap((change, index) => [
|
|
150
|
+
...(hasUniqueIndex(change.table)
|
|
151
|
+
? [JSON.stringify([change.table.name])]
|
|
152
|
+
: []),
|
|
153
|
+
JSON.stringify([change.table.name, frame.changes[index]!.rowId]),
|
|
154
|
+
]);
|
|
154
155
|
restoreFailedBases(db, schema, scope);
|
|
155
156
|
for (const [index, change] of resolved.entries()) {
|
|
156
157
|
const rowId = frame.changes[index]!.rowId;
|
|
157
158
|
db.exec(
|
|
158
|
-
`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE
|
|
159
|
+
`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`,
|
|
159
160
|
[frame.commitSeq, change.table.name, rowId],
|
|
160
161
|
);
|
|
161
162
|
db.exec(
|
|
@@ -212,15 +213,19 @@ export function validateSegmentColumns(
|
|
|
212
213
|
}
|
|
213
214
|
|
|
214
215
|
/**
|
|
215
|
-
* Scope-matched local delete (§3.3 purge / §5.6 first-page
|
|
216
|
-
* rows whose generated local scope columns match `effective`
|
|
217
|
-
* column value must be in the key's value list
|
|
218
|
-
*
|
|
219
|
-
*
|
|
216
|
+
* Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
|
|
217
|
+
* rule): delete rows whose generated local scope columns match `effective`
|
|
218
|
+
* (every key's column value must be in the key's value list) and that no
|
|
219
|
+
* entry of `owners` matches. `owners` holds the effective scopes of every
|
|
220
|
+
* other active subscription on the table that holds rows; a row one of them
|
|
221
|
+
* still covers is never removed. Fails closed (`sync.scope_revoked`) when
|
|
222
|
+
* the table has no local mapping for a key: precision or nothing, never
|
|
223
|
+
* clear-the-table.
|
|
220
224
|
*/
|
|
221
225
|
export function localScopePredicate(
|
|
222
226
|
table: CompiledClientTable,
|
|
223
227
|
effective: ScopeMap,
|
|
228
|
+
owners: readonly ScopeMap[],
|
|
224
229
|
): { sql: string; params: string[] } | undefined {
|
|
225
230
|
const entries = Object.entries(effective);
|
|
226
231
|
if (!entries.length || entries.some(([, values]) => !values.length)) return;
|
|
@@ -237,7 +242,26 @@ export function localScopePredicate(
|
|
|
237
242
|
return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
|
|
238
243
|
})
|
|
239
244
|
.join(' AND ');
|
|
240
|
-
|
|
245
|
+
const kept = owners.flatMap((owner) => {
|
|
246
|
+
const scope = localScopePredicate(table, owner, []);
|
|
247
|
+
if (scope === undefined) return [];
|
|
248
|
+
params.push(...scope.params);
|
|
249
|
+
return [` AND NOT (${scope.sql})`];
|
|
250
|
+
});
|
|
251
|
+
return { sql: sql + kept.join(''), params };
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/** {@link localScopePredicate} over decoded row values (retained rows). */
|
|
255
|
+
export function ownsLocalRow(
|
|
256
|
+
table: CompiledClientTable,
|
|
257
|
+
effective: ScopeMap,
|
|
258
|
+
owners: readonly ScopeMap[],
|
|
259
|
+
values: Readonly<Record<string, JsonRowValue>>,
|
|
260
|
+
): boolean {
|
|
261
|
+
return (
|
|
262
|
+
matchesLocalScopes(table, effective, values) &&
|
|
263
|
+
!owners.some((owner) => matchesLocalScopes(table, owner, values))
|
|
264
|
+
);
|
|
241
265
|
}
|
|
242
266
|
|
|
243
267
|
function scopedRows(
|
|
@@ -257,8 +281,13 @@ function bootstrapScope(
|
|
|
257
281
|
db: ClientDatabase,
|
|
258
282
|
table: CompiledClientTable,
|
|
259
283
|
effective: ScopeMap,
|
|
284
|
+
owners: readonly ScopeMap[],
|
|
260
285
|
): string[] {
|
|
261
|
-
const rows = scopedRows(
|
|
286
|
+
const rows = scopedRows(
|
|
287
|
+
db,
|
|
288
|
+
table,
|
|
289
|
+
localScopePredicate(table, effective, owners),
|
|
290
|
+
);
|
|
262
291
|
rows.push(
|
|
263
292
|
...db
|
|
264
293
|
.query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
|
|
@@ -268,7 +297,7 @@ function bootstrapScope(
|
|
|
268
297
|
[row.base, row.intent].some(
|
|
269
298
|
(json) =>
|
|
270
299
|
json !== null &&
|
|
271
|
-
|
|
300
|
+
ownsLocalRow(table, effective, owners, JSON.parse(json as string)),
|
|
272
301
|
),
|
|
273
302
|
),
|
|
274
303
|
);
|
|
@@ -279,8 +308,9 @@ export function deleteScopedRows(
|
|
|
279
308
|
db: ClientDatabase,
|
|
280
309
|
table: CompiledClientTable,
|
|
281
310
|
effective: ScopeMap,
|
|
311
|
+
owners: readonly ScopeMap[],
|
|
282
312
|
): void {
|
|
283
|
-
const scope = localScopePredicate(table, effective);
|
|
313
|
+
const scope = localScopePredicate(table, effective, owners);
|
|
284
314
|
if (!scope) return;
|
|
285
315
|
const { sql, params } = scope;
|
|
286
316
|
for (const row of scopedRows(db, table, scope)) {
|
|
@@ -291,8 +321,8 @@ export function deleteScopedRows(
|
|
|
291
321
|
|
|
292
322
|
/**
|
|
293
323
|
* §4.8 window eviction: delete rows matching a departing unit's effective
|
|
294
|
-
* scopes (same local-scope-column rule and fail-closed
|
|
295
|
-
* {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
324
|
+
* scopes (same local-scope-column rule, owner exclusion and fail-closed
|
|
325
|
+
* clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
296
326
|
* `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
|
|
297
327
|
* whether unpinned work remains and whether any scoped rows remain. Each
|
|
298
328
|
* call removes at most 1,024 rows; the caller commits before yielding. Also removes the
|
|
@@ -303,9 +333,10 @@ export function evictScopedRows(
|
|
|
303
333
|
db: ClientDatabase,
|
|
304
334
|
table: CompiledClientTable,
|
|
305
335
|
effective: ScopeMap,
|
|
336
|
+
owners: readonly ScopeMap[],
|
|
306
337
|
pinnedRowIds: ReadonlySet<string>,
|
|
307
338
|
): { remaining: boolean; deferred: boolean } {
|
|
308
|
-
const scope = localScopePredicate(table, effective);
|
|
339
|
+
const scope = localScopePredicate(table, effective, owners);
|
|
309
340
|
if (!scope) return { remaining: false, deferred: false };
|
|
310
341
|
const { sql, params } = scope;
|
|
311
342
|
const pk = quoteIdent(table.primaryKey);
|
|
@@ -325,9 +356,10 @@ export function evictScopedRows(
|
|
|
325
356
|
[row.intent, row.base].some(
|
|
326
357
|
(json) =>
|
|
327
358
|
json !== null &&
|
|
328
|
-
|
|
359
|
+
ownsLocalRow(
|
|
329
360
|
table,
|
|
330
361
|
effective,
|
|
362
|
+
owners,
|
|
331
363
|
JSON.parse(json as string) as Record<string, JsonRowValue>,
|
|
332
364
|
),
|
|
333
365
|
)
|
|
@@ -386,6 +418,8 @@ export async function applySqliteSegment(
|
|
|
386
418
|
options: {
|
|
387
419
|
readonly clearFirst: boolean;
|
|
388
420
|
readonly effective: ScopeMap;
|
|
421
|
+
/** Effective scopes of the other row-holding subscriptions (§5.6). */
|
|
422
|
+
readonly owners: readonly ScopeMap[];
|
|
389
423
|
readonly transaction?: ApplyTransaction;
|
|
390
424
|
readonly onProgress?: (rowsProcessed: number) => void;
|
|
391
425
|
readonly isCurrent?: () => boolean;
|
|
@@ -400,6 +434,9 @@ export async function applySqliteSegment(
|
|
|
400
434
|
if (descriptor.table !== table.name) {
|
|
401
435
|
imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
|
|
402
436
|
}
|
|
437
|
+
// §5.11: an image bypasses the decrypt seam, so a server cannot serve one
|
|
438
|
+
// for a table with encrypted columns.
|
|
439
|
+
if (table.hasEncryptedColumns) imageInvalid('table has encrypted columns');
|
|
403
440
|
return withImage(bytes, IMAGE_ALIAS, async () => {
|
|
404
441
|
// 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
|
|
405
442
|
// SQLite database or lacks the metadata table fails right here.
|
|
@@ -499,19 +536,18 @@ export async function applySqliteSegment(
|
|
|
499
536
|
(options.transaction ?? ((fn) => db.transaction(fn)))(() => {
|
|
500
537
|
const scope = !replay
|
|
501
538
|
? []
|
|
502
|
-
:
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
];
|
|
539
|
+
: [
|
|
540
|
+
...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
|
|
541
|
+
...(after === undefined && options.clearFirst
|
|
542
|
+
? bootstrapScope(db, table, options.effective, options.owners)
|
|
543
|
+
: []),
|
|
544
|
+
...rows.map((row) =>
|
|
545
|
+
JSON.stringify([table.name, String(row[table.primaryKey])]),
|
|
546
|
+
),
|
|
547
|
+
];
|
|
512
548
|
const protectedRows = restoreFailedBases(db, schema, scope);
|
|
513
549
|
if (after === undefined && options.clearFirst)
|
|
514
|
-
deleteScopedRows(db, table, options.effective);
|
|
550
|
+
deleteScopedRows(db, table, options.effective, options.owners);
|
|
515
551
|
db.exec(
|
|
516
552
|
`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${predicates.join(' AND ') || 'true'} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates}`,
|
|
517
553
|
params,
|
|
@@ -561,6 +597,8 @@ export async function applyRowsSegment(
|
|
|
561
597
|
options: {
|
|
562
598
|
readonly clearFirst: boolean;
|
|
563
599
|
readonly effective: ScopeMap;
|
|
600
|
+
/** Effective scopes of the other row-holding subscriptions (§5.6). */
|
|
601
|
+
readonly owners: readonly ScopeMap[];
|
|
564
602
|
readonly transaction?: ApplyTransaction;
|
|
565
603
|
readonly onProgress?: (rowsProcessed: number) => void;
|
|
566
604
|
readonly isCurrent?: () => boolean;
|
|
@@ -579,13 +617,12 @@ export async function applyRowsSegment(
|
|
|
579
617
|
// aborts before any write in this block.
|
|
580
618
|
const rows: { values: readonly RowValue[]; serverVersion: number }[] = [];
|
|
581
619
|
for (const row of block) {
|
|
582
|
-
const values =
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
: row.values;
|
|
620
|
+
const values = table.hasEncryptedColumns
|
|
621
|
+
? await (async () => {
|
|
622
|
+
const { decryptRowValues } = await import('./encryption');
|
|
623
|
+
return decryptRowValues(encryption, table, row.values);
|
|
624
|
+
})()
|
|
625
|
+
: row.values;
|
|
589
626
|
rows.push({ values, serverVersion: row.serverVersion });
|
|
590
627
|
}
|
|
591
628
|
if (options.isCurrent?.() === false) break;
|
|
@@ -593,22 +630,21 @@ export async function applyRowsSegment(
|
|
|
593
630
|
first = false;
|
|
594
631
|
if (!clearThisBlock && rows.length === 0) continue;
|
|
595
632
|
(options.transaction ?? ((fn) => db.transaction(fn)))(() => {
|
|
596
|
-
const scope: OverlayScope =
|
|
597
|
-
? [JSON.stringify([table.name])]
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
];
|
|
633
|
+
const scope: OverlayScope = [
|
|
634
|
+
...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
|
|
635
|
+
...(clearThisBlock
|
|
636
|
+
? bootstrapScope(db, table, options.effective, options.owners)
|
|
637
|
+
: []),
|
|
638
|
+
...rows.map((row) =>
|
|
639
|
+
JSON.stringify([
|
|
640
|
+
table.name,
|
|
641
|
+
String(row.values[table.primaryKeyIndex]),
|
|
642
|
+
]),
|
|
643
|
+
),
|
|
644
|
+
];
|
|
609
645
|
const protectedRows = restoreFailedBases(db, schema, scope);
|
|
610
646
|
if (clearThisBlock) {
|
|
611
|
-
deleteScopedRows(db, table, options.effective);
|
|
647
|
+
deleteScopedRows(db, table, options.effective, options.owners);
|
|
612
648
|
}
|
|
613
649
|
for (const row of rows) {
|
|
614
650
|
upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
|
package/src/blob.ts
CHANGED
|
@@ -42,22 +42,33 @@ export type BlobUploadGrant =
|
|
|
42
42
|
| { readonly kind: 'present' }
|
|
43
43
|
| { readonly kind: 'none' };
|
|
44
44
|
|
|
45
|
-
/**
|
|
45
|
+
/**
|
|
46
|
+
* The transport seam for blob upload/download (§5.9.3/§5.9.5). The upload
|
|
47
|
+
* calls receive the round's `signal`, which aborts when the `syncUntilIdle`
|
|
48
|
+
* deadline elapses (§7.7).
|
|
49
|
+
*/
|
|
46
50
|
export interface BlobTransport {
|
|
47
51
|
/** `PUT <mount>/blobs/{blobId}` — host-authenticated direct upload (§5.9.3). */
|
|
48
|
-
upload(
|
|
52
|
+
upload(
|
|
53
|
+
blobId: string,
|
|
54
|
+
bytes: Uint8Array,
|
|
55
|
+
mediaType?: string,
|
|
56
|
+
signal?: AbortSignal,
|
|
57
|
+
): Promise<void>;
|
|
49
58
|
/**
|
|
50
59
|
* `GET <mount>/blobs/{blobId}` — re-authorized (§5.9.5). Returns inline
|
|
51
60
|
* bytes, or a presigned `url` the client core fetches via `fetchUrl`.
|
|
61
|
+
* `byteLength` is the BlobRef's declared size when the caller passed one;
|
|
62
|
+
* reading inline bytes stops once the body exceeds it.
|
|
52
63
|
*/
|
|
53
|
-
download(blobId: string): Promise<BlobDownloadResponse>;
|
|
64
|
+
download(blobId: string, byteLength?: number): Promise<BlobDownloadResponse>;
|
|
54
65
|
/**
|
|
55
66
|
* §5.9.5 presigned-download fetch: a bare GET of the signed `url`. Present
|
|
56
67
|
* iff the transport can consume URLs. MUST attach NO host authentication —
|
|
57
68
|
* the URL is the entire grant (§5.4). Only called when `download` returned
|
|
58
|
-
* a `url` arm.
|
|
69
|
+
* a `url` arm. Reading stops once the body exceeds `byteLength`.
|
|
59
70
|
*/
|
|
60
|
-
fetchUrl?(url: string): Promise<Uint8Array>;
|
|
71
|
+
fetchUrl?(url: string, byteLength?: number): Promise<Uint8Array>;
|
|
61
72
|
/**
|
|
62
73
|
* §5.9.3 presigned-upload grant: `POST /blobs/{blobId}/upload-grant` with
|
|
63
74
|
* the declared size. Present iff the transport supports the grant flow;
|
|
@@ -68,16 +79,20 @@ export interface BlobTransport {
|
|
|
68
79
|
blobId: string,
|
|
69
80
|
byteLength: number,
|
|
70
81
|
mediaType?: string,
|
|
82
|
+
signal?: AbortSignal,
|
|
71
83
|
): Promise<BlobUploadGrant>;
|
|
72
84
|
/**
|
|
73
85
|
* §5.9.3 direct-to-storage PUT of the granted `url`. MUST attach NO host
|
|
74
|
-
* authentication — the presigned URL is the entire grant (§5.4)
|
|
75
|
-
*
|
|
86
|
+
* authentication — the presigned URL is the entire grant (§5.4) — and MUST
|
|
87
|
+
* send `x-amz-checksum-sha256` (base64 of the body's SHA-256), which the
|
|
88
|
+
* grant signs beside `content-length`. Only called when `uploadGrant`
|
|
89
|
+
* returned a `url` arm.
|
|
76
90
|
*/
|
|
77
91
|
uploadToUrl?(
|
|
78
92
|
url: string,
|
|
79
93
|
bytes: Uint8Array,
|
|
80
94
|
mediaType?: string,
|
|
95
|
+
signal?: AbortSignal,
|
|
81
96
|
): Promise<void>;
|
|
82
97
|
}
|
|
83
98
|
|
|
@@ -188,7 +203,7 @@ export function enforceBlobCacheCap(
|
|
|
188
203
|
if (total <= maxBytes) return [];
|
|
189
204
|
// Oldest eligible body first, with blob ID as a stable tie.
|
|
190
205
|
const candidates = db.query(
|
|
191
|
-
`SELECT blob_id,byte_length
|
|
206
|
+
`SELECT blob_id,byte_length ${unreferencedBlobsSql(schema)}ORDER BY created_at_ms ASC,blob_id ASC`,
|
|
192
207
|
);
|
|
193
208
|
const evicted: string[] = [];
|
|
194
209
|
db.transaction(() => {
|
|
@@ -266,7 +281,8 @@ export function schemaHasBlobs(schema: CompiledClientSchema): boolean {
|
|
|
266
281
|
return false;
|
|
267
282
|
}
|
|
268
283
|
|
|
269
|
-
|
|
284
|
+
/** The cached bodies no upload, pending commit, or visible row references. */
|
|
285
|
+
function unreferencedBlobsSql(schema: CompiledClientSchema): string {
|
|
270
286
|
const selects: string[] = [];
|
|
271
287
|
for (const [tableName, columns] of blobRefColumnsBySchema(schema)) {
|
|
272
288
|
for (const column of columns) {
|
|
@@ -276,18 +292,14 @@ function visibleBlobIdsSql(schema: CompiledClientSchema): string {
|
|
|
276
292
|
);
|
|
277
293
|
}
|
|
278
294
|
}
|
|
279
|
-
return selects.length === 0
|
|
280
|
-
? 'SELECT NULL AS blob_id WHERE 0'
|
|
281
|
-
: selects.join(' UNION ');
|
|
295
|
+
return `FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${selects.length === 0 ? 'SELECT NULL AS blob_id WHERE 0' : selects.join(' UNION ')})`;
|
|
282
296
|
}
|
|
283
297
|
|
|
284
298
|
export function deleteUnreferencedCachedBlobs(
|
|
285
299
|
db: ClientDatabase,
|
|
286
300
|
schema: CompiledClientSchema,
|
|
287
301
|
): void {
|
|
288
|
-
db.exec(
|
|
289
|
-
`DELETE FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${visibleBlobIdsSql(schema)})`,
|
|
290
|
-
);
|
|
302
|
+
db.exec(`DELETE ${unreferencedBlobsSql(schema)}`);
|
|
291
303
|
}
|
|
292
304
|
|
|
293
305
|
export type { BlobRef };
|
package/src/bun-database.ts
CHANGED
|
@@ -15,6 +15,7 @@ import {
|
|
|
15
15
|
type SqlRow,
|
|
16
16
|
type SqlValue,
|
|
17
17
|
} from './database';
|
|
18
|
+
import { prepareReadOnly, refuseRawSql } from './query-guard';
|
|
18
19
|
|
|
19
20
|
declare module 'bun:sqlite' {
|
|
20
21
|
interface Database {
|
|
@@ -64,6 +65,34 @@ export class BunClientDatabase implements ClientDatabase {
|
|
|
64
65
|
return this.db.query(sql).all(...coerceParams(params)) as SqlRow[];
|
|
65
66
|
}
|
|
66
67
|
|
|
68
|
+
queryReadOnly(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
|
|
69
|
+
const statement = prepareReadOnly(sql, () => {
|
|
70
|
+
const prepared = this.db.query(sql);
|
|
71
|
+
// bun:sqlite exposes no `sqlite3_sql`, so the first statement ends at
|
|
72
|
+
// the first `;` outside literals, identifiers and comments.
|
|
73
|
+
return [
|
|
74
|
+
prepared,
|
|
75
|
+
/^(?:'[^']*'|"[^"]*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|[^;])*/.exec(
|
|
76
|
+
sql,
|
|
77
|
+
)![0],
|
|
78
|
+
prepared.columnNames.length > 0,
|
|
79
|
+
] as const;
|
|
80
|
+
});
|
|
81
|
+
// bun:sqlite exposes `sqlite3_stmt_readonly` only from Bun 1.4.4, so
|
|
82
|
+
// SQLite refuses a write when the statement runs: under `query_only` a
|
|
83
|
+
// write transaction fails before it changes anything.
|
|
84
|
+
this.db.run('PRAGMA query_only = ON');
|
|
85
|
+
try {
|
|
86
|
+
return statement.all(...coerceParams(params)) as SqlRow[];
|
|
87
|
+
} catch (error) {
|
|
88
|
+
if ((error as { code?: unknown }).code === 'SQLITE_READONLY')
|
|
89
|
+
refuseRawSql();
|
|
90
|
+
throw error;
|
|
91
|
+
} finally {
|
|
92
|
+
this.db.run('PRAGMA query_only = OFF');
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
67
96
|
/** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
|
|
68
97
|
openSibling(name: string): SiblingDatabase {
|
|
69
98
|
const siblingPath =
|