Trait rust_ipfs::NetworkBehaviour

source ·

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

    // Required methods
    fn handle_established_inbound_connection(
        &mut self,
        _connection_id: ConnectionId,
        peer: PeerId,
        local_addr: &Multiaddr,
        remote_addr: &Multiaddr,
    ) -> Result<Self::ConnectionHandler, ConnectionDenied>;
    fn handle_established_outbound_connection(
        &mut self,
        _connection_id: ConnectionId,
        peer: PeerId,
        addr: &Multiaddr,
        role_override: Endpoint,
    ) -> Result<Self::ConnectionHandler, ConnectionDenied>;
    fn on_swarm_event(&mut self, event: FromSwarm<'_>);
    fn on_connection_handler_event(
        &mut self,
        _peer_id: PeerId,
        _connection_id: ConnectionId,
        _event: <Self::ConnectionHandler as ConnectionHandler>::ToBehaviour,
    );
    fn poll(
        &mut self,
        cx: &mut Context<'_>,
    ) -> Poll<ToSwarm<Self::ToSwarm, <Self::ConnectionHandler as ConnectionHandler>::FromBehaviour>>;

    // Provided methods
    fn handle_pending_inbound_connection(
        &mut self,
        _connection_id: ConnectionId,
        _local_addr: &Multiaddr,
        _remote_addr: &Multiaddr,
    ) -> Result<(), ConnectionDenied> { ... }
    fn handle_pending_outbound_connection(
        &mut self,
        _connection_id: ConnectionId,
        _maybe_peer: Option<PeerId>,
        _addresses: &[Multiaddr],
        _effective_role: Endpoint,
    ) -> Result<Vec<Multiaddr>, ConnectionDenied> { ... }
}

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.

Events (NetworkBehaviour::ToSwarm) 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(to_swarm = "MyCustomOutEvent")]. If the user does not specify an to_swarm, 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 to_swarm is handled by From implementations which the user needs to define in addition to the event enum itself.

#[derive(NetworkBehaviour)]
#[behaviour(to_swarm = "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§

source

type ConnectionHandler: ConnectionHandler

Handler for all the protocols the network behaviour supports.

source

type ToSwarm: Send + 'static

Event generated by the NetworkBehaviour and that the swarm will report back.

Required Methods§

source

fn handle_established_inbound_connection( &mut self, _connection_id: ConnectionId, peer: PeerId, local_addr: &Multiaddr, remote_addr: &Multiaddr, ) -> Result<Self::ConnectionHandler, 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.

source

fn handle_established_outbound_connection( &mut self, _connection_id: ConnectionId, peer: PeerId, addr: &Multiaddr, role_override: Endpoint, ) -> Result<Self::ConnectionHandler, 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.

source

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

Informs the behaviour about an event from the Swarm.

source

