[−][src]Trait libp2p::swarm::protocols_handler::ProtocolsHandler

pub trait ProtocolsHandler: 'static + Send {
    type InEvent: 'static + Send;
    type OutEvent: 'static + Send;
    type Error: 'static + Error + Send;
    type InboundProtocol: 'static + InboundUpgradeSend + Send;
    type OutboundProtocol: OutboundUpgradeSend;
    type OutboundOpenInfo: 'static + Send;
    fn listen_protocol(&self) -> SubstreamProtocol<Self::InboundProtocol>;

    fn inject_fully_negotiated_inbound(
        &mut self, 
        protocol: <Self::InboundProtocol as InboundUpgradeSend>::Output
    );

    fn inject_fully_negotiated_outbound(
        &mut self, 
        protocol: <Self::OutboundProtocol as OutboundUpgradeSend>::Output, 
        info: Self::OutboundOpenInfo
    );

    fn inject_event(&mut self, event: Self::InEvent);

    fn inject_dial_upgrade_error(
        &mut self, 
        info: Self::OutboundOpenInfo, 
        error: ProtocolsHandlerUpgrErr<<Self::OutboundProtocol as OutboundUpgradeSend>::Error>
    );

    fn connection_keep_alive(&self) -> KeepAlive;

    fn poll(
        &mut self, 
        cx: &mut Context
    ) -> Poll<ProtocolsHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent, Self::Error>>;

    fn map_in_event<TNewIn, TMap>(
        self, 
        map: TMap
    ) -> MapInEvent<Self, TNewIn, TMap>
    where
        TMap: Fn(&TNewIn) -> Option<&Self::InEvent>,
    { ... }

    fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap>
    where
        TMap: FnMut(Self::OutEvent) -> TNewOut,
    { ... }

    fn select<TProto2>(
        self, 
        other: TProto2
    ) -> ProtocolsHandlerSelect<Self, TProto2> { ... }

    fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self> { ... }

    fn into_node_handler(self) -> NodeHandlerWrapper<Self> { ... }
}

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, [ProtocolsHandler::poll()] must return an [ProtocolsHandlerEvent::OutboundSubstreamRequest], providing an instance of libp2p_core::upgrade::OutboundUpgrade that is used to negotiate the protocol(s). Upon success, [ProtocolsHandler::inject_fully_negotiated_outbound] is called with the final output of the upgrade.

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

Connection Keep-Alive

