Struct PeerDiscoveryProtocol 

pub struct PeerDiscoveryProtocol { /* private fields */ }

Multi-strategy peer discovery protocol.

Maintains a bounded peer table with TTL expiry, verification tracking, capability filtering, and per-method statistics. All state transitions emit PdpDiscoveryEvent values buffered internally and drained by the caller.

Implementations

impl PeerDiscoveryProtocol

pub fn new(config: PdpDiscoveryConfig) -> Result<Self, PdpDiscoveryError>

Create a new protocol instance with the given configuration.

Errors

Returns PdpDiscoveryError::ConfigurationError if max_peers is 0 or peer_ttl_us is 0.

pub fn with_defaults() -> Self

Create a new protocol instance with the default configuration.

pub fn add_peer( &mut self, peer: PdpDiscoveredPeer, ) -> Result<PdpDiscoveryEvent, PdpDiscoveryError>

Add a peer to the table.

• If the peer is new and the table has capacity, it is inserted and PdpDiscoveryEvent::PeerDiscovered is emitted.
• If the peer already exists, its addresses are merged (deduped) and its TTL is refreshed; PdpDiscoveryEvent::PeerDiscovered is emitted again to signal the update.
• If the table is full and the peer is unknown, PdpDiscoveryError::MaxPeersExceeded is returned and PdpDiscoveryEvent::PeerTableFull is emitted.

pub fn remove_peer(&mut self, id: &str) -> Result<(), PdpDiscoveryError>

Remove a peer by id.

Errors

Returns PdpDiscoveryError::PeerNotFound if the peer does not exist.

pub fn verify_peer( &mut self, id: &str, current_ts: u64, ) -> Result<PdpDiscoveryEvent, PdpDiscoveryError>

Mark a peer as verified and record the current timestamp.

Emits PdpDiscoveryEvent::PeerVerified on success.

Errors

Returns PdpDiscoveryError::PeerNotFound if the peer does not exist.

pub fn expire_peers(&mut self, current_ts: u64) -> Vec<PdpDiscoveryEvent>

Remove all peers whose TTL has elapsed relative to current_ts.

Returns one PdpDiscoveryEvent::PeerExpired per removed peer.

pub fn refresh_peer( &mut self, id: &str, current_ts: u64, ) -> Result<(), PdpDiscoveryError>

Reset the TTL of a known peer to current_ts + config.peer_ttl_us.

Errors

Returns PdpDiscoveryError::PeerNotFound if the peer does not exist.

pub fn get_peer( &self, id: &str, ) -> Result<&PdpDiscoveredPeer, PdpDiscoveryError>

Retrieve an immutable reference to a peer by id.

Errors

Returns PdpDiscoveryError::PeerNotFound if the peer does not exist.

pub fn peers_by_method(&self, method: &str) -> Vec<&PdpDiscoveredPeer>

Return all peers discovered by the given method variant name.

The method string must match one of the values returned by PdpDiscoveryMethod::variant_name (e.g., "bootstrap", "mdns").

pub fn peers_with_capability(&self, capability: &str) -> Vec<&PdpDiscoveredPeer>

Return all peers that have the given capability string.

pub fn random_peers(&self, n: usize, seed: u64) -> Vec<&PdpDiscoveredPeer>

Return up to n randomly selected peers using an xorshift64-based Fisher-Yates shuffle seeded with seed.

If the table has fewer than n peers, all peers are returned in shuffled order.

pub fn merge_peer_table( &mut self, other: Vec<PdpDiscoveredPeer>, current_ts: u64, ) -> Vec<PdpDiscoveryEvent>

Bulk-import peers from a PeerExchange handshake.

For each peer in other:

• Skip if already expired (discovered_at + ttl_us < current_ts).
• If the peer is already known, merge addresses + capabilities and refresh TTL.
• If the peer is new, insert it (subject to capacity).

Returns the list of events generated.

pub fn stats(&self) -> PdpDiscoveryStats

Return a snapshot of current statistics.

pub fn drain_events(&mut self) -> Vec<PdpDiscoveryEvent>

Drain and return all buffered events.

After this call the internal event buffer is empty.

pub fn peer_count(&self) -> usize

Return the current number of peers in the table.

pub fn all_peers(&self) -> impl Iterator<Item = &PdpDiscoveredPeer>

Return an iterator over all peers currently in the table.

pub fn record_method_failure( &mut self, method: impl Into<String>, reason: impl Into<String>, )

Record a discovery method failure, emitting PdpDiscoveryEvent::DiscoveryMethodFailed.

Trait Implementations

impl Debug for PeerDiscoveryProtocol

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.