replication_engine/lib.rs
1// Copyright (c) 2025-2026 Adrian Robinson. Licensed under the AGPL-3.0.
2// See LICENSE file in the project root for full license text.
3
4//! # Replication Engine
5//!
6//! A mesh replication agent for synchronizing data between `sync-engine` nodes.
7//!
8//! ## Architecture
9//!
10//! The replication engine sits between the local `sync-engine` and remote peers,
11//! managing bidirectional data flow via Redis Streams:
12//!
13//! ```text
14//! ┌───────────────────────────────────────────────────────────────────────────┐
15//! │ replication-engine │
16//! │ │
17//! │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ │
18//! │ │ PeerManager │───►│ StreamTailer │───►│ Dedup + Apply to sync-engine │ │
19//! │ │ (per peer) │ │ (XREAD) │ │ (hash comparison) │ │
20//! │ └─────────────┘ └──────────────┘ └──────────────────────────────┘ │
21//! │ │ │ │
22//! │ ▼ ▼ │
23//! │ ┌─────────────┐ ┌─────────────────────────┐ │
24//! │ │ CursorStore │ │ MerkleRepair (cold path)│ │
25//! │ │ (SQLite) │ │ (periodic anti-entropy) │ │
26//! │ └─────────────┘ └─────────────────────────┘ │
27//! └───────────────────────────────────────────────────────────────────────────┘
28//! ```
29//!
30//! ## Two-Path Replication
31//!
32//! 1. **Hot Path (CDC Streams)**: Real-time tailing of peer `cdc` streams
33//! 2. **Cold Path (Merkle Repair)**: Periodic anti-entropy using Merkle tree comparison
34//!
35//! ## Usage
36//!
37//! ```rust,no_run
38//! use replication_engine::{ReplicationEngine, ReplicationEngineConfig};
39//! use tokio::sync::watch;
40//!
41//! #[tokio::main]
42//! async fn main() {
43//! let config = ReplicationEngineConfig::default();
44//! let (_tx, rx) = watch::channel(config.clone());
45//!
46//! let mut engine = ReplicationEngine::new(config, rx);
47//! engine.start().await.expect("Failed to start");
48//!
49//! // Engine runs until shutdown signal
50//! engine.shutdown().await;
51//! }
52//! ```
53
54pub mod batch;
55pub mod circuit_breaker;
56pub mod config;
57pub mod coordinator;
58pub mod cursor;
59pub mod error;
60pub mod metrics;
61pub mod peer;
62pub mod resilience;
63pub mod stream;
64pub mod sync_engine;
65
66// Re-exports for convenience
67pub use circuit_breaker::{CircuitBreaker, CircuitConfig, CircuitError, SyncEngineCircuit};
68pub use config::{
69 ReplicationEngineConfig, ReplicationEngineSettings, PeerConfig,
70 HotPathConfig, ColdPathConfig, CursorConfig,
71 SloConfig, PeerHealthConfig,
72};
73pub use coordinator::{ReplicationEngine, EngineState, HealthCheck, PeerHealth};
74pub use error::{ReplicationError, Result};
75pub use cursor::CursorStore;
76pub use peer::{PeerManager, PeerCircuitState};
77pub use stream::{StreamTailer, CdcEvent};
78pub use sync_engine::{SyncEngineRef, NoOpSyncEngine, SyncError};