A ProtocolsHandler can influence the lifetime of the underlying connection through [ProtocolsHandler::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.

Associated Types

type InEvent: 'static + Send

Custom event that can be received from the outside.

type OutEvent: 'static + Send

Custom event that can be produced by the handler and that will be returned to the outside.

type Error: 'static + Error + Send

The type of errors returned by [ProtocolsHandler::poll].

type InboundProtocol: 'static + InboundUpgradeSend + Send

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 OutboundOpenInfo: 'static + Send

The type of additional information passed to an OutboundSubstreamRequest.

Loading content...

Required methods

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

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 inject_fully_negotiated_inbound(
    &mut self,
    protocol: <Self::InboundProtocol as InboundUpgradeSend>::Output
)

Injects the output of a successful upgrade on a new inbound substream.

fn inject_fully_negotiated_outbound(
    &mut self,
    protocol: <Self::OutboundProtocol as OutboundUpgradeSend>::Output,
    info: Self::OutboundOpenInfo
)

Injects the output of a successful upgrade on a new outbound substream.

The second argument is the information that was previously passed to [ProtocolsHandlerEvent::OutboundSubstreamRequest].

fn inject_event(&mut self, event: Self::InEvent)

Injects an event coming from the outside in the handler.

fn inject_dial_upgrade_error(
    &mut self,
    info: Self::OutboundOpenInfo,
    error: ProtocolsHandlerUpgrErr<<Self::OutboundProtocol as OutboundUpgradeSend>::Error>
)

Indicates to the handler that upgrading a substream to the given protocol has failed.

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 [ProtocolsHandler::poll] to determine if the connection and the associated ProtocolsHandlers 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 [ProtocolsHandler::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<ProtocolsHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent, Self::Error>>

Should behave like Stream::poll().

Loading content...

Provided methods

fn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where
    TMap: Fn(&TNewIn) -> Option<&Self::InEvent>, 

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

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

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

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

Creates a new ProtocolsHandler 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 [ProtocolsHandler::connection_keep_alive] by the returned handler.

fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self>

Creates a builder that allows creating a NodeHandler that handles this protocol exclusively.

Note: This method should not be redefined in a custom ProtocolsHandler.

fn into_node_handler(self) -> NodeHandlerWrapper<Self>

Deprecated:

Use into_node_handler_builder instead

Builds an implementation of NodeHandler that handles this protocol exclusively.

Note: This is a shortcut for self.into_node_handler_builder().build().

Loading content...

Implementors

impl ProtocolsHandler for PingHandler[src]

type InEvent = Void

type OutEvent = Result<PingSuccess, PingFailure>

type Error = PingFailure

type InboundProtocol = Ping

type OutboundProtocol = Ping

type OutboundOpenInfo = ()

impl ProtocolsHandler for DummyProtocolsHandler[src]

type InEvent = Void

type OutEvent = Void

type Error = Void

type InboundProtocol = DeniedUpgrade

type OutboundProtocol = DeniedUpgrade

type OutboundOpenInfo = Void

impl<TInProto, TOutProto, TOutEvent> ProtocolsHandler for OneShotHandler<TInProto, TOutProto, TOutEvent> where
    TInProto: InboundUpgradeSend + Send + 'static,
    TOutEvent: Send + 'static,
    TOutProto: OutboundUpgradeSend,
    <TInProto as InboundUpgradeSend>::Output: Into<TOutEvent>,
    <TOutProto as OutboundUpgradeSend>::Output: Into<TOutEvent>,
    <TOutProto as OutboundUpgradeSend>::Error: Error,
    <TOutProto as OutboundUpgradeSend>::Error: Send,
    <TOutProto as OutboundUpgradeSend>::Error: 'static,
    SubstreamProtocol<TInProto>: Clone, [src]

type InEvent = TOutProto

type OutEvent = TOutEvent

type Error = ProtocolsHandlerUpgrErr<<<OneShotHandler<TInProto, TOutProto, TOutEvent> as ProtocolsHandler>::OutboundProtocol as OutboundUpgradeSend>::Error>

type InboundProtocol = TInProto

type OutboundProtocol = TOutProto

type OutboundOpenInfo = ()

impl<TInner> ProtocolsHandler for ToggleProtoHandler<TInner> where
    TInner: ProtocolsHandler, [src]

type InEvent = <TInner as ProtocolsHandler>::InEvent

type OutEvent = <TInner as ProtocolsHandler>::OutEvent

type Error = <TInner as ProtocolsHandler>::Error

type InboundProtocol = EitherUpgrade<SendWrapper<<TInner as ProtocolsHandler>::InboundProtocol>, SendWrapper<DeniedUpgrade>>

type OutboundProtocol = <TInner as ProtocolsHandler>::OutboundProtocol

type OutboundOpenInfo = <TInner as ProtocolsHandler>::OutboundOpenInfo

impl<TProto1, TProto2> ProtocolsHandler for ProtocolsHandlerSelect<TProto1, TProto2> where
    TProto1: ProtocolsHandler,
    TProto2: ProtocolsHandler, [src]

type InEvent = EitherOutput<<TProto1 as ProtocolsHandler>::InEvent, <TProto2 as ProtocolsHandler>::InEvent>

type OutEvent = EitherOutput<<TProto1 as ProtocolsHandler>::OutEvent, <TProto2 as ProtocolsHandler>::OutEvent>

type Error = EitherError<<TProto1 as ProtocolsHandler>::Error, <TProto2 as ProtocolsHandler>::Error>

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

type OutboundProtocol = EitherUpgrade<SendWrapper<<TProto1 as ProtocolsHandler>::OutboundProtocol>, SendWrapper<<TProto2 as ProtocolsHandler>::OutboundProtocol>>

type OutboundOpenInfo = EitherOutput<<TProto1 as ProtocolsHandler>::OutboundOpenInfo, <TProto2 as ProtocolsHandler>::OutboundOpenInfo>

impl<TProtoHandler, TMap, TNewIn> ProtocolsHandler for MapInEvent<TProtoHandler, TNewIn, TMap> where
    TMap: Fn(TNewIn) -> Option<<TProtoHandler as ProtocolsHandler>::InEvent> + Send + 'static,
    TNewIn: Send + 'static,
    TProtoHandler: ProtocolsHandler, [src]

type InEvent = TNewIn

type OutEvent = <TProtoHandler as ProtocolsHandler>::OutEvent

type Error = <TProtoHandler as ProtocolsHandler>::Error

type InboundProtocol = <TProtoHandler as ProtocolsHandler>::InboundProtocol

type OutboundProtocol = <TProtoHandler as ProtocolsHandler>::OutboundProtocol

type OutboundOpenInfo = <TProtoHandler as ProtocolsHandler>::OutboundOpenInfo

impl<TProtoHandler, TMap, TNewOut> ProtocolsHandler for MapOutEvent<TProtoHandler, TMap> where
    TMap: FnMut(<TProtoHandler as ProtocolsHandler>::OutEvent) -> TNewOut + Send + 'static,
    TNewOut: Send + 'static,
    TProtoHandler: ProtocolsHandler, [src]

type InEvent = <TProtoHandler as ProtocolsHandler>::InEvent

type OutEvent = TNewOut

type Error = <TProtoHandler as ProtocolsHandler>::Error

type InboundProtocol = <TProtoHandler as ProtocolsHandler>::InboundProtocol

type OutboundProtocol = <TProtoHandler as ProtocolsHandler>::OutboundProtocol

type OutboundOpenInfo = <TProtoHandler as ProtocolsHandler>::OutboundOpenInfo

impl<TUserData> ProtocolsHandler for KademliaHandler<TUserData> where
    TUserData: Clone + Send + 'static, [src]

type InEvent = KademliaHandlerIn<TUserData>

type OutEvent = KademliaHandlerEvent<TUserData>

type Error = Error

type InboundProtocol = EitherUpgrade<KademliaProtocolConfig, DeniedUpgrade>

type OutboundProtocol = KademliaProtocolConfig

type OutboundOpenInfo = (KadRequestMsg, Option<TUserData>)

Loading content...