Struct AddressBook 

pub struct AddressBook { /* private fields */ }

Ref-counted PeerId → Vec<Address> registry. Single source of truth for “where can I reach this peer.”

Implementations

impl AddressBook

pub fn new() -> Self

Fresh, empty address book.

pub fn set_cap(&mut self, cap: usize)

Override the entry cap. Production hosts can match the cap to their topology size (a small cluster + 2× headroom).

pub fn add_peer( &mut self, peer: PeerId, addresses: Vec<Address>, ) -> Result<(), AddressBookError>

Announce a peer with one or more addresses.

• New peer → entry created with ref_count = 1, addresses inserted in the given order.
• Known peer → ref_count += 1. New addresses appended; duplicates dropped, existing entries preserve their position (first caller’s preference wins).

Errors with AddressBookError::EmptyAddressList if addresses is empty.

Components MUST pair every add_peer with an eventual Self::drop_peer so ref_count converges to zero.

pub fn drop_peer(&mut self, peer: PeerId) -> Result<(), AddressBookError>

Release one reference to peer. Decrements ref_count; removes the entry (and all addresses) when the count reaches zero. Errors with AddressBookError::UnknownPeer if no entry exists.

pub fn register_address( &mut self, peer: PeerId, address: Address, ) -> Result<(), AddressBookError>

Append address to the peer’s list. Idempotent - duplicates are dropped. Does NOT change ref_count. Errors with AddressBookError::UnknownPeer if the peer has no entry.

pub fn forget_address( &mut self, peer: PeerId, address: &Address, ) -> Result<(), AddressBookError>

Prune one unreachable address from the peer’s list. Transport adapters call this after observing a transport-level failure on a specific address. Does NOT change ref_count and does NOT remove the entry even if pruning leaves the address list empty - Self::drop_peer is the only path that removes entries. Errors with AddressBookError::UnknownPeer if no entry exists.

pub fn lookup(&self, peer: PeerId) -> Option<&[Address]>

Ordered slice of every address bound to peer. Returns None for an unknown peer OR a peer whose address list is empty (e.g. all addresses pruned via forget_address and nothing re-added). Both cases mean “can’t route” to the wire syscall.

pub fn lookup_first(&self, peer: PeerId) -> Option<&Address>

Convenience: the first (highest-preference) address.

pub fn ref_count(&self, peer: PeerId) -> u64

Current reference count for peer, or 0 if unregistered.

pub fn len(&self) -> usize

Number of registered peers (regardless of ref_count).

pub fn is_empty(&self) -> bool

true when no peers are registered.

pub fn iter(&self) -> impl Iterator<Item = (PeerId, &[Address], u64)>

Iterate (peer, &[Address], ref_count) triples for every registered peer. Used by snapshot capture.

pub fn restore_entry( &mut self, peer: PeerId, addresses: Vec<Address>, ref_count: u64, )

Snapshot-restore setter - reconstructs an entry with the recorded addresses + ref_count without going through Self::add_peer (which would force ref_count = 1). Used exclusively by Node::restore.

Trait Implementations

impl Default for AddressBook

fn default() -> Self

Returns the “default value” for a type.