Struct ClusterMembership 

pub struct ClusterMembership { /* private fields */ }

Implementations

impl ClusterMembership

pub fn new(config: ClusterConfig) -> Self

Create a new cluster membership tracker.

Peer-add rate limiting is initialised from ClusterConfig::peer_add_rate_config (defaults: 1 per source per 100 ms).

pub fn facts(&self) -> &NodeFactsCache

Verified node facts (local and peers) with TTL (card mesh-placement-03).

pub fn with_chain(self, cm: Arc<ChainManager>) -> Self

Attach a chain manager for audit logging (builder style).

pub fn with_gate(self, gate: Arc<GovernanceGate>) -> Self

Attach a governance gate for policy enforcement (builder style).

pub fn with_min_peer_interval(self, interval: Duration) -> Self

Set the minimum interval between peer additions from the same source (builder style).

Duration::ZERO disables rate limiting (used by unit tests). Non-zero intervals configure a per-source limit of 1 addition per interval. Prefer Self::with_peer_add_rate_limit for multi-count windows.

pub fn with_peer_add_rate_limit(self, config: RateLimitConfig) -> Self

Configure the per-source add_peer rate limit (WEFT-148).

pub fn peer_add_rate_limit(&self) -> RateLimitConfig

Current peer-add rate-limit configuration.

pub fn peer_add_source_key(peer: &PeerNode) -> &str

Resolve the rate-limit source key for a peer.

Prefers network address when present (so one host flooding many node IDs still hits the same bucket); falls back to peer id.

pub fn with_persist_path(self, path: impl AsRef<Path>) -> Self

Enable peer persistence at the given path (builder style).

If the file exists and is readable, peers are rehydrated into the in-memory map so joins survive kernel restarts. Parse errors log a warning and leave the map empty. Subsequent mutations write back to the same path via Self::persist.

pub fn config(&self) -> &ClusterConfig

Get the cluster configuration.

pub fn local_node_id(&self) -> &str

Get this node’s ID.

pub fn add_peer(&self, peer: PeerNode) -> Result<(), ClusterError>

Register a peer node.

Rate-limited per source (WEFT-148): by default at most one addition per source per 100 ms. Source key is the peer’s network address when set, otherwise its node id. Thresholds are configurable via ClusterConfig / Self::with_peer_add_rate_limit.

pub fn remove_peer(&self, node_id: &str) -> Result<PeerNode, ClusterError>

Remove a peer node.

pub fn update_state( &self, node_id: &str, new_state: NodeState, ) -> Result<(), ClusterError>

Update a peer’s state.

pub fn heartbeat(&self, node_id: &str) -> Result<(), ClusterError>

Record a heartbeat from a peer.

pub fn get_peer(&self, node_id: &str) -> Option<PeerNode>

Get a snapshot of a peer’s state.

pub fn list_peers(&self) -> Vec<(NodeId, NodeState, NodePlatform)>

List all peers with their states.

pub fn count_by_state(&self, state: &NodeState) -> usize

Count peers by state.

pub fn len(&self) -> usize

Count total peers.

pub fn is_empty(&self) -> bool

Check if cluster has no peers.

pub fn add_peer_with_tree( &self, peer: PeerNode, tree: &Mutex<ResourceTree>, ) -> Result<(), ClusterError>

Add a peer and optionally create a resource tree node.

pub fn add_peer_checked( &self, peer: PeerNode, revocation_list: &RevocationList, ) -> Result<(), ClusterError>

Register a peer node, checking the revocation list first.

If the peer’s ID appears in the revocation list, the add is rejected with ClusterError::AuthFailed.

pub fn active_peers(&self) -> Vec<NodeId>

Get all active peer node IDs.

pub fn expire_unverified(&self, max_age: Duration) -> usize

Drop Unverified peers not heard from for max_age. They are not members, so nothing else ages them out (a peer that never sends a Left, or whose route vanished without an event, would linger). Returns how many were dropped.

pub fn apply_mesh_peer_event( &self, event: &MeshPeerEvent, ) -> Result<bool, ClusterError>

Apply a live mesh peer event to membership atomically (WEFT-120).

Mesh is the authority for connect/health; this path upserts peers without the operator-facing add_peer rate limit (mesh already authenticated the session). A single event produces one consistent membership mutation + one persist.

Returns true when membership changed.

pub fn spawn_mesh_peer_listener(self: &Arc<Self>, rx: Receiver<MeshPeerEvent>)

Drain a mesh peer-event receiver and apply each event (WEFT-120).

Spawns a background task. Intended for boot when ClusterService is not available (mesh-only builds) or as a shared membership path. Prefer ClusterService::spawn_mesh_peer_listener when the cluster feature is on so ruvector nodes stay in sync too.