fn on_connection_handler_event( &mut self, _peer_id: PeerId, _connection_id: ConnectionId, _event: <Self::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

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.

source

fn poll( &mut self, cx: &mut Context<'_>, ) -> Poll<ToSwarm<Self::ToSwarm, <Self::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

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§

source

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.

source

fn handle_pending_outbound_connection( &mut self, _connection_id: ConnectionId, _maybe_peer: Option<PeerId>, _addresses: &[Multiaddr], _effective_role: Endpoint, ) -> Result<Vec<Multiaddr>, ConnectionDenied>

Callback that is invoked for every outbound connection attempt.

We have access to:

The PeerId, if known. Remember that we can dial without a PeerId.
All addresses passed to DialOpts are passed in here too.
The effective Role of this peer in the dial attempt. Typically, this is set to Endpoint::Dialer except if we are attempting a hole-punch.
The ConnectionId identifying 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.

Trait rust_ipfs::NetworkBehaviourCopy item path

§Hierarchy of NetworkBehaviour

§Combinators

§Custom NetworkBehaviour with the Derive Macro

Required Associated Types§

type ConnectionHandler: ConnectionHandler

type ToSwarm: Send + 'static

Required Methods§

fn handle_established_inbound_connection( &mut self, _connection_id: ConnectionId, peer: PeerId, local_addr: &Multiaddr, remote_addr: &Multiaddr, ) -> Result<Self::ConnectionHandler, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, _connection_id: ConnectionId, peer: PeerId, addr: &Multiaddr, role_override: Endpoint, ) -> Result<Self::ConnectionHandler, ConnectionDenied>

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

fn on_connection_handler_event( &mut self, _peer_id: PeerId, _connection_id: ConnectionId, _event: <Self::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

fn poll( &mut self, cx: &mut Context<'_>, ) -> Poll<ToSwarm<Self::ToSwarm, <Self::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

Provided Methods§

fn handle_pending_inbound_connection( &mut self, _connection_id: ConnectionId, _local_addr: &Multiaddr, _remote_addr: &Multiaddr, ) -> Result<(), ConnectionDenied>

fn handle_pending_outbound_connection( &mut self, _connection_id: ConnectionId, _maybe_peer: Option<PeerId>, _addresses: &[Multiaddr], _effective_role: Endpoint, ) -> Result<Vec<Multiaddr>, ConnectionDenied>

Implementations on Foreign Types§

impl NetworkBehaviour for Behaviour

type ConnectionHandler = <Behaviour<AutoNatCodec> as NetworkBehaviour>::ConnectionHandler

type ToSwarm = Event

fn poll( &mut self, cx: &mut Context<'_>, ) -> Poll<ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

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<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_pending_outbound_connection( &mut self, connection_id: ConnectionId, maybe_peer: Option<PeerId>, addresses: &[Multiaddr], effective_role: Endpoint, ) -> Result<Vec<Multiaddr>, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, connection_id: ConnectionId, peer: PeerId, addr: &Multiaddr, role_override: Endpoint, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

fn on_connection_handler_event( &mut self, peer_id: PeerId, connection_id: ConnectionId, event: <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

impl NetworkBehaviour for Behaviour

type ConnectionHandler = ConnectionHandler

type ToSwarm = Void

fn handle_pending_inbound_connection( &mut self, connection_id: ConnectionId, _: &Multiaddr, _: &Multiaddr, ) -> Result<(), ConnectionDenied>

fn handle_established_inbound_connection( &mut self, connection_id: ConnectionId, peer: PeerId, _: &Multiaddr, _: &Multiaddr, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_pending_outbound_connection( &mut self, connection_id: ConnectionId, _: Option<PeerId>, _: &[Multiaddr], _: Endpoint, ) -> Result<Vec<Multiaddr>, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, connection_id: ConnectionId, peer: PeerId, _: &Multiaddr, _: Endpoint, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

fn on_connection_handler_event( &mut self, _id: PeerId, _: ConnectionId, event: <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

fn poll( &mut self, _: &mut Context<'_>, ) -> Poll<ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

impl NetworkBehaviour for Behaviour

type ConnectionHandler = Either<Handler, ConnectionHandler>

type ToSwarm = Event

fn handle_established_inbound_connection( &mut self, connection_id: ConnectionId, peer: PeerId, local_addr: &Multiaddr, remote_addr: &Multiaddr, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, connection_id: ConnectionId, peer: PeerId, addr: &Multiaddr, role_override: Endpoint, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn on_connection_handler_event( &mut self, event_source: PeerId, connection_id: ConnectionId, handler_event: <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

fn poll( &mut self, _: &mut Context<'_>, ) -> Poll<ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

impl NetworkBehaviour for Behaviour

type ConnectionHandler = Handler

type ToSwarm = Event

fn handle_established_inbound_connection( &mut self, _: ConnectionId, peer: PeerId, _: &Multiaddr, remote_addr: &Multiaddr, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, _: ConnectionId, peer: PeerId, addr: &Multiaddr, _: Endpoint, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn on_connection_handler_event( &mut self, peer_id: PeerId, id: ConnectionId, event: <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

fn poll( &mut self, _: &mut Context<'_>, ) -> Poll<ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

fn handle_pending_outbound_connection( &mut self, _connection_id: ConnectionId, maybe_peer: Option<PeerId>, _addresses: &[Multiaddr], _effective_role: Endpoint, ) -> Result<Vec<Multiaddr>, ConnectionDenied>

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

impl NetworkBehaviour for Behaviour

type ConnectionHandler = Handler

type ToSwarm = Event

fn handle_established_inbound_connection( &mut self, _: ConnectionId, _: PeerId, _: &Multiaddr, _: &Multiaddr, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, _: ConnectionId, _: PeerId, _: &Multiaddr, _: Endpoint, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn on_connection_handler_event( &mut self, peer: PeerId, connection: ConnectionId, result: <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

fn poll( &mut self, _: &mut Context<'_>, ) -> Poll<ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

fn on_swarm_event(&mut self, _event: FromSwarm<'_>)

impl NetworkBehaviour for Behaviour

type ToSwarm = Event

type ConnectionHandler = Handler

fn handle_established_inbound_connection( &mut self, _connection_id: ConnectionId, _peer: PeerId, _local_addr: &Multiaddr, _remote_addr: &Multiaddr, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, _connection_id: ConnectionId, _peer: PeerId, _addr: &Multiaddr, _role_override: Endpoint, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_pending_outbound_connection( &mut self, _: ConnectionId, maybe_peer: Option<PeerId>, _: &[Multiaddr], _: Endpoint, ) -> Result<Vec<Multiaddr>, ConnectionDenied>

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

fn on_connection_handler_event( &mut self, peer_id: PeerId, connection_id: ConnectionId, event: <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

fn poll( &mut self, cx: &mut Context<'_>, ) -> Poll<ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

impl NetworkBehaviour for Behaviour

type ConnectionHandler = Either<Handler, ConnectionHandler>

type ToSwarm = Event

fn handle_established_inbound_connection( &mut self, _: ConnectionId, _: PeerId, local_addr: &Multiaddr, remote_addr: &Multiaddr, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn handle_established_outbound_connection( &mut self, _: ConnectionId, _: PeerId, addr: &Multiaddr, role_override: Endpoint, ) -> Result<<Behaviour as NetworkBehaviour>::ConnectionHandler, ConnectionDenied>

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

fn on_connection_handler_event( &mut self, event_source: PeerId, connection: ConnectionId, event: <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::ToBehaviour, )

fn poll( &mut self, _: &mut Context<'_>, ) -> Poll<ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, <<Behaviour as NetworkBehaviour>::ConnectionHandler as ConnectionHandler>::FromBehaviour>>

impl NetworkBehaviour for Behaviour

Trait rust_ipfs::NetworkBehaviour

§Hierarchy of `NetworkBehaviour`

§Custom `NetworkBehaviour` with the Derive Macro

impl<C, F> NetworkBehaviour for Behaviour<C, F>
where C: Send + 'static + DataTransform, F: Send + 'static + TopicSubscriptionFilter,

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

impl<P> NetworkBehaviour for Behaviour<P>
where P: Provider,

impl<S> NetworkBehaviour for Behaviour<S>
where S: Enforce,