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 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:
PexRequest: a request for addresses received from a peer, handled as
described here
PexAddrs: a list of addresses received from a peer, as a reponse to a PEX
request sent by the node, as described here
