@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/README.md
CHANGED
|
@@ -14,9 +14,9 @@ server-authoritative commands, and live query watches through the remote
|
|
|
14
14
|
operation transport. See [remote server operations](https://syncular.dev/guide-remote-operations/).
|
|
15
15
|
Its schema and sync transport are optional for query-only or command-only
|
|
16
16
|
processes.
|
|
17
|
-
|
|
18
|
-
partition
|
|
19
|
-
|
|
17
|
+
Without a `logEpoch`, the first `prepareCommit` sends one empty pull to learn
|
|
18
|
+
the partition log epoch and binds every later commit to it; set `logEpoch` in
|
|
19
|
+
the constructor to skip that round.
|
|
20
20
|
|
|
21
21
|
Applied and cached acknowledgements drain the send queue while protected local
|
|
22
22
|
intent stays visible until the same row's server image arrives at that commit
|
|
@@ -315,8 +315,8 @@ stable code-like values (`A-Z`, `a-z`, `0-9`, dot, underscore, dash).
|
|
|
315
315
|
During Vite development, retain the React client resource only while its
|
|
316
316
|
captured generated schema version and published Syncular runtime identity both
|
|
317
317
|
match. The
|
|
318
|
-
[schema-and-runtime-aware Vite guide](https://syncular.dev/platform-web-
|
|
319
|
-
`
|
|
318
|
+
[schema-and-runtime-aware Vite guide](https://syncular.dev/platform-web-realtime/#keep-one-owner-during-hmr) uses
|
|
319
|
+
`createViteSyncClientResource` to close the old worker before constructing a
|
|
320
320
|
schema-bump or package-upgrade replacement; hot-reloading query code alone does
|
|
321
321
|
not migrate the worker-owned database.
|
|
322
322
|
|
|
@@ -740,8 +740,8 @@ bun run build:packages && bun run verify:packages
|
|
|
740
740
|
|
|
741
741
|
`init`, `call`, `ready`, `result`, `error`, `event` — every API method
|
|
742
742
|
multiplexes over `call` (typed end-to-end from the single `WorkerApi`
|
|
743
|
-
shape in `worker-protocol.ts`); `event` carries `sync-needed`,
|
|
744
|
-
`
|
|
743
|
+
shape in `worker-protocol.ts`); `event` carries `progress`, `sync-needed`,
|
|
744
|
+
`conflict`, `synced`, `upgrading`, `presence`, `change` and `diagnostics`. Query-result blobs transfer (not copy) when
|
|
745
745
|
they own their buffer.
|
|
746
746
|
|
|
747
747
|
## Package layout
|
package/dist/apply.d.ts
CHANGED
|
@@ -7,7 +7,7 @@ import { type OverlayScope } from './failed-overlay.js';
|
|
|
7
7
|
import { type CommitFrame, type RowsSegment, type RowValue, type ScopeMap } from '@syncular/core';
|
|
8
8
|
import type { ClientDatabase } from './database.js';
|
|
9
9
|
import type { EncryptionConfig } from './encryption.js';
|
|
10
|
-
import { type CompiledClientSchema, type CompiledClientTable } from './schema.js';
|
|
10
|
+
import { type CompiledClientSchema, type CompiledClientTable, type JsonRowValue } from './schema.js';
|
|
11
11
|
/** Lets the client wrap the physical write in its revision transaction. */
|
|
12
12
|
export type ApplyTransaction = (fn: () => OverlayScope) => unknown;
|
|
13
13
|
export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean): void;
|
|
@@ -32,28 +32,33 @@ export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledCli
|
|
|
32
32
|
*/
|
|
33
33
|
export declare function validateSegmentColumns(schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment): void;
|
|
34
34
|
/**
|
|
35
|
-
* Scope-matched local delete (§3.3 purge / §5.6 first-page
|
|
36
|
-
* rows whose generated local scope columns match `effective`
|
|
37
|
-
* column value must be in the key's value list
|
|
38
|
-
*
|
|
39
|
-
*
|
|
35
|
+
* Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
|
|
36
|
+
* rule): delete rows whose generated local scope columns match `effective`
|
|
37
|
+
* (every key's column value must be in the key's value list) and that no
|
|
38
|
+
* entry of `owners` matches. `owners` holds the effective scopes of every
|
|
39
|
+
* other active subscription on the table that holds rows; a row one of them
|
|
40
|
+
* still covers is never removed. Fails closed (`sync.scope_revoked`) when
|
|
41
|
+
* the table has no local mapping for a key: precision or nothing, never
|
|
42
|
+
* clear-the-table.
|
|
40
43
|
*/
|
|
41
|
-
export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap): {
|
|
44
|
+
export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): {
|
|
42
45
|
sql: string;
|
|
43
46
|
params: string[];
|
|
44
47
|
} | undefined;
|
|
45
|
-
|
|
48
|
+
/** {@link localScopePredicate} over decoded row values (retained rows). */
|
|
49
|
+
export declare function ownsLocalRow(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], values: Readonly<Record<string, JsonRowValue>>): boolean;
|
|
50
|
+
export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): void;
|
|
46
51
|
/**
|
|
47
52
|
* §4.8 window eviction: delete rows matching a departing unit's effective
|
|
48
|
-
* scopes (same local-scope-column rule and fail-closed
|
|
49
|
-
* {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
53
|
+
* scopes (same local-scope-column rule, owner exclusion and fail-closed
|
|
54
|
+
* clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
50
55
|
* `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
|
|
51
56
|
* whether unpinned work remains and whether any scoped rows remain. Each
|
|
52
57
|
* call removes at most 1,024 rows; the caller commits before yielding. Also removes the
|
|
53
58
|
* evicted rows' `server_version` with them (E2 — no residual version
|
|
54
59
|
* cache), which is automatic since the version column is per-row.
|
|
55
60
|
*/
|
|
56
|
-
export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, pinnedRowIds: ReadonlySet<string>): {
|
|
61
|
+
export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], pinnedRowIds: ReadonlySet<string>): {
|
|
57
62
|
remaining: boolean;
|
|
58
63
|
deferred: boolean;
|
|
59
64
|
};
|
|
@@ -75,6 +80,8 @@ export interface SqliteSegmentDescriptor {
|
|
|
75
80
|
export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
|
|
76
81
|
readonly clearFirst: boolean;
|
|
77
82
|
readonly effective: ScopeMap;
|
|
83
|
+
/** Effective scopes of the other row-holding subscriptions (§5.6). */
|
|
84
|
+
readonly owners: readonly ScopeMap[];
|
|
78
85
|
readonly transaction?: ApplyTransaction;
|
|
79
86
|
readonly onProgress?: (rowsProcessed: number) => void;
|
|
80
87
|
readonly isCurrent?: () => boolean;
|
|
@@ -90,6 +97,8 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
|
|
|
90
97
|
export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
|
|
91
98
|
readonly clearFirst: boolean;
|
|
92
99
|
readonly effective: ScopeMap;
|
|
100
|
+
/** Effective scopes of the other row-holding subscriptions (§5.6). */
|
|
101
|
+
readonly owners: readonly ScopeMap[];
|
|
93
102
|
readonly transaction?: ApplyTransaction;
|
|
94
103
|
readonly onProgress?: (rowsProcessed: number) => void;
|
|
95
104
|
readonly isCurrent?: () => boolean;
|
package/dist/apply.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { hasUniqueIndex } from './schema.js';
|
|
2
|
-
import {
|
|
2
|
+
import { OUTBOX_IMAGES, countOutbox } from './outbox.js';
|
|
3
3
|
import { RETAINED_ROWS } from './failed-overlay.js';
|
|
4
4
|
import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
|
|
5
5
|
/**
|
|
@@ -66,7 +66,7 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
|
|
|
66
66
|
throw invalidRequest('upsert change without row payload');
|
|
67
67
|
}
|
|
68
68
|
let values = decodeRow(table.columns, change.row);
|
|
69
|
-
if (
|
|
69
|
+
if (table.hasEncryptedColumns) {
|
|
70
70
|
const { decryptRowValues } = await import('./encryption.js');
|
|
71
71
|
values = await decryptRowValues(encryption, table, values);
|
|
72
72
|
}
|
|
@@ -78,13 +78,18 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
|
|
|
78
78
|
});
|
|
79
79
|
}
|
|
80
80
|
transaction(() => {
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
81
|
+
// Exact keys name the rows this frame rebases; unique-key peers widen the
|
|
82
|
+
// replay to the table.
|
|
83
|
+
const scope = resolved.flatMap((change, index) => [
|
|
84
|
+
...(hasUniqueIndex(change.table)
|
|
85
|
+
? [JSON.stringify([change.table.name])]
|
|
86
|
+
: []),
|
|
87
|
+
JSON.stringify([change.table.name, frame.changes[index].rowId]),
|
|
88
|
+
]);
|
|
84
89
|
restoreFailedBases(db, schema, scope);
|
|
85
90
|
for (const [index, change] of resolved.entries()) {
|
|
86
91
|
const rowId = frame.changes[index].rowId;
|
|
87
|
-
db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE
|
|
92
|
+
db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`, [frame.commitSeq, change.table.name, rowId]);
|
|
88
93
|
db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
|
|
89
94
|
if (change.op === 'delete') {
|
|
90
95
|
deleteLocalRow(db, change.table, change.rowId);
|
|
@@ -127,13 +132,16 @@ export function validateSegmentColumns(schema, table, segment) {
|
|
|
127
132
|
}
|
|
128
133
|
}
|
|
129
134
|
/**
|
|
130
|
-
* Scope-matched local delete (§3.3 purge / §5.6 first-page
|
|
131
|
-
* rows whose generated local scope columns match `effective`
|
|
132
|
-
* column value must be in the key's value list
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
+
* Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
|
|
136
|
+
* rule): delete rows whose generated local scope columns match `effective`
|
|
137
|
+
* (every key's column value must be in the key's value list) and that no
|
|
138
|
+
* entry of `owners` matches. `owners` holds the effective scopes of every
|
|
139
|
+
* other active subscription on the table that holds rows; a row one of them
|
|
140
|
+
* still covers is never removed. Fails closed (`sync.scope_revoked`) when
|
|
141
|
+
* the table has no local mapping for a key: precision or nothing, never
|
|
142
|
+
* clear-the-table.
|
|
135
143
|
*/
|
|
136
|
-
export function localScopePredicate(table, effective) {
|
|
144
|
+
export function localScopePredicate(table, effective, owners) {
|
|
137
145
|
const entries = Object.entries(effective);
|
|
138
146
|
if (!entries.length || entries.some(([, values]) => !values.length))
|
|
139
147
|
return;
|
|
@@ -147,25 +155,37 @@ export function localScopePredicate(table, effective) {
|
|
|
147
155
|
return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
|
|
148
156
|
})
|
|
149
157
|
.join(' AND ');
|
|
150
|
-
|
|
158
|
+
const kept = owners.flatMap((owner) => {
|
|
159
|
+
const scope = localScopePredicate(table, owner, []);
|
|
160
|
+
if (scope === undefined)
|
|
161
|
+
return [];
|
|
162
|
+
params.push(...scope.params);
|
|
163
|
+
return [` AND NOT (${scope.sql})`];
|
|
164
|
+
});
|
|
165
|
+
return { sql: sql + kept.join(''), params };
|
|
166
|
+
}
|
|
167
|
+
/** {@link localScopePredicate} over decoded row values (retained rows). */
|
|
168
|
+
export function ownsLocalRow(table, effective, owners, values) {
|
|
169
|
+
return (matchesLocalScopes(table, effective, values) &&
|
|
170
|
+
!owners.some((owner) => matchesLocalScopes(table, owner, values)));
|
|
151
171
|
}
|
|
152
172
|
function scopedRows(db, table, scope) {
|
|
153
173
|
return scope
|
|
154
174
|
? db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${scope.sql}`, scope.params)
|
|
155
175
|
: [];
|
|
156
176
|
}
|
|
157
|
-
function bootstrapScope(db, table, effective) {
|
|
158
|
-
const rows = scopedRows(db, table, localScopePredicate(table, effective));
|
|
177
|
+
function bootstrapScope(db, table, effective, owners) {
|
|
178
|
+
const rows = scopedRows(db, table, localScopePredicate(table, effective, owners));
|
|
159
179
|
rows.push(...db
|
|
160
180
|
.query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
|
|
161
181
|
table.name,
|
|
162
182
|
])
|
|
163
183
|
.filter((row) => [row.base, row.intent].some((json) => json !== null &&
|
|
164
|
-
|
|
184
|
+
ownsLocalRow(table, effective, owners, JSON.parse(json)))));
|
|
165
185
|
return rows.map((row) => JSON.stringify([table.name, String(row.id)]));
|
|
166
186
|
}
|
|
167
|
-
export function deleteScopedRows(db, table, effective) {
|
|
168
|
-
const scope = localScopePredicate(table, effective);
|
|
187
|
+
export function deleteScopedRows(db, table, effective, owners) {
|
|
188
|
+
const scope = localScopePredicate(table, effective, owners);
|
|
169
189
|
if (!scope)
|
|
170
190
|
return;
|
|
171
191
|
const { sql, params } = scope;
|
|
@@ -176,16 +196,16 @@ export function deleteScopedRows(db, table, effective) {
|
|
|
176
196
|
}
|
|
177
197
|
/**
|
|
178
198
|
* §4.8 window eviction: delete rows matching a departing unit's effective
|
|
179
|
-
* scopes (same local-scope-column rule and fail-closed
|
|
180
|
-
* {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
199
|
+
* scopes (same local-scope-column rule, owner exclusion and fail-closed
|
|
200
|
+
* clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
181
201
|
* `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
|
|
182
202
|
* whether unpinned work remains and whether any scoped rows remain. Each
|
|
183
203
|
* call removes at most 1,024 rows; the caller commits before yielding. Also removes the
|
|
184
204
|
* evicted rows' `server_version` with them (E2 — no residual version
|
|
185
205
|
* cache), which is automatic since the version column is per-row.
|
|
186
206
|
*/
|
|
187
|
-
export function evictScopedRows(db, table, effective, pinnedRowIds) {
|
|
188
|
-
const scope = localScopePredicate(table, effective);
|
|
207
|
+
export function evictScopedRows(db, table, effective, owners, pinnedRowIds) {
|
|
208
|
+
const scope = localScopePredicate(table, effective, owners);
|
|
189
209
|
if (!scope)
|
|
190
210
|
return { remaining: false, deferred: false };
|
|
191
211
|
const { sql, params } = scope;
|
|
@@ -200,7 +220,7 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
|
|
|
200
220
|
for (const row of db.query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl=?`, [table.name])) {
|
|
201
221
|
if (!pinnedRowIds.has(row.id) &&
|
|
202
222
|
[row.intent, row.base].some((json) => json !== null &&
|
|
203
|
-
|
|
223
|
+
ownsLocalRow(table, effective, owners, JSON.parse(json))))
|
|
204
224
|
db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq IS NOT NULL`, [table.name, row.id]);
|
|
205
225
|
}
|
|
206
226
|
db.exec(`DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1024)`, params);
|
|
@@ -229,6 +249,10 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
229
249
|
if (descriptor.table !== table.name) {
|
|
230
250
|
imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
|
|
231
251
|
}
|
|
252
|
+
// §5.11: an image bypasses the decrypt seam, so a server cannot serve one
|
|
253
|
+
// for a table with encrypted columns.
|
|
254
|
+
if (table.hasEncryptedColumns)
|
|
255
|
+
imageInvalid('table has encrypted columns');
|
|
232
256
|
return withImage(bytes, IMAGE_ALIAS, async () => {
|
|
233
257
|
// 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
|
|
234
258
|
// SQLite database or lacks the metadata table fails right here.
|
|
@@ -314,17 +338,16 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
314
338
|
(options.transaction ?? ((fn) => db.transaction(fn)))(() => {
|
|
315
339
|
const scope = !replay
|
|
316
340
|
? []
|
|
317
|
-
:
|
|
318
|
-
? [JSON.stringify([table.name])]
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
];
|
|
341
|
+
: [
|
|
342
|
+
...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
|
|
343
|
+
...(after === undefined && options.clearFirst
|
|
344
|
+
? bootstrapScope(db, table, options.effective, options.owners)
|
|
345
|
+
: []),
|
|
346
|
+
...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
|
|
347
|
+
];
|
|
325
348
|
const protectedRows = restoreFailedBases(db, schema, scope);
|
|
326
349
|
if (after === undefined && options.clearFirst)
|
|
327
|
-
deleteScopedRows(db, table, options.effective);
|
|
350
|
+
deleteScopedRows(db, table, options.effective, options.owners);
|
|
328
351
|
db.exec(`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}`, params);
|
|
329
352
|
applied += Number(db.query('SELECT changes()AS n')[0]?.n ?? 0);
|
|
330
353
|
if (protectedRows)
|
|
@@ -368,7 +391,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
|
|
|
368
391
|
// aborts before any write in this block.
|
|
369
392
|
const rows = [];
|
|
370
393
|
for (const row of block) {
|
|
371
|
-
const values =
|
|
394
|
+
const values = table.hasEncryptedColumns
|
|
372
395
|
? await (async () => {
|
|
373
396
|
const { decryptRowValues } = await import('./encryption.js');
|
|
374
397
|
return decryptRowValues(encryption, table, row.values);
|
|
@@ -383,20 +406,19 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
|
|
|
383
406
|
if (!clearThisBlock && rows.length === 0)
|
|
384
407
|
continue;
|
|
385
408
|
(options.transaction ?? ((fn) => db.transaction(fn)))(() => {
|
|
386
|
-
const scope =
|
|
387
|
-
? [JSON.stringify([table.name])]
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
];
|
|
409
|
+
const scope = [
|
|
410
|
+
...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
|
|
411
|
+
...(clearThisBlock
|
|
412
|
+
? bootstrapScope(db, table, options.effective, options.owners)
|
|
413
|
+
: []),
|
|
414
|
+
...rows.map((row) => JSON.stringify([
|
|
415
|
+
table.name,
|
|
416
|
+
String(row.values[table.primaryKeyIndex]),
|
|
417
|
+
])),
|
|
418
|
+
];
|
|
397
419
|
const protectedRows = restoreFailedBases(db, schema, scope);
|
|
398
420
|
if (clearThisBlock) {
|
|
399
|
-
deleteScopedRows(db, table, options.effective);
|
|
421
|
+
deleteScopedRows(db, table, options.effective, options.owners);
|
|
400
422
|
}
|
|
401
423
|
for (const row of rows) {
|
|
402
424
|
upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
|
package/dist/blob.d.ts
CHANGED
|
@@ -39,35 +39,43 @@ export type BlobUploadGrant = {
|
|
|
39
39
|
} | {
|
|
40
40
|
readonly kind: 'none';
|
|
41
41
|
};
|
|
42
|
-
/**
|
|
42
|
+
/**
|
|
43
|
+
* The transport seam for blob upload/download (§5.9.3/§5.9.5). The upload
|
|
44
|
+
* calls receive the round's `signal`, which aborts when the `syncUntilIdle`
|
|
45
|
+
* deadline elapses (§7.7).
|
|
46
|
+
*/
|
|
43
47
|
export interface BlobTransport {
|
|
44
48
|
/** `PUT <mount>/blobs/{blobId}` — host-authenticated direct upload (§5.9.3). */
|
|
45
|
-
upload(blobId: string, bytes: Uint8Array, mediaType?: string): Promise<void>;
|
|
49
|
+
upload(blobId: string, bytes: Uint8Array, mediaType?: string, signal?: AbortSignal): Promise<void>;
|
|
46
50
|
/**
|
|
47
51
|
* `GET <mount>/blobs/{blobId}` — re-authorized (§5.9.5). Returns inline
|
|
48
52
|
* bytes, or a presigned `url` the client core fetches via `fetchUrl`.
|
|
53
|
+
* `byteLength` is the BlobRef's declared size when the caller passed one;
|
|
54
|
+
* reading inline bytes stops once the body exceeds it.
|
|
49
55
|
*/
|
|
50
|
-
download(blobId: string): Promise<BlobDownloadResponse>;
|
|
56
|
+
download(blobId: string, byteLength?: number): Promise<BlobDownloadResponse>;
|
|
51
57
|
/**
|
|
52
58
|
* §5.9.5 presigned-download fetch: a bare GET of the signed `url`. Present
|
|
53
59
|
* iff the transport can consume URLs. MUST attach NO host authentication —
|
|
54
60
|
* the URL is the entire grant (§5.4). Only called when `download` returned
|
|
55
|
-
* a `url` arm.
|
|
61
|
+
* a `url` arm. Reading stops once the body exceeds `byteLength`.
|
|
56
62
|
*/
|
|
57
|
-
fetchUrl?(url: string): Promise<Uint8Array>;
|
|
63
|
+
fetchUrl?(url: string, byteLength?: number): Promise<Uint8Array>;
|
|
58
64
|
/**
|
|
59
65
|
* §5.9.3 presigned-upload grant: `POST /blobs/{blobId}/upload-grant` with
|
|
60
66
|
* the declared size. Present iff the transport supports the grant flow;
|
|
61
67
|
* absent ⇒ the client always streams through `upload`. A `url` grant is
|
|
62
68
|
* PUT via `uploadToUrl`.
|
|
63
69
|
*/
|
|
64
|
-
uploadGrant?(blobId: string, byteLength: number, mediaType?: string): Promise<BlobUploadGrant>;
|
|
70
|
+
uploadGrant?(blobId: string, byteLength: number, mediaType?: string, signal?: AbortSignal): Promise<BlobUploadGrant>;
|
|
65
71
|
/**
|
|
66
72
|
* §5.9.3 direct-to-storage PUT of the granted `url`. MUST attach NO host
|
|
67
|
-
* authentication — the presigned URL is the entire grant (§5.4)
|
|
68
|
-
*
|
|
73
|
+
* authentication — the presigned URL is the entire grant (§5.4) — and MUST
|
|
74
|
+
* send `x-amz-checksum-sha256` (base64 of the body's SHA-256), which the
|
|
75
|
+
* grant signs beside `content-length`. Only called when `uploadGrant`
|
|
76
|
+
* returned a `url` arm.
|
|
69
77
|
*/
|
|
70
|
-
uploadToUrl?(url: string, bytes: Uint8Array, mediaType?: string): Promise<void>;
|
|
78
|
+
uploadToUrl?(url: string, bytes: Uint8Array, mediaType?: string, signal?: AbortSignal): Promise<void>;
|
|
71
79
|
}
|
|
72
80
|
export interface CachedBlob {
|
|
73
81
|
readonly blobId: string;
|
package/dist/blob.js
CHANGED
|
@@ -71,7 +71,7 @@ export function enforceBlobCacheCap(db, schema, maxBytes) {
|
|
|
71
71
|
if (total <= maxBytes)
|
|
72
72
|
return [];
|
|
73
73
|
// Oldest eligible body first, with blob ID as a stable tie.
|
|
74
|
-
const candidates = db.query(`SELECT blob_id,byte_length
|
|
74
|
+
const candidates = db.query(`SELECT blob_id,byte_length ${unreferencedBlobsSql(schema)}ORDER BY created_at_ms ASC,blob_id ASC`);
|
|
75
75
|
const evicted = [];
|
|
76
76
|
db.transaction(() => {
|
|
77
77
|
for (const row of candidates) {
|
|
@@ -126,7 +126,8 @@ export function schemaHasBlobs(schema) {
|
|
|
126
126
|
}
|
|
127
127
|
return false;
|
|
128
128
|
}
|
|
129
|
-
|
|
129
|
+
/** The cached bodies no upload, pending commit, or visible row references. */
|
|
130
|
+
function unreferencedBlobsSql(schema) {
|
|
130
131
|
const selects = [];
|
|
131
132
|
for (const [tableName, columns] of blobRefColumnsBySchema(schema)) {
|
|
132
133
|
for (const column of columns) {
|
|
@@ -134,11 +135,9 @@ function visibleBlobIdsSql(schema) {
|
|
|
134
135
|
selects.push(`SELECT json_extract(${identifier},'$.blobId')AS blob_id FROM ${quoteIdent(tableName)} WHERE typeof(${identifier})='text' AND json_valid(${identifier})AND json_type(${identifier},'$.blobId')='text'`);
|
|
135
136
|
}
|
|
136
137
|
}
|
|
137
|
-
return selects.length === 0
|
|
138
|
-
? 'SELECT NULL AS blob_id WHERE 0'
|
|
139
|
-
: selects.join(' UNION ');
|
|
138
|
+
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 ')})`;
|
|
140
139
|
}
|
|
141
140
|
export function deleteUnreferencedCachedBlobs(db, schema) {
|
|
142
|
-
db.exec(`DELETE
|
|
141
|
+
db.exec(`DELETE ${unreferencedBlobsSql(schema)}`);
|
|
143
142
|
}
|
|
144
143
|
export { parseBlobRef, serializeBlobRef };
|
package/dist/bun-database.d.ts
CHANGED
|
@@ -16,6 +16,7 @@ export declare class BunClientDatabase implements ClientDatabase {
|
|
|
16
16
|
constructor(path?: string);
|
|
17
17
|
exec(sql: string, params?: readonly SqlValue[]): void;
|
|
18
18
|
query(sql: string, params?: readonly SqlValue[]): SqlRow[];
|
|
19
|
+
queryReadOnly(sql: string, params?: readonly SqlValue[]): SqlRow[];
|
|
19
20
|
/** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
|
|
20
21
|
openSibling(name: string): SiblingDatabase;
|
|
21
22
|
siblingExists(name: string): boolean;
|
package/dist/bun-database.js
CHANGED
|
@@ -8,6 +8,7 @@ import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
|
|
|
8
8
|
import { tmpdir } from 'node:os';
|
|
9
9
|
import { join } from 'node:path';
|
|
10
10
|
import { assertImageAlias, runTransaction, } from './database.js';
|
|
11
|
+
import { prepareReadOnly, refuseRawSql } from './query-guard.js';
|
|
11
12
|
function coerceParams(params) {
|
|
12
13
|
return params.map((value) => {
|
|
13
14
|
if (typeof value === 'boolean')
|
|
@@ -45,6 +46,33 @@ export class BunClientDatabase {
|
|
|
45
46
|
query(sql, params = []) {
|
|
46
47
|
return this.db.query(sql).all(...coerceParams(params));
|
|
47
48
|
}
|
|
49
|
+
queryReadOnly(sql, params = []) {
|
|
50
|
+
const statement = prepareReadOnly(sql, () => {
|
|
51
|
+
const prepared = this.db.query(sql);
|
|
52
|
+
// bun:sqlite exposes no `sqlite3_sql`, so the first statement ends at
|
|
53
|
+
// the first `;` outside literals, identifiers and comments.
|
|
54
|
+
return [
|
|
55
|
+
prepared,
|
|
56
|
+
/^(?:'[^']*'|"[^"]*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|[^;])*/.exec(sql)[0],
|
|
57
|
+
prepared.columnNames.length > 0,
|
|
58
|
+
];
|
|
59
|
+
});
|
|
60
|
+
// bun:sqlite exposes `sqlite3_stmt_readonly` only from Bun 1.4.4, so
|
|
61
|
+
// SQLite refuses a write when the statement runs: under `query_only` a
|
|
62
|
+
// write transaction fails before it changes anything.
|
|
63
|
+
this.db.run('PRAGMA query_only = ON');
|
|
64
|
+
try {
|
|
65
|
+
return statement.all(...coerceParams(params));
|
|
66
|
+
}
|
|
67
|
+
catch (error) {
|
|
68
|
+
if (error.code === 'SQLITE_READONLY')
|
|
69
|
+
refuseRawSql();
|
|
70
|
+
throw error;
|
|
71
|
+
}
|
|
72
|
+
finally {
|
|
73
|
+
this.db.run('PRAGMA query_only = OFF');
|
|
74
|
+
}
|
|
75
|
+
}
|
|
48
76
|
/** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
|
|
49
77
|
openSibling(name) {
|
|
50
78
|
const siblingPath = this.#path === ':memory:' ? ':memory:' : `${this.#path}.${name}`;
|
package/dist/client.d.ts
CHANGED
|
@@ -9,7 +9,7 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
|
|
|
9
9
|
* ownership behind `LeaderLock`. One combined push+pull request per
|
|
10
10
|
* `sync()` round (§7.2); local reads go straight to the database.
|
|
11
11
|
*/
|
|
12
|
-
import { type ScopeMap, type WakeReason } from '@syncular/core';
|
|
12
|
+
import { type PresenceErrorCode, type ScopeMap, type WakeReason } from '@syncular/core';
|
|
13
13
|
import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
|
|
14
14
|
import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
|
|
15
15
|
import type { DevtoolsRegistrar } from './devtools.js';
|
|
@@ -176,6 +176,15 @@ export interface SyncClientConfig {
|
|
|
176
176
|
* `required` without a `realtime` connector is refused at construction.
|
|
177
177
|
*/
|
|
178
178
|
readonly realtimePolicy?: RealtimePolicy;
|
|
179
|
+
/**
|
|
180
|
+
* SPEC §8.5: the server's heartbeat interval in ms, default 30,000. The
|
|
181
|
+
* socket's first `heartbeat` event arms a watchdog; once armed, twice the
|
|
182
|
+
* interval without an inbound frame loses the socket with
|
|
183
|
+
* `transport.timeout` (`causeKind` `heartbeat`).
|
|
184
|
+
*/
|
|
185
|
+
readonly realtimeHeartbeatMs?: number;
|
|
186
|
+
/** Timer seam for the heartbeat watchdog; defaults to `setTimeout`. */
|
|
187
|
+
readonly schedule?: (callback: () => void, delayMs: number) => () => void;
|
|
179
188
|
/** Stable per-device id (§1.5); defaults to a persisted random UUID. */
|
|
180
189
|
readonly clientId?: string;
|
|
181
190
|
readonly leaderLock?: LeaderLock;
|
|
@@ -197,9 +206,11 @@ export interface SyncClientConfig {
|
|
|
197
206
|
/**
|
|
198
207
|
* §8.6 presence: a scope-mate's presence on a key this client holds
|
|
199
208
|
* changed (join/update/leave). Fired after the local presence map is
|
|
200
|
-
* updated — the app's cue to re-render who's-online.
|
|
209
|
+
* updated — the app's cue to re-render who's-online. `error` is set when
|
|
210
|
+
* the server refused this client's own publish on `scopeKey` (§8.6.2);
|
|
211
|
+
* the map is unchanged then.
|
|
201
212
|
*/
|
|
202
|
-
readonly onPresence?: (scopeKey: string) => void;
|
|
213
|
+
readonly onPresence?: (scopeKey: string, error?: PresenceErrorCode) => void;
|
|
203
214
|
/**
|
|
204
215
|
* §5.11 client-side encryption. Supplies the key material (`keyProvider`)
|
|
205
216
|
* and key selection (`keyIdFor`) for columns the generated schema marks
|
|
@@ -433,8 +444,8 @@ export declare class SyncClient {
|
|
|
433
444
|
/** The underlying database: raw SQL is the local query API. */
|
|
434
445
|
get database(): ClientDatabase;
|
|
435
446
|
/**
|
|
436
|
-
* The raw-SQL read tier. Guarded (query-guard.ts): a single
|
|
437
|
-
*
|
|
447
|
+
* The raw-SQL read tier. Guarded (query-guard.ts): a single statement
|
|
448
|
+
* SQLite reports read-only — writes must go through `mutate()` so they hit the
|
|
438
449
|
* outbox (SPEC §7.1). Reserved `_sync_*` columns are stripped from the
|
|
439
450
|
* result, so a `SELECT *` row is safe to feed back into `mutate()`
|
|
440
451
|
* values; alias explicitly (`_sync_version AS v`) to read one. Engine
|
|
@@ -534,7 +545,11 @@ export declare class SyncClient {
|
|
|
534
545
|
* Accepts a raw `blob_ref` column string or a bare `blobId`.
|
|
535
546
|
*/
|
|
536
547
|
fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
|
|
537
|
-
/**
|
|
548
|
+
/**
|
|
549
|
+
* Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. It
|
|
550
|
+
* runs on the round's operation chain because a refused upload drops
|
|
551
|
+
* outbox commits a round may have captured.
|
|
552
|
+
*/
|
|
538
553
|
flushBlobUploads(): Promise<void>;
|
|
539
554
|
conflicts(): readonly ConflictRecord[];
|
|
540
555
|
rejections(): readonly RejectionRecord[];
|
|
@@ -565,12 +580,14 @@ export declare class SyncClient {
|
|
|
565
580
|
/** Every scope key this client currently has presence state for. */
|
|
566
581
|
presenceKeys(): string[];
|
|
567
582
|
/**
|
|
568
|
-
* §8.6: subscribe to presence changes (join/update/leave on any held key)
|
|
569
|
-
*
|
|
570
|
-
*
|
|
583
|
+
* §8.6: subscribe to presence changes (join/update/leave on any held key)
|
|
584
|
+
* and to the server's refusal of this client's own publish (`error`,
|
|
585
|
+
* §8.6.2). The subscribable twin of the `onPresence` config callback —
|
|
586
|
+
* React's `usePresence` targets this so many components can watch one
|
|
587
|
+
* client.
|
|
571
588
|
* Returns an unsubscribe function.
|
|
572
589
|
*/
|
|
573
|
-
onPresence(listener: (scopeKey: string) => void): () => void;
|
|
590
|
+
onPresence(listener: (scopeKey: string, error?: PresenceErrorCode) => void): () => void;
|
|
574
591
|
/**
|
|
575
592
|
* §8.6.2 publish (or clear, `doc: null`) this client's presence document
|
|
576
593
|
* for `scopeKey`. Requires a live socket; the document is ephemeral and
|