Trait libp2p::swarm::NetworkBehaviour
source · pub trait NetworkBehaviour: 'static {
type ConnectionHandler: IntoConnectionHandler;
type OutEvent: Send + 'static;
// Required methods
fn on_swarm_event(&mut self, event: FromSwarm<'_, Self::ConnectionHandler>);
fn on_connection_handler_event(
&mut self,
_peer_id: PeerId,
_connection_id: ConnectionId,
_event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent
);
fn poll(
&mut self,
cx: &mut Context<'_>,
params: &mut impl PollParameters
) -> Poll<ToSwarm<Self::OutEvent, <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::InEvent>>;
// Provided methods
fn new_handler(&mut self) -> Self::ConnectionHandler { ... }
fn handle_pending_inbound_connection(
&mut self,
_connection_id: ConnectionId,
_local_addr: &Multiaddr,
_remote_addr: &Multiaddr
) -> Result<(), ConnectionDenied> { ... }
fn handle_established_inbound_connection(
&mut self,
_connection_id: ConnectionId,
peer: PeerId,
local_addr: &Multiaddr,
remote_addr: &Multiaddr
) -> Result<<Self::ConnectionHandler as IntoConnectionHandler>::Handler, ConnectionDenied> { ... }
fn handle_pending_outbound_connection(
&mut self,
_connection_id: ConnectionId,
maybe_peer: Option<PeerId>,
_addresses: &[Multiaddr],
_effective_role: Endpoint
) -> Result<Vec<Multiaddr, Global>, ConnectionDenied> { ... }
fn handle_established_outbound_connection(
&mut self,
_connection_id: ConnectionId,
peer: PeerId,
addr: &Multiaddr,
role_override: Endpoint
) -> Result<<Self::ConnectionHandler as IntoConnectionHandler>::Handler, ConnectionDenied> { ... }
fn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr, Global> { ... }
}Expand description
A NetworkBehaviour defines the behaviour of the local node on the network.
In contrast to Transport which defines how to send bytes on the
network, NetworkBehaviour defines what bytes to send and to whom.
Each protocol (e.g. libp2p-ping, libp2p-identify or libp2p-kad) implements
NetworkBehaviour. Multiple implementations of NetworkBehaviour can be composed into a
hierarchy of NetworkBehaviours where parent implementations delegate to child
implementations. Finally the root of the NetworkBehaviour hierarchy is passed to
Swarm where it can then control the behaviour of the local node on a libp2p
network.
Hierarchy of NetworkBehaviour
To compose multiple NetworkBehaviour implementations into a single NetworkBehaviour
implementation, potentially building a multi-level hierarchy of NetworkBehaviours, one can
use one of the NetworkBehaviour combinators, and/or use the NetworkBehaviour derive
macro.
Combinators
NetworkBehaviour combinators wrap one or more NetworkBehaviour implementations and
implement NetworkBehaviour themselves. Example is the
Toggle NetworkBehaviour.
let my_behaviour = dummy::Behaviour;
let my_toggled_behaviour = Toggle::from(Some(my_behaviour));Custom NetworkBehaviour with the Derive Macro
One can derive NetworkBehaviour for a custom struct via the #[derive(NetworkBehaviour)]
proc macro re-exported by the libp2p crate. The macro generates a delegating trait
implementation for the custom struct. Each NetworkBehaviour trait method is simply
delegated to each struct member in the order the struct is defined. For example for
NetworkBehaviour::poll it will first poll the first struct member until it returns
Poll::Pending before moving on to later members. For NetworkBehaviour::addresses_of_peer
it will delegate to each struct member and return a concatenated array of all addresses
returned by the struct members.
Events (NetworkBehaviour::OutEvent) returned by each struct member are wrapped in a new
enum event, with an enum variant for each struct member. Users can define this event
enum themselves and provide the name to the derive macro via #[behaviour(out_event = "MyCustomOutEvent")]. If the user does not specify an out_event, the derive macro generates
the event definition itself, naming it <STRUCT_NAME>Event.
The aforementioned conversion of each of the event types generated by the struct members to the
custom out_event is handled by From implementations which the user needs to define in
addition to the event enum itself.
#[derive(NetworkBehaviour)]
#[behaviour(out_event = "Event")]
struct MyBehaviour {
identify: identify::Behaviour,
ping: ping::Behaviour,
}
enum Event {
Identify(identify::Event),
Ping(ping::Event),
}
impl From<identify::Event> for Event {
fn from(event: identify::Event) -> Self {
Self::Identify(event)
}
}
impl From<ping::Event> for Event {
fn from(event: ping::Event) -> Self {
Self::Ping(event)
}
}Required Associated Types§
sourcetype ConnectionHandler: IntoConnectionHandler
type ConnectionHandler: IntoConnectionHandler
Handler for all the protocols the network behaviour supports.
Required Methods§
sourcefn on_swarm_event(&mut self, event: FromSwarm<'_, Self::ConnectionHandler>)
fn on_swarm_event(&mut self, event: FromSwarm<'_, Self::ConnectionHandler>)
Informs the behaviour about an event from the Swarm.
sourcefn on_connection_handler_event(
&mut self,
_peer_id: PeerId,
_connection_id: ConnectionId,
_event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent
)
fn on_connection_handler_event( &mut self, _peer_id: PeerId, _connection_id: ConnectionId, _event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent )
Informs the behaviour about an event generated by the ConnectionHandler
dedicated to the peer identified by peer_id. for the behaviour.
The PeerId is guaranteed to be in a connected state. In other words,
FromSwarm::ConnectionEstablished has previously been received with this PeerId.
sourcefn poll(
&mut self,
cx: &mut Context<'_>,
params: &mut impl PollParameters
) -> Poll<ToSwarm<Self::OutEvent, <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::InEvent>>
fn poll( &mut self, cx: &mut Context<'_>, params: &mut impl PollParameters ) -> Poll<ToSwarm<Self::OutEvent, <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::InEvent>>
Polls for things that swarm should do.
This API mimics the API of the Stream trait. The method may register the current task in
order to wake it up at a later point in time.
Provided Methods§
sourcefn new_handler(&mut self) -> Self::ConnectionHandler
fn new_handler(&mut self) -> Self::ConnectionHandler
NetworkBehaviour::{handle_pending_inbound_connection,handle_established_inbound_connection,handle_pending_outbound_connection,handle_established_outbound_connection} instead.Creates a new ConnectionHandler for a connection with a peer.
Every time an incoming connection is opened, and every time another NetworkBehaviour
emitted a dial request, this method is called.
The returned object is a handler for that specific connection, and will be moved to a background task dedicated to that connection.
The network behaviour (ie. the implementation of this trait) and the handlers it has spawned
(ie. the objects returned by new_handler) can communicate by passing messages. Messages
sent from the handler to the behaviour are invoked with
NetworkBehaviour::on_connection_handler_event,
and the behaviour can send a message to the handler by making NetworkBehaviour::poll
return ToSwarm::NotifyHandler.
Note that the handler is returned to the NetworkBehaviour on connection failure and
connection closing.
sourcefn handle_pending_inbound_connection(
&mut self,
_connection_id: ConnectionId,
_local_addr: &Multiaddr,
_remote_addr: &Multiaddr
) -> Result<(), ConnectionDenied>
fn handle_pending_inbound_connection( &mut self, _connection_id: ConnectionId, _local_addr: &Multiaddr, _remote_addr: &Multiaddr ) -> Result<(), ConnectionDenied>
Callback that is invoked for every new inbound connection.
At this point in the connection lifecycle, only the remote’s and our local address are known.
We have also already allocated a ConnectionId.
Any error returned from this function will immediately abort the dial attempt.
sourcefn handle_established_inbound_connection(
&mut self,
_connection_id: ConnectionId,
peer: PeerId,
local_addr: &Multiaddr,
remote_addr: &Multiaddr
) -> Result<<Self::ConnectionHandler as IntoConnectionHandler>::Handler, ConnectionDenied>
fn handle_established_inbound_connection( &mut self, _connection_id: ConnectionId, peer: PeerId, local_addr: &Multiaddr, remote_addr: &Multiaddr ) -> Result<<Self::ConnectionHandler as IntoConnectionHandler>::Handler, ConnectionDenied>
Callback that is invoked for every established inbound connection.
This is invoked once another peer has successfully dialed us.
At this point, we have verified their PeerId and we know, which particular Multiaddr succeeded in the dial.
In order to actually use this connection, this function must return a ConnectionHandler.
Returning an error will immediately close the connection.
sourcefn handle_pending_outbound_connection(
&mut self,
_connection_id: ConnectionId,
maybe_peer: Option<PeerId>,
_addresses: &[Multiaddr],
_effective_role: Endpoint
) -> Result<Vec<Multiaddr, Global>, ConnectionDenied>
fn handle_pending_outbound_connection( &mut self, _connection_id: ConnectionId, maybe_peer: Option<PeerId>, _addresses: &[Multiaddr], _effective_role: Endpoint ) -> Result<Vec<Multiaddr, Global>, ConnectionDenied>
Callback that is invoked for every outbound connection attempt.
We have access to:
- The
PeerId, if known. Remember that we can dial without aPeerId. - All addresses passed to
DialOptsare passed in here too. - The effective
Roleof this peer in the dial attempt. Typically, this is set toEndpoint::Dialerexcept if we are attempting a hole-punch. - The
ConnectionIdidentifying the future connection resulting from this dial, if successful.
Note that the addresses returned from this function are only used for dialing if WithPeerIdWithAddresses::extend_addresses_through_behaviour is set.
Any error returned from this function will immediately abort the dial attempt.
sourcefn handle_established_outbound_connection(
&mut self,
_connection_id: ConnectionId,
peer: PeerId,
addr: &Multiaddr,
role_override: Endpoint
) -> Result<<Self::ConnectionHandler as IntoConnectionHandler>::Handler, ConnectionDenied>
fn handle_established_outbound_connection( &mut self, _connection_id: ConnectionId, peer: PeerId, addr: &Multiaddr, role_override: Endpoint ) -> Result<<Self::ConnectionHandler as IntoConnectionHandler>::Handler, ConnectionDenied>
Callback that is invoked for every established outbound connection.
This is invoked once we have successfully dialed a peer.
At this point, we have verified their PeerId and we know, which particular Multiaddr succeeded in the dial.
In order to actually use this connection, this function must return a ConnectionHandler.
Returning an error will immediately close the connection.
sourcefn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr, Global>
fn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr, Global>
NetworkBehaviour::handle_pending_outbound_connection instead.Addresses that this behaviour is aware of for this specific peer, and that may allow reaching the peer.
The addresses will be tried in the order returned by this function, which means that they should be ordered by decreasing likelihood of reachability. In other words, the first address should be the most likely to be reachable.
Implementations on Foreign Types§
source§impl<L, R> NetworkBehaviour for Either<L, R>where
L: NetworkBehaviour,
R: NetworkBehaviour,
impl<L, R> NetworkBehaviour for Either<L, R>where L: NetworkBehaviour, R: NetworkBehaviour,
Implementation of NetworkBehaviour that can be either of two implementations.