@syncular/client 0.71.1 → 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 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 = 'preflight';
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.#securityLifecycle = 'active';
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
  /**
@@ -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
@@ -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
- this.#claimError = errorOf(error);
379
- this.#requestRead();
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.71.1",
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.71.1"
124
+ "@syncular/core": "0.72.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.71.1",
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 = 'preflight';
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.#securityLifecycle = 'active';
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
 
@@ -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
@@ -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
- this.#claimError = errorOf(error);
522
- this.#requestRead();
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({