@syncular/client 0.58.0 → 0.60.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 +34 -34
- package/dist/apply.d.ts +24 -14
- package/dist/apply.js +119 -70
- package/dist/authority.js +21 -16
- 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 +15 -0
- package/dist/client.d.ts +83 -75
- package/dist/client.js +982 -910
- package/dist/database.d.ts +5 -0
- 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/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +3 -1
- package/dist/errors.js +5 -1
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +6 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +67 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +14 -14
- package/dist/invalidation.js +24 -48
- 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 +226 -0
- package/dist/native-bridge.js +764 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +21 -1
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +20 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +34 -24
- package/dist/query-guard.js +61 -186
- package/dist/reactive-store.js +55 -13
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +19 -23
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +43 -22
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +83 -75
- package/dist/worker-host.d.ts +19 -13
- package/dist/worker-host.js +75 -18
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +15 -10
- package/package.json +11 -3
- package/src/apply.ts +176 -86
- package/src/authority.ts +31 -17
- package/src/blob.ts +28 -15
- package/src/bun-database.ts +24 -0
- package/src/client.ts +1282 -1217
- package/src/database.ts +5 -0
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/encryption.ts +10 -5
- package/src/errors.ts +9 -1
- package/src/failed-overlay.ts +8 -7
- package/src/http.ts +95 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +26 -61
- 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 +1153 -0
- package/src/node-database.ts +32 -1
- package/src/outbox.ts +20 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +77 -177
- package/src/reactive-store.ts +52 -12
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +23 -31
- package/src/schema.ts +67 -25
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/window.ts +55 -134
- package/src/worker-core.ts +97 -77
- package/src/worker-host.ts +76 -32
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +14 -10
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
|
|
@@ -75,7 +75,7 @@ if (handle.role === 'follower') {
|
|
|
75
75
|
// Another tab owns the core for this origin. The default multi-tab mode
|
|
76
76
|
// transparently proxies this handle to that leader.
|
|
77
77
|
}
|
|
78
|
-
await handle.subscribe({
|
|
78
|
+
await handle.subscribe({ list_id: 'l1' });
|
|
79
79
|
await handle.syncUntilIdle();
|
|
80
80
|
const rows = await handle.query('SELECT * FROM todos');
|
|
81
81
|
```
|
|
@@ -132,7 +132,7 @@ persists, on purpose, and that is the only main-thread mode.
|
|
|
132
132
|
|
|
133
133
|
## Supported realtime lifecycle
|
|
134
134
|
|
|
135
|
-
Register
|
|
135
|
+
Register units, then install the cross-host supervisor:
|
|
136
136
|
|
|
137
137
|
```ts
|
|
138
138
|
import {
|
|
@@ -141,7 +141,7 @@ import {
|
|
|
141
141
|
installRealtimeSupervisor,
|
|
142
142
|
} from '@syncular/client';
|
|
143
143
|
|
|
144
|
-
await handle.subscribe({
|
|
144
|
+
await handle.subscribe({ list_id: 'groceries' });
|
|
145
145
|
installRealtimeSupervisor(handle, {
|
|
146
146
|
connectivity: browserConnectivitySignal(),
|
|
147
147
|
lifecycle: documentLifecycleSignal(),
|
|
@@ -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
|
|
|
@@ -387,20 +387,18 @@ loading state.
|
|
|
387
387
|
Every direct and Worker/multi-tab client exposes the same versioned snapshot:
|
|
388
388
|
|
|
389
389
|
```ts
|
|
390
|
-
const snapshot = await client.diagnosticsSnapshot(
|
|
391
|
-
|
|
392
|
-
{ id: 'membership-security', table: 'facility_memberships' },
|
|
393
|
-
{ id: 'scheduler-window', table: 'surgeries' },
|
|
394
|
-
],
|
|
395
|
-
});
|
|
390
|
+
const snapshot = await client.diagnosticsSnapshot();
|
|
391
|
+
// snapshot.version === 2; snapshot.units, snapshot.activeUnits, snapshot.replicaCursor
|
|
396
392
|
|
|
397
393
|
const off = client.onDiagnostics(() => refreshSupportView());
|
|
398
394
|
```
|
|
399
395
|
|
|
400
|
-
`
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
396
|
+
`units` counts the registered units per state (`bootstrapping`, `complete`,
|
|
397
|
+
`reset`, `revoked`, `failed`) with their distinct reason codes; `activeUnits`
|
|
398
|
+
is the number of units the next registration list carries, which the server's
|
|
399
|
+
`maxSubscriptionsPerRequest` counts; `replicaCursor` is the replica cursor,
|
|
400
|
+
`-1` while no unit is live. A unit id is a hash of scope values, so no unit id
|
|
401
|
+
enters the snapshot. The snapshot also distinguishes schema floor, lease
|
|
404
402
|
stop, pending outbox, offline transport, and storage pressure/unreadability.
|
|
405
403
|
Failed progress and `lastRound` diagnostics expose an optional bounded
|
|
406
404
|
`causeKind` and HTTP status. Worker leaders and followers receive the same
|
|
@@ -417,8 +415,8 @@ role.
|
|
|
417
415
|
The contract intentionally excludes scope values, rows and clinical row
|
|
418
416
|
counts, SQL, paths, client/actor/lease ids, auth, keys, mutation bodies, stack
|
|
419
417
|
traces, and arbitrary prose. It is safe to copy the JSON snapshot into a
|
|
420
|
-
redacted support ticket as long as the application
|
|
421
|
-
|
|
418
|
+
redacted support ticket as long as the application keeps query owner ids free
|
|
419
|
+
of patient/user data. Do not attach database files, console dumps, query
|
|
422
420
|
results, or app state alongside it. See SPEC §7.6.
|
|
423
421
|
|
|
424
422
|
## Durable commit outcomes
|
|
@@ -480,7 +478,8 @@ security purge erase the retained aggregate's protected journal payloads.
|
|
|
480
478
|
- `maxPushOperationsPerRequest`: operations across those commits. Default:
|
|
481
479
|
500.
|
|
482
480
|
- `maxPushRequestBytes`: bytes of the complete encoded SSP2 request, including
|
|
483
|
-
the request header, pull header,
|
|
481
|
+
the request header, pull header, unit and progress frames, framing, and E2EE
|
|
482
|
+
ciphertext.
|
|
484
483
|
Default: unbounded.
|
|
485
484
|
|
|
486
485
|
The client sends whole commits in FIFO order and never splits one. A later
|
|
@@ -512,13 +511,13 @@ const result = await client.purgeLocalData({
|
|
|
512
511
|
```
|
|
513
512
|
|
|
514
513
|
The host MUST first quarantine the affected feature and gate/remove any
|
|
515
|
-
|
|
514
|
+
unit that could download the protected rows again. This method does
|
|
516
515
|
not authenticate a directive, revoke server authority, delete app-owned files,
|
|
517
516
|
or remove a key from the OS secure store.
|
|
518
517
|
|
|
519
518
|
For a race-free bootstrap, construct the client/worker handle with
|
|
520
519
|
`securityPreflight: true`. Before activation, protected reads, writes,
|
|
521
|
-
|
|
520
|
+
unit registrations, sync/realtime, blobs, and the automatic host loop fail with
|
|
522
521
|
`client.security_preflight_required`; status, local revision, lifecycle, and
|
|
523
522
|
the exact local purge remain available.
|
|
524
523
|
|
|
@@ -552,10 +551,10 @@ counts only—never row ids or selector values.
|
|
|
552
551
|
|
|
553
552
|
`rebootstrapLocalData({ rebootstrapId })` is the recovery primitive for a
|
|
554
553
|
locally damaged or persistently inconsistent replicated projection. It drops
|
|
555
|
-
and recreates only Syncular's server-derived tables, rewinds
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
554
|
+
and recreates only Syncular's server-derived tables, rewinds every registered
|
|
555
|
+
unit to cursor `-1`, and requests a fresh bootstrap. It preserves the client
|
|
556
|
+
id, lease state, pending outbox commits, commit outcomes, the registration
|
|
557
|
+
list, and protected bookkeeping.
|
|
559
558
|
|
|
560
559
|
```ts
|
|
561
560
|
const result = await client.rebootstrapLocalData({
|
|
@@ -710,7 +709,8 @@ const client = new SyncClient({ database, schema, /* … */ });
|
|
|
710
709
|
```
|
|
711
710
|
|
|
712
711
|
The export selects `bun:sqlite` on Bun and the built-in `node:sqlite` module on
|
|
713
|
-
Node 22.
|
|
712
|
+
Node 22.16 or newer. On an older Node, `openNodeDatabase()` throws
|
|
713
|
+
`client.storage_unavailable`. No SQLite package or native addon is required. Both
|
|
714
714
|
adapters support synchronous `exec`, `query`, nested transactions, boolean
|
|
715
715
|
bindings, `null`, `Uint8Array` BLOB values, and §5.3 SQLite-image attachment.
|
|
716
716
|
|
|
@@ -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
|
|
@@ -779,7 +779,7 @@ bun run test:browser
|
|
|
779
779
|
|
|
780
780
|
Each case reloads the page using the same replica identity and requires successful
|
|
781
781
|
startup in the same browser session. It checks SQLite and FTS integrity, search
|
|
782
|
-
results, exact rows, persisted client identity, and
|
|
782
|
+
results, exact rows, persisted client identity, and unit checkpoints.
|
|
783
783
|
Incomplete sections must download again; completed sections must not. A held
|
|
784
784
|
synchronous test request after a physical page write keeps the mid-import crash
|
|
785
785
|
boundary stable until worker termination. Two additional ownership cases verify
|
|
@@ -830,7 +830,7 @@ stop();
|
|
|
830
830
|
```
|
|
831
831
|
|
|
832
832
|
Each snapshot identifies the round with `attempt`, and the current payload with
|
|
833
|
-
`
|
|
833
|
+
`unitId`, `table`, and optional `segmentId`. Counters reset for each
|
|
834
834
|
payload; `syncUntilIdle` starts a new attempt for each round. `phase` is `request`,
|
|
835
835
|
`download`, or `import`; `state` is `running`, `complete`, or `failed`. Unknown
|
|
836
836
|
totals remain absent. A new attempt clears prior errors and counters.
|
|
@@ -846,7 +846,7 @@ inside the current transaction; a failed import can roll those rows back. SQLite
|
|
|
846
846
|
images commit in chunks of at most 1,024 rows and yield after each commit.
|
|
847
847
|
Earlier committed chunks survive a later interruption. `complete` follows checkpoint persistence
|
|
848
848
|
and optimistic-state reconciliation for the round. More bootstrap pages can
|
|
849
|
-
remain; use
|
|
849
|
+
remain; use window coverage to determine whether a query is complete.
|
|
850
850
|
Listener exceptions do not fail sync. Listeners should hand UI work off and avoid
|
|
851
851
|
reentering database commands during an import.
|
|
852
852
|
|
|
@@ -916,7 +916,7 @@ creation to enable the zero-argument `authoritySnapshot()`. It reads approved
|
|
|
916
916
|
plain authority columns and accepted bases with revision and persisted scope
|
|
917
917
|
coverage from one SQLite snapshot, including during security preflight.
|
|
918
918
|
Unaccepted local intent remains separate. The read changes no keys, transport,
|
|
919
|
-
|
|
919
|
+
units or lifecycle. See the [authority contract](../../docs/SPEC.md)
|
|
920
920
|
and [native configuration](../tauri/README.md#authority-evidence-before-activation).
|
|
921
921
|
|
|
922
922
|
Workers must opt in in their entry script:
|
package/dist/apply.d.ts
CHANGED
|
@@ -7,15 +7,16 @@ 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;
|
|
14
14
|
export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string, serverWrite?: boolean): void;
|
|
15
15
|
/**
|
|
16
|
-
* Apply one `COMMIT` frame in one local transaction (§1.4 rule 4)
|
|
17
|
-
*
|
|
18
|
-
*
|
|
16
|
+
* Apply one `COMMIT` frame in one local transaction (§1.4 rule 4) under the
|
|
17
|
+
* §4.5 version guard: a change lands only when its `rowVersion` exceeds the
|
|
18
|
+
* local row's `_sync_version`. Upserts land with `_sync_version = rowVersion`;
|
|
19
|
+
* deletes remove the row. Re-application changes nothing.
|
|
19
20
|
*
|
|
20
21
|
* §5.11: encrypted columns are decrypted here — the apply seam. Because
|
|
21
22
|
* WebCrypto is async and the local transaction is synchronous, every row is
|
|
@@ -32,28 +33,33 @@ export declare function applyCommitFrame(db: ClientDatabase, schema: CompiledCli
|
|
|
32
33
|
*/
|
|
33
34
|
export declare function validateSegmentColumns(schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment): void;
|
|
34
35
|
/**
|
|
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
|
-
*
|
|
36
|
+
* Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
|
|
37
|
+
* rule): delete rows whose generated local scope columns match `effective`
|
|
38
|
+
* (every key's column value must be in the key's value list) and that no
|
|
39
|
+
* entry of `owners` matches. `owners` holds the effective scopes of every
|
|
40
|
+
* other active subscription on the table that holds rows; a row one of them
|
|
41
|
+
* still covers is never removed. Fails closed (`sync.scope_revoked`) when
|
|
42
|
+
* the table has no local mapping for a key: precision or nothing, never
|
|
43
|
+
* clear-the-table.
|
|
40
44
|
*/
|
|
41
|
-
export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap): {
|
|
45
|
+
export declare function localScopePredicate(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): {
|
|
42
46
|
sql: string;
|
|
43
47
|
params: string[];
|
|
44
48
|
} | undefined;
|
|
45
|
-
|
|
49
|
+
/** {@link localScopePredicate} over decoded row values (retained rows). */
|
|
50
|
+
export declare function ownsLocalRow(table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], values: Readonly<Record<string, JsonRowValue>>): boolean;
|
|
51
|
+
export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[]): void;
|
|
46
52
|
/**
|
|
47
53
|
* §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
|
|
54
|
+
* scopes (same local-scope-column rule, owner exclusion and fail-closed
|
|
55
|
+
* clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
50
56
|
* `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
|
|
51
57
|
* whether unpinned work remains and whether any scoped rows remain. Each
|
|
52
58
|
* call removes at most 1,024 rows; the caller commits before yielding. Also removes the
|
|
53
59
|
* evicted rows' `server_version` with them (E2 — no residual version
|
|
54
60
|
* cache), which is automatic since the version column is per-row.
|
|
55
61
|
*/
|
|
56
|
-
export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, pinnedRowIds: ReadonlySet<string>): {
|
|
62
|
+
export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, owners: readonly ScopeMap[], pinnedRowIds: ReadonlySet<string>): {
|
|
57
63
|
remaining: boolean;
|
|
58
64
|
deferred: boolean;
|
|
59
65
|
};
|
|
@@ -75,6 +81,8 @@ export interface SqliteSegmentDescriptor {
|
|
|
75
81
|
export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
|
|
76
82
|
readonly clearFirst: boolean;
|
|
77
83
|
readonly effective: ScopeMap;
|
|
84
|
+
/** Pair scopes of the units that own rows of the table (§3.3). */
|
|
85
|
+
readonly owners: readonly ScopeMap[];
|
|
78
86
|
readonly transaction?: ApplyTransaction;
|
|
79
87
|
readonly onProgress?: (rowsProcessed: number) => void;
|
|
80
88
|
readonly isCurrent?: () => boolean;
|
|
@@ -90,6 +98,8 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
|
|
|
90
98
|
export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, segment: RowsSegment, options: {
|
|
91
99
|
readonly clearFirst: boolean;
|
|
92
100
|
readonly effective: ScopeMap;
|
|
101
|
+
/** Pair scopes of the units that own rows of the table (§3.3). */
|
|
102
|
+
readonly owners: readonly ScopeMap[];
|
|
93
103
|
readonly transaction?: ApplyTransaction;
|
|
94
104
|
readonly onProgress?: (rowsProcessed: number) => void;
|
|
95
105
|
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
|
/**
|
|
@@ -36,9 +36,29 @@ export function deleteLocalRow(db, table, rowId, serverWrite = true) {
|
|
|
36
36
|
db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)]);
|
|
37
37
|
}
|
|
38
38
|
/**
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
39
|
+
* §4.5 version guard for one server row: whether a write at `version` lands.
|
|
40
|
+
* A skipped row keeps its overlay, so its key leaves the rebase scope unless a
|
|
41
|
+
* retained base was restored for it; `kept` and `skipped` collect the keys.
|
|
42
|
+
*/
|
|
43
|
+
function lands(db, table, rowId, version, kept, skipped) {
|
|
44
|
+
const key = JSON.stringify([table.name, rowId]);
|
|
45
|
+
const local = db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v,EXISTS(SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=?) AS retained FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [table.name, rowId, pkSqlValue(table, rowId)])[0];
|
|
46
|
+
const land = local === undefined || Number(local.v) < version;
|
|
47
|
+
if (land || local.retained)
|
|
48
|
+
kept.add(key);
|
|
49
|
+
else
|
|
50
|
+
skipped.add(key);
|
|
51
|
+
return land;
|
|
52
|
+
}
|
|
53
|
+
/** The scope a guarded write leaves for the overlay replay. */
|
|
54
|
+
function rebaseScope(scope, kept, skipped) {
|
|
55
|
+
return scope.filter((key) => kept.has(key) || !skipped.has(key));
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Apply one `COMMIT` frame in one local transaction (§1.4 rule 4) under the
|
|
59
|
+
* §4.5 version guard: a change lands only when its `rowVersion` exceeds the
|
|
60
|
+
* local row's `_sync_version`. Upserts land with `_sync_version = rowVersion`;
|
|
61
|
+
* deletes remove the row. Re-application changes nothing.
|
|
42
62
|
*
|
|
43
63
|
* §5.11: encrypted columns are decrypted here — the apply seam. Because
|
|
44
64
|
* WebCrypto is async and the local transaction is synchronous, every row is
|
|
@@ -59,41 +79,44 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
|
|
|
59
79
|
throw new ClientSyncError('sync.schema_mismatch', `COMMIT delivers unknown local table ${JSON.stringify(tableName)}`);
|
|
60
80
|
}
|
|
61
81
|
if (change.op === 'delete') {
|
|
62
|
-
resolved.push({ op: 'delete', table
|
|
82
|
+
resolved.push({ op: 'delete', table });
|
|
63
83
|
continue;
|
|
64
84
|
}
|
|
65
|
-
if (change.row === undefined
|
|
85
|
+
if (change.row === undefined) {
|
|
66
86
|
throw invalidRequest('upsert change without row payload');
|
|
67
87
|
}
|
|
68
88
|
let values = decodeRow(table.columns, change.row);
|
|
69
|
-
if (
|
|
89
|
+
if (table.hasEncryptedColumns) {
|
|
70
90
|
const { decryptRowValues } = await import('./encryption.js');
|
|
71
91
|
values = await decryptRowValues(encryption, table, values);
|
|
72
92
|
}
|
|
73
|
-
resolved.push({
|
|
74
|
-
op: 'upsert',
|
|
75
|
-
table,
|
|
76
|
-
values,
|
|
77
|
-
rowVersion: change.rowVersion,
|
|
78
|
-
});
|
|
93
|
+
resolved.push({ op: 'upsert', table, values });
|
|
79
94
|
}
|
|
80
95
|
transaction(() => {
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
96
|
+
// Exact keys name the rows this frame rebases; unique-key peers widen the
|
|
97
|
+
// replay to the table.
|
|
98
|
+
const scope = resolved.flatMap((change, index) => [
|
|
99
|
+
...(hasUniqueIndex(change.table)
|
|
100
|
+
? [JSON.stringify([change.table.name])]
|
|
101
|
+
: []),
|
|
102
|
+
JSON.stringify([change.table.name, frame.changes[index].rowId]),
|
|
103
|
+
]);
|
|
84
104
|
restoreFailedBases(db, schema, scope);
|
|
105
|
+
const kept = new Set();
|
|
106
|
+
const skipped = new Set();
|
|
85
107
|
for (const [index, change] of resolved.entries()) {
|
|
86
|
-
const rowId = frame.changes[index]
|
|
87
|
-
|
|
108
|
+
const { rowId, rowVersion } = frame.changes[index];
|
|
109
|
+
const land = lands(db, change.table, rowId, rowVersion, kept, skipped);
|
|
110
|
+
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
111
|
db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
|
|
89
|
-
if (
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
112
|
+
if (!land)
|
|
113
|
+
continue;
|
|
114
|
+
if (change.op === 'delete')
|
|
115
|
+
deleteLocalRow(db, change.table, rowId);
|
|
116
|
+
else
|
|
117
|
+
upsertLocalRow(db, change.table, change.values, rowVersion);
|
|
95
118
|
}
|
|
96
|
-
return scope;
|
|
119
|
+
return rebaseScope(scope, kept, skipped);
|
|
97
120
|
});
|
|
98
121
|
}
|
|
99
122
|
/**
|
|
@@ -127,13 +150,16 @@ export function validateSegmentColumns(schema, table, segment) {
|
|
|
127
150
|
}
|
|
128
151
|
}
|
|
129
152
|
/**
|
|
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
|
-
*
|
|
153
|
+
* Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
|
|
154
|
+
* rule): delete rows whose generated local scope columns match `effective`
|
|
155
|
+
* (every key's column value must be in the key's value list) and that no
|
|
156
|
+
* entry of `owners` matches. `owners` holds the effective scopes of every
|
|
157
|
+
* other active subscription on the table that holds rows; a row one of them
|
|
158
|
+
* still covers is never removed. Fails closed (`sync.scope_revoked`) when
|
|
159
|
+
* the table has no local mapping for a key: precision or nothing, never
|
|
160
|
+
* clear-the-table.
|
|
135
161
|
*/
|
|
136
|
-
export function localScopePredicate(table, effective) {
|
|
162
|
+
export function localScopePredicate(table, effective, owners) {
|
|
137
163
|
const entries = Object.entries(effective);
|
|
138
164
|
if (!entries.length || entries.some(([, values]) => !values.length))
|
|
139
165
|
return;
|
|
@@ -147,25 +173,37 @@ export function localScopePredicate(table, effective) {
|
|
|
147
173
|
return `${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`;
|
|
148
174
|
})
|
|
149
175
|
.join(' AND ');
|
|
150
|
-
|
|
176
|
+
const kept = owners.flatMap((owner) => {
|
|
177
|
+
const scope = localScopePredicate(table, owner, []);
|
|
178
|
+
if (scope === undefined)
|
|
179
|
+
return [];
|
|
180
|
+
params.push(...scope.params);
|
|
181
|
+
return [` AND NOT (${scope.sql})`];
|
|
182
|
+
});
|
|
183
|
+
return { sql: sql + kept.join(''), params };
|
|
184
|
+
}
|
|
185
|
+
/** {@link localScopePredicate} over decoded row values (retained rows). */
|
|
186
|
+
export function ownsLocalRow(table, effective, owners, values) {
|
|
187
|
+
return (matchesLocalScopes(table, effective, values) &&
|
|
188
|
+
!owners.some((owner) => matchesLocalScopes(table, owner, values)));
|
|
151
189
|
}
|
|
152
190
|
function scopedRows(db, table, scope) {
|
|
153
191
|
return scope
|
|
154
192
|
? db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${scope.sql}`, scope.params)
|
|
155
193
|
: [];
|
|
156
194
|
}
|
|
157
|
-
function bootstrapScope(db, table, effective) {
|
|
158
|
-
const rows = scopedRows(db, table, localScopePredicate(table, effective));
|
|
195
|
+
function bootstrapScope(db, table, effective, owners) {
|
|
196
|
+
const rows = scopedRows(db, table, localScopePredicate(table, effective, owners));
|
|
159
197
|
rows.push(...db
|
|
160
198
|
.query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
|
|
161
199
|
table.name,
|
|
162
200
|
])
|
|
163
201
|
.filter((row) => [row.base, row.intent].some((json) => json !== null &&
|
|
164
|
-
|
|
202
|
+
ownsLocalRow(table, effective, owners, JSON.parse(json)))));
|
|
165
203
|
return rows.map((row) => JSON.stringify([table.name, String(row.id)]));
|
|
166
204
|
}
|
|
167
|
-
export function deleteScopedRows(db, table, effective) {
|
|
168
|
-
const scope = localScopePredicate(table, effective);
|
|
205
|
+
export function deleteScopedRows(db, table, effective, owners) {
|
|
206
|
+
const scope = localScopePredicate(table, effective, owners);
|
|
169
207
|
if (!scope)
|
|
170
208
|
return;
|
|
171
209
|
const { sql, params } = scope;
|
|
@@ -176,16 +214,16 @@ export function deleteScopedRows(db, table, effective) {
|
|
|
176
214
|
}
|
|
177
215
|
/**
|
|
178
216
|
* §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
|
|
217
|
+
* scopes (same local-scope-column rule, owner exclusion and fail-closed
|
|
218
|
+
* clause as {@link deleteScopedRows}) EXCEPT rows whose primary key is in
|
|
181
219
|
* `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
|
|
182
220
|
* whether unpinned work remains and whether any scoped rows remain. Each
|
|
183
221
|
* call removes at most 1,024 rows; the caller commits before yielding. Also removes the
|
|
184
222
|
* evicted rows' `server_version` with them (E2 — no residual version
|
|
185
223
|
* cache), which is automatic since the version column is per-row.
|
|
186
224
|
*/
|
|
187
|
-
export function evictScopedRows(db, table, effective, pinnedRowIds) {
|
|
188
|
-
const scope = localScopePredicate(table, effective);
|
|
225
|
+
export function evictScopedRows(db, table, effective, owners, pinnedRowIds) {
|
|
226
|
+
const scope = localScopePredicate(table, effective, owners);
|
|
189
227
|
if (!scope)
|
|
190
228
|
return { remaining: false, deferred: false };
|
|
191
229
|
const { sql, params } = scope;
|
|
@@ -200,7 +238,7 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
|
|
|
200
238
|
for (const row of db.query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl=?`, [table.name])) {
|
|
201
239
|
if (!pinnedRowIds.has(row.id) &&
|
|
202
240
|
[row.intent, row.base].some((json) => json !== null &&
|
|
203
|
-
|
|
241
|
+
ownsLocalRow(table, effective, owners, JSON.parse(json))))
|
|
204
242
|
db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq IS NOT NULL`, [table.name, row.id]);
|
|
205
243
|
}
|
|
206
244
|
db.exec(`DELETE FROM ${target} WHERE ${pk} IN(SELECT ${pk} FROM ${target} WHERE ${sql}${pinnedClause} LIMIT 1024)`, params);
|
|
@@ -229,6 +267,10 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
229
267
|
if (descriptor.table !== table.name) {
|
|
230
268
|
imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
|
|
231
269
|
}
|
|
270
|
+
// §5.11: an image bypasses the decrypt seam, so a server cannot serve one
|
|
271
|
+
// for a table with encrypted columns.
|
|
272
|
+
if (table.hasEncryptedColumns)
|
|
273
|
+
imageInvalid('table has encrypted columns');
|
|
232
274
|
return withImage(bytes, IMAGE_ALIAS, async () => {
|
|
233
275
|
// 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
|
|
234
276
|
// SQLite database or lacks the metadata table fails right here.
|
|
@@ -286,6 +328,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
286
328
|
.filter((name) => name !== primaryKey)
|
|
287
329
|
.map((name) => `${name}=excluded.${name}`)
|
|
288
330
|
.join(', ');
|
|
331
|
+
const version = quoteIdent(SYNC_VERSION_COLUMN);
|
|
289
332
|
let after;
|
|
290
333
|
let applied = 0;
|
|
291
334
|
for (;;) {
|
|
@@ -314,27 +357,30 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
|
|
|
314
357
|
(options.transaction ?? ((fn) => db.transaction(fn)))(() => {
|
|
315
358
|
const scope = !replay
|
|
316
359
|
? []
|
|
317
|
-
:
|
|
318
|
-
? [JSON.stringify([table.name])]
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
];
|
|
360
|
+
: [
|
|
361
|
+
...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
|
|
362
|
+
...(after === undefined && options.clearFirst
|
|
363
|
+
? bootstrapScope(db, table, options.effective, options.owners)
|
|
364
|
+
: []),
|
|
365
|
+
...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
|
|
366
|
+
];
|
|
325
367
|
const protectedRows = restoreFailedBases(db, schema, scope);
|
|
326
368
|
if (after === undefined && options.clearFirst)
|
|
327
|
-
deleteScopedRows(db, table, options.effective);
|
|
328
|
-
|
|
329
|
-
|
|
369
|
+
deleteScopedRows(db, table, options.effective, options.owners);
|
|
370
|
+
const kept = new Set();
|
|
371
|
+
const skipped = new Set();
|
|
372
|
+
const landing = rows.filter((row) => lands(db, table, String(row[table.primaryKey]), Number(row._syncular_version), kept, skipped));
|
|
373
|
+
const where = predicates.join(' AND ') || 'true';
|
|
374
|
+
db.exec(`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${where} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates} WHERE excluded.${version}>${quoteIdent(table.name)}.${version}`, params);
|
|
375
|
+
applied += Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
|
|
330
376
|
if (protectedRows)
|
|
331
|
-
for (const row of
|
|
377
|
+
for (const row of landing) {
|
|
332
378
|
retainedBaseWrite(db, table, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
|
|
333
379
|
column.name,
|
|
334
380
|
rowValueToJson(row[column.name]),
|
|
335
381
|
])), Number(row._syncular_version));
|
|
336
382
|
}
|
|
337
|
-
return scope;
|
|
383
|
+
return rebaseScope(scope, kept, skipped);
|
|
338
384
|
});
|
|
339
385
|
options.onProgress?.(applied);
|
|
340
386
|
await yieldToHost();
|
|
@@ -368,7 +414,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
|
|
|
368
414
|
// aborts before any write in this block.
|
|
369
415
|
const rows = [];
|
|
370
416
|
for (const row of block) {
|
|
371
|
-
const values =
|
|
417
|
+
const values = table.hasEncryptedColumns
|
|
372
418
|
? await (async () => {
|
|
373
419
|
const { decryptRowValues } = await import('./encryption.js');
|
|
374
420
|
return decryptRowValues(encryption, table, row.values);
|
|
@@ -383,28 +429,31 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
|
|
|
383
429
|
if (!clearThisBlock && rows.length === 0)
|
|
384
430
|
continue;
|
|
385
431
|
(options.transaction ?? ((fn) => db.transaction(fn)))(() => {
|
|
386
|
-
const scope =
|
|
387
|
-
? [JSON.stringify([table.name])]
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
];
|
|
432
|
+
const scope = [
|
|
433
|
+
...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
|
|
434
|
+
...(clearThisBlock
|
|
435
|
+
? bootstrapScope(db, table, options.effective, options.owners)
|
|
436
|
+
: []),
|
|
437
|
+
...rows.map((row) => JSON.stringify([
|
|
438
|
+
table.name,
|
|
439
|
+
String(row.values[table.primaryKeyIndex]),
|
|
440
|
+
])),
|
|
441
|
+
];
|
|
397
442
|
const protectedRows = restoreFailedBases(db, schema, scope);
|
|
398
443
|
if (clearThisBlock) {
|
|
399
|
-
deleteScopedRows(db, table, options.effective);
|
|
444
|
+
deleteScopedRows(db, table, options.effective, options.owners);
|
|
400
445
|
}
|
|
446
|
+
const kept = new Set();
|
|
447
|
+
const skipped = new Set();
|
|
401
448
|
for (const row of rows) {
|
|
402
|
-
|
|
449
|
+
const rowId = String(row.values[table.primaryKeyIndex]);
|
|
450
|
+
if (lands(db, table, rowId, row.serverVersion, kept, skipped))
|
|
451
|
+
upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
|
|
403
452
|
applied += 1;
|
|
404
453
|
if (applied % 1024 === 0)
|
|
405
454
|
options.onProgress?.(applied);
|
|
406
455
|
}
|
|
407
|
-
return scope;
|
|
456
|
+
return rebaseScope(scope, kept, skipped);
|
|
408
457
|
});
|
|
409
458
|
options.onProgress?.(applied);
|
|
410
459
|
await yieldToHost();
|