aegis-replication

Distributed replication and consensus for the Aegis Database Platform.

Overview

aegis-replication provides the distributed systems layer including Raft consensus, consistent hashing, sharding, distributed transactions, and conflict-free replicated data types (CRDTs).

Features

• Raft Consensus - Leader election and log replication
• Consistent Hashing - HashRing, JumpHash, Rendezvous hashing
• Sharding - Automatic data partitioning
• Distributed Transactions - Two-phase commit (2PC)
• CRDTs - Conflict-free replication for eventual consistency
• Vector Clocks - Causality tracking

Architecture

┌────────────────────────────────────────────────────────┐
│                   Cluster Manager                       │
├────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │    Raft     │  │   Shard     │  │ Transaction │    │
│  │  Consensus  │  │   Router    │  │ Coordinator │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
├────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Hash      │  │   Vector    │  │    CRDT     │    │
│  │   Ring      │  │   Clocks    │  │   Engine    │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
├────────────────────────────────────────────────────────┤
│                    Transport Layer                      │
│              (gRPC / TCP / In-Memory)                   │
└────────────────────────────────────────────────────────┘

Modules

Usage

[dependencies]
aegis-replication = { path = "../aegis-replication" }

Raft Consensus

use aegis_replication::raft::{RaftNode, RaftConfig};

let config = RaftConfig {
    node_id: 1,
    peers: vec![2, 3],
    election_timeout: Duration::from_millis(150..300),
    heartbeat_interval: Duration::from_millis(50),
};

let node = RaftNode::new(config, storage)?;

// Start the node
node.start().await?;

// Propose a value (only leader can propose)
if node.is_leader() {
    node.propose(command).await?;
}

Consistent Hashing

use aegis_replication::hash::{HashRing, JumpHash};

// HashRing with virtual nodes
let mut ring = HashRing::new(150); // 150 virtual nodes per physical node
ring.add_node("node-1");
ring.add_node("node-2");
ring.add_node("node-3");

// Get nodes for a key (returns primary + replicas)
let nodes = ring.get_nodes("user:123", 3);

// JumpHash for fixed node count
let node_index = JumpHash::hash("user:123", 3);

Distributed Transactions

use aegis_replication::transaction::{TwoPhaseCommit, TransactionCoordinator};

let coordinator = TransactionCoordinator::new(cluster);

// Begin distributed transaction
let tx = coordinator.begin().await?;

// Execute on multiple shards
tx.execute_on_shard(shard_1, operation_1).await?;
tx.execute_on_shard(shard_2, operation_2).await?;

// Two-phase commit
coordinator.commit(tx).await?;

CRDTs

use aegis_replication::crdt::{GCounter, LWWRegister, ORSet};

// G-Counter (grow-only counter)
let mut counter = GCounter::new(node_id);
counter.increment(5);
counter.merge(&remote_counter);
println!("Count: {}", counter.value());

// LWW-Register (last-writer-wins)
let mut register = LWWRegister::new();
register.set("value", timestamp);

// OR-Set (observed-remove set)
let mut set = ORSet::new(node_id);
set.add("item");
set.remove("item");

Vector Clocks

use aegis_replication::vector_clock::VectorClock;

let mut clock = VectorClock::new();

// Increment local time
clock.increment(node_id);

// Merge with remote clock
clock.merge(&remote_clock);

// Compare causality
match clock.compare(&other_clock) {
    Ordering::Before => println!("Happened before"),
    Ordering::After => println!("Happened after"),
    Ordering::Concurrent => println!("Concurrent events"),
}

Configuration

[replication]
replication_factor = 3
consistency_level = "quorum"    # one, quorum, all

[raft]
election_timeout_min = 150
election_timeout_max = 300
heartbeat_interval = 50

[sharding]
strategy = "hash"               # hash, range
shard_count = 16
auto_rebalance = true

Tests

cargo test -p aegis-replication

Test count: 634 tests (workspace total)

License

Apache-2.0