Module candidate_set 

Candidate peer selection for outbound connections.

The crawler in crawl_and_dial manages outbound peer connection attempts using the services in this module. Successful connections become peers in the PeerSet.

Candidate selection 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()      │
 └───────────────────────────────────────┘

Modules

crawl 🔒

Crawling the network for more peer addresses.

rate_limit 🔒

Rate-limiting middleware for candidate peer selection and crawling.

Functions

crawler_services 🔒

Builds the candidate selection services used by the crawler: a NextPeerService and a CrawlService.

next_reconnect_peer 🔒

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

ready_peer_count 🔒

Returns the number of candidate peers that are currently ready for a connection attempt, as selected by next_reconnect_peer.

Type Aliases

NextPeerService 🔒

The service that chooses the next reconnection candidate.