Struct BootstrapCache 

pub struct BootstrapCache { /* private fields */ }

Greedy bootstrap cache with quality-based peer selection.

This cache stores peer information with quality metrics and provides epsilon-greedy selection to balance exploitation (using known-good peers) with exploration (trying new peers to discover potentially better ones).

Implementations

impl BootstrapCache

pub async fn open(config: BootstrapCacheConfig) -> Result<Self>

Open or create a bootstrap cache.

Loads existing cache data from disk if available, otherwise starts fresh.

pub fn subscribe(&self) -> Receiver<CacheEvent>

Subscribe to cache events

pub async fn peer_count(&self) -> usize

Get the number of cached peers

pub async fn get_peer(&self, peer_id: &PeerId) -> Option<CachedPeer>

Get a specific peer from the cache

pub async fn select_peers(&self, count: usize) -> Vec<CachedPeer>

Select peers for bootstrap using epsilon-greedy strategy.

Returns up to count peers, balancing exploitation of known-good peers with exploration of untested peers based on the configured epsilon.

pub async fn select_relay_peers(&self, count: usize) -> Vec<CachedPeer>

Select peers that support relay functionality.

Returns peers sorted by quality score, preferring observed relay capability.

pub async fn select_coordinators(&self, count: usize) -> Vec<CachedPeer>

Select peers that support NAT coordination.

Returns peers sorted by quality score, preferring observed coordination capability.

pub async fn select_relays_for_target( &self, count: usize, target: &SocketAddr, prefer_dual_stack: bool, ) -> Vec<CachedPeer>

Select relay peers that can reach a target IP version.

Returns relays sorted by quality that can bridge traffic to the target. Dual-stack relays are preferred as they can reach any target.

Arguments

• count - Maximum number of relays to return
• target - The target address to reach
• prefer_dual_stack - If true, prioritize dual-stack relays

pub async fn select_dual_stack_relays(&self, count: usize) -> Vec<CachedPeer>

Select relay peers that support dual-stack (IPv4 + IPv6) bridging.

These peers are valuable for bridging between IPv4-only and IPv6-only networks.

pub async fn upsert(&self, peer: CachedPeer)

Add or update a peer in the cache.

If the cache is at capacity, evicts the lowest quality peers.

pub async fn add_seed(&self, peer_id: PeerId, addresses: Vec<SocketAddr>)

Add a seed peer (user-provided bootstrap node).

pub async fn add_from_connection( &self, peer_id: PeerId, addresses: Vec<SocketAddr>, caps: Option<PeerCapabilities>, )

Add a peer discovered from an active connection.

pub async fn record_outcome(&self, peer_id: &PeerId, outcome: ConnectionOutcome)

Record a connection attempt result.

pub async fn record_success(&self, peer_id: &PeerId, rtt_ms: u32)

Record successful connection.

pub async fn record_failure(&self, peer_id: &PeerId)

Record failed connection.

pub async fn update_capabilities( &self, peer_id: &PeerId, caps: PeerCapabilities, )

Update peer capabilities.

pub async fn get(&self, peer_id: &PeerId) -> Option<CachedPeer>

Get a specific peer.

pub async fn update_token(&self, peer_id: PeerId, token: Vec<u8>)

Update the address validation token for a peer

pub async fn get_all_tokens(&self) -> HashMap<PeerId, Vec<u8>>

Get all tokens from cached peers (for initializing TokenStore)

pub async fn contains(&self, peer_id: &PeerId) -> bool

Check if peer exists in cache.

pub async fn remove(&self, peer_id: &PeerId) -> Option<CachedPeer>

Remove a peer from cache.

pub async fn save(&self) -> Result<()>

Save cache to disk.

pub async fn cleanup_stale(&self) -> usize

Cleanup stale peers.

Removes peers that haven’t been seen within the stale threshold. Returns the number of peers removed.

pub async fn recalculate_quality(&self)

Recalculate quality scores for all peers.

pub async fn stats(&self) -> CacheStats

Get cache statistics.

pub fn start_maintenance(self: Arc<Self>) -> JoinHandle<()>

Start background maintenance tasks.

Spawns a task that periodically:

• Saves the cache to disk
• Cleans up stale peers
• Recalculates quality scores

Returns a handle that can be used to cancel the task.

pub async fn all_peers(&self) -> Vec<CachedPeer>

Get all cached peers (for export/debug).

pub fn config(&self) -> &BootstrapCacheConfig

Get the configuration.

Trait Implementations

impl Debug for BootstrapCache

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

Formats the value using the given formatter.