Struct zebra_network::address_book::AddressBook

pub struct AddressBook {
    by_addr: OrderedMap<SocketAddr, MetaAddr, Reverse<MetaAddr>>,
    local_listener: SocketAddr,
    network: Network,
    addr_limit: usize,
    span: Span,
    address_metrics_tx: Sender<AddressMetrics>,
    last_address_log: Option<Instant>,
}

A database of peer listener addresses, their advertised services, and information on when they were last seen.

Security

Address book state must be based on outbound connections to peers.

If the address book is updated incorrectly:

• malicious peers can interfere with other peers’ AddressBook state, or
• Zebra can advertise unreachable addresses to its own peers.

Adding Addresses

The address book should only contain Zcash listener port addresses from peers on the configured network. These addresses can come from:

• DNS seeders
• addresses gossiped by other peers
• the canonical address (Version.address_from) provided by each peer, particularly peers on inbound connections.

The remote addresses of inbound connections must not be added to the address book, because they contain ephemeral outbound ports, not listener ports.

Isolated connections must not add addresses or update the address book.

Updating Address State

Updates to address state must be based on outbound connections to peers.

Updates must not be based on:

• the remote addresses of inbound connections, or
• the canonical address of any connection.

Fields

by_addr: OrderedMap<SocketAddr, MetaAddr, Reverse<MetaAddr>>

Peer listener addresses, suitable for outbound connections, in connection attempt order.

Some peers in this list might have open outbound or inbound connections.

We reverse the comparison order, because the standard library (BTreeMap) sorts in ascending order, but [OrderedMap] sorts in descending order.

local_listener: SocketAddr

The local listener address.

network: Network

The configured Zcash network.

addr_limit: usize

The maximum number of addresses in the address book.

Always set to MAX_ADDRS_IN_ADDRESS_BOOK, in release builds. Lower values are used during testing.

span: Span

The span for operations on this address book.

address_metrics_tx: Sender<AddressMetrics>

A channel used to send the latest address book metrics.

last_address_log: Option<Instant>

The last time we logged a message about the address metrics.

Implementations

impl AddressBook

pub fn new( local_listener: SocketAddr, network: Network, span: Span ) -> AddressBook

Construct an AddressBook with the given local_listener on network.

Uses the supplied tracing::Span for address book operations.

pub fn new_with_addrs( local_listener: SocketAddr, network: Network, addr_limit: usize, span: Span, addrs: impl IntoIterator<Item = MetaAddr> ) -> AddressBook

Construct an AddressBook with the given local_listener, network, addr_limit, tracing::Span, and addresses.

addr_limit is enforced by this method, and by AddressBook::update.

If there are multiple MetaAddrs with the same address, an arbitrary address is inserted into the address book, and the rest are dropped.

This constructor can be used to break address book invariants, so it should only be used in tests.

pub fn address_metrics_watcher(&self) -> Receiver<AddressMetrics>

Return a watch channel for the address book metrics.

The metrics in the watch channel are only updated when the address book updates, so they can be significantly outdated if Zebra is disconnected or hung.

The current metrics value is marked as seen. So Receiver::changed will only return after the next address book update.

pub fn local_listener_meta_addr(&self) -> MetaAddr

Get the local listener address.

This address contains minimal state, but it is not sanitized.

pub fn sanitized(&self, now: DateTime<Utc>) -> Vec<MetaAddr>

Get the contents of self in random order with sanitized timestamps.

pub fn get(&mut self, addr: &SocketAddr) -> Option<MetaAddr>

Look up addr in the address book, and return its MetaAddr.

Converts addr to a canonical address before looking it up.

pub fn update(&mut self, change: MetaAddrChange) -> Option<MetaAddr>

Apply change to the address book, returning the updated MetaAddr, if the change was valid.

Correctness

All changes should go through update, so that the address book only contains valid outbound addresses.

Change addresses must be canonical SocketAddrs. This makes sure that each address book entry has a unique IP address.

Security

This function must apply every attempted, responded, and failed change to the address book. This prevents rapid reconnections to the same peer.

As an exception, this function can ignore all changes for specific SocketAddrs. Ignored addresses will never be used to connect to peers.

fn take(&mut self, removed_addr: SocketAddr) -> Option<MetaAddr>

Removes the entry with addr, returning it if it exists

Note

All address removals should go through take, so that the address book metrics are accurate.

pub fn pending_reconnection_addr(&mut self, addr: &SocketAddr) -> bool

Returns true if the given SocketAddr is pending a reconnection attempt.

pub fn peers(&self) -> impl Iterator<Item = MetaAddr> + DoubleEndedIterator + '_

Return an iterator over all peers.

Returns peers in reconnection attempt order, including recently connected peers.

pub fn reconnection_peers( &self, instant_now: Instant, chrono_now: DateTime<Utc> ) -> impl Iterator<Item = MetaAddr> + DoubleEndedIterator + '_

Return an iterator over peers that are due for a reconnection attempt, in reconnection attempt order.

pub fn state_peers( &self, state: PeerAddrState ) -> impl Iterator<Item = MetaAddr> + DoubleEndedIterator + '_

Return an iterator over all the peers in state, in reconnection attempt order, including recently connected peers.

pub fn maybe_connected_peers( &self, instant_now: Instant, chrono_now: DateTime<Utc> ) -> impl Iterator<Item = MetaAddr> + DoubleEndedIterator + '_

Return an iterator over peers that might be connected, in reconnection attempt order.

pub fn len(&self) -> usize

Returns the number of entries in this address book.

fn address_metrics_internal(&self, now: DateTime<Utc>) -> AddressMetrics

Returns metrics for the addresses in this address book.

Correctness

External callers should use [AddressBook::address_metrics_watcher().borrow()] in production code, to avoid deadlocks. (Using the watch channel receiver does not lock the address book mutex.)

fn update_metrics(&mut self, instant_now: Instant, chrono_now: DateTime<Utc>)

Update the metrics for this address book.

fn log_metrics(&mut self, m: &AddressMetrics, now: Instant)

Log metrics for this address book

Trait Implementations

impl AddressBookPeers for AddressBook

fn recently_live_peers(&self, now: DateTime<Utc>) -> Vec<MetaAddr>

Return an Vec of peers we’ve seen recently, in reconnection attempt order.

impl Clone for AddressBook

fn clone(&self) -> AddressBook

Clone the addresses, address limit, local listener address, and span.

Cloned address books have a separate metrics struct watch channel, and an empty last address log.

All address books update the same prometheus metrics.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AddressBook

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

Formats the value using the given formatter.

impl Extend<MetaAddrChange> for AddressBook

fn extend<T>(&mut self, iter: T)where T: IntoIterator<Item = MetaAddrChange>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.