Enum libp2p_swarm::NetworkBehaviourAction

pub enum NetworkBehaviourAction<TOutEvent, THandler: IntoProtocolsHandler, TInEvent = <<THandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::InEvent> {
    GenerateEvent(TOutEvent),
    DialAddress {
        address: Multiaddr,
        handler: THandler,
    },
    DialPeer {
        peer_id: PeerId,
        condition: DialPeerCondition,
        handler: THandler,
    },
    NotifyHandler {
        peer_id: PeerId,
        handler: NotifyHandler,
        event: TInEvent,
    },
    ReportObservedAddr {
        address: Multiaddr,
        score: AddressScore,
    },
    CloseConnection {
        peer_id: PeerId,
        connection: CloseConnection,
    },
}

An action that a NetworkBehaviour can trigger in the Swarm in whose context it is executing.

Variants

GenerateEvent(TOutEvent)

Instructs the Swarm to return an event when it is being polled.

Tuple Fields of GenerateEvent

0: TOutEvent

DialAddress

Instructs the swarm to dial the given multiaddress optionally including a PeerId.

On success, NetworkBehaviour::inject_connection_established is invoked. On failure, NetworkBehaviour::inject_dial_failure is invoked.

Note that the provided handler is returned to the NetworkBehaviour on connection failure and connection closing. Thus it can be used to carry state, which otherwise would have to be tracked in the NetworkBehaviour itself. E.g. a message destined to an unconnected peer can be included in the handler, and thus directly send on connection success or extracted by the NetworkBehaviour on connection failure. See NetworkBehaviourAction::DialPeer for example.

Fields of DialAddress

address: Multiaddr

The address to dial.

handler: THandler

The handler to be used to handle the connection to the peer.

DialPeer

Instructs the swarm to dial a known PeerId.

The NetworkBehaviour::addresses_of_peer method is called to determine which addresses to attempt to reach.

If we were already trying to dial this node, the addresses that are not yet in the queue of addresses to try are added back to this queue.

On success, NetworkBehaviour::inject_connection_established is invoked. On failure, NetworkBehaviour::inject_dial_failure is invoked.

Note that the provided handler is returned to the NetworkBehaviour on connection failure and connection closing. Thus it can be used to carry state, which otherwise would have to be tracked in the NetworkBehaviour itself. E.g. a message destined to an unconnected peer can be included in the handler, and thus directly send on connection success or extracted by the NetworkBehaviour on connection failure.

Example

// Super precious message that we should better not lose.
let message = PreciousMessage("My precious message".to_string());

// Unfortunately this peer is offline, thus sending our message to it will fail.
let offline_peer = PeerId::random();

// Let's send it anyways. We should get it back in case connecting to the peer fails.
swarm.behaviour_mut().send(offline_peer, message);

block_on(async {
    // As expected, sending failed. But great news, we got our message back.
    matches!(
        swarm.next().await.expect("Infinite stream"),
        SwarmEvent::Behaviour(PreciousMessage(_))
    );
});

impl NetworkBehaviour for MyBehaviour {
    fn inject_dial_failure(
        &mut self,
        _: Option<PeerId>,
        handler: Self::ProtocolsHandler,
        _: &DialError,
    ) {
        // As expected, sending the message failed. But lucky us, we got the handler back, thus
        // the precious message is not lost and we can return it back to the user.
        let msg = handler.message.unwrap();
        self.outbox_to_swarm
            .push_back(NetworkBehaviourAction::GenerateEvent(msg))
    }
}

Fields of DialPeer

peer_id: PeerId

The peer to try reach.

condition: DialPeerCondition

The condition for initiating a new dialing attempt.

handler: THandler

The handler to be used to handle the connection to the peer.

NotifyHandler

Instructs the Swarm to send an event to the handler dedicated to a connection with a peer.

If the Swarm is connected to the peer, the message is delivered to the ProtocolsHandler instance identified by the peer ID and connection ID.

If the specified connection no longer exists, the event is silently dropped.

Typically the connection ID given is the same as the one passed to NetworkBehaviour::inject_event, i.e. whenever the behaviour wishes to respond to a request on the same connection (and possibly the same substream, as per the implementation of ProtocolsHandler).

Note that even if the peer is currently connected, connections can get closed at any time and thus the event may not reach a handler.

Fields of NotifyHandler

peer_id: PeerId

The peer for whom a ProtocolsHandler should be notified.

handler: NotifyHandler

The options w.r.t. which connection handler to notify of the event.

event: TInEvent

The event to send.

ReportObservedAddr

Informs the Swarm about an address observed by a remote for the local node by which the local node is supposedly publicly reachable.

It is advisable to issue ReportObservedAddr actions at a fixed frequency per node. This way address information will be more accurate over time and individual outliers carry less weight.

Fields of ReportObservedAddr

address: Multiaddr

The observed address of the local node.

score: AddressScore

The score to associate with this observation, i.e. an indicator for the trusworthiness of this address relative to other observed addresses.

CloseConnection

Instructs the Swarm to initiate a graceful close of one or all connections with the given peer.

Note: Closing a connection via NetworkBehaviourAction::CloseConnection does not inform the corresponding ProtocolsHandler. Closing a connection via a ProtocolsHandler can be done either in a collaborative manner across ProtocolsHandlers with ProtocolsHandler::connection_keep_alive or directly with ProtocolsHandlerEvent::Close.

Fields of CloseConnection

peer_id: PeerId

The peer to disconnect.

connection: CloseConnection

Whether to close a specific or all connections to the given peer.

Implementations

impl<TOutEvent, THandler: IntoProtocolsHandler, TInEventOld> NetworkBehaviourAction<TOutEvent, THandler, TInEventOld>

pub fn map_in<TInEventNew>(
    self,
    f: impl FnOnce(TInEventOld) -> TInEventNew
) -> NetworkBehaviourAction<TOutEvent, THandler, TInEventNew>

Map the handler event.

impl<TOutEvent, THandler: IntoProtocolsHandler> NetworkBehaviourAction<TOutEvent, THandler>

pub fn map_out<E>(
    self,
    f: impl FnOnce(TOutEvent) -> E
) -> NetworkBehaviourAction<E, THandler>

Map the event the swarm will return.

impl<TInEvent, TOutEvent, THandlerOld> NetworkBehaviourAction<TOutEvent, THandlerOld> where
    THandlerOld: IntoProtocolsHandler,
    <THandlerOld as IntoProtocolsHandler>::Handler: ProtocolsHandler<InEvent = TInEvent>, 

pub fn map_handler<THandlerNew>(
    self,
    f: impl FnOnce(THandlerOld) -> THandlerNew
) -> NetworkBehaviourAction<TOutEvent, THandlerNew> where
    THandlerNew: IntoProtocolsHandler,
    <THandlerNew as IntoProtocolsHandler>::Handler: ProtocolsHandler<InEvent = TInEvent>, 

Map the handler.

Trait Implementations

impl<TOutEvent: Debug, THandler: Debug + IntoProtocolsHandler, TInEvent: Debug> Debug for NetworkBehaviourAction<TOutEvent, THandler, TInEvent>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.