@syncular/server 0.54.0 → 0.55.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.
@@ -66,6 +66,7 @@ interface Registration {
66
66
  readonly codec: CompiledTable;
67
67
  readonly id: string;
68
68
  readonly table: string;
69
+ readonly schemaVersion: number;
69
70
  readonly effective: ScopeMap;
70
71
  }
71
72
  type PresenceDoc = Record<string, unknown>;
package/dist/realtime.js CHANGED
@@ -149,6 +149,12 @@ export class RealtimeSession {
149
149
  * never clobbers a follow-up round's in-flight marker. */
150
150
  #requestScanner;
151
151
  #activeRound;
152
+ /** Deltas wait for every round response and registration refresh to finish. */
153
+ #roundsRefreshing = 0;
154
+ #deferredDeltas = [];
155
+ #deferredBytes = 0;
156
+ #deferredRegistrations;
157
+ #closed = false;
152
158
  /** §8.6.4 rate cap: per-scope-key last-fanout time + a pending latest
153
159
  * document coalesced while over the cap. */
154
160
  #presenceRate = new Map();
@@ -346,6 +352,10 @@ export class RealtimeSession {
346
352
  }
347
353
  /** §8.6.1: on disconnect, leave every key this session was present on. */
348
354
  dropAllPresence() {
355
+ this.#closed = true;
356
+ this.#deferredDeltas = [];
357
+ this.#deferredBytes = 0;
358
+ this.#deferredRegistrations = undefined;
349
359
  for (const key of this.#hub.presence.keysOf(this.partition, this)) {
350
360
  this.#leavePresence(key);
351
361
  }
@@ -406,6 +416,7 @@ export class RealtimeSession {
406
416
  }
407
417
  const token = Symbol('round');
408
418
  this.#activeRound = token;
419
+ this.#roundsRefreshing += 1;
409
420
  return this.#runRound(done.message.slice(), token);
410
421
  }
411
422
  /** Drive the shared handler and stream the response back (§8.7). */
@@ -488,6 +499,31 @@ export class RealtimeSession {
488
499
  // §8.7 registration at round end: reload the persisted list — it
489
500
  // only advances on success, so failed rounds change nothing.
490
501
  await this.refreshRegistrations(false);
502
+ this.#roundsRefreshing -= 1;
503
+ if (!this.#closed &&
504
+ this.#roundsRefreshing === 0 &&
505
+ this.#deferredRegistrations !== undefined) {
506
+ const registrations = JSON.stringify([
507
+ this.wireVersion,
508
+ this.registrations.map(({ id, table, schemaVersion, effective }) => [
509
+ id,
510
+ table,
511
+ schemaVersion,
512
+ effective,
513
+ ]),
514
+ ]);
515
+ if (registrations !== this.#deferredRegistrations) {
516
+ this.sendWake('catchup-required');
517
+ }
518
+ else {
519
+ const deltas = this.#deferredDeltas;
520
+ this.#deferredDeltas = [];
521
+ this.#deferredBytes = 0;
522
+ this.#deferredRegistrations = undefined;
523
+ for (const delta of deltas)
524
+ this.#sendDelta(delta.bytes, delta.commitSeq, delta.changes);
525
+ }
526
+ }
491
527
  }
492
528
  }
493
529
  async #sendRoundChunk(chunk) {
@@ -526,8 +562,11 @@ export class RealtimeSession {
526
562
  registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId);
527
563
  }
528
564
  catch {
529
- if (!failClosed)
565
+ if (!failClosed) {
566
+ if (this.#deferredRegistrations !== undefined)
567
+ this.sendWake('catchup-required');
530
568
  return;
569
+ }
531
570
  // Fail closed (host refresh): drop every grant on the connection.
532
571
  registrations = [];
533
572
  }
@@ -582,6 +621,9 @@ export class RealtimeSession {
582
621
  }));
583
622
  }
