ember-cluster

distributed coordination for ember. provides cluster topology management, gossip-based failure detection, raft consensus, and live slot migration.

features

slot management — 16384 hash slots with CRC16 hashing (Redis Cluster compatible)
topology tracking — node identity, roles (primary/replica), health status
SWIM gossip — failure detection with configurable probe intervals and suspicion timeouts
raft consensus — cluster configuration changes via openraft
live migration — slot resharding without downtime, MOVED/ASK redirects
authentication — HMAC-SHA256 signing and constant-time verification for cluster transport messages
automatic failover — replica election state machine; first replica to reach quorum is promoted via raft

modules

module	description
`slots`	CRC16 hash function, slot-to-node mapping, slot ranges
`topology`	`NodeId`, `ClusterNode`, `ClusterState`, health tracking
`gossip`	SWIM protocol engine, membership events, probe management
`raft`	openraft integration, cluster commands, state machine
`migration`	migration state machine, batch streaming, key tracking
`message`	binary wire format for gossip messages
`error`	cluster-specific error types with MOVED/ASK support
`auth`	HMAC-SHA256 cluster transport authentication
`election`	replica failover election state machine
`raft_transport`	raft network transport over TCP

usage

use ember_cluster::{ClusterState, ClusterNode, NodeId, key_slot};

// create a single-node cluster
let node_id = NodeId::new();
let node = ClusterNode::new_primary(node_id, "127.0.0.1:6379".parse().unwrap());
let cluster = ClusterState::single_node(node);

// route a key to its slot
let slot = key_slot(b"mykey");
assert!(cluster.owns_slot(slot));

cluster commands

the following CLUSTER commands are supported at the protocol layer:

command	description
`CLUSTER INFO`	cluster state and configuration
`CLUSTER NODES`	list of cluster nodes
`CLUSTER SLOTS`	slot distribution across nodes
`CLUSTER KEYSLOT <key>`	compute slot for a key
`CLUSTER MYID`	local node's ID
`CLUSTER MEET <ip> <port>`	add a node to the cluster
`CLUSTER ADDSLOTS <slot>...`	assign slots to local node
`CLUSTER DELSLOTS <slot>...`	remove slots from local node
`CLUSTER SETSLOT <slot> IMPORTING/MIGRATING/NODE/STABLE`	migration control
`CLUSTER FORGET <node-id>`	remove a node
`CLUSTER REPLICATE <node-id>`	become a replica
`CLUSTER FAILOVER [FORCE\|TAKEOVER]`	manual failover
`CLUSTER COUNTKEYSINSLOT <slot>`	key count in slot
`CLUSTER GETKEYSINSLOT <slot> <count>`	get keys in slot
`ASKING`	follow ASK redirect
`MIGRATE <host> <port> <key> <db> <timeout>`	migrate a key

design notes

persistent raft log — vote, log entries, and snapshots are persisted to disk when a data directory is configured; nodes recover cluster state on restart
single raft group — all cluster config changes go through one raft group (simpler than multi-raft)
fully integrated — cluster mode is wired into ember-server with gossip, raft, slot routing, MOVED/ASK redirects, live migration, replication, and automatic failover

related crates

crate	what it does
ember-core	storage engine, keyspace, sharding
ember-protocol	RESP3 parsing and command dispatch
ember-persistence	AOF, snapshots, and crash recovery
ember-server	TCP server and connection handling
ember-cli	interactive CLI client (REPL, cluster subcommands, benchmark)