Trait libp2p_swarm::handler::ConnectionHandler

pub trait ConnectionHandler: Send + 'static {
    type FromBehaviour: Debug + Send + 'static;
    type ToBehaviour: Debug + Send + 'static;
    type Error: Error + Debug + Send + 'static;
    type InboundProtocol: InboundUpgradeSend;
    type OutboundProtocol: OutboundUpgradeSend;
    type InboundOpenInfo: Send + 'static;
    type OutboundOpenInfo: Send + 'static;

    // Required methods
    fn listen_protocol(
        &self,
    ) -> SubstreamProtocol<Self::InboundProtocol, Self::InboundOpenInfo>;
    fn connection_keep_alive(&self) -> KeepAlive;
    fn poll(
        &mut self,
        cx: &mut Context<'_>,
    ) -> Poll<ConnectionHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::ToBehaviour, Self::Error>>;
    fn on_behaviour_event(&mut self, _event: Self::FromBehaviour);
    fn on_connection_event(
        &mut self,
        event: ConnectionEvent<'_, Self::InboundProtocol, Self::OutboundProtocol, Self::InboundOpenInfo, Self::OutboundOpenInfo>,
    );

    // Provided methods
    fn map_in_event<TNewIn, TMap>(
        self,
        map: TMap,
    ) -> MapInEvent<Self, TNewIn, TMap>
       where Self: Sized,
             TMap: Fn(&TNewIn) -> Option<&Self::FromBehaviour> { ... }
    fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap>
       where Self: Sized,
             TMap: FnMut(Self::ToBehaviour) -> TNewOut { ... }
    fn select<TProto2>(
        self,
        other: TProto2,
    ) -> ConnectionHandlerSelect<Self, TProto2>
       where Self: Sized { ... }
}

A handler for a set of protocols used on a connection with a remote.

This trait should be implemented for a type that maintains the state for the execution of a specific protocol with a remote.

Handling a protocol

Communication with a remote over a set of protocols is initiated in one of two ways:

1. Dialing by initiating a new outbound substream. In order to do so, ConnectionHandler::poll() must return an ConnectionHandlerEvent::OutboundSubstreamRequest, providing an instance of libp2p_core::upgrade::OutboundUpgrade that is used to negotiate the protocol(s). Upon success, ConnectionHandler::on_connection_event is called with ConnectionEvent::FullyNegotiatedOutbound translating the final output of the upgrade.

2. Listening by accepting a new inbound substream. When a new inbound substream is created on a connection, ConnectionHandler::listen_protocol is called to obtain an instance of libp2p_core::upgrade::InboundUpgrade that is used to negotiate the protocol(s). Upon success, ConnectionHandler::on_connection_event is called with ConnectionEvent::FullyNegotiatedInbound translating the final output of the upgrade.

Connection Keep-Alive

A ConnectionHandler can influence the lifetime of the underlying connection through ConnectionHandler::connection_keep_alive. That is, the protocol implemented by the handler can include conditions for terminating the connection. The lifetime of successfully negotiated substreams is fully controlled by the handler.

Implementors of this trait should keep in mind that the connection can be closed at any time. When a connection is closed gracefully, the substreams used by the handler may still continue reading data until the remote closes its side of the connection.

Required Associated Types

type FromBehaviour: Debug + Send + 'static

A type representing the message(s) a NetworkBehaviour can send to a ConnectionHandler via ToSwarm::NotifyHandler

type ToBehaviour: Debug + Send + 'static

A type representing message(s) a ConnectionHandler can send to a NetworkBehaviour via ConnectionHandlerEvent::NotifyBehaviour.

type Error: Error + Debug + Send + 'static

👎Deprecated: Will be removed together with ConnectionHandlerEvent::Close. See https://github.com/libp2p/rust-libp2p/issues/3591 for details.

The type of errors returned by ConnectionHandler::poll.

type InboundProtocol: InboundUpgradeSend

