@syncular/client 0.71.0 → 0.72.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/dist/client.js +27 -5
- package/dist/invalidation.d.ts +6 -1
- package/dist/reactive-store.js +50 -2
- package/package.json +3 -3
- package/src/client.ts +33 -10
- package/src/invalidation.ts +6 -1
- package/src/reactive-store.ts +59 -2
package/dist/client.js
CHANGED
|
@@ -772,7 +772,11 @@ export class SyncClient {
|
|
|
772
772
|
this.#requireStarted();
|
|
773
773
|
if (this.#preflightBarrier !== undefined)
|
|
774
774
|
return this.#preflightBarrier;
|
|
775
|
-
this.#securityLifecycle
|
|
775
|
+
if (this.#securityLifecycle !== 'preflight')
|
|
776
|
+
this.#applyBatch((batch) => {
|
|
777
|
+
this.#securityLifecycle = 'preflight';
|
|
778
|
+
batch.status();
|
|
779
|
+
});
|
|
776
780
|
this.#securityEpoch += 1;
|
|
777
781
|
this.disconnectRealtime();
|
|
778
782
|
const barrier = (async () => {
|
|
@@ -805,13 +809,15 @@ export class SyncClient {
|
|
|
805
809
|
// §4.8: an interrupted eviction finishes before protected reads open.
|
|
806
810
|
await this.#serialize(() => this.#drainPendingEvictions());
|
|
807
811
|
this.#encryption = options.encryption;
|
|
808
|
-
this.#
|
|
812
|
+
this.#applyBatch((batch) => {
|
|
813
|
+
this.#securityLifecycle = 'active';
|
|
814
|
+
batch.status();
|
|
815
|
+
});
|
|
809
816
|
if (this.#hasStartupWork()) {
|
|
810
817
|
this.#setSyncNeeded(true);
|
|
811
818
|
this.#emitSyncNeeded('startup');
|
|
812
819
|
this.#emitSyncIntent({ kind: 'interactive' });
|
|
813
820
|
}
|
|
814
|
-
this.#emitDiagnostics();
|
|
815
821
|
}
|
|
816
822
|
/** Persisted work an opened or activated replica owes one round (§8.4). */
|
|
817
823
|
#hasStartupWork() {
|
|
@@ -1401,6 +1407,7 @@ export class SyncClient {
|
|
|
1401
1407
|
schemaFloor: this.#schemaFloor,
|
|
1402
1408
|
syncNeeded: this.#needsPull,
|
|
1403
1409
|
previousVersionContext: this.#previousVersionStatus(),
|
|
1410
|
+
securityLifecycle: this.#securityLifecycle,
|
|
1404
1411
|
};
|
|
1405
1412
|
}
|
|
1406
1413
|
/**
|
|
@@ -3975,8 +3982,23 @@ export class SyncClient {
|
|
|
3975
3982
|
prefetched.delete(frame);
|
|
3976
3983
|
if (pending !== undefined)
|
|
3977
3984
|
reporting = frame;
|
|
3978
|
-
|
|
3979
|
-
|
|
3985
|
+
try {
|
|
3986
|
+
bytes = await (pending ??
|
|
3987
|
+
this.#downloadSegment(frame, section.unit.scopes, (bytesReceived) => this.#progress.update({ bytesReceived }), signal));
|
|
3988
|
+
}
|
|
3989
|
+
catch (error) {
|
|
3990
|
+
// §5.5: access changed since the response. The unit stays
|
|
3991
|
+
// catching up with its cursor unpersisted, and the next
|
|
3992
|
+
// round's SUB_START settles it (revoked or a new bootstrap).
|
|
3993
|
+
// A host downloader may throw any error carrying the code.
|
|
3994
|
+
if (typeof error !== 'object' ||
|
|
3995
|
+
error === null ||
|
|
3996
|
+
!('code' in error) ||
|
|
3997
|
+
error.code !== 'sync.forbidden')
|
|
3998
|
+
throw error;
|
|
3999
|
+
section.skip = true;
|
|
4000
|
+
break;
|
|
4001
|
+
}
|
|
3980
4002
|
this.#progress.update({ phase: 'import' });
|
|
3981
4003
|
}
|
|
3982
4004
|
else {
|
package/dist/invalidation.d.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* the frozen batch only after commit. Bridges forward this shape verbatim.
|
|
7
7
|
*/
|
|
8
8
|
import type { ScopeMap } from '@syncular/core';
|
|
9
|
-
import type { LeaseState, SchemaFloor } from './client.js';
|
|
9
|
+
import type { LeaseState, SchemaFloor, SecurityLifecycle } from './client.js';
|
|
10
10
|
import type { CompiledClientTable } from './schema.js';
|
|
11
11
|
export type LocalRevision = bigint;
|
|
12
12
|
export interface TableChange {
|
|
@@ -26,6 +26,11 @@ export interface SyncStatusSnapshot {
|
|
|
26
26
|
readonly leaseState: LeaseState | undefined;
|
|
27
27
|
readonly schemaFloor: SchemaFloor | undefined;
|
|
28
28
|
readonly syncNeeded: boolean;
|
|
29
|
+
/**
|
|
30
|
+
* §5.11: 'preflight' while protected reads, claims and sync are refused;
|
|
31
|
+
* a change batch carries the snapshot at each transition.
|
|
32
|
+
*/
|
|
33
|
+
readonly securityLifecycle: SecurityLifecycle;
|
|
29
34
|
/**
|
|
30
35
|
* RFC 0005 A2: whether a previous-version cache is present, so a host's
|
|
31
36
|
* update/rollback path can require its discard. `createdAtMs` is the capture
|
package/dist/reactive-store.js
CHANGED
|
@@ -258,6 +258,12 @@ function localReadsBlocked(availability) {
|
|
|
258
258
|
availability.reason === 'leader-incompatible' ||
|
|
259
259
|
availability.reason === 'leadership-taken'));
|
|
260
260
|
}
|
|
261
|
+
/** §5.11: a read or claim the security gate refused waits for activation. */
|
|
262
|
+
function refusedByPreflight(error) {
|
|
263
|
+
return (error instanceof Error &&
|
|
264
|
+
'code' in error &&
|
|
265
|
+
error.code === 'client.security_preflight_required');
|
|
266
|
+
}
|
|
261
267
|
/** One frozen snapshot per phase and availability for entries that have no
|
|
262
268
|
* successful read, so switching between unread entries keeps the snapshot and
|
|
263
269
|
* `rows` identity. */
|
|
@@ -295,6 +301,8 @@ class QueryEntry {
|
|
|
295
301
|
#desiredRevision = 0n;
|
|
296
302
|
#claimError;
|
|
297
303
|
#claimPending = false;
|
|
304
|
+
#claimGated = false;
|
|
305
|
+
#gated = false;
|
|
298
306
|
#offStatus;
|
|
299
307
|
#offRound;
|
|
300
308
|
constructor(store, spec, key, cache) {
|
|
@@ -375,8 +383,12 @@ class QueryEntry {
|
|
|
375
383
|
if (generation !== this.#generation || this.#listeners.size === 0)
|
|
376
384
|
return;
|
|
377
385
|
this.#claimPending = false;
|
|
378
|
-
|
|
379
|
-
|
|
386
|
+
if (refusedByPreflight(error))
|
|
387
|
+
this.#gate(true);
|
|
388
|
+
else {
|
|
389
|
+
this.#claimError = errorOf(error);
|
|
390
|
+
this.#requestRead();
|
|
391
|
+
}
|
|
380
392
|
});
|
|
381
393
|
}
|
|
382
394
|
refresh = () => {
|
|
@@ -395,6 +407,8 @@ class QueryEntry {
|
|
|
395
407
|
this.#desiredRevision = 0n;
|
|
396
408
|
this.#claimError = undefined;
|
|
397
409
|
this.#claimPending = false;
|
|
410
|
+
this.#claimGated = false;
|
|
411
|
+
this.#gated = false;
|
|
398
412
|
this.#state = unreadQuerySnapshot('loading', { state: 'ready' });
|
|
399
413
|
}
|
|
400
414
|
dispose() {
|
|
@@ -479,6 +493,9 @@ class QueryEntry {
|
|
|
479
493
|
});
|
|
480
494
|
}
|
|
481
495
|
#onAvailabilityChange() {
|
|
496
|
+
if (this.#gated &&
|
|
497
|
+
this.store.status.getSnapshot().status?.securityLifecycle !== 'preflight')
|
|
498
|
+
this.#resume();
|
|
482
499
|
const availability = this.store.availabilitySnapshot();
|
|
483
500
|
if (localReadsBlocked(availability)) {
|
|
484
501
|
this.#publish({
|
|
@@ -502,6 +519,32 @@ class QueryEntry {
|
|
|
502
519
|
if (wasBlocked)
|
|
503
520
|
this.#requestRead();
|
|
504
521
|
}
|
|
522
|
+
/** §5.11: the security gate refused this entry's read or claim. The
|
|
523
|
+
* entry keeps its snapshot and reads again when the status reports
|
|
524
|
+
* activation; a refusal that raced activation finds the client active. */
|
|
525
|
+
#gate(claim = false) {
|
|
526
|
+
this.#gated = true;
|
|
527
|
+
if (claim)
|
|
528
|
+
this.#claimGated = true;
|
|
529
|
+
if (this.#state.isRefreshing)
|
|
530
|
+
this.#publish({ ...this.#state, isRefreshing: false });
|
|
531
|
+
const generation = this.#generation;
|
|
532
|
+
void Promise.resolve(this.store.client.statusSnapshot()).then((status) => {
|
|
533
|
+
if (generation === this.#generation &&
|
|
534
|
+
status.securityLifecycle !== 'preflight')
|
|
535
|
+
this.#resume();
|
|
536
|
+
}, () => { });
|
|
537
|
+
}
|
|
538
|
+
#resume() {
|
|
539
|
+
if (!this.#gated)
|
|
540
|
+
return;
|
|
541
|
+
this.#gated = false;
|
|
542
|
+
if (this.#claimGated) {
|
|
543
|
+
this.#claimGated = false;
|
|
544
|
+
this.#claimCoverage();
|
|
545
|
+
}
|
|
546
|
+
this.#requestRead();
|
|
547
|
+
}
|
|
505
548
|
/** SPEC §7.5 failed transfer: incomplete coverage stops waiting on a failed
|
|
506
549
|
* sync attempt and resumes waiting when the next attempt starts. */
|
|
507
550
|
#onRoundFailureChange() {
|
|
@@ -603,6 +646,11 @@ class QueryEntry {
|
|
|
603
646
|
catch (error) {
|
|
604
647
|
if (generation !== this.#generation || this.#listeners.size === 0)
|
|
605
648
|
return;
|
|
649
|
+
if (refusedByPreflight(error)) {
|
|
650
|
+
this.#requested = false;
|
|
651
|
+
this.#gate();
|
|
652
|
+
return;
|
|
653
|
+
}
|
|
606
654
|
// SPEC §7.5: a failed latest read is never `ready`; the last
|
|
607
655
|
// successful rows and revision stay available beside the error.
|
|
608
656
|
this.#publish({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.72.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",
|
|
@@ -121,11 +121,11 @@
|
|
|
121
121
|
},
|
|
122
122
|
"dependencies": {
|
|
123
123
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
124
|
-
"@syncular/core": "0.
|
|
124
|
+
"@syncular/core": "0.72.0"
|
|
125
125
|
},
|
|
126
126
|
"devDependencies": {
|
|
127
127
|
"@electric-sql/pglite": "^0.5.4",
|
|
128
|
-
"@syncular/server": "0.
|
|
128
|
+
"@syncular/server": "0.72.0",
|
|
129
129
|
"playwright": "1.63.0",
|
|
130
130
|
"vite": "8.3.4"
|
|
131
131
|
}
|
package/src/client.ts
CHANGED
|
@@ -1642,7 +1642,11 @@ export class SyncClient {
|
|
|
1642
1642
|
beginSecurityPreflight(): Promise<void> {
|
|
1643
1643
|
this.#requireStarted();
|
|
1644
1644
|
if (this.#preflightBarrier !== undefined) return this.#preflightBarrier;
|
|
1645
|
-
this.#securityLifecycle
|
|
1645
|
+
if (this.#securityLifecycle !== 'preflight')
|
|
1646
|
+
this.#applyBatch((batch) => {
|
|
1647
|
+
this.#securityLifecycle = 'preflight';
|
|
1648
|
+
batch.status();
|
|
1649
|
+
});
|
|
1646
1650
|
this.#securityEpoch += 1;
|
|
1647
1651
|
this.disconnectRealtime();
|
|
1648
1652
|
const barrier = (async () => {
|
|
@@ -1681,13 +1685,15 @@ export class SyncClient {
|
|
|
1681
1685
|
// §4.8: an interrupted eviction finishes before protected reads open.
|
|
1682
1686
|
await this.#serialize(() => this.#drainPendingEvictions());
|
|
1683
1687
|
this.#encryption = options.encryption;
|
|
1684
|
-
this.#
|
|
1688
|
+
this.#applyBatch((batch) => {
|
|
1689
|
+
this.#securityLifecycle = 'active';
|
|
1690
|
+
batch.status();
|
|
1691
|
+
});
|
|
1685
1692
|
if (this.#hasStartupWork()) {
|
|
1686
1693
|
this.#setSyncNeeded(true);
|
|
1687
1694
|
this.#emitSyncNeeded('startup');
|
|
1688
1695
|
this.#emitSyncIntent({ kind: 'interactive' });
|
|
1689
1696
|
}
|
|
1690
|
-
this.#emitDiagnostics();
|
|
1691
1697
|
}
|
|
1692
1698
|
|
|
1693
1699
|
/** Persisted work an opened or activated replica owes one round (§8.4). */
|
|
@@ -2399,6 +2405,7 @@ export class SyncClient {
|
|
|
2399
2405
|
schemaFloor: this.#schemaFloor,
|
|
2400
2406
|
syncNeeded: this.#needsPull,
|
|
2401
2407
|
previousVersionContext: this.#previousVersionStatus(),
|
|
2408
|
+
securityLifecycle: this.#securityLifecycle,
|
|
2402
2409
|
};
|
|
2403
2410
|
}
|
|
2404
2411
|
|
|
@@ -5523,13 +5530,29 @@ export class SyncClient {
|
|
|
5523
5530
|
const pending = prefetched.get(frame);
|
|
5524
5531
|
prefetched.delete(frame);
|
|
5525
5532
|
if (pending !== undefined) reporting = frame;
|
|
5526
|
-
|
|
5527
|
-
|
|
5528
|
-
|
|
5529
|
-
|
|
5530
|
-
|
|
5531
|
-
|
|
5532
|
-
|
|
5533
|
+
try {
|
|
5534
|
+
bytes = await (pending ??
|
|
5535
|
+
this.#downloadSegment(
|
|
5536
|
+
frame,
|
|
5537
|
+
section.unit.scopes,
|
|
5538
|
+
(bytesReceived) => this.#progress.update({ bytesReceived }),
|
|
5539
|
+
signal,
|
|
5540
|
+
));
|
|
5541
|
+
} catch (error) {
|
|
5542
|
+
// §5.5: access changed since the response. The unit stays
|
|
5543
|
+
// catching up with its cursor unpersisted, and the next
|
|
5544
|
+
// round's SUB_START settles it (revoked or a new bootstrap).
|
|
5545
|
+
// A host downloader may throw any error carrying the code.
|
|
5546
|
+
if (
|
|
5547
|
+
typeof error !== 'object' ||
|
|
5548
|
+
error === null ||
|
|
5549
|
+
!('code' in error) ||
|
|
5550
|
+
error.code !== 'sync.forbidden'
|
|
5551
|
+
)
|
|
5552
|
+
throw error;
|
|
5553
|
+
section.skip = true;
|
|
5554
|
+
break;
|
|
5555
|
+
}
|
|
5533
5556
|
this.#progress.update({ phase: 'import' });
|
|
5534
5557
|
} else {
|
|
5535
5558
|
bytes = frame.payload;
|
package/src/invalidation.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* the frozen batch only after commit. Bridges forward this shape verbatim.
|
|
7
7
|
*/
|
|
8
8
|
import type { ScopeMap } from '@syncular/core';
|
|
9
|
-
import type { LeaseState, SchemaFloor } from './client';
|
|
9
|
+
import type { LeaseState, SchemaFloor, SecurityLifecycle } from './client';
|
|
10
10
|
import type { CompiledClientTable } from './schema';
|
|
11
11
|
|
|
12
12
|
export type LocalRevision = bigint;
|
|
@@ -30,6 +30,11 @@ export interface SyncStatusSnapshot {
|
|
|
30
30
|
readonly leaseState: LeaseState | undefined;
|
|
31
31
|
readonly schemaFloor: SchemaFloor | undefined;
|
|
32
32
|
readonly syncNeeded: boolean;
|
|
33
|
+
/**
|
|
34
|
+
* §5.11: 'preflight' while protected reads, claims and sync are refused;
|
|
35
|
+
* a change batch carries the snapshot at each transition.
|
|
36
|
+
*/
|
|
37
|
+
readonly securityLifecycle: SecurityLifecycle;
|
|
33
38
|
/**
|
|
34
39
|
* RFC 0005 A2: whether a previous-version cache is present, so a host's
|
|
35
40
|
* update/rollback path can require its discard. `createdAtMs` is the capture
|
package/src/reactive-store.ts
CHANGED
|
@@ -391,6 +391,15 @@ function localReadsBlocked(availability: SyncAvailability): boolean {
|
|
|
391
391
|
);
|
|
392
392
|
}
|
|
393
393
|
|
|
394
|
+
/** §5.11: a read or claim the security gate refused waits for activation. */
|
|
395
|
+
function refusedByPreflight(error: unknown): boolean {
|
|
396
|
+
return (
|
|
397
|
+
error instanceof Error &&
|
|
398
|
+
'code' in error &&
|
|
399
|
+
error.code === 'client.security_preflight_required'
|
|
400
|
+
);
|
|
401
|
+
}
|
|
402
|
+
|
|
394
403
|
/** One frozen snapshot per phase and availability for entries that have no
|
|
395
404
|
* successful read, so switching between unread entries keeps the snapshot and
|
|
396
405
|
* `rows` identity. */
|
|
@@ -428,6 +437,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
|
|
|
428
437
|
#desiredRevision = 0n;
|
|
429
438
|
#claimError: Error | undefined;
|
|
430
439
|
#claimPending = false;
|
|
440
|
+
#claimGated = false;
|
|
441
|
+
#gated = false;
|
|
431
442
|
#offStatus: (() => void) | undefined;
|
|
432
443
|
#offRound: (() => void) | undefined;
|
|
433
444
|
|
|
@@ -518,8 +529,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
|
|
|
518
529
|
if (generation !== this.#generation || this.#listeners.size === 0)
|
|
519
530
|
return;
|
|
520
531
|
this.#claimPending = false;
|
|
521
|
-
|
|
522
|
-
|
|
532
|
+
if (refusedByPreflight(error)) this.#gate(true);
|
|
533
|
+
else {
|
|
534
|
+
this.#claimError = errorOf(error);
|
|
535
|
+
this.#requestRead();
|
|
536
|
+
}
|
|
523
537
|
},
|
|
524
538
|
);
|
|
525
539
|
}
|
|
@@ -538,6 +552,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
|
|
|
538
552
|
this.#desiredRevision = 0n;
|
|
539
553
|
this.#claimError = undefined;
|
|
540
554
|
this.#claimPending = false;
|
|
555
|
+
this.#claimGated = false;
|
|
556
|
+
this.#gated = false;
|
|
541
557
|
this.#state = unreadQuerySnapshot('loading', { state: 'ready' });
|
|
542
558
|
}
|
|
543
559
|
|
|
@@ -626,6 +642,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
|
|
|
626
642
|
}
|
|
627
643
|
|
|
628
644
|
#onAvailabilityChange(): void {
|
|
645
|
+
if (
|
|
646
|
+
this.#gated &&
|
|
647
|
+
this.store.status.getSnapshot().status?.securityLifecycle !== 'preflight'
|
|
648
|
+
)
|
|
649
|
+
this.#resume();
|
|
629
650
|
const availability = this.store.availabilitySnapshot();
|
|
630
651
|
if (localReadsBlocked(availability)) {
|
|
631
652
|
this.#publish({
|
|
@@ -649,6 +670,37 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
|
|
|
649
670
|
if (wasBlocked) this.#requestRead();
|
|
650
671
|
}
|
|
651
672
|
|
|
673
|
+
/** §5.11: the security gate refused this entry's read or claim. The
|
|
674
|
+
* entry keeps its snapshot and reads again when the status reports
|
|
675
|
+
* activation; a refusal that raced activation finds the client active. */
|
|
676
|
+
#gate(claim = false): void {
|
|
677
|
+
this.#gated = true;
|
|
678
|
+
if (claim) this.#claimGated = true;
|
|
679
|
+
if (this.#state.isRefreshing)
|
|
680
|
+
this.#publish({ ...this.#state, isRefreshing: false });
|
|
681
|
+
const generation = this.#generation;
|
|
682
|
+
void Promise.resolve(this.store.client.statusSnapshot()).then(
|
|
683
|
+
(status) => {
|
|
684
|
+
if (
|
|
685
|
+
generation === this.#generation &&
|
|
686
|
+
status.securityLifecycle !== 'preflight'
|
|
687
|
+
)
|
|
688
|
+
this.#resume();
|
|
689
|
+
},
|
|
690
|
+
() => {},
|
|
691
|
+
);
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
#resume(): void {
|
|
695
|
+
if (!this.#gated) return;
|
|
696
|
+
this.#gated = false;
|
|
697
|
+
if (this.#claimGated) {
|
|
698
|
+
this.#claimGated = false;
|
|
699
|
+
this.#claimCoverage();
|
|
700
|
+
}
|
|
701
|
+
this.#requestRead();
|
|
702
|
+
}
|
|
703
|
+
|
|
652
704
|
/** SPEC §7.5 failed transfer: incomplete coverage stops waiting on a failed
|
|
653
705
|
* sync attempt and resumes waiting when the next attempt starts. */
|
|
654
706
|
#onRoundFailureChange(): void {
|
|
@@ -759,6 +811,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
|
|
|
759
811
|
} while (this.#requested && this.#listeners.size > 0);
|
|
760
812
|
} catch (error) {
|
|
761
813
|
if (generation !== this.#generation || this.#listeners.size === 0) return;
|
|
814
|
+
if (refusedByPreflight(error)) {
|
|
815
|
+
this.#requested = false;
|
|
816
|
+
this.#gate();
|
|
817
|
+
return;
|
|
818
|
+
}
|
|
762
819
|
// SPEC §7.5: a failed latest read is never `ready`; the last
|
|
763
820
|
// successful rows and revision stay available beside the error.
|
|
764
821
|
this.#publish({
|