@syncular/server 0.83.0 → 0.85.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/src/storage.ts CHANGED
@@ -20,10 +20,12 @@ import type { AuthoritativeRelationPlan } from './authoritative-query';
20
20
  */
21
21
  import type {
22
22
  PushOperationResult,
23
+ RejectionDetails,
23
24
  RowValue,
24
25
  ScopeMap,
25
26
  UnitScopes,
26
27
  } from '@syncular/core';
28
+ import { asNumber } from './pg-executor';
27
29
  import type { CompiledSchema } from './schema';
28
30
 
29
31
  export interface CommitPruneQuery {
@@ -500,6 +502,296 @@ export function clientRoundState(
500
502
  };
501
503
  }
502
504
 
505
+ /** Runtime-neutral base64 (no `Buffer`, Workers-safe) for stored push results. */
506
+ function bytesToBase64(bytes: Uint8Array): string {
507
+ let binary = '';
508
+ for (const byte of bytes) binary += String.fromCharCode(byte);
509
+ return btoa(binary);
510
+ }
511
+
512
+ function base64ToBytes(text: string): Uint8Array {
513
+ const binary = atob(text);
514
+ const bytes = new Uint8Array(binary.length);
515
+ for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
516
+ return bytes;
517
+ }
518
+
519
+ /**
520
+ * Some drivers return a JSON column already parsed (pglite, node-postgres);
521
+ * SQLite returns the `TEXT`.
522
+ */
523
+ export function asJson<T>(value: unknown): T {
524
+ if (typeof value === 'string') return JSON.parse(value) as T;
525
+ return value as T;
526
+ }
527
+
528
+ /** Native SQLite and Postgres return `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
529
+ export function asUint8Array(value: unknown): Uint8Array {
530
+ if (value instanceof Uint8Array) return value;
531
+ if (value instanceof ArrayBuffer) return new Uint8Array(value);
532
+ if (Array.isArray(value)) return new Uint8Array(value);
533
+ throw new Error(`expected a BLOB column, got ${typeof value}`);
534
+ }
535
+
536
+ interface SerializedResult {
537
+ opIndex: number;
538
+ status: string;
539
+ code?: string;
540
+ message?: string;
541
+ serverVersion?: number;
542
+ serverRow?: string;
543
+ conflictColumns?: string;
544
+ retryable?: boolean;
545
+ details?: RejectionDetails;
546
+ }
547
+
548
+ /**
549
+ * Convert a push result to the JSON-able object both SQL backends store.
550
+ * `serverRow` bytes are base64-encoded: JSON cannot hold raw bytes.
551
+ */
552
+ export function pushResultToJson(result: StoredPushResult): unknown {
553
+ return {
554
+ status: result.status,
555
+ ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
556
+ ...(result.recordedAtMs !== undefined
557
+ ? { recordedAtMs: result.recordedAtMs }
558
+ : {}),
559
+ ...(result.cacheIdentity !== undefined
560
+ ? { cacheIdentity: result.cacheIdentity }
561
+ : {}),
562
+ ...(result.conflictAuthorization !== undefined
563
+ ? { conflictAuthorization: result.conflictAuthorization }
564
+ : {}),
565
+ results: result.results.map((record) => {
566
+ if (record.status === 'conflict') {
567
+ return {
568
+ opIndex: record.opIndex,
569
+ status: record.status,
570
+ code: record.code,
571
+ message: record.message,
572
+ serverVersion: record.serverVersion,
573
+ serverRow: bytesToBase64(record.serverRow),
574
+ conflictColumns: bytesToBase64(record.conflictColumns),
575
+ };
576
+ }
577
+ if (record.status === 'error') {
578
+ return {
579
+ opIndex: record.opIndex,
580
+ status: record.status,
581
+ code: record.code,
582
+ message: record.message,
583
+ retryable: record.retryable,
584
+ ...(record.details !== undefined ? { details: record.details } : {}),
585
+ };
586
+ }
587
+ return { opIndex: record.opIndex, status: record.status };
588
+ }),
589
+ };
590
+ }
591
+
592
+ export function pushResultFromJson(value: unknown): StoredPushResult {
593
+ const parsed = value as {
594
+ status: 'applied' | 'rejected';
595
+ commitSeq?: number;
596
+ recordedAtMs?: number;
597
+ cacheIdentity?: string;
598
+ conflictAuthorization?: StoredPushResult['conflictAuthorization'];
599
+ results: SerializedResult[];
600
+ };
601
+ const results: PushOperationResult[] = parsed.results.map((record) => {
602
+ if (record.status === 'conflict') {
603
+ return {
604
+ opIndex: record.opIndex,
605
+ status: 'conflict',
606
+ code: record.code ?? '',
607
+ message: record.message ?? '',
608
+ serverVersion: record.serverVersion ?? 0,
609
+ serverRow: base64ToBytes(record.serverRow ?? ''),
610
+ conflictColumns: base64ToBytes(record.conflictColumns ?? ''),
611
+ };
612
+ }
613
+ if (record.status === 'error') {
614
+ return {
615
+ opIndex: record.opIndex,
616
+ status: 'error',
617
+ code: record.code ?? '',
618
+ message: record.message ?? '',
619
+ retryable: record.retryable ?? false,
620
+ ...(record.details !== undefined ? { details: record.details } : {}),
621
+ };
622
+ }
623
+ return { opIndex: record.opIndex, status: 'applied' };
624
+ });
625
+ return {
626
+ status: parsed.status,
627
+ ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
628
+ ...(parsed.recordedAtMs !== undefined
629
+ ? { recordedAtMs: parsed.recordedAtMs }
630
+ : {}),
631
+ ...(parsed.cacheIdentity !== undefined
632
+ ? { cacheIdentity: parsed.cacheIdentity }
633
+ : {}),
634
+ ...(parsed.conflictAuthorization !== undefined
635
+ ? { conflictAuthorization: parsed.conflictAuthorization }
636
+ : {}),
637
+ results,
638
+ };
639
+ }
640
+
641
+ /** Row shapes the SQL backends' `SELECT`s return; values are driver-typed. */
642
+ export interface StoredRowRecord {
643
+ row_id: string;
644
+ server_version: unknown;
645
+ scopes: unknown;
646
+ payload: unknown;
647
+ column_versions: unknown;
648
+ }
649
+
650
+ export interface StoredChangeRecord {
651
+ tbl: string;
652
+ row_id: string;
653
+ op: unknown;
654
+ row_version: unknown;
655
+ scopes: unknown;
656
+ payload: unknown;
657
+ }
658
+
659
+ export interface StoredReactionRecord {
660
+ idempotency_key: string;
661
+ type: string;
662
+ version: unknown;
663
+ payload: unknown;
664
+ source_client_id: string;
665
+ source_client_commit_id: string;
666
+ source_commit_seq: unknown;
667
+ created_at_ms: unknown;
668
+ available_at_ms: unknown;
669
+ status: StoredReaction['status'];
670
+ attempts: unknown;
671
+ max_attempts: unknown;
672
+ lease_owner: string | null;
673
+ lease_expires_at_ms: unknown | null;
674
+ completed_at_ms: unknown | null;
675
+ last_failure: unknown | null;
676
+ }
677
+
678
+ export interface ClientRowRecord {
679
+ client_id: string;
680
+ actor_id: string;
681
+ wire_version: unknown;
682
+ cursor: unknown;
683
+ updated_at_ms: unknown;
684
+ schema_version: unknown;
685
+ units: unknown;
686
+ registration_digest: unknown;
687
+ catching_up: unknown;
688
+ last_round_at_ms: unknown;
689
+ last_error_code: string | null;
690
+ consecutive_failures: unknown;
691
+ }
692
+
693
+ export function toStoredRow(record: StoredRowRecord): StoredRow {
694
+ return {
695
+ rowId: record.row_id,
696
+ serverVersion: asNumber(record.server_version),
697
+ scopes: asJson<Record<string, string>>(record.scopes),
698
+ payload: asUint8Array(record.payload),
699
+ ...(record.column_versions === null || record.column_versions === undefined
700
+ ? {}
701
+ : { columnVersions: asUint8Array(record.column_versions) }),
702
+ };
703
+ }
704
+
705
+ export function toTombstone(record: {
706
+ commit_seq: unknown;
707
+ server_version: unknown;
708
+ scopes: unknown;
709
+ }): Tombstone {
710
+ return {
711
+ commitSeq: asNumber(record.commit_seq),
712
+ ...(record.server_version === null || record.server_version === undefined
713
+ ? {}
714
+ : { serverVersion: asNumber(record.server_version) }),
715
+ ...(record.scopes === null || record.scopes === undefined
716
+ ? {}
717
+ : { scopes: asJson<Record<string, string>>(record.scopes) }),
718
+ };
719
+ }
720
+
721
+ export function toStoredChange(record: StoredChangeRecord): StoredChange {
722
+ return {
723
+ table: record.tbl,
724
+ rowId: record.row_id,
725
+ op: asNumber(record.op) === 1 ? 'upsert' : 'delete',
726
+ ...(record.row_version !== null && record.row_version !== undefined
727
+ ? { rowVersion: asNumber(record.row_version) }
728
+ : {}),
729
+ scopes: asJson<Record<string, string>>(record.scopes),
730
+ ...(record.payload !== null && record.payload !== undefined
731
+ ? { payload: asUint8Array(record.payload) }
732
+ : {}),
733
+ };
734
+ }
735
+
736
+ export function toStoredReaction(record: StoredReactionRecord): StoredReaction {
737
+ return {
738
+ idempotencyKey: record.idempotency_key,
739
+ type: record.type,
740
+ version: asNumber(record.version),
741
+ payload: asJson(record.payload) as DurableJsonValue,
742
+ sourceClientId: record.source_client_id,
743
+ sourceClientCommitId: record.source_client_commit_id,
744
+ sourceCommitSeq: asNumber(record.source_commit_seq),
745
+ createdAtMs: asNumber(record.created_at_ms),
746
+ maxAttempts: asNumber(record.max_attempts),
747
+ status: record.status,
748
+ attempts: asNumber(record.attempts),
749
+ availableAtMs: asNumber(record.available_at_ms),
750
+ ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
751
+ ...(record.lease_expires_at_ms !== null
752
+ ? { leaseExpiresAtMs: asNumber(record.lease_expires_at_ms) }
753
+ : {}),
754
+ ...(record.completed_at_ms !== null
755
+ ? { completedAtMs: asNumber(record.completed_at_ms) }
756
+ : {}),
757
+ ...(record.last_failure !== null
758
+ ? { lastFailure: asJson(record.last_failure) as ReactionFailure }
759
+ : {}),
760
+ };
761
+ }
762
+
763
+ export const CLIENT_RECORD_COLUMNS =
764
+ 'client_id, actor_id, wire_version, cursor, updated_at_ms, schema_version, units, registration_digest, catching_up, last_round_at_ms, last_error_code, consecutive_failures';
765
+
766
+ export function toClientRecord(record: ClientRowRecord): ClientRecord {
767
+ return {
768
+ clientId: record.client_id,
769
+ actorId: record.actor_id,
770
+ wireVersion: asNumber(record.wire_version),
771
+ cursor: asNumber(record.cursor),
772
+ updatedAtMs: asNumber(record.updated_at_ms),
773
+ ...(record.schema_version === null
774
+ ? {}
775
+ : { schemaVersion: asNumber(record.schema_version) }),
776
+ ...(record.units === null || record.registration_digest === null
777
+ ? {}
778
+ : {
779
+ registration: {
780
+ units: asJson<UnitScopes[]>(record.units),
781
+ digest: asUint8Array(record.registration_digest),
782
+ },
783
+ }),
784
+ catchingUp: asJson<ClientRecord['catchingUp']>(record.catching_up),
785
+ ...clientRoundState(
786
+ record.last_round_at_ms === null
787
+ ? null
788
+ : asNumber(record.last_round_at_ms),
789
+ record.last_error_code,
790
+ asNumber(record.consecutive_failures),
791
+ ),
792
+ };
793
+ }
794
+
503
795
  /** One unit of the §4.5 scan set. */
504
796
  export interface LiveScanUnit {
505
797
  /** The unit's scope map; its first variable (keys sorted) is its index key. */