Trait libp2p_swarm::behaviour::NetworkBehaviour
source · [−]pub trait NetworkBehaviour: Send + 'static {
type ProtocolsHandler: IntoProtocolsHandler;
type OutEvent: Send + 'static;
Show 18 methods
fn new_handler(&mut self) -> Self::ProtocolsHandler;
fn inject_event(
&mut self,
peer_id: PeerId,
connection: ConnectionId,
event: <<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::OutEvent
);
fn poll(
&mut self,
cx: &mut Context<'_>,
params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ProtocolsHandler>>;
fn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr> { ... }
fn inject_connected(&mut self, _: &PeerId) { ... }
fn inject_disconnected(&mut self, _: &PeerId) { ... }
fn inject_connection_established(
&mut self,
_peer_id: &PeerId,
_connection_id: &ConnectionId,
_endpoint: &ConnectedPoint,
_failed_addresses: Option<&Vec<Multiaddr>>
) { ... }
fn inject_connection_closed(
&mut self,
_: &PeerId,
_: &ConnectionId,
_: &ConnectedPoint,
_: <Self::ProtocolsHandler as IntoProtocolsHandler>::Handler
) { ... }
fn inject_address_change(
&mut self,
_: &PeerId,
_: &ConnectionId,
_old: &ConnectedPoint,
_new: &ConnectedPoint
) { ... }
fn inject_dial_failure(
&mut self,
_peer_id: Option<PeerId>,
_handler: Self::ProtocolsHandler,
_error: &DialError
) { ... }
fn inject_listen_failure(
&mut self,
_local_addr: &Multiaddr,
_send_back_addr: &Multiaddr,
_handler: Self::ProtocolsHandler
) { ... }
fn inject_new_listener(&mut self, _id: ListenerId) { ... }
fn inject_new_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr) { ... }
fn inject_expired_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr) { ... }
fn inject_listener_error(
&mut self,
_id: ListenerId,
_err: &(dyn Error + 'static)
) { ... }
fn inject_listener_closed(
&mut self,
_id: ListenerId,
_reason: Result<(), &Error>
) { ... }
fn inject_new_external_addr(&mut self, _addr: &Multiaddr) { ... }
fn inject_expired_external_addr(&mut self, _addr: &Multiaddr) { ... }
}
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 NetworkBehaviour
s 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 NetworkBehaviour
s, 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 = DummyBehaviour::default();
let my_toggled_behaviour = Toggle::from(Some(my_behaviour));
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.
By default the derive sets the NetworkBehaviour::OutEvent
as ()
but this can be overridden
with #[behaviour(out_event = "AnotherType")]
.
When setting a custom out_event
users have to implement From
converting from each of the
event types generated by the struct members to the custom out_event
.
#[derive(NetworkBehaviour)]
#[behaviour(out_event = "Event")]
struct MyBehaviour {
identify: Identify,
ping: Ping,
}
enum Event {
Identify(IdentifyEvent),
Ping(PingEvent),
}
impl From<IdentifyEvent> for Event {
fn from(event: IdentifyEvent) -> Self {
Self::Identify(event)
}
}
impl From<PingEvent> for Event {
fn from(event: PingEvent) -> Self {
Self::Ping(event)
}
}
Struct members that don’t implement NetworkBehaviour
must be annotated with
#[behaviour(ignore)]
.
#[derive(NetworkBehaviour)]
#[behaviour(out_event = "Event")]
struct MyBehaviour {
identify: Identify,
ping: Ping,
#[behaviour(ignore)]
some_string: String,
}
For users that need access to the root NetworkBehaviour
implementation while processing
emitted events, one can specify #[behaviour(event_process = true)]
. Events generated by the
struct members are delegated to NetworkBehaviourEventProcess
implementations. Those must be
provided by the user on the type that NetworkBehaviour
is derived on.
Optionally one can provide a custom poll
function through the #[behaviour(poll_method = "poll")]
attribute. This function must have the same signature as the NetworkBehaviour
function and will be called last within the generated NetworkBehaviour
implementation.
Associated Types
Handler for all the protocols the network behaviour supports.
Required methods
fn new_handler(&mut self) -> Self::ProtocolsHandler
fn new_handler(&mut self) -> Self::ProtocolsHandler
Creates a new ProtocolsHandler
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 injected with NetworkBehaviour::inject_event
,
and the behaviour can send a message to the handler by making NetworkBehaviour::poll
return NetworkBehaviourAction::NotifyHandler
.
Note that the handler is returned to the NetworkBehaviour
on connection failure and
connection closing.
fn inject_event(
&mut self,
peer_id: PeerId,
connection: ConnectionId,
event: <<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::OutEvent
)
fn inject_event(
&mut self,
peer_id: PeerId,
connection: ConnectionId,
event: <<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::OutEvent
)
Informs the behaviour about an event generated by the handler dedicated to the peer identified by peer_id
.
for the behaviour.
The peer_id
is guaranteed to be in a connected state. In other words, inject_connected
has previously been called with this PeerId
.
fn poll(
&mut self,
cx: &mut Context<'_>,
params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ProtocolsHandler>>
fn poll(
&mut self,
cx: &mut Context<'_>,
params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ProtocolsHandler>>
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
fn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr>
fn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr>
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.
fn inject_connected(&mut self, _: &PeerId)
fn inject_connected(&mut self, _: &PeerId)
Indicate to the behaviour that we connected to the node with the given peer id.
This node now has a handler (as spawned by new_handler
) running in the background.
This method is only called when the first connection to the peer is established, preceded by
inject_connection_established
.
fn inject_disconnected(&mut self, _: &PeerId)
fn inject_disconnected(&mut self, _: &PeerId)
Indicates to the behaviour that we disconnected from the node with the given peer id.
There is no handler running anymore for this node. Any event that has been sent to it may or may not have been processed by the handler.
This method is only called when the last established connection to the peer is closed,
preceded by inject_connection_closed
.
fn inject_connection_established(
&mut self,
_peer_id: &PeerId,
_connection_id: &ConnectionId,
_endpoint: &ConnectedPoint,
_failed_addresses: Option<&Vec<Multiaddr>>
)
fn inject_connection_established(
&mut self,
_peer_id: &PeerId,
_connection_id: &ConnectionId,
_endpoint: &ConnectedPoint,
_failed_addresses: Option<&Vec<Multiaddr>>
)
Informs the behaviour about a newly established connection to a peer.
fn inject_connection_closed(
&mut self,
_: &PeerId,
_: &ConnectionId,
_: &ConnectedPoint,
_: <Self::ProtocolsHandler as IntoProtocolsHandler>::Handler
)
fn inject_connection_closed(
&mut self,
_: &PeerId,
_: &ConnectionId,
_: &ConnectedPoint,
_: <Self::ProtocolsHandler as IntoProtocolsHandler>::Handler
)
Informs the behaviour about a closed connection to a peer.
A call to this method is always paired with an earlier call to
inject_connection_established
with the same peer ID, connection ID and
endpoint.
fn inject_address_change(
&mut self,
_: &PeerId,
_: &ConnectionId,
_old: &ConnectedPoint,
_new: &ConnectedPoint
)
fn inject_address_change(
&mut self,
_: &PeerId,
_: &ConnectionId,
_old: &ConnectedPoint,
_new: &ConnectedPoint
)
Informs the behaviour that the ConnectedPoint
of an existing connection has changed.
fn inject_dial_failure(
&mut self,
_peer_id: Option<PeerId>,
_handler: Self::ProtocolsHandler,
_error: &DialError
)
fn inject_dial_failure(
&mut self,
_peer_id: Option<PeerId>,
_handler: Self::ProtocolsHandler,
_error: &DialError
)
Indicates to the behaviour that the dial to a known or unknown node failed.
fn inject_listen_failure(
&mut self,
_local_addr: &Multiaddr,
_send_back_addr: &Multiaddr,
_handler: Self::ProtocolsHandler
)
fn inject_listen_failure(
&mut self,
_local_addr: &Multiaddr,
_send_back_addr: &Multiaddr,
_handler: Self::ProtocolsHandler
)
Indicates to the behaviour that an error happened on an incoming connection during its initial handshake.
This can include, for example, an error during the handshake of the encryption layer, or the connection unexpectedly closed.
fn inject_new_listener(&mut self, _id: ListenerId)
fn inject_new_listener(&mut self, _id: ListenerId)
Indicates to the behaviour that a new listener was created.
fn inject_new_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr)
fn inject_new_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr)
Indicates to the behaviour that we have started listening on a new multiaddr.
fn inject_expired_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr)
fn inject_expired_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr)
Indicates to the behaviour that a multiaddr we were listening on has expired, which means that we are no longer listening in it.
fn inject_listener_error(
&mut self,
_id: ListenerId,
_err: &(dyn Error + 'static)
)
fn inject_listener_error(
&mut self,
_id: ListenerId,
_err: &(dyn Error + 'static)
)
A listener experienced an error.
fn inject_listener_closed(
&mut self,
_id: ListenerId,
_reason: Result<(), &Error>
)
fn inject_listener_closed(
&mut self,
_id: ListenerId,
_reason: Result<(), &Error>
)
A listener closed.
fn inject_new_external_addr(&mut self, _addr: &Multiaddr)
fn inject_new_external_addr(&mut self, _addr: &Multiaddr)
Indicates to the behaviour that we have discovered a new external address for us.
fn inject_expired_external_addr(&mut self, _addr: &Multiaddr)
fn inject_expired_external_addr(&mut self, _addr: &Multiaddr)
Indicates to the behaviour that an external address was removed.
Implementations on Foreign Types
Implementation of NetworkBehaviour
that can be either of two implementations.