Struct CandidateSet

pub(crate) struct CandidateSet<S>
where
    S: Service<Request, Response = Response, Error = BoxError> + Send,
    S::Future: Send + 'static,
{
    address_book: Arc<Mutex<AddressBook>>,
    peer_service: S,
    min_next_handshake: Instant,
    min_next_crawl: Instant,
}

The CandidateSet manages outbound peer connection attempts. Successful connections become peers in the PeerSet.

The candidate set divides the set of all possible outbound peers into disjoint subsets, using the PeerAddrState:

1. Responded peers, which we have had an outbound connection to.
2. NeverAttemptedGossiped peers, which we learned about from other peers but have never connected to. This includes gossiped peers, DNS seeder peers, cached peers, canonical addresses from the Version messages of inbound and outbound connections, and remote IP addresses of inbound connections.
3. Failed peers, which failed a connection attempt, or had an error during an outbound connection.
4. AttemptPending peers, which we’ve recently queued for a connection.

Never attempted peers are always available for connection.

If a peer’s attempted, responded, or failure time is recent (within the liveness limit), we avoid reconnecting to it. Otherwise, we assume that it has disconnected or hung, and attempt reconnection.

                        ┌──────────────────┐
                        │   Config / DNS   │
            ┌───────────│       Seed       │───────────┐
            │           │    Addresses     │           │
            │           └──────────────────┘           │
            │                    │ untrusted_last_seen │
            │                    │     is unknown      │
            ▼                    │                     ▼
   ┌──────────────────┐          │          ┌──────────────────┐
   │    Handshake     │          │          │     Peer Set     │
   │    Canonical     │──────────┼──────────│     Gossiped     │
   │    Addresses     │          │          │    Addresses     │
   └──────────────────┘          │          └──────────────────┘
    untrusted_last_seen          │                provides
        set to now               │           untrusted_last_seen
                                 ▼
                                 Λ   if attempted, responded, or failed:
                                ╱ ╲         ignore gossiped info
                               ▕   ▏    otherwise, if never attempted:
                                ╲ ╱    skip updates to existing fields
                                 V
 ┌───────────────────────────────┼───────────────────────────────┐
 │ AddressBook                   │                               │
 │ disjoint `PeerAddrState`s     ▼                               │
 │ ┌─────────────┐  ┌─────────────────────────┐  ┌─────────────┐ │
 │ │ `Responded` │  │`NeverAttemptedGossiped` │  │  `Failed`   │ │
┌┼▶│    Peers    │  │          Peers          │  │   Peers     │◀┼┐
││ └─────────────┘  └─────────────────────────┘  └─────────────┘ ││
││        │                      │                      │        ││
││ #1 oldest_first        #2 newest_first        #3 oldest_first ││
││        ├──────────────────────┴──────────────────────┘        ││
││        ▼                                                      ││
││        Λ                                                      ││
││       ╱ ╲              filter by                              ││
││      ▕   ▏   is_ready_for_connection_attempt                  ││
││       ╲ ╱     to remove recent `Responded`,                   ││
││        V  `AttemptPending`, and `Failed` peers                ││
││        │                                                      ││
││        │    try outbound connection,                          ││
││        ▼  update last_attempt to now()                        ││
││┌────────────────┐                                             ││
│││`AttemptPending`│                                             ││
│││     Peers      │                                             ││
││└────────────────┘                                             ││
│└────────┼──────────────────────────────────────────────────────┘│
│         ▼                                                       │
│         Λ                                                       │
│        ╱ ╲                                                      │
│       ▕   ▏─────────────────────────────────────────────────────┘
│        ╲ ╱   connection failed, update last_failure to now()
│         V
│         │
│         │ connection succeeded
│         ▼
│  ┌────────────┐
│  │    send    │
│  │peer::Client│
│  │to Discover │
│  └────────────┘
│         │
│         ▼
│┌───────────────────────────────────────┐
││ when connection succeeds, and every   │
││  time we receive a peer heartbeat:    │
└│  * update state to `Responded`        │
 │  * update last_response to now()      │
 └───────────────────────────────────────┘

