Trait ProtocolsHandler

Source
pub trait ProtocolsHandler: Send + 'static {
    type InEvent: Send + 'static;
    type OutEvent: Send + 'static;
    type Error: Error + Send + 'static;
    type InboundProtocol: InboundUpgradeSend;
    type OutboundProtocol: OutboundUpgradeSend;
    type InboundOpenInfo: Send + 'static;
    type OutboundOpenInfo: Send + 'static;

Show 13 methods // Required methods fn listen_protocol( &self, ) -> SubstreamProtocol<Self::InboundProtocol, Self::InboundOpenInfo>; fn inject_fully_negotiated_inbound( &mut self, protocol: <Self::InboundProtocol as InboundUpgradeSend>::Output, info: Self::InboundOpenInfo, ); 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>>; // Provided methods fn inject_address_change(&mut self, _new_address: &Multiaddr) { ... } fn inject_listen_upgrade_error( &mut self, _: Self::InboundOpenInfo, _: ProtocolsHandlerUpgrErr<<Self::InboundProtocol as InboundUpgradeSend>::Error>, ) { ... } fn map_in_event<TNewIn, TMap>( self, map: TMap, ) -> MapInEvent<Self, TNewIn, TMap> where Self: Sized, TMap: Fn(&TNewIn) -> Option<&Self::InEvent> { ... } fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap> where Self: Sized, TMap: FnMut(Self::OutEvent) -> TNewOut { ... } fn select<TProto2>( self, other: TProto2, ) -> ProtocolsHandlerSelect<Self, TProto2> where Self: Sized { ... } fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self> where Self: Sized { ... }
}
Expand description

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

Required Associated Types§

Source

type InEvent: Send + 'static

Custom event that can be received from the outside.

Source

type OutEvent: Send + 'static

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

Source

type Error: Error + Send + 'static

The type of errors returned by ProtocolsHandler::poll.

Source

type InboundProtocol: InboundUpgradeSend

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

Source

type OutboundProtocol: OutboundUpgradeSend

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

Source

type InboundOpenInfo: Send + 'static

The type of additional information returned from listen_protocol.

Source

type OutboundOpenInfo: Send + 'static

The type of additional information passed to an OutboundSubstreamRequest.

Required Methods§

Source

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.

Source

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

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

Source

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.

Source

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

Injects an event coming from the outside in the handler.

Source

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

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

Source

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.

Source

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

Should behave like Stream::poll().

Provided Methods§

Source

fn inject_address_change(&mut self, _new_address: &Multiaddr)

Notifies the handler of a change in the address of the remote.

Source

fn inject_listen_upgrade_error( &mut self, _: Self::InboundOpenInfo, _: ProtocolsHandlerUpgrErr<<Self::InboundProtocol as InboundUpgradeSend>::Error>, )

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

Source

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

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

Source

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

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

Source

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

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.

Source

fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self>
where Self: Sized,

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

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

Implementors§

Source§

impl ProtocolsHandler for DummyProtocolsHandler

Source§

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

Source§

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

Source§

impl<TInner> ProtocolsHandler for ToggleProtoHandler<TInner>
where TInner: ProtocolsHandler,

Source§

impl<TProto1, TProto2> ProtocolsHandler for ProtocolsHandlerSelect<TProto1, TProto2>
where TProto1: ProtocolsHandler, TProto2: ProtocolsHandler,

Source§

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

Source§

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