Struct ClusterHandle 

pub struct ClusterHandle { /* private fields */ }

An opaque handle to the running cluster layer.

Callers obtain it via ClusterHandle::start (multi-node Raft) or ClusterHandle::start_standalone (single-node, no Raft).

Implementations

impl ClusterHandle

pub async fn start( node_id: u64, peers: Vec<(u64, SocketAddr)>, ) -> ServerResult<Self>

Start the Raft node for multi-node operation.

peers must contain at least 3 (node_id, address) pairs (including this node) because the Raft quorum algorithm requires an odd-sized cluster of ≥ 3. The addresses are stored for use by the RPC transport (Phase 8 work).

pub async fn start_standalone(node_id: u64) -> ServerResult<Self>

Start in standalone (single-node) mode — no Raft, always leader.

This path does not create a RaftNode (which would fail for < 3 peers) and simply returns a sentinel that reports is_leader = true.

pub fn is_leader(&self) -> bool

Returns true when this node currently believes it is the Raft leader.

pub fn node_id(&self) -> u64

Return this node’s numeric identifier.

pub fn shard_count(&self) -> usize

Number of shards tracked by the placement registry.

Returns 0 when running in standalone mode or without the cluster feature.

pub fn raft_node(&self) -> Option<Arc<RaftNode>>

Expose the underlying RaftNode for advanced use.

pub fn shard_registry(&self) -> Option<Arc<ShardRegistry>>

Expose the underlying ShardRegistry for advanced use.

pub fn list_shards(&self) -> Vec<ShardMetadata>

List all shards currently registered in the placement layer.

Returns an empty Vec when running in standalone mode.

pub fn shards_on_node(&self, node_id: NodeId) -> Vec<ShardMetadata>

List shards currently assigned to a specific node.

Returns an empty Vec when running in standalone mode.

pub fn find_shard_for_key(&self, key: &Key) -> Option<ShardMetadata>

Find the shard responsible for a given key.

Returns None when running in standalone mode.

pub fn propose_split( &self, shard_id: ShardId, split_key: Key, ) -> ServerResult<LogIndex>

Propose a shard split via Raft (leader only).

Returns Err(ServerError::Cluster("NotLeader: ...")) if this node is not the current Raft leader.

pub fn propose_merge( &self, left_shard_id: ShardId, right_shard_id: ShardId, ) -> ServerResult<LogIndex>

Propose a shard merge via Raft (leader only).

Returns Err(ServerError::Cluster("NotLeader: ...")) if this node is not the current Raft leader.

pub fn propose_transfer( &self, shard_id: ShardId, from_node: NodeId, to_node: NodeId, ) -> ServerResult<LogIndex>

Propose a shard transfer via Raft (leader only).

Returns Err(ServerError::Cluster("NotLeader: ...")) if this node is not the current Raft leader.