Module sync 

Available on crate feature sync only.

Native sync protocol for distributed PulseDB instances.

Requires the sync feature flag. Provides types, transport trait, and echo prevention for synchronizing data between PulseDB instances. Native sync protocol for distributed PulseDB instances.

This module enables synchronizing data between PulseDB instances across a network — PulseDB’s evolution from embedded-only to distributed agentic database.

Architecture

Desktop (Tauri)                    Server (Axum)
┌──────────────────┐              ┌──────────────────┐
│  PulseDB (local) │              │  PulseDB (server)│
│  ┌─────────────┐ │   push/pull  │  ┌─────────────┐ │
│  │ SyncManager │◄├─────────────►├──│ SyncManager │ │
│  │ (background)│ │  HTTP / WS   │  │ (background)│ │
│  └─────────────┘ │              │  └─────────────┘ │
└──────────────────┘              └──────────────────┘

Feature Flags

Feature	Description
sync	Core types, transport trait, sync engine, in-memory transport
sync-http	HTTP transport (reqwest) + server helper for Axum consumers
sync-websocket	WebSocket transport (tokio-tungstenite, future)

Module Overview

Core (always with sync feature):

• types — Wire types: SyncChange, SyncPayload, InstanceId, SyncCursor
• config — SyncConfig, SyncDirection, ConflictResolution, RetryConfig
• error — SyncError enum (Transport, Timeout, ProtocolVersion, etc.)
• transport — SyncTransport pluggable trait
• transport_mem — InMemorySyncTransport for testing
• guard — SyncApplyGuard thread-local echo prevention

Engine:

• manager — SyncManager: start/stop/sync_once/initial_sync lifecycle
• applier — RemoteChangeApplier: applies remote changes with idempotency
• progress — SyncProgressCallback for initial sync UI feedback

HTTP (with sync-http feature):

• server — SyncServer: framework-agnostic server handler
• transport_http — HttpSyncTransport: reqwest-based client

WAL Compaction

The WAL grows unboundedly as entities are created/updated/deleted. Call PulseDB::compact_wal() periodically to trim events that all peers have already synced. Compaction uses the min-cursor strategy: only events below the oldest peer’s cursor are removed.

Re-exports

pub use config::SyncConfig;

pub use error::SyncError;

pub use guard::is_sync_applying;

pub use guard::SyncApplyGuard;

pub use manager::SyncManager;

pub use progress::SyncProgressCallback;

pub use server::SyncServer;sync-http

pub use transport::SyncTransport;

pub use transport_http::HttpSyncTransport;sync-http

pub use transport_mem::InMemorySyncTransport;

pub use types::HandshakeRequest;

pub use types::HandshakeResponse;

pub use types::InstanceId;

pub use types::PullRequest;

pub use types::PullResponse;

pub use types::PushResponse;

pub use types::SerializableExperienceUpdate;

pub use types::SyncChange;

pub use types::SyncCursor;

pub use types::SyncEntityType;

pub use types::SyncPayload;

pub use types::SyncStatus;

Modules

applier

Remote change applier — applies changes received from a remote peer.

config

Sync configuration types.

error

Sync-specific error types.

guard

Echo prevention guard for sync operations.

manager

Sync manager — orchestrates sync lifecycle between PulseDB instances.

progress

Progress callback for initial sync operations.

serversync-http

Server-side sync handler for HTTP consumers.

transport

Pluggable transport trait for the sync protocol.

transport_httpsync-http

HTTP sync transport implementation.

transport_mem

In-memory sync transport for testing.

types

Core types for the PulseDB sync protocol.

Constants

SYNC_PROTOCOL_VERSION

Sync protocol version.