Strongly consistent distributed cache with Raft consensus.

This crate provides an embedded distributed cache that uses:

• Moka for high-performance local caching with automatic TTL/eviction
• raft-rs for strong consistency via Raft consensus
• Two-tier membership for safe cluster management

Features

• Strong consistency for writes via Raft consensus
• Fast local reads from Moka cache
• Automatic TTL and TinyLFU eviction
• Two-tier cluster membership (discovery + manual Raft control)
• Pre-validation to ensure state machine apply never fails

Example

use distributed_cache::{DistributedCache, CacheConfig};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create configuration
    let config = CacheConfig::new(1, "127.0.0.1:9000".parse()?)
        .with_max_capacity(100_000)
        .with_default_ttl(Duration::from_secs(3600));

    // Create the distributed cache
    let cache = DistributedCache::new(config).await?;

    // Write operations go through Raft consensus
    cache.put("user:123", "Alice").await?;

    // Read operations are local (fast, but may be stale on followers)
    if let Some(value) = cache.get(b"user:123").await {
        println!("Found: {:?}", value);
    }

    // Delete
    cache.delete("user:123").await?;

    Ok(())
}

Architecture

┌─────────────────────────────────────────────┐
│            Application Layer                 │
└─────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│          DistributedCache API               │
│  • get(key) -> Option<Value>                │
│  • put(key, value) -> Result<()>            │
│  • delete(key) -> Result<()>                │
└─────────────────────────────────────────────┘
                    │
    ┌───────────────┼───────────────┐
    ▼               ▼               ▼
┌─────────┐   ┌──────────┐   ┌─────────┐
│ Cluster │   │  Raft    │   │  Moka   │
│Membership│  │Consensus │   │ Cache   │
└─────────┘   └──────────┘   └─────────┘

Consistency Model

• Writes: Strongly consistent via Raft (linearizable)
• Reads: Locally consistent (may be stale on followers)
• Leader reads: Strongly consistent if reading from leader

Checkpointing

The cache supports periodic checkpointing for fast recovery:

use distributed_cache::checkpoint::{CheckpointConfig, CheckpointManager};

let config = CheckpointConfig::new("./checkpoints")
    .with_log_threshold(10_000)
    .with_compression(true);

// Snapshots are automatically created based on configured triggers