[−][src]Trait libp2p_core::protocols_handler::ProtocolsHandler
Handler for a set of protocols for a specific connection with a remote.
This trait should be implemented on a struct that holds the state for a specific protocol behaviour with a specific remote.
Handling a protocol
Communication with a remote over a set of protocols opened in two different ways:
- Dialing, which is a voluntary process. In order to do so, make
poll()
return anOutboundSubstreamRequest
variant containing the connection upgrade to use to start using a protocol. - Listening, which is used to determine which protocols are supported when the remote wants
to open a substream. The
listen_protocol()
method should return the upgrades supported when listening.
The upgrade when dialing and the upgrade when listening have to be of the same type, but you
are free to return for example an OrUpgrade
enum, or an enum of your own, containing the
upgrade you want depending on the situation.
Shutting down
Implementors of this trait should keep in mind that the connection can be closed at any time.
When a connection is closed (either by us or by the remote) shutdown()
is called and the
handler continues to be processed until it produces ProtocolsHandlerEvent::Shutdown
. Only
then the handler is destroyed.
This makes it possible for the handler to finish delivering events even after knowing that it is shutting down.
Implementors of this trait should keep in mind that when shutdown()
is called, the connection
might already be closed or unresponsive. They should therefore not rely on being able to
deliver messages.
Associated Types
type InEvent
Custom event that can be received from the outside.
type OutEvent
Custom event that can be produced by the handler and that will be returned to the outside.
type Error: Error
Error that can happen when polling.
type Substream: AsyncRead + AsyncWrite
The type of the substream that contains the raw data.
type InboundProtocol: InboundUpgrade<Self::Substream>
The upgrade for the protocol or protocols handled by this handler.
type OutboundProtocol: OutboundUpgrade<Self::Substream>
The upgrade for the protocol or protocols handled by this handler.
type OutboundOpenInfo
Information about a substream. Can be sent to the handler through a NodeHandlerEndpoint
,
and will be passed back in inject_substream
or inject_outbound_closed
.
Required methods
fn listen_protocol(&self) -> Self::InboundProtocol
Produces a ConnectionUpgrade
for the protocol or protocols to accept when listening.
Note: You should always accept all the protocols you support, even if in a specific context you wouldn't accept one in particular (eg. only allow one substream at a time for a given protocol). The reason is that remotes are allowed to put the list of supported protocols in a cache in order to avoid spurious queries.
fn inject_fully_negotiated_inbound(
&mut self,
protocol: <Self::InboundProtocol as InboundUpgrade<Self::Substream>>::Output
)
&mut self,
protocol: <Self::InboundProtocol as InboundUpgrade<Self::Substream>>::Output
)
Injects a fully-negotiated substream in the handler.
This method is called when a substream has been successfully opened and negotiated.
fn inject_fully_negotiated_outbound(
&mut self,
protocol: <Self::OutboundProtocol as OutboundUpgrade<Self::Substream>>::Output,
info: Self::OutboundOpenInfo
)
&mut self,
protocol: <Self::OutboundProtocol as OutboundUpgrade<Self::Substream>>::Output,
info: Self::OutboundOpenInfo
)
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 OutboundUpgrade<Self::Substream>>::Error>
)
&mut self,
info: Self::OutboundOpenInfo,
error: ProtocolsHandlerUpgrErr<<Self::OutboundProtocol as OutboundUpgrade<Self::Substream>>::Error>
)
Indicates to the handler that upgrading a substream to the given protocol has failed.
fn inject_inbound_closed(&mut self)
Indicates to the handler that the inbound part of the muxer has been closed, and that therefore no more inbound substreams will be produced.
fn connection_keep_alive(&self) -> bool
Returns whether the connection should be kept alive.
If returns false
, that indicates that this connection is not important and the user may
invoke shutdown()
if they think that they will no longer need the connection in the
future.
On the other hand, returning true
is only an indication and doesn't mean that the user
will not call shutdown()
.
When multiple ProtocolsHandler
are combined together, they should use OR to merge the
result of this method.
The result of this method should be checked every time poll()
is invoked.
After shutdown()
is called, the result of this method doesn't matter anymore.
fn shutdown(&mut self)
Indicates to the node that it should shut down. After that, it is expected that poll()
returns Ready(ProtocolsHandlerEvent::Shutdown)
as soon as possible.
This method allows an implementation to perform a graceful shutdown of the substreams, and send back various events.
fn poll(
&mut self
) -> Poll<ProtocolsHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent>, Self::Error>
&mut self
) -> Poll<ProtocolsHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent>, Self::Error>
Should behave like Stream::poll()
. Should close if no more event can be produced and the
node should be closed.
Note: If this handler is combined with other handlers, as soon as
poll()
returnsOk(Async::Ready(ProtocolsHandlerEvent::Shutdown))
, all the other handlers will receive a call toshutdown()
and will eventually be closed and destroyed.
Provided methods
fn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where
Self: Sized,
TMap: Fn(&TNewIn) -> Option<&Self::InEvent>,
Self: Sized,
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
Self: Sized,
TMap: FnMut(Self::OutEvent) -> TNewOut,
Self: Sized,
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> where
Self: Sized,
self,
other: TProto2
) -> ProtocolsHandlerSelect<Self, TProto2> where
Self: Sized,
Builds an implementation of ProtocolsHandler
that handles both this protocol and the
other one together.
fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self> where
Self: Sized,
Self: Sized,
Creates a builder that will allow creating a NodeHandler
that handles this protocol
exclusively.
fn into_node_handler(self) -> NodeHandlerWrapper<Self> where
Self: Sized,
Self: Sized,
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()
.
Implementors
impl<TProtoHandler, TMap, TNewIn> ProtocolsHandler for MapInEvent<TProtoHandler, TNewIn, TMap> where
TProtoHandler: ProtocolsHandler,
TMap: Fn(TNewIn) -> Option<TProtoHandler::InEvent>,
[src]
impl<TProtoHandler, TMap, TNewIn> ProtocolsHandler for MapInEvent<TProtoHandler, TNewIn, TMap> where
TProtoHandler: ProtocolsHandler,
TMap: Fn(TNewIn) -> Option<TProtoHandler::InEvent>,
type InEvent = TNewIn
type OutEvent = TProtoHandler::OutEvent
type Error = TProtoHandler::Error
type Substream = TProtoHandler::Substream
type InboundProtocol = TProtoHandler::InboundProtocol
type OutboundProtocol = TProtoHandler::OutboundProtocol
type OutboundOpenInfo = TProtoHandler::OutboundOpenInfo
fn listen_protocol(&self) -> Self::InboundProtocol | [src] |
fn inject_fully_negotiated_inbound( | [src] |
fn inject_fully_negotiated_outbound( | [src] |
fn inject_event(&mut self, event: TNewIn) | [src] |
fn inject_dial_upgrade_error( | [src] |
fn inject_inbound_closed(&mut self) | [src] |
fn connection_keep_alive(&self) -> bool | [src] |
fn shutdown(&mut self) | [src] |
fn poll( | [src] |
fn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where | [src] |
fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap> where | [src] |
fn select<TProto2>( | [src] |
fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self> where | [src] |
fn into_node_handler(self) -> NodeHandlerWrapper<Self> where | [src] |
Use into_node_handler_builder instead
impl<TProtoHandler, TMap, TNewOut> ProtocolsHandler for MapOutEvent<TProtoHandler, TMap> where
TProtoHandler: ProtocolsHandler,
TMap: FnMut(TProtoHandler::OutEvent) -> TNewOut,
[src]
impl<TProtoHandler, TMap, TNewOut> ProtocolsHandler for MapOutEvent<TProtoHandler, TMap> where
TProtoHandler: ProtocolsHandler,
TMap: FnMut(TProtoHandler::OutEvent) -> TNewOut,
type InEvent = TProtoHandler::InEvent
type OutEvent = TNewOut
type Error = TProtoHandler::Error
type Substream = TProtoHandler::Substream
type InboundProtocol = TProtoHandler::InboundProtocol
type OutboundProtocol = TProtoHandler::OutboundProtocol
type OutboundOpenInfo = TProtoHandler::OutboundOpenInfo
fn listen_protocol(&self) -> Self::InboundProtocol | [src] |
fn inject_fully_negotiated_inbound( | [src] |
fn inject_fully_negotiated_outbound( | [src] |
fn inject_event(&mut self, event: Self::InEvent) | [src] |
fn inject_dial_upgrade_error( | [src] |
fn inject_inbound_closed(&mut self) | [src] |
fn connection_keep_alive(&self) -> bool | [src] |
fn shutdown(&mut self) | [src] |
fn poll( | [src] |
fn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where | [src] |
fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap> where | [src] |
fn select<TProto2>( | [src] |
fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self> where | [src] |
fn into_node_handler(self) -> NodeHandlerWrapper<Self> where | [src] |
Use into_node_handler_builder instead
impl<TSubstream> ProtocolsHandler for DummyProtocolsHandler<TSubstream> where
TSubstream: AsyncRead + AsyncWrite,
[src]
impl<TSubstream> ProtocolsHandler for DummyProtocolsHandler<TSubstream> where
TSubstream: AsyncRead + AsyncWrite,
type InEvent = Void
type OutEvent = Void
type Error = Void
type Substream = TSubstream
type InboundProtocol = DeniedUpgrade
type OutboundProtocol = DeniedUpgrade
type OutboundOpenInfo = Void
fn listen_protocol(&self) -> Self::InboundProtocol | [src] |
fn inject_fully_negotiated_inbound( | [src] |
fn inject_fully_negotiated_outbound( | [src] |
fn inject_event(&mut self, _: Self::InEvent) | [src] |
fn inject_dial_upgrade_error( | [src] |
fn inject_inbound_closed(&mut self) | [src] |
fn connection_keep_alive(&self) -> bool | [src] |
fn shutdown(&mut self) | [src] |
fn poll( | [src] |
fn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where | [src] |
fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap> where | [src] |
fn select<TProto2>( | [src] |
fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self> where | [src] |
fn into_node_handler(self) -> NodeHandlerWrapper<Self> where | [src] |
Use into_node_handler_builder instead
impl<TSubstream, TProto1, TProto2> ProtocolsHandler for ProtocolsHandlerSelect<TProto1, TProto2> where
TProto1: ProtocolsHandler<Substream = TSubstream>,
TProto2: ProtocolsHandler<Substream = TSubstream>,
TSubstream: AsyncRead + AsyncWrite,
TProto1::InboundProtocol: InboundUpgrade<TSubstream>,
TProto2::InboundProtocol: InboundUpgrade<TSubstream>,
TProto1::OutboundProtocol: OutboundUpgrade<TSubstream>,
TProto2::OutboundProtocol: OutboundUpgrade<TSubstream>,
[src]
impl<TSubstream, TProto1, TProto2> ProtocolsHandler for ProtocolsHandlerSelect<TProto1, TProto2> where
TProto1: ProtocolsHandler<Substream = TSubstream>,
TProto2: ProtocolsHandler<Substream = TSubstream>,
TSubstream: AsyncRead + AsyncWrite,
TProto1::InboundProtocol: InboundUpgrade<TSubstream>,
TProto2::InboundProtocol: InboundUpgrade<TSubstream>,
TProto1::OutboundProtocol: OutboundUpgrade<TSubstream>,
TProto2::OutboundProtocol: OutboundUpgrade<TSubstream>,
type InEvent = EitherOutput<TProto1::InEvent, TProto2::InEvent>
type OutEvent = EitherOutput<TProto1::OutEvent, TProto2::OutEvent>
type Error = EitherError<TProto1::Error, TProto2::Error>
type Substream = TSubstream
type InboundProtocol = SelectUpgrade<TProto1::InboundProtocol, TProto2::InboundProtocol>
type OutboundProtocol = EitherUpgrade<TProto1::OutboundProtocol, TProto2::OutboundProtocol>
type OutboundOpenInfo = EitherOutput<TProto1::OutboundOpenInfo, TProto2::OutboundOpenInfo>
fn listen_protocol(&self) -> Self::InboundProtocol | [src] |
fn inject_fully_negotiated_outbound( | [src] |
fn inject_fully_negotiated_inbound( | [src] |
fn inject_event(&mut self, event: Self::InEvent) | [src] |
fn inject_inbound_closed(&mut self) | [src] |
fn inject_dial_upgrade_error( | [src] |
fn connection_keep_alive(&self) -> bool | [src] |
fn shutdown(&mut self) | [src] |
fn poll( | [src] |
fn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where | [src] |
fn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap> where | [src] |
fn select<TProto2>( | [src] |
fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self> where | [src] |
fn into_node_handler(self) -> NodeHandlerWrapper<Self> where | [src] |
Use into_node_handler_builder instead