pub trait ProtocolsHandler {
type InEvent;
type OutEvent;
type Error: Error;
type Substream: AsyncRead + AsyncWrite;
type InboundProtocol: InboundUpgrade<Self::Substream>;
type OutboundProtocol: OutboundUpgrade<Self::Substream>;
type OutboundOpenInfo;
Show 13 methods
fn listen_protocol(&self) -> Self::InboundProtocol;
fn inject_fully_negotiated_inbound(
&mut self,
protocol: <Self::InboundProtocol as InboundUpgrade<Self::Substream>>::Output
);
fn inject_fully_negotiated_outbound(
&mut self,
protocol: <Self::OutboundProtocol as OutboundUpgrade<Self::Substream>>::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 OutboundUpgrade<Self::Substream>>::Error>
);
fn inject_inbound_closed(&mut self);
fn shutdown(&mut self);
fn poll(
&mut self
) -> Poll<ProtocolsHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent>, Self::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,
{ ... }
fn into_node_handler(self) -> NodeHandlerWrapper<Self>
where
Self: Sized,
{ ... }
}
Expand description
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.
Relationship with NodeHandler
.
This trait is very similar to the NodeHandler
trait. The fundamental differences are:
- The
NodeHandler
trait gives you more control and is therefore more difficult to implement. - The
NodeHandler
trait is designed to have exclusive ownership of the connection to a node, while theProtocolsHandler
trait is designed to handle only a specific set of protocols. Two or more implementations ofProtocolsHandler
can be combined into one that supports all the protocols together, which is not possible withNodeHandler
.
Required Associated Types
sourcetype OutEvent
type OutEvent
Custom event that can be produced by the handler and that will be returned to the outside.
sourcetype Substream: AsyncRead + AsyncWrite
type Substream: AsyncRead + AsyncWrite
The type of the substream that contains the raw data.
sourcetype InboundProtocol: InboundUpgrade<Self::Substream>
type InboundProtocol: InboundUpgrade<Self::Substream>
The upgrade for the protocol or protocols handled by this handler.
sourcetype OutboundProtocol: OutboundUpgrade<Self::Substream>
type OutboundProtocol: OutboundUpgrade<Self::Substream>
The upgrade for the protocol or protocols handled by this handler.
sourcetype OutboundOpenInfo
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
sourcefn listen_protocol(&self) -> Self::InboundProtocol
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.
sourcefn inject_fully_negotiated_inbound(
&mut self,
protocol: <Self::InboundProtocol as InboundUpgrade<Self::Substream>>::Output
)
fn inject_fully_negotiated_inbound(
&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
)
sourcefn inject_event(&mut self, event: Self::InEvent)
fn inject_event(&mut self, event: Self::InEvent)
Injects an event coming from the outside in the handler.
sourcefn inject_dial_upgrade_error(
&mut self,
info: Self::OutboundOpenInfo,
error: ProtocolsHandlerUpgrErr<<Self::OutboundProtocol as OutboundUpgrade<Self::Substream>>::Error>
)
fn inject_dial_upgrade_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.
sourcefn inject_inbound_closed(&mut self)
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.
sourcefn shutdown(&mut self)
fn shutdown(&mut self)
Indicates to the node that it should shut down. After that, it is expected that poll()
returns Ready(None)
as soon as possible.
This method allows an implementation to perform a graceful shutdown of the substreams, and send back various events.
sourcefn poll(
&mut self
) -> Poll<ProtocolsHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent>, Self::Error>
fn poll(
&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(None))
, all the other handlers will receive a call toshutdown()
and will eventually be closed and destroyed.
Provided Methods
sourcefn map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap>where
Self: Sized,
TMap: Fn(&TNewIn) -> Option<&Self::InEvent>,
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.
sourcefn map_out_event<TMap, TNewOut>(self, map: TMap) -> MapOutEvent<Self, TMap>where
Self: Sized,
TMap: FnMut(Self::OutEvent) -> TNewOut,
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.
sourcefn select<TProto2>(self, other: TProto2) -> ProtocolsHandlerSelect<Self, TProto2>where
Self: Sized,
fn select<TProto2>(self, other: TProto2) -> ProtocolsHandlerSelect<Self, TProto2>where
Self: Sized,
Builds an implementation of ProtocolsHandler
that handles both this protocol and the
other one together.
sourcefn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self>where
Self: Sized,
fn into_node_handler_builder(self) -> NodeHandlerWrapperBuilder<Self>where
Self: Sized,
Creates a builder that will allow creating a NodeHandler
that handles this protocol
exclusively.
sourcefn into_node_handler(self) -> NodeHandlerWrapper<Self>where
Self: Sized,
fn into_node_handler(self) -> NodeHandlerWrapper<Self>where
Self: Sized,
Builds an implementation of NodeHandler
that handles this protocol exclusively.
Note: This is a shortcut for
self.into_node_handler_builder().build()
.