Struct SyncClient 

pub struct SyncClient { /* private fields */ }

Sync client — manages the WebSocket connection to Origin.

The client runs as a background Tokio task. It:

1. Connects to Origin via WebSocket
2. Sends handshake with JWT + vector clock + shape subscriptions
3. Pushes accumulated CRDT deltas
4. Receives shape snapshots and incremental deltas
5. Handles rejections via CompensationRegistry
6. Auto-reconnects with exponential backoff on disconnect

Implementations

impl SyncClient

pub fn new(config: SyncConfig, peer_id: u64) -> Self

Create a new sync client (does not connect yet).

pub fn with_flow_control( config: SyncConfig, peer_id: u64, flow_config: FlowControlConfig, ) -> Self

Create a new sync client with custom flow control config.

pub fn set_identity(&mut self, lite_id: String, epoch: u64)

Set the Lite identity for fork detection (called after LiteIdentity::load_or_create).

pub async fn state(&self) -> SyncState

Current connection state.

pub fn set_compensation_handler(&self, handler: Arc<dyn CompensationHandler>)

Register a compensation handler.

pub fn shapes(&self) -> &Arc<Mutex<ShapeManager>>

Access the shape manager (for subscribing/unsubscribing).

pub fn clock(&self) -> &Arc<Mutex<VectorClock>>

Access the vector clock.

pub async fn build_handshake(&self) -> HandshakeMsg

Build a handshake message from current state.

pub async fn handle_handshake_ack(&self, ack: &HandshakeAckMsg) -> bool

Process a handshake acknowledgment from Origin.

pub async fn build_delta_pushes( &self, pending: &[PendingDelta], ) -> Vec<DeltaPushMsg>

Build DeltaPush messages from pending deltas.

Respects the flow control window: returns at most next_batch_size() deltas. Each message includes a CRC32C checksum of the delta payload for integrity verification at Origin.

pub async fn record_push(&self, mutation_ids: &[u64])

Record that deltas were pushed (update flow control in-flight tracking).

pub async fn handle_delta_ack(&self, ack: &DeltaAckMsg)

Process a DeltaAck from Origin.

pub async fn handle_delta_reject(&self, reject: &DeltaRejectMsg)

Process a DeltaReject from Origin.

pub async fn handle_shape_snapshot(&self, msg: &ShapeSnapshotMsg)

Process a ShapeSnapshot from Origin.

pub async fn handle_shape_delta(&self, msg: &ShapeDeltaMsg)

Process a ShapeDelta from Origin.

pub async fn handle_clock_sync(&self, msg: &VectorClockSyncMsg)

Process a VectorClockSync from Origin.

pub async fn check_sequence_gap( &self, shape_id: &str, lsn: u64, ) -> Option<ResyncRequestMsg>

Check an incoming ShapeDelta for sequence gaps.

For each shape, we track the last LSN received. If the incoming LSN is not contiguous (gap > 1), this indicates missing deltas in the stream. Returns Some(ResyncRequestMsg) if a gap is detected, None otherwise.

Note: LSNs may not be strictly +1 sequential (Origin may skip LSNs for other shapes), so we only flag a gap when the new LSN is MORE than 1 ahead of the last seen LSN for the SAME shape. A gap means deltas were lost in transit.

pub async fn reset_sequence_tracking(&self)

Reset sequence tracking state on reconnect.

pub async fn set_pending_resync(&self, msg: ResyncRequestMsg)

Store a pending re-sync request (set by gap detection in receive loop).

pub async fn take_pending_resync(&self) -> Option<ResyncRequestMsg>

Take the pending re-sync request (consumed by delta push loop).

pub fn build_ping(&self) -> SyncFrame

Build a ping frame.

pub fn backoff_duration(&self, attempt: u32) -> Duration

Calculate backoff duration for reconnection attempt N.

pub async fn set_state(&self, new_state: SyncState)

Set the connection state.

pub fn compensation(&self) -> &Arc<CompensationRegistry>

Access the compensation registry.

pub fn config(&self) -> &SyncConfig

Access config.

pub fn peer_id(&self) -> u64

Peer ID.

pub fn flow(&self) -> &Arc<Mutex<FlowController>>

Access the flow controller.

pub fn metrics(&self) -> &Arc<SyncMetrics>

Access the sync metrics.

pub async fn update_pending_stats(&self, count: usize, bytes: usize)

Update pending queue stats in the flow controller. Called from the push loop after reading pending deltas.

pub async fn is_queue_full(&self) -> bool

Check if the pending queue is at capacity (flow control).

pub async fn sync_metrics(&self) -> SyncMetricsSnapshot

Get a snapshot of sync metrics for monitoring/health.

pub async fn reset_flow_control(&self)

Reset flow controller on reconnect.

pub async fn should_refresh_token(&self) -> bool

Check if the JWT token needs proactive refresh (at 80% of lifetime).

Returns true if a refresh should be initiated. Called from the ping loop to piggyback on the keepalive timer.

pub async fn initiate_token_refresh(&self) -> Option<TokenRefreshMsg>

Initiate a token refresh via the token provider.

Returns Some(TokenRefreshMsg) with the new token if the provider returned one, or None if the provider failed.

pub async fn handle_token_refresh_ack(&self, ack: &TokenRefreshAckMsg)

Handle a TokenRefreshAck from Origin.

pub async fn pause_for_auth(&self)

Pause delta push due to auth failure. Called when Origin rejects with PermissionDenied, indicating the token has expired.

pub async fn is_push_paused_for_auth(&self) -> bool

Check if push is paused for auth.