584
623
  sendWake(reason) {
624
+ this.#deferredDeltas = [];
625
+ this.#deferredBytes = 0;
626
+ this.#deferredRegistrations = undefined;
585
627
  this.wakePending = true;
586
628
  this.#wakeRequiredThroughSeq = Math.max(this.#wakeRequiredThroughSeq, this.lastKnownSeq);
587
629
  this.#sendSafe(JSON.stringify({
@@ -638,15 +680,25 @@ export class RealtimeSession {
638
680
  this.sendWake('catchup-required');
639
681
  return;
640
682
  }
683
+ if (this.#roundsRefreshing > 0 && !this.wakePending) {
684
+ const registrations = JSON.stringify([
685
+ this.wireVersion,
686
+ this.registrations.map(({ id, table, schemaVersion, effective }) => [
687
+ id,
688
+ table,
689
+ schemaVersion,
690
+ effective,
691
+ ]),
692
+ ]);
693
+ if (this.#deferredRegistrations !== undefined &&
694
+ this.#deferredRegistrations !== registrations) {
695
+ this.sendWake('catchup-required');
696
+ return;
697
+ }
698
+ this.#deferredRegistrations = registrations;
699
+ }
641
700
  if (sections.length === 0)
642
701
  return;
643
- if (this.#activeRound !== undefined) {
644
- // §8.7 interleaving: no 0x00 messages while a response stream is
645
- // in flight — the §8.2 suppression path takes over (the client's
646
- // post-round ack lifts it when the round covered this commit).
647
- this.sendWake('catchup-required');
648
- return;
649
- }
650
702
  if (this.wakePending) {
651
703
  // §8.2: deltas must be cursor-contiguous; while the client is behind
652
704
  // we send (coalescible) wake-ups instead of a delta past its cursor.
@@ -693,8 +745,25 @@ export class RealtimeSession {
693
745
  const tagged = new Uint8Array(bytes.length + 1);
694
746
  tagged[0] = REALTIME_TAG_DELTA;
695
747
  tagged.set(bytes, 1);
748
+ const changeCount = sections.reduce((n, s) => n + s.changes.length, 0);
749
+ if (this.#roundsRefreshing > 0) {
750
+ if (this.#deferredBytes + tagged.length > this.#maxDeltaBytes) {
751
+ this.sendWake('catchup-required');
752
+ return;
753
+ }
754
+ this.#deferredDeltas.push({
755
+ bytes: tagged,
756
+ commitSeq: commit.commitSeq,
757
+ changes: changeCount,
758
+ });
759
+ this.#deferredBytes += tagged.length;
760
+ return;
761
+ }
762
+ this.#sendDelta(tagged, commit.commitSeq, changeCount);
763
+ }
764
+ #sendDelta(tagged, commitSeq, changes) {
696
765
  this.#sendSafe(tagged);
697
- this.cursor = Math.max(this.cursor, commit.commitSeq);
766
+ this.cursor = Math.max(this.cursor, commitSeq);
698
767
  const events = this.#events;
699
768
  if (events !== undefined) {
700
769
  emitEvent(events, {
@@ -704,9 +773,9 @@ export class RealtimeSession {
704
773
  actorId: this.actorId,
705
774
  clientId: this.clientId,
706
775
  sessionId: this.sessionId,
707
- commitSeq: commit.commitSeq,
708
- bytes: bytes.length,
709
- changes: sections.reduce((n, s) => n + s.changes.length, 0),
776
+ commitSeq,
777
+ bytes: tagged.length - 1,
778
+ changes,
710
779
  });
711
780
  }
712
781
  }
@@ -837,6 +906,7 @@ export class RealtimeHub {
837
906
  id: subscription.id,
838
907
  codec: table,
839
908
  table: subscription.table,
909
+ schemaVersion: subscription.schemaVersion ?? this.#config.schema.version,
840
910
  effective: outcome.effective,
841
911
  });
842
912
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server",
3
- "version": "0.54.0",
3
+ "version": "0.55.0",
4
4
  "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
68
68
  "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
69
69
  },