The inbound upgrade for the protocol(s) used by the handler.

type OutboundProtocol: OutboundUpgradeSend

The outbound upgrade for the protocol(s) used by the handler.

type InboundOpenInfo: Send + 'static

The type of additional information returned from listen_protocol.

type OutboundOpenInfo: Send + 'static

The type of additional information passed to an OutboundSubstreamRequest.

Required Methods

fn listen_protocol( &self, ) -> SubstreamProtocol<Self::InboundProtocol, Self::InboundOpenInfo>

The InboundUpgrade to apply on inbound substreams to negotiate the desired protocols.

Note: The returned InboundUpgrade should always accept all the generally supported protocols, even if in a specific context a particular one is not supported, (eg. when only allowing one substream at a time for a protocol). This allows a remote to put the list of supported protocols in a cache.

fn connection_keep_alive(&self) -> KeepAlive

Returns until when the connection should be kept alive.

This method is called by the Swarm after each invocation of ConnectionHandler::poll to determine if the connection and the associated ConnectionHandlers should be kept alive as far as this handler is concerned and if so, for how long.

Returning KeepAlive::No indicates that the connection should be closed and this handler destroyed immediately.

Returning KeepAlive::Until indicates that the connection may be closed and this handler destroyed after the specified Instant.

Returning KeepAlive::Yes indicates that the connection should be kept alive until the next call to this method.

Note: The connection is always closed and the handler destroyed when ConnectionHandler::poll returns an error. Furthermore, the connection may be closed for reasons outside of the control of the handler.