Fields

address_book: Arc<Mutex<AddressBook>>

The outbound address book for this peer set.

Correctness

The address book must be private, so all operations are performed on a blocking thread (see #1976).

peer_service: S

The peer set used to crawl the network for peers.

min_next_handshake: Instant

A timer that enforces a rate-limit on new outbound connections.

min_next_crawl: Instant

A timer that enforces a rate-limit on peer set requests for more peers.

Implementations

impl<S> CandidateSet<S>

where S: Service<Request, Response = Response, Error = BoxError> + Send, S::Future: Send + 'static,

pub fn new( address_book: Arc<Mutex<AddressBook>>, peer_service: S, ) -> CandidateSet<S>

Uses address_book and peer_service to manage a CandidateSet of peers.

pub async fn update(&mut self) -> Result<Option<MorePeers>, BoxError>

Update the peer set from the network, using the default fanout limit.

See update_initial for details.

pub async fn update_initial( &mut self, fanout_limit: usize, ) -> Result<Option<MorePeers>, BoxError>

Update the peer set from the network, limiting the fanout to fanout_limit.

• Ask a few live Responded peers to send us more peers.
• Process all completed peer responses, adding new peers in the NeverAttemptedGossiped state.

Returns Some(MorePeers) if the crawl was successful and the crawler should ask for more peers. Returns None if there are no new peers.

Correctness

Pass the initial peer set size as fanout_limit during initialization, so that Zebra does not send duplicate requests to the same peer.

The crawler exits when update returns an error, so it must only return errors on permanent failures.

The handshaker sets up the peer message receiver so it also sends a Responded peer address update.

next puts peers into the AttemptPending state.

Security

This call is rate-limited to prevent sending a burst of repeated requests for new peer addresses. Each call will only update the CandidateSet if more time than MIN_PEER_GET_ADDR_INTERVAL has passed since the last call. Otherwise, the update is skipped.

async fn update_timeout( &mut self, fanout_limit: Option<usize>, ) -> Result<Option<MorePeers>, BoxError>

Update the peer set from the network, limiting the fanout to fanout_limit, and imposing a timeout on the entire fanout.

See update_initial for details.

async fn update_fanout( &mut self, fanout_limit: Option<usize>, ) -> Result<Option<MorePeers>, BoxError>

Update the peer set from the network, limiting the fanout to fanout_limit.

Opportunistically crawl the network on every update call to ensure we’re actively fetching peers. Continue independently of whether we actually receive any peers, but always ask the network for more.

Because requests are load-balanced across existing peers, we can make multiple requests concurrently, which will be randomly assigned to existing peers, but we don’t make too many because update may be called while the peer set is already loaded.

See update_initial for more details.

Correctness

This function does not have a timeout. Use update_timeout instead.

async fn send_addrs(&self, addrs: impl IntoIterator<Item = MetaAddr>)

Add new addrs to the address book.

pub async fn next(&mut self) -> Option<MetaAddr>

Returns the next candidate for a connection attempt, if any are available.

Returns peers in reconnection order, based on AddressBook::reconnection_peers.

Skips peers that have recently been active, attempted, or failed.

Correctness

AttemptPending peers will become Responded if they respond, or become Failed if they time out or provide a bad response.

Live Responded peers will stay live if they keep responding, or become a reconnection candidate if they stop responding.

Security

Zebra resists distributed denial of service attacks by making sure that new peer connections are initiated at least MIN_OUTBOUND_PEER_CONNECTION_INTERVAL apart. If next() has recently provided a peer, then its future will sleep until the rate-limit has passed.

pub async fn address_book(&self) -> Arc<Mutex<AddressBook>>

Returns the address book for this CandidateSet.

Trait Implementations

impl<S> Debug for CandidateSet<S>

where S: Service<Request, Response = Response, Error = BoxError> + Send, S::Future: Send + 'static,

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

Formats the value using the given formatter.