70
70
  "dependencies": {
71
- "@syncular/core": "0.54.0"
71
+ "@syncular/core": "0.55.0"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@electric-sql/pglite": "^0.5.4"
package/src/realtime.ts CHANGED
@@ -110,6 +110,7 @@ interface Registration {
110
110
  readonly codec: CompiledTable;
111
111
  readonly id: string;
112
112
  readonly table: string;
113
+ readonly schemaVersion: number;
113
114
  readonly effective: ScopeMap;
114
115
  }
115
116
 
@@ -261,6 +262,13 @@ export class RealtimeSession {
261
262
  * never clobbers a follow-up round's in-flight marker. */
262
263
  #requestScanner: MessageStreamScanner | undefined;
263
264
  #activeRound: symbol | undefined;
265
+ /** Deltas wait for every round response and registration refresh to finish. */
266
+ #roundsRefreshing = 0;
267
+ #deferredDeltas: { bytes: Uint8Array; commitSeq: number; changes: number }[] =
268
+ [];
269
+ #deferredBytes = 0;
270
+ #deferredRegistrations: string | undefined;
271
+ #closed = false;
264
272
  /** §8.6.4 rate cap: per-scope-key last-fanout time + a pending latest
265
273
  * document coalesced while over the cap. */
266
274
  #presenceRate = new Map<
@@ -505,6 +513,10 @@ export class RealtimeSession {
505
513
 
506
514
  /** §8.6.1: on disconnect, leave every key this session was present on. */
507
515
  dropAllPresence(): void {
516
+ this.#closed = true;
517
+ this.#deferredDeltas = [];
518
+ this.#deferredBytes = 0;
519
+ this.#deferredRegistrations = undefined;
508
520
  for (const key of this.#hub.presence.keysOf(this.partition, this)) {
509
521
  this.#leavePresence(key);
510
522
  }
@@ -564,6 +576,7 @@ export class RealtimeSession {
564
576
  }
565
577
  const token = Symbol('round');
566
578
  this.#activeRound = token;
579
+ this.#roundsRefreshing += 1;
567
580
  return this.#runRound(done.message.slice(), token);
568
581
  }
569
582
 
@@ -668,6 +681,32 @@ export class RealtimeSession {
668
681
  // §8.7 registration at round end: reload the persisted list — it
669
682
  // only advances on success, so failed rounds change nothing.
670
683
  await this.refreshRegistrations(false);
684
+ this.#roundsRefreshing -= 1;
685
+ if (
686
+ !this.#closed &&
687
+ this.#roundsRefreshing === 0 &&
688
+ this.#deferredRegistrations !== undefined
689
+ ) {
690
+ const registrations = JSON.stringify([
691
+ this.wireVersion,
692
+ this.registrations.map(({ id, table, schemaVersion, effective }) => [
693
+ id,
694
+ table,
695
+ schemaVersion,
696
+ effective,
697
+ ]),
698
+ ]);
699
+ if (registrations !== this.#deferredRegistrations) {
700
+ this.sendWake('catchup-required');
701
+ } else {
702
+ const deltas = this.#deferredDeltas;
703
+ this.#deferredDeltas = [];
704
+ this.#deferredBytes = 0;
705
+ this.#deferredRegistrations = undefined;
706
+ for (const delta of deltas)
707
+ this.#sendDelta(delta.bytes, delta.commitSeq, delta.changes);
708
+ }
709
+ }
671
710
  }
672
711
  }
673
712
 
@@ -711,7 +750,11 @@ export class RealtimeSession {
711
750
  this.clientId,
712
751
  );
713
752
  } catch {
714
- if (!failClosed) return;
753
+ if (!failClosed) {
754
+ if (this.#deferredRegistrations !== undefined)
755
+ this.sendWake('catchup-required');
756
+ return;
757
+ }
715
758
  // Fail closed (host refresh): drop every grant on the connection.
716
759
  registrations = [];
717
760
  }
@@ -779,6 +822,9 @@ export class RealtimeSession {
779
822
  }
780
823
 
781
824
  sendWake(reason: WakeReason): void {
825
+ this.#deferredDeltas = [];
826
+ this.#deferredBytes = 0;
827
+ this.#deferredRegistrations = undefined;
782
828
  this.wakePending = true;
783
829
  this.#wakeRequiredThroughSeq = Math.max(
784
830
  this.#wakeRequiredThroughSeq,
@@ -848,14 +894,26 @@ export class RealtimeSession {
848
894
  this.sendWake('catchup-required');
849
895
  return;
850
896
  }
851
- if (sections.length === 0) return;
852
- if (this.#activeRound !== undefined) {
853
- // §8.7 interleaving: no 0x00 messages while a response stream is
854
- // in flight — the §8.2 suppression path takes over (the client's
855
- // post-round ack lifts it when the round covered this commit).
856
- this.sendWake('catchup-required');
857
- return;
897
+ if (this.#roundsRefreshing > 0 && !this.wakePending) {
898
+ const registrations = JSON.stringify([
899
+ this.wireVersion,
900
+ this.registrations.map(({ id, table, schemaVersion, effective }) => [
901
+ id,
902
+ table,
903
+ schemaVersion,
904
+ effective,
905
+ ]),
906
+ ]);
907
+ if (
908
+ this.#deferredRegistrations !== undefined &&
909
+ this.#deferredRegistrations !== registrations
910
+ ) {
911
+ this.sendWake('catchup-required');
912
+ return;
913
+ }
914
+ this.#deferredRegistrations = registrations;
858
915
  }
916
+ if (sections.length === 0) return;
859
917
  if (this.wakePending) {
860
918
  // §8.2: deltas must be cursor-contiguous; while the client is behind
861
919
  // we send (coalescible) wake-ups instead of a delta past its cursor.
@@ -902,8 +960,26 @@ export class RealtimeSession {
902
960
  const tagged = new Uint8Array(bytes.length + 1);
903
961
  tagged[0] = REALTIME_TAG_DELTA;
904
962
  tagged.set(bytes, 1);
963
+ const changeCount = sections.reduce((n, s) => n + s.changes.length, 0);
964
+ if (this.#roundsRefreshing > 0) {
965
+ if (this.#deferredBytes + tagged.length > this.#maxDeltaBytes) {
966
+ this.sendWake('catchup-required');
967
+ return;
968
+ }
969
+ this.#deferredDeltas.push({
970
+ bytes: tagged,
971
+ commitSeq: commit.commitSeq,
972
+ changes: changeCount,
973
+ });
974
+ this.#deferredBytes += tagged.length;
975
+ return;
976
+ }
977
+ this.#sendDelta(tagged, commit.commitSeq, changeCount);
978
+ }
979
+
980
+ #sendDelta(tagged: Uint8Array, commitSeq: number, changes: number): void {
905
981
  this.#sendSafe(tagged);
906
- this.cursor = Math.max(this.cursor, commit.commitSeq);
982
+ this.cursor = Math.max(this.cursor, commitSeq);
907
983
  const events = this.#events;
908
984
  if (events !== undefined) {
909
985
  emitEvent(events, {
@@ -913,9 +989,9 @@ export class RealtimeSession {
913
989
  actorId: this.actorId,
914
990
  clientId: this.clientId,
915
991
  sessionId: this.sessionId,
916
- commitSeq: commit.commitSeq,
917
- bytes: bytes.length,
918
- changes: sections.reduce((n, s) => n + s.changes.length, 0),
992
+ commitSeq,
993
+ bytes: tagged.length - 1,
994
+ changes,
919
995
  });
920
996
  }
921
997
  }
@@ -1089,6 +1165,8 @@ export class RealtimeHub {
1089
1165
  id: subscription.id,
1090
1166
  codec: table,
1091
1167
  table: subscription.table,
1168
+ schemaVersion:
1169
+ subscription.schemaVersion ?? this.#config.schema.version,
1092
1170
  effective: outcome.effective,
1093
1171
  });
1094
1172
  }