fn poll( &mut self, cx: &mut Context<'_>, ) -> Poll<ConnectionHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::ToBehaviour, Self::Error>>

Should behave like Stream::poll().

fn on_behaviour_event(&mut self, _event: Self::FromBehaviour)

Informs the handler about an event from the NetworkBehaviour.

fn on_connection_event( &mut self, event: ConnectionEvent<'_, Self::InboundProtocol, Self::OutboundProtocol, Self::InboundOpenInfo, Self::OutboundOpenInfo>, )

Provided Methods

fn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap>

where Self: Sized, TMap: Fn(&TNewIn) -> Option<&Self::FromBehaviour>,

Adds a closure that turns the input event into something else.

fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap>

where Self: Sized, TMap: FnMut(Self::ToBehaviour) -> TNewOut,

Adds a closure that turns the output event into something else.

fn select<TProto2>( self, other: TProto2, ) -> ConnectionHandlerSelect<Self, TProto2>

where Self: Sized,

Creates a new ConnectionHandler that selects either this handler or other by delegating methods calls appropriately.

Note: The largest KeepAlive returned by the two handlers takes precedence, i.e. is returned from ConnectionHandler::connection_keep_alive by the returned handler.

Implementations on Foreign Types

impl<L, R> ConnectionHandler for Either<L, R>

where L: ConnectionHandler, R: ConnectionHandler,

Implementation of a ConnectionHandler that represents either of two ConnectionHandler implementations.

type FromBehaviour = Either<<L as ConnectionHandler>::FromBehaviour, <R as ConnectionHandler>::FromBehaviour>

type ToBehaviour = Either<<L as ConnectionHandler>::ToBehaviour, <R as ConnectionHandler>::ToBehaviour>

type Error = Either<<L as ConnectionHandler>::Error, <R as ConnectionHandler>::Error>

👎Deprecated: Will be removed together with ConnectionHandlerEvent::Close. See https://github.com/libp2p/rust-libp2p/issues/3591 for details.

type InboundProtocol = Either<SendWrapper<<L as ConnectionHandler>::InboundProtocol>, SendWrapper<<R as ConnectionHandler>::InboundProtocol>>

type OutboundProtocol = Either<SendWrapper<<L as ConnectionHandler>::OutboundProtocol>, SendWrapper<<R as ConnectionHandler>::OutboundProtocol>>

type InboundOpenInfo = Either<<L as ConnectionHandler>::InboundOpenInfo, <R as ConnectionHandler>::InboundOpenInfo>

type OutboundOpenInfo = Either<<L as ConnectionHandler>::OutboundOpenInfo, <R as ConnectionHandler>::OutboundOpenInfo>

fn listen_protocol( &self, ) -> SubstreamProtocol<Self::InboundProtocol, Self::InboundOpenInfo>

fn on_behaviour_event(&mut self, event: Self::FromBehaviour)

fn connection_keep_alive(&self) -> KeepAlive

fn poll( &mut self, cx: &mut Context<'_>, ) -> Poll<ConnectionHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::ToBehaviour, Self::Error>>

fn on_connection_event( &mut self, event: ConnectionEvent<'_, Self::InboundProtocol, Self::OutboundProtocol, Self::InboundOpenInfo, Self::OutboundOpenInfo>, )

Implementors

impl ConnectionHandler for libp2p_swarm::dummy::ConnectionHandler

type FromBehaviour = Void

type ToBehaviour = Void

type Error = Void

type InboundProtocol = DeniedUpgrade

type OutboundProtocol = DeniedUpgrade

type InboundOpenInfo = ()

type OutboundOpenInfo = Void

impl ConnectionHandler for libp2p_swarm::keep_alive::ConnectionHandler

type FromBehaviour = Void

type ToBehaviour = Void

type Error = Void

type InboundProtocol = DeniedUpgrade

type OutboundProtocol = DeniedUpgrade

type InboundOpenInfo = ()

type OutboundOpenInfo = Void

impl ConnectionHandler for PendingConnectionHandler

type FromBehaviour = Void

type ToBehaviour = Void

type Error = Void

type InboundProtocol = PendingUpgrade<String>

type OutboundProtocol = PendingUpgrade<String>

type OutboundOpenInfo = Void

type InboundOpenInfo = ()

impl<K, H> ConnectionHandler for MultiHandler<K, H>

where K: Clone + Debug + Hash + Eq + Send + 'static, H: ConnectionHandler, H::InboundProtocol: InboundUpgradeSend, H::OutboundProtocol: OutboundUpgradeSend,

type FromBehaviour = (K, <H as ConnectionHandler>::FromBehaviour)

type ToBehaviour = (K, <H as ConnectionHandler>::ToBehaviour)

type Error = <H as ConnectionHandler>::Error

type InboundProtocol = Upgrade<K, <H as ConnectionHandler>::InboundProtocol>

type OutboundProtocol = <H as ConnectionHandler>::OutboundProtocol

type InboundOpenInfo = Info<K, <H as ConnectionHandler>::InboundOpenInfo>

type OutboundOpenInfo = (K, <H as ConnectionHandler>::OutboundOpenInfo)

impl<TConnectionHandler, TMap, TNewIn> ConnectionHandler for MapInEvent<TConnectionHandler, TNewIn, TMap>

where TConnectionHandler: ConnectionHandler, TMap: Fn(TNewIn) -> Option<TConnectionHandler::FromBehaviour> + Send + 'static, TNewIn: Debug + Send + 'static,

type FromBehaviour = TNewIn

type ToBehaviour = <TConnectionHandler as ConnectionHandler>::ToBehaviour

type Error = <TConnectionHandler as ConnectionHandler>::Error

type InboundProtocol = <TConnectionHandler as ConnectionHandler>::InboundProtocol

type OutboundProtocol = <TConnectionHandler as ConnectionHandler>::OutboundProtocol

type InboundOpenInfo = <TConnectionHandler as ConnectionHandler>::InboundOpenInfo

type OutboundOpenInfo = <TConnectionHandler as ConnectionHandler>::OutboundOpenInfo

impl<TConnectionHandler, TMap, TNewOut> ConnectionHandler for MapOutEvent<TConnectionHandler, TMap>

where TConnectionHandler: ConnectionHandler, TMap: FnMut(TConnectionHandler::ToBehaviour) -> TNewOut + Send + 'static, TNewOut: Debug + Send + 'static,

type FromBehaviour = <TConnectionHandler as ConnectionHandler>::FromBehaviour

type ToBehaviour = TNewOut

type Error = <TConnectionHandler as ConnectionHandler>::Error

type InboundProtocol = <TConnectionHandler as ConnectionHandler>::InboundProtocol

type OutboundProtocol = <TConnectionHandler as ConnectionHandler>::OutboundProtocol

type InboundOpenInfo = <TConnectionHandler as ConnectionHandler>::InboundOpenInfo

type OutboundOpenInfo = <TConnectionHandler as ConnectionHandler>::OutboundOpenInfo

impl<TInbound, TOutbound, TEvent> ConnectionHandler for OneShotHandler<TInbound, TOutbound, TEvent>

where TInbound: InboundUpgradeSend + Send + 'static, TOutbound: Debug + OutboundUpgradeSend, TInbound::Output: Into<TEvent>, TOutbound::Output: Into<TEvent>, TOutbound::Error: Error + Send + 'static, SubstreamProtocol<TInbound, ()>: Clone, TEvent: Debug + Send + 'static,

type FromBehaviour = TOutbound

type ToBehaviour = TEvent

type Error = StreamUpgradeError<<<OneShotHandler<TInbound, TOutbound, TEvent> as ConnectionHandler>::OutboundProtocol as OutboundUpgradeSend>::Error>

type InboundProtocol = TInbound

type OutboundProtocol = TOutbound

type OutboundOpenInfo = ()

type InboundOpenInfo = ()

impl<TInner> ConnectionHandler for ToggleConnectionHandler<TInner>

where TInner: ConnectionHandler,

type FromBehaviour = <TInner as ConnectionHandler>::FromBehaviour

type ToBehaviour = <TInner as ConnectionHandler>::ToBehaviour

type Error = <TInner as ConnectionHandler>::Error

type InboundProtocol = Either<SendWrapper<<TInner as ConnectionHandler>::InboundProtocol>, SendWrapper<DeniedUpgrade>>

type OutboundProtocol = <TInner as ConnectionHandler>::OutboundProtocol

type OutboundOpenInfo = <TInner as ConnectionHandler>::OutboundOpenInfo

type InboundOpenInfo = Either<<TInner as ConnectionHandler>::InboundOpenInfo, ()>

impl<TProto1, TProto2> ConnectionHandler for ConnectionHandlerSelect<TProto1, TProto2>

where TProto1: ConnectionHandler, TProto2: ConnectionHandler,

type FromBehaviour = Either<<TProto1 as ConnectionHandler>::FromBehaviour, <TProto2 as ConnectionHandler>::FromBehaviour>

type ToBehaviour = Either<<TProto1 as ConnectionHandler>::ToBehaviour, <TProto2 as ConnectionHandler>::ToBehaviour>

type Error = Either<<TProto1 as ConnectionHandler>::Error, <TProto2 as ConnectionHandler>::Error>

type InboundProtocol = SelectUpgrade<SendWrapper<<TProto1 as ConnectionHandler>::InboundProtocol>, SendWrapper<<TProto2 as ConnectionHandler>::InboundProtocol>>

type OutboundProtocol = Either<SendWrapper<<TProto1 as ConnectionHandler>::OutboundProtocol>, SendWrapper<<TProto2 as ConnectionHandler>::OutboundProtocol>>

type OutboundOpenInfo = Either<<TProto1 as ConnectionHandler>::OutboundOpenInfo, <TProto2 as ConnectionHandler>::OutboundOpenInfo>

type InboundOpenInfo = (<TProto1 as ConnectionHandler>::InboundOpenInfo, <TProto2 as ConnectionHandler>::InboundOpenInfo)