Trait libp2p::swarm::NetworkBehaviour

pub trait NetworkBehaviour: 'static + Send {
    type ProtocolsHandler: IntoProtocolsHandler;
    type OutEvent: 'static + Send;
    pub fn new_handler(&mut self) -> Self::ProtocolsHandler;
    pub fn addresses_of_peer(
        &mut self, 
        peer_id: &PeerId
    ) -> Vec<Multiaddr, Global>;
    pub fn inject_connected(&mut self, peer_id: &PeerId);
    pub fn inject_disconnected(&mut self, peer_id: &PeerId);
    pub fn inject_event(
        &mut self, 
        peer_id: PeerId, 
        connection: ConnectionId, 
        event: <<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::OutEvent
    );
    pub fn poll(
        &mut self, 
        cx: &mut Context<'_>, 
        params: &mut impl PollParameters
    ) -> Poll<NetworkBehaviourAction<<<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::InEvent, Self::OutEvent>>;

    pub fn inject_connection_established(
        &mut self, 
        &PeerId, 
        &ConnectionId, 
        &ConnectedPoint
    ) { ... }
    pub fn inject_connection_closed(
        &mut self, 
        &PeerId, 
        &ConnectionId, 
        &ConnectedPoint
    ) { ... }
    pub fn inject_address_change(
        &mut self, 
        &PeerId, 
        &ConnectionId, 
        _old: &ConnectedPoint, 
        _new: &ConnectedPoint
    ) { ... }
    pub fn inject_addr_reach_failure(
        &mut self, 
        _peer_id: Option<&PeerId>, 
        _addr: &Multiaddr, 
        _error: &dyn Error
    ) { ... }
    pub fn inject_dial_failure(&mut self, _peer_id: &PeerId) { ... }
    pub fn inject_new_listen_addr(&mut self, _addr: &Multiaddr) { ... }
    pub fn inject_expired_listen_addr(&mut self, _addr: &Multiaddr) { ... }
    pub fn inject_new_external_addr(&mut self, _addr: &Multiaddr) { ... }
    pub fn inject_listener_error(
        &mut self, 
        _id: ListenerId, 
        _err: &(dyn Error + 'static)
    ) { ... }
    pub fn inject_listener_closed(
        &mut self, 
        _id: ListenerId, 
        _reason: Result<(), &Error>
    ) { ... }
}

A behaviour for the network. Allows customizing the swarm.

This trait has been designed to be composable. Multiple implementations can be combined into one that handles all the behaviours at once.

Deriving NetworkBehaviour

Crate users can implement this trait by using the the #[derive(NetworkBehaviour)] proc macro re-exported by the libp2p crate. The macro generates a delegating trait implementation for the struct, which delegates method calls to all trait members.

By default the derive sets the NetworkBehaviour::OutEvent as () but this can be overridden with #[behaviour(out_event = "AnotherType")].

Struct members that don’t implement NetworkBehaviour must be annotated with #[behaviour(ignore)].

By default, events generated by the remaining members are delegated to NetworkBehaviourEventProcess implementations. Those must be provided by the user on the type that NetworkBehaviour is derived on.

Alternatively, users can specify #[behaviour(event_process = false)]. In this case, users should provide a custom out_event and implement From for each of the event types generated by the struct members. Not processing events within the derived NetworkBehaviour will cause them to be emitted as part of polling the swarm in SwarmEvent::Behaviour.

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

type ProtocolsHandler: IntoProtocolsHandler

Handler for all the protocols the network behaviour supports.

type OutEvent: 'static + Send

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

Loading content...

Required methods

pub 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 we start dialing a node, 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 inject_event, and the behaviour can send a message to the handler by making poll return SendEvent.

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

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.

pub fn inject_connected(&mut self, peer_id: &PeerId)

Indicates 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 connection to the peer is established, preceded by inject_connection_established.

pub fn inject_disconnected(&mut self, peer_id: &PeerId)

Indicates 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.

pub 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.

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::InEvent, Self::OutEvent>>

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.

Loading content...

Provided methods

pub fn inject_connection_established(
    &mut self,
    &PeerId,
    &ConnectionId,
    &ConnectedPoint
)

Informs the behaviour about a newly established connection to a peer.

pub fn inject_connection_closed(
    &mut self,
    &PeerId,
    &ConnectionId,
    &ConnectedPoint
)

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.

pub fn inject_address_change(
    &mut self,
    &PeerId,
    &ConnectionId,
    _old: &ConnectedPoint,
    _new: &ConnectedPoint
)

Informs the behaviour that the ConnectedPoint of an existing connection has changed.

pub fn inject_addr_reach_failure(
    &mut self,
    _peer_id: Option<&PeerId>,
    _addr: &Multiaddr,
    _error: &dyn Error
)

Indicates to the behaviour that we tried to reach an address, but failed.

If we were trying to reach a specific node, its ID is passed as parameter. If this is the last address to attempt for the given node, then inject_dial_failure is called afterwards.

pub fn inject_dial_failure(&mut self, _peer_id: &PeerId)

Indicates to the behaviour that we tried to dial all the addresses known for a node, but failed.

The peer_id is guaranteed to be in a disconnected state. In other words, inject_connected has not been called, or inject_disconnected has been called since then.

pub fn inject_new_listen_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that we have started listening on a new multiaddr.

pub fn inject_expired_listen_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that a new multiaddr we were listening on has expired, which means that we are no longer listening in it.

pub fn inject_new_external_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that we have discovered a new external address for us.

pub fn inject_listener_error(
    &mut self,
    _id: ListenerId,
    _err: &(dyn Error + 'static)
)

A listener experienced an error.

pub fn inject_listener_closed(
    &mut self,
    _id: ListenerId,
    _reason: Result<(), &Error>
)

A listener closed.

Loading content...

Implementors

impl NetworkBehaviour for Floodsub

type ProtocolsHandler = OneShotHandler<FloodsubProtocol, FloodsubRpc, InnerMessage>

type OutEvent = FloodsubEvent

pub fn new_handler(
    &mut self
) -> <Floodsub as NetworkBehaviour>::ProtocolsHandler

pub fn addresses_of_peer(&mut self, &PeerId) -> Vec<Multiaddr, Global>

pub fn inject_connected(&mut self, id: &PeerId)

pub fn inject_disconnected(&mut self, id: &PeerId)

pub fn inject_event(
    &mut self,
    propagation_source: PeerId,
    _connection: ConnectionId,
    event: InnerMessage
)

pub fn poll(
    &mut self,
    &mut Context<'_>,
    &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<Floodsub as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::InEvent, <Floodsub as NetworkBehaviour>::OutEvent>>

impl NetworkBehaviour for Gossipsub

type ProtocolsHandler = GossipsubHandler

type OutEvent = GossipsubEvent

pub fn new_handler(
    &mut self
) -> <Gossipsub as NetworkBehaviour>::ProtocolsHandler

pub fn addresses_of_peer(&mut self, &PeerId) -> Vec<Multiaddr, Global>

pub fn inject_connected(&mut self, id: &PeerId)

pub fn inject_disconnected(&mut self, id: &PeerId)

pub fn inject_event(
    &mut self,
    propagation_source: PeerId,
    ConnectionId,
    event: GossipsubRpc
)

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<Gossipsub as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::InEvent, <Gossipsub as NetworkBehaviour>::OutEvent>>

impl NetworkBehaviour for Identify

type ProtocolsHandler = IdentifyHandler

type OutEvent = IdentifyEvent

pub fn new_handler(
    &mut self
) -> <Identify as NetworkBehaviour>::ProtocolsHandler

pub fn addresses_of_peer(&mut self, &PeerId) -> Vec<Multiaddr, Global>

pub fn inject_connected(&mut self, &PeerId)

pub fn inject_connection_established(
    &mut self,
    peer_id: &PeerId,
    conn: &ConnectionId,
    endpoint: &ConnectedPoint
)

pub fn inject_connection_closed(
    &mut self,
    peer_id: &PeerId,
    conn: &ConnectionId,
    &ConnectedPoint
)

pub fn inject_disconnected(&mut self, peer_id: &PeerId)

pub fn inject_event(
    &mut self,
    peer_id: PeerId,
    connection: ConnectionId,
    event: <<Identify as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::OutEvent
)

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<Identify as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::InEvent, <Identify as NetworkBehaviour>::OutEvent>>

impl NetworkBehaviour for Mdns

type ProtocolsHandler = DummyProtocolsHandler

type OutEvent = MdnsEvent

pub fn new_handler(&mut self) -> <Mdns as NetworkBehaviour>::ProtocolsHandler

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

pub fn inject_connected(&mut self, &PeerId)

pub fn inject_disconnected(&mut self, &PeerId)

pub fn inject_event(
    &mut self,
    PeerId,
    ConnectionId,
    _ev: <<Mdns as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::OutEvent
)

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<Mdns as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::InEvent, <Mdns as NetworkBehaviour>::OutEvent>>

impl NetworkBehaviour for Ping

type ProtocolsHandler = PingHandler

type OutEvent = PingEvent

pub fn new_handler(&mut self) -> <Ping as NetworkBehaviour>::ProtocolsHandler

pub fn addresses_of_peer(&mut self, _peer_id: &PeerId) -> Vec<Multiaddr, Global>

pub fn inject_connected(&mut self, &PeerId)

pub fn inject_disconnected(&mut self, &PeerId)

pub fn inject_event(
    &mut self,
    peer: PeerId,
    ConnectionId,
    result: Result<PingSuccess, PingFailure>
)

pub fn poll(
    &mut self,
    &mut Context<'_>,
    &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<Void, PingEvent>>

impl NetworkBehaviour for DummyBehaviour

type ProtocolsHandler = DummyProtocolsHandler

type OutEvent = Void

pub fn new_handler(
    &mut self
) -> <DummyBehaviour as NetworkBehaviour>::ProtocolsHandler

pub fn addresses_of_peer(&mut self, &PeerId) -> Vec<Multiaddr, Global>

pub fn inject_connected(&mut self, &PeerId)

pub fn inject_connection_established(
    &mut self,
    &PeerId,
    &ConnectionId,
    &ConnectedPoint
)

pub fn inject_disconnected(&mut self, &PeerId)

pub fn inject_connection_closed(
    &mut self,
    &PeerId,
    &ConnectionId,
    &ConnectedPoint
)

pub fn inject_event(
    &mut self,
    PeerId,
    ConnectionId,
    <<DummyBehaviour as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::OutEvent
)

pub fn poll(
    &mut self,
    &mut Context<'_>,
    &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<DummyBehaviour as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::InEvent, <DummyBehaviour as NetworkBehaviour>::OutEvent>>

impl<C> NetworkBehaviour for Throttled<C> where
    C: RequestResponseCodec + Send + Clone + 'static,
    <C as RequestResponseCodec>::Protocol: Sync, 

type ProtocolsHandler = RequestResponseHandler<Codec<C>>

type OutEvent = Event<<C as RequestResponseCodec>::Request, <C as RequestResponseCodec>::Response, Message<<C as RequestResponseCodec>::Response>>

pub fn new_handler(
    &mut self
) -> <Throttled<C> as NetworkBehaviour>::ProtocolsHandler

pub fn addresses_of_peer(&mut self, p: &PeerId) -> Vec<Multiaddr, Global>

pub fn inject_connection_established(
    &mut self,
    p: &PeerId,
    id: &ConnectionId,
    end: &ConnectedPoint
)

pub fn inject_connection_closed(
    &mut self,
    peer: &PeerId,
    id: &ConnectionId,
    end: &ConnectedPoint
)

pub fn inject_connected(&mut self, p: &PeerId)

pub fn inject_disconnected(&mut self, p: &PeerId)

pub fn inject_dial_failure(&mut self, p: &PeerId)

pub fn inject_event(
    &mut self,
    p: PeerId,
    i: ConnectionId,
    e: RequestResponseHandlerEvent<Codec<C>>
)

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<RequestProtocol<Codec<C>>, <Throttled<C> as NetworkBehaviour>::OutEvent>>

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

type ProtocolsHandler = ToggleIntoProtoHandler<<TBehaviour as NetworkBehaviour>::ProtocolsHandler>

type OutEvent = <TBehaviour as NetworkBehaviour>::OutEvent

pub fn new_handler(
    &mut self
) -> <Toggle<TBehaviour> as NetworkBehaviour>::ProtocolsHandler

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

pub fn inject_connected(&mut self, peer_id: &PeerId)

pub fn inject_disconnected(&mut self, peer_id: &PeerId)

pub fn inject_connection_established(
    &mut self,
    peer_id: &PeerId,
    connection: &ConnectionId,
    endpoint: &ConnectedPoint
)

pub fn inject_connection_closed(
    &mut self,
    peer_id: &PeerId,
    connection: &ConnectionId,
    endpoint: &ConnectedPoint
)

pub fn inject_event(
    &mut self,
    peer_id: PeerId,
    connection: ConnectionId,
    event: <<<Toggle<TBehaviour> as NetworkBehaviour>::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::OutEvent
)

pub fn inject_addr_reach_failure(
    &mut self,
    peer_id: Option<&PeerId>,
    addr: &Multiaddr,
    error: &dyn Error
)

pub fn inject_dial_failure(&mut self, peer_id: &PeerId)

pub fn inject_new_listen_addr(&mut self, addr: &Multiaddr)

pub fn inject_expired_listen_addr(&mut self, addr: &Multiaddr)

pub fn inject_new_external_addr(&mut self, addr: &Multiaddr)

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    params: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<<Toggle<TBehaviour> as NetworkBehaviour>::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::InEvent, <Toggle<TBehaviour> as NetworkBehaviour>::OutEvent>>

impl<TCodec> NetworkBehaviour for RequestResponse<TCodec> where
    TCodec: RequestResponseCodec + Send + Clone + 'static, 

type ProtocolsHandler = RequestResponseHandler<TCodec>

type OutEvent = RequestResponseEvent<<TCodec as RequestResponseCodec>::Request, <TCodec as RequestResponseCodec>::Response, <TCodec as RequestResponseCodec>::Response>

pub fn new_handler(
    &mut self
) -> <RequestResponse<TCodec> as NetworkBehaviour>::ProtocolsHandler

pub fn addresses_of_peer(&mut self, peer: &PeerId) -> Vec<Multiaddr, Global>

pub fn inject_connected(&mut self, peer: &PeerId)

pub fn inject_connection_established(
    &mut self,
    peer: &PeerId,
    conn: &ConnectionId,
    endpoint: &ConnectedPoint
)

pub fn inject_connection_closed(
    &mut self,
    peer: &PeerId,
    conn: &ConnectionId,
    &ConnectedPoint
)

pub fn inject_disconnected(&mut self, peer: &PeerId)

pub fn inject_dial_failure(&mut self, peer: &PeerId)

pub fn inject_event(
    &mut self,
    peer: PeerId,
    ConnectionId,
    event: RequestResponseHandlerEvent<TCodec>
)

pub fn poll(
    &mut self,
    &mut Context<'_>,
    &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<RequestProtocol<TCodec>, RequestResponseEvent<<TCodec as RequestResponseCodec>::Request, <TCodec as RequestResponseCodec>::Response, <TCodec as RequestResponseCodec>::Response>>>

impl<TStore> NetworkBehaviour for Kademlia<TStore> where
    TStore: for<'a> RecordStore<'a> + Send + 'static, 

type ProtocolsHandler = KademliaHandler<QueryId>

type OutEvent = KademliaEvent

pub fn new_handler(
    &mut self
) -> <Kademlia<TStore> as NetworkBehaviour>::ProtocolsHandler

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

pub fn inject_connection_established(
    &mut self,
    peer: &PeerId,
    &ConnectionId,
    endpoint: &ConnectedPoint
)

pub fn inject_connected(&mut self, peer: &PeerId)

pub fn inject_address_change(
    &mut self,
    peer: &PeerId,
    &ConnectionId,
    old: &ConnectedPoint,
    new: &ConnectedPoint
)

pub fn inject_addr_reach_failure(
    &mut self,
    peer_id: Option<&PeerId>,
    addr: &Multiaddr,
    err: &dyn Error
)

pub fn inject_dial_failure(&mut self, peer_id: &PeerId)

pub fn inject_disconnected(&mut self, id: &PeerId)

pub fn inject_event(
    &mut self,
    source: PeerId,
    connection: ConnectionId,
    event: KademliaHandlerEvent<QueryId>
)

pub fn inject_new_listen_addr(&mut self, addr: &Multiaddr)

pub fn inject_expired_listen_addr(&mut self, addr: &Multiaddr)

pub fn inject_new_external_addr(&mut self, addr: &Multiaddr)

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    parameters: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<KademliaHandler<QueryId> as ProtocolsHandler>::InEvent, <Kademlia<TStore> as NetworkBehaviour>::OutEvent>>

Loading content...