Struct AddressBook

pub struct AddressBook {
    by_addr: OrderedMap<PeerSocketAddr, MetaAddr, Reverse<MetaAddr>>,
    most_recent_by_ip: Option<HashMap<IpAddr, 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<PeerSocketAddr, 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.

most_recent_by_ip: Option<HashMap<IpAddr, MetaAddr>>

The address with a last_connection_state of PeerAddrState::Responded and the most recent last_response time by IP.

This is used to avoid initiating outbound connections past Config::max_connections_per_ip, and currently only supports a max_connections_per_ip of 1, and must be None when used with a greater max_connections_per_ip.

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, max_connections_per_ip: usize, 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, max_connections_per_ip: usize, 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 set_local_listener(&mut self, addr: SocketAddr)

Set the local listener address. Only for use in tests.

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

Get the local listener address.

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

pub fn local_listener_socket_addr(&self) -> SocketAddr

Get the local listener SocketAddr.

pub fn fresh_get_addr_response(&self) -> Vec<MetaAddr>

Get the active addresses in self in random order with sanitized timestamps, including our local listener address.

Limited to a the number of peer addresses Zebra should give out per GetAddr request.

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

Get the active addresses in self in random order with sanitized timestamps, including our local listener address.

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

Get the active addresses in self, in preferred caching order, excluding our local listener address.

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

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

Converts addr to a canonical address before looking it up.

fn should_update_most_recent_by_ip(&self, updated: MetaAddr) -> bool

Returns true if updated needs to be applied to the recent outbound peer connection IP cache.

Checks if there are no existing entries in the address book with this IP, or if updated has a more recent last_response requiring the outbound connector to wait longer before initiating handshakes with peers at this IP.

This code only needs to check a single cache entry, rather than the entire address book, because other code maintains these invariants:

• last_response times for an entry can only increase.
• this is the only field checked by has_connection_recently_responded()

See AddressBook::is_ready_for_connection_attempt_with_ip for more details.

fn should_remove_most_recent_by_ip(&self, addr: PeerSocketAddr) -> bool

Returns true if addr is the latest entry for its IP, which is stored in most_recent_by_ip. The entry is checked for an exact match to the IP and port of addr.

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 PeerSocketAddrs. 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 PeerSocketAddrs. Ignored addresses will never be used to connect to peers.

fn take(&mut self, removed_addr: PeerSocketAddr) -> 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: PeerSocketAddr) -> bool

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

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

Return an iterator over all peers.

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

fn is_ready_for_connection_attempt_with_ip( &self, ip: &IpAddr, chrono_now: DateTime<Utc>, ) -> bool

Is this IP ready for a new outbound connection attempt? Checks if the outbound connection with the most recent response at this IP has recently responded.

Note: last_response times may remain live for a long time if the local clock is changed to an earlier time.

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

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

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

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 DoubleEndedIterator<Item = MetaAddr> + '_

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.