Struct StorageShardBalancer 

pub struct StorageShardBalancer { /* private fields */ }

Production-grade consistent-hashing shard balancer.

Virtual nodes for each shard are distributed across a BTreeMap<u64, String> ring. Content is assigned to shards by walking the ring clockwise from the FNV-1a hash of the CID, selecting the first replication_factor distinct healthy shards.

Implementations

impl StorageShardBalancer

pub fn new(config: BalancerConfig) -> Self

Create a new balancer with the provided configuration.

pub fn with_defaults() -> Self

Create a balancer with default configuration.

pub fn add_shard(&mut self, shard: ShardNode) -> Result<(), BalancerError>

Register a shard and add its virtual nodes to the ring.

pub fn remove_shard( &mut self, shard_id: &str, ) -> Result<Vec<RebalanceOp>, BalancerError>

Remove a shard from the ring and generate MoveContent ops for all affected assignments.

pub fn assign(&mut self, cid: &str) -> Result<ShardAssignment, BalancerError>

Assign a CID to shards using consistent hashing.

Returns an error when fewer than replication_factor healthy shards are available.

pub fn lookup(&self, cid: &str) -> Result<&ShardAssignment, BalancerError>

Returns a reference to an existing assignment.

pub fn record_usage( &mut self, shard_id: &str, delta_bytes: i64, ) -> Result<(), BalancerError>

Update used bytes for a shard (delta can be negative for deletions).

pub fn set_shard_health( &mut self, shard_id: &str, healthy: bool, ) -> Result<(), BalancerError>

Mark a shard healthy or unhealthy.

pub fn rebalance(&mut self) -> Result<Vec<RebalanceOp>, BalancerError>

Compute rebalance operations if the imbalance ratio exceeds the configured threshold. Operations are also stored in pending_ops.

pub fn stats(&self) -> SsbBalancerStats

Return a snapshot of current balancer statistics.

pub fn ring_positions(&self) -> Vec<(u64, String)>

Return all virtual node ring positions, sorted ascending.

pub fn config(&self) -> &BalancerConfig

Return the current config.

pub fn shard(&self, shard_id: &str) -> Option<&ShardNode>

Return a reference to a shard by id.

pub fn shards(&self) -> impl Iterator<Item = &ShardNode>

Return iterator over all registered shards.

pub fn assignment_count(&self) -> usize

Return the number of CIDs currently assigned.