Expand description
Consensus layer for AmateRS (Ukehi - The Sacred Pledge)
This crate implements Raft consensus with support for encrypted logs and distributed cluster management.
§Architecture
The consensus layer consists of:
- Raft Node: Core consensus implementation with leader election and log replication
- Log Management: Persistent log with in-memory cache and compaction
- State Management: Persistent and volatile state tracking
- RPC Layer: Request/response messages for inter-node communication
§Example
ⓘ
use amaters_cluster::{RaftNode, RaftConfig, Command};
// Create a 3-node cluster
let config = RaftConfig::new(1, vec![1, 2, 3]);
let node = RaftNode::new(config)?;
// Propose a command (as leader)
let cmd = Command::from_str("SET key value");
let index = node.propose(cmd)?;§Consensus Flow
propose(cmd) → [Leader]
│ replicate_to_followers()
├──→ [Follower 1] handle_append_entries()
└──→ [Follower 2] handle_append_entries()
↓
handle_replication_response() (on leader)
↓
commit_index advances → StateMachine::apply()Re-exports§
pub use cluster_command::ClusterCommand;pub use cluster_topology::ClusterTopology;pub use cluster_topology::NodeState as ClusterNodeState;pub use cluster_topology::NodeStatus;pub use cluster_topology::TopologyCollector;pub use encryption::EncryptedPayload;pub use encryption::EntryEncryptor;pub use encryption::LogEncryptionKey;pub use encryption::LogIntegrityVerifier;pub use error::RaftError;pub use error::RaftResult;pub use failover::AlertCallback;pub use failover::AlertEvent;pub use failover::AlertManager;pub use failover::FailoverConfig;pub use failover::FailoverController;pub use failover::FailoverCoordinator;pub use failover::FailoverEvent;pub use alert_rules::AlertRule;pub use alert_rules::AlertSeverity;pub use alert_rules::AlertSink;pub use alert_rules::CollectingSink;pub use alert_rules::FiredAlert;pub use alert_rules::LogSink;pub use alert_rules::RuleEngine;pub use alert_rules::default_rules;pub use alert_rules::event_dedup_key;pub use heartbeat::FailureDetector;pub use key_rotation::KeyManager;pub use key_rotation::KeyVersion;pub use key_rotation::LEGACY_KEY_VERSION;pub use log::ApplyResult;pub use log::Command;pub use log::LogEntry;pub use log::RaftLog;pub use log::SnapshotData;pub use log::StateMachine;pub use merkle::MerkleProof;pub use merkle::MerkleTree;pub use metrics::ClusterMetrics;pub use migration::Migration;pub use migration::MigrationStatus;pub use migration::MigrationTracker;pub use migration::compute_rebalance_plan;pub use node::RaftNode;pub use partitioner::PartitionStrategy;pub use partitioner::Partitioner;pub use partitioner::QueryPlan;pub use partitioner::QueryRouter;pub use partitioner::QueryStats;pub use partitioner::ResultMerger;pub use persistence::FilePersistence;pub use persistence::MemoryPersistence;pub use persistence::RaftPersistence;pub use placement::PlacementAction;pub use placement::PlacementCoordinator;pub use placement::PlacementPlan;pub use placement::PlacementPolicy;pub use placement_scheduler::PlacementScheduler;pub use placement_scheduler::PlacementSchedulerConfig;pub use placement_scheduler::PlacementSchedulerHandle;pub use placement_state_machine::PlacementStateMachine;pub use rpc::AppendEntriesRequest;pub use rpc::AppendEntriesResponse;pub use rpc::RequestVoteRequest;pub use rpc::RequestVoteResponse;pub use shard::KeyRange;pub use shard::ShardId;pub use shard::ShardMerge;pub use shard::ShardMetadata;pub use shard::ShardRegistry;pub use shard::ShardSplit;pub use shard::ShardState;pub use shard::ShardTransfer;pub use snapshot::DiskSnapshotStore;pub use snapshot::InstallSnapshotRequest;pub use snapshot::InstallSnapshotResponse;pub use snapshot::Snapshot;pub use snapshot::SnapshotConfig;pub use snapshot::SnapshotManager;pub use snapshot::SnapshotMetadata;pub use snapshot::SnapshotPolicy;pub use snapshot::SnapshotReceiver;pub use snapshot::SnapshotStore;pub use state::CandidateState;pub use state::FencingTokenState;pub use state::LeaderState;pub use state::PersistentState;pub use state::VolatileState;pub use types::ClusterConfig;pub use types::ConfigState;pub use types::FailureEvent;pub use types::FencingToken;pub use types::HeartbeatConfig;pub use types::LogIndex;pub use types::MembershipChange;pub use types::NodeId;pub use types::NodeState;pub use types::RaftConfig;pub use types::Term;pub use wal::CorruptionPolicy;pub use wal::SyncMode;pub use wal::WalDiagnostics;pub use wal::WalReader;pub use wal::WalWriter;
Modules§
- alert_
rules - Alert rule engine for the AmateRS cluster layer.
- cluster_
command - Typed cluster command encoding for Raft log entries.
- cluster_
topology - Cluster topology snapshot for dashboards and observability.
- config
- Cluster node configuration: TOML file + environment variable overrides + dynamic reload.
- encryption
- AES-256-GCM encryption and HMAC-SHA256 integrity for Raft log payloads.
- error
- Error types for the Raft consensus module
- failover
- Automatic failover coordination for Raft clusters.
- heartbeat
- Heartbeat-based failure detection for cluster peers.
- key_
rotation - Key rotation for
LogEncryptionKeys. - log
- Log management for Raft consensus
- merkle
- Merkle tree for batch log integrity verification.
- metrics
- Prometheus-compatible metrics for the AmateRS cluster consensus layer.
- migration
- Live data migration tracker for load-balanced shard movement.
- node
- Main Raft node implementation
- partitioner
- Key range partitioning and query routing
- persistence
- Persistent storage backends for Raft consensus
- placement
- Placement driver — deterministic shard placement planning.
- placement_
scheduler - Background placement scheduling task.
- placement_
state_ machine - State machine for the placement layer.
- rpc
- RPC message types for Raft consensus
- shard
- Shard metadata and operations
- snapshot
- Snapshot management and log compaction for Raft consensus
- state
- Raft persistent and volatile state
- types
- Core types for Raft consensus
- wal
- Segment-based Write-Ahead Log (WAL) with CRC32 integrity and fsync.