pulsedb/sync/
mod.rs

1//! Native sync protocol for distributed PulseDB instances.
2//!
3//! This module enables synchronizing data between PulseDB instances
4//! across a network — PulseDB's evolution from embedded-only to
5//! distributed agentic database.
6//!
7//! # Architecture
8//!
9//! ```text
10//! Desktop (Tauri)                    Server (Axum)
11//! ┌──────────────────┐              ┌──────────────────┐
12//! │  PulseDB (local) │              │  PulseDB (server)│
13//! │  ┌─────────────┐ │   push/pull  │  ┌─────────────┐ │
14//! │  │ SyncManager │◄├─────────────►├──│ SyncManager │ │
15//! │  │ (background)│ │  HTTP / WS   │  │ (background)│ │
16//! │  └─────────────┘ │              │  └─────────────┘ │
17//! └──────────────────┘              └──────────────────┘
18//! ```
19//!
20//! # Feature Flags
21//!
22//! | Feature | Description |
23//! |---------|-------------|
24//! | `sync` | Core types, transport trait, sync engine, in-memory transport |
25//! | `sync-http` | HTTP transport (reqwest) + server helper for Axum consumers |
26//! | `sync-websocket` | WebSocket transport (tokio-tungstenite, future) |
27//!
28//! # Module Overview
29//!
30//! **Core** (always with `sync` feature):
31//! - `types` — Wire types: `SyncChange`, `SyncPayload`, `InstanceId`, `SyncCursor`
32//! - `config` — `SyncConfig`, `SyncDirection`, `ConflictResolution`, `RetryConfig`
33//! - `error` — `SyncError` enum (Transport, Timeout, ProtocolVersion, etc.)
34//! - `transport` — `SyncTransport` pluggable trait
35//! - `transport_mem` — `InMemorySyncTransport` for testing
36//! - `guard` — `SyncApplyGuard` thread-local echo prevention
37//!
38//! **Engine**:
39//! - `manager` — `SyncManager`: start/stop/sync_once/initial_sync lifecycle
40//! - `applier` — `RemoteChangeApplier`: applies remote changes with idempotency
41//! - `progress` — `SyncProgressCallback` for initial sync UI feedback
42//!
43//! **HTTP** (with `sync-http` feature):
44//! - `server` — `SyncServer`: framework-agnostic server handler
45//! - `transport_http` — `HttpSyncTransport`: reqwest-based client
46//!
47//! # WAL Compaction
48//!
49//! The WAL grows unboundedly as entities are created/updated/deleted.
50//! Call [`PulseDB::compact_wal()`](crate::PulseDB::compact_wal) periodically
51//! to trim events that all peers have already synced. Compaction uses the
52//! min-cursor strategy: only events below the oldest peer's cursor are removed.
53
54pub mod applier;
55pub mod config;
56pub mod error;
57pub mod guard;
58pub mod manager;
59pub mod progress;
60pub(crate) mod pusher;
61#[cfg(feature = "sync-http")]
62#[cfg_attr(docsrs, doc(cfg(feature = "sync-http")))]
63pub mod server;
64pub mod transport;
65#[cfg(feature = "sync-http")]
66#[cfg_attr(docsrs, doc(cfg(feature = "sync-http")))]
67pub mod transport_http;
68pub mod transport_mem;
69pub mod types;
70
71/// Sync protocol version.
72///
73/// Exchanged during handshake to ensure compatibility between peers.
74/// Increment when making breaking changes to the wire format.
75pub const SYNC_PROTOCOL_VERSION: u32 = 1;
76
77// Re-exports for ergonomic access
78pub use config::SyncConfig;
79pub use error::SyncError;
80pub use guard::{is_sync_applying, SyncApplyGuard};
81pub use manager::SyncManager;
82pub use progress::SyncProgressCallback;
83#[cfg(feature = "sync-http")]
84pub use server::SyncServer;
85pub use transport::SyncTransport;
86#[cfg(feature = "sync-http")]
87pub use transport_http::HttpSyncTransport;
88pub use transport_mem::InMemorySyncTransport;
89pub use types::{
90    HandshakeRequest, HandshakeResponse, InstanceId, PullRequest, PullResponse, PushResponse,
91    SerializableExperienceUpdate, SyncChange, SyncCursor, SyncEntityType, SyncPayload, SyncStatus,
92};
pulsedb/sync/mod.rs

pulsedb/sync/
mod.rs
