The PEX reactor is one of the reactors running in a CometBFT node.
Its implementation is located in the p2p/pex
package, and it is considered
part of the implementation of the p2p layer.
This document overviews the implementation of the PEX reactor, describing how
the methods from the Reactor
interface are implemented.
The actual operation of the PEX reactor is presented in documents describing the roles played by the PEX reactor in the p2p layer:
- Address Book: stores known peer addresses and information about peers to which the node is connected or has attempted to connect
- Peer Manager: manages connections established with peers, defining when a node should dial peers and which peers it should dial
- Peer Exchange protocol: enables nodes to exchange peer addresses, thus implementing a peer discovery service
The OnStart
method implements BaseService
and starts the PEX reactor.
The address book, which is a Service
is started.
This loads the address book content from disk,
and starts a routine that periodically persists the address book content to disk.
The PEX reactor is configured with the addresses of a number of seed nodes,
the Seeds
parameter of the ReactorConfig
.
The addresses of seed nodes are parsed into NetAddress
instances and resolved
into IP addresses, which is implemented by the checkSeeds
method.
Valid seed node addresses are stored in the seedAddrs
field,
and are used by the dialSeeds
method to contact the configured seed nodes.
The last action is to start one of the following persistent routines, based on
the SeedMode
configuration parameter:
- Regular nodes run the
ensurePeersRoutine
to check whether the node has enough outbound peers, dialing peers when necessary - Seed nodes run the
crawlPeersRoutine
to periodically start a new round of crawling to discover as many peer addresses as possible
Errors encountered when loading the address book from disk are returned,
and prevent the reactor from being started.
An exception is made for the service.ErrAlreadyStarted
error, which is ignored.
Errors encountered when parsing the configured addresses of seed nodes
are returned and cause the reactor startup to fail.
An exception is made for DNS resolution ErrNetAddressLookup
errors,
which are not deemed fatal and are only logged as invalid addresses.
If none of the configured seed node addresses is valid, and the loaded address book is empty, the reactor is not started and an error is returned.
The OnStop
method implements BaseService
and stops the PEX reactor.
The address book routine that periodically saves its content to disk is stopped.
The GetChannels
method, from the Reactor
interface, returns the descriptor
of the channel used by the PEX protocol.
The channel ID is PexChannel
(0), with priority 1
, send queue capacity of
10
, and maximum message size of 64000
bytes.
The AddPeer
method, from the Reactor
interface,
adds a new peer to the PEX protocol.
If the new peer is an inbound peer, i.e., if the peer has dialed the node, the peer's address is added to the address book. Since the peer was authenticated when establishing a secret connection with it, the source of the peer address is trusted, and its source is set by the peer itself. In the case of an outbound peer, the node should already have its address in the address book, as the switch has dialed the peer.
If the peer is an outbound peer, i.e., if the node has dialed the peer, and the PEX protocol needs more addresses, the node sends a PEX request to the peer. The same is not done when inbound peers are added because they are deemed least trustworthy than outbound peers.
The RemovePeer
method, from the Reactor
interface,
removes a peer from the PEX protocol.
The peer's ID is removed from the tables tracking PEX requests sent but not yet replied and PEX requests received.
The Receive
method, from the Reactor
interface,
handles a message received by the PEX protocol.
A node receives two type of messages as part of the PEX protocol: