Trait libp2p_swarm::behaviour::NetworkBehaviour

source ·

pub trait NetworkBehaviour: 'static {
    type ConnectionHandler: IntoConnectionHandler;
    type OutEvent: Send + 'static;

Show 18 methods    // Required methods
    fn new_handler(&mut self) -> Self::ConnectionHandler;
    fn poll(
        &mut self,
        cx: &mut Context<'_>,
        params: &mut impl PollParameters
    ) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ConnectionHandler>>;

    // Provided methods
    fn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr> { ... }
    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 inject_connection_established(
        &mut self,
        peer_id: &PeerId,
        connection_id: &ConnectionId,
        endpoint: &ConnectedPoint,
        failed_addresses: Option<&Vec<Multiaddr>>,
        other_established: usize
    ) { ... }
    fn inject_connection_closed(
        &mut self,
        peer_id: &PeerId,
        connection_id: &ConnectionId,
        endpoint: &ConnectedPoint,
        handler: <Self::ConnectionHandler as IntoConnectionHandler>::Handler,
        remaining_established: usize
    ) { ... }
    fn inject_address_change(
        &mut self,
        peer_id: &PeerId,
        connection_id: &ConnectionId,
        old: &ConnectedPoint,
        new: &ConnectedPoint
    ) { ... }
    fn inject_event(
        &mut self,
        peer_id: PeerId,
        connection: ConnectionId,
        event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent
    ) { ... }
    fn inject_dial_failure(
        &mut self,
        peer_id: Option<PeerId>,
        handler: Self::ConnectionHandler,
        error: &DialError
    ) { ... }
    fn inject_listen_failure(
        &mut self,
        local_addr: &Multiaddr,
        send_back_addr: &Multiaddr,
        handler: Self::ConnectionHandler
    ) { ... }
    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 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)
  }
}

Trait libp2p_swarm::behaviour::NetworkBehaviour

Required Associated Types§

type ConnectionHandler: IntoConnectionHandler

type OutEvent: Send + 'static

Required Methods§

fn new_handler(&mut self) -> Self::ConnectionHandler

fn poll( &mut self, cx: &mut Context<'_>, params: &mut impl PollParameters ) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ConnectionHandler>>

Provided Methods§

fn addresses_of_peer(&mut self, _: &PeerId) -> Vec<Multiaddr>

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 inject_connection_established( &mut self, peer_id: &PeerId, connection_id: &ConnectionId, endpoint: &ConnectedPoint, failed_addresses: Option<&Vec<Multiaddr>>, other_established: usize )

fn inject_connection_closed( &mut self, peer_id: &PeerId, connection_id: &ConnectionId, endpoint: &ConnectedPoint, handler: <Self::ConnectionHandler as IntoConnectionHandler>::Handler, remaining_established: usize )

fn inject_address_change( &mut self, peer_id: &PeerId, connection_id: &ConnectionId, old: &ConnectedPoint, new: &ConnectedPoint )

fn inject_event( &mut self, peer_id: PeerId, connection: ConnectionId, event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent )

fn inject_dial_failure( &mut self, peer_id: Option<PeerId>, handler: Self::ConnectionHandler, error: &DialError )

fn inject_listen_failure( &mut self, local_addr: &Multiaddr, send_back_addr: &Multiaddr, handler: Self::ConnectionHandler )

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)

Implementations on Foreign Types§

impl<L, R> NetworkBehaviour for Either<L, R>where L: NetworkBehaviour, R: NetworkBehaviour,

type ConnectionHandler = IntoEitherHandler<<L as NetworkBehaviour>::ConnectionHandler, <R as NetworkBehaviour>::ConnectionHandler>

type OutEvent = Either<<L as NetworkBehaviour>::OutEvent, <R as NetworkBehaviour>::OutEvent>

fn new_handler(&mut self) -> Self::ConnectionHandler

fn addresses_of_peer(&mut self, peer_id: &PeerId) -> Vec<Multiaddr>

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 as NetworkBehaviour>::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent )

fn poll( &mut self, cx: &mut Context<'_>, params: &mut impl PollParameters ) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ConnectionHandler>>

Implementors§

impl NetworkBehaviour for libp2p_swarm::dummy::Behaviour

type ConnectionHandler = ConnectionHandler

type OutEvent = Void

impl NetworkBehaviour for libp2p_swarm::keep_alive::Behaviour

type ConnectionHandler = ConnectionHandler

type OutEvent = Void

impl<TBehaviour> NetworkBehaviour for Toggle<TBehaviour>where TBehaviour: NetworkBehaviour,

type ConnectionHandler = ToggleIntoConnectionHandler<<TBehaviour as NetworkBehaviour>::ConnectionHandler>

type OutEvent = <TBehaviour as NetworkBehaviour>::OutEvent