Trait libp2p_core::protocols_handler::ProtocolsHandler

source · 
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 an OutboundSubstreamRequest 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 the ProtocolsHandler trait is designed to handle only a specific set of protocols. Two or more implementations of ProtocolsHandler can be combined into one that supports all the protocols together, which is not possible with NodeHandler.

Required Associated Types

Custom event that can be received from the outside.

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

Error that can happen when polling.

The type of the substream that contains the raw data.

The upgrade for the protocol or protocols handled by this handler.

The upgrade for the protocol or protocols handled by this handler.

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

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.

Injects a fully-negotiated substream in the handler.

This method is called when a substream has been successfully opened and negotiated.

Injects an event coming from the outside in the handler.

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

Indicates to the handler that the inbound part of the muxer has been closed, and that therefore no more inbound substreams will be produced.

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.

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() returns Ok(Async::Ready(None)), all the other handlers will receive a call to shutdown() and will eventually be closed and destroyed.

Provided Methods

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

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

Builds an implementation of ProtocolsHandler that handles both this protocol and the other one together.

Creates a builder that will allow creating a NodeHandler that handles this protocol exclusively.

Builds an implementation of NodeHandler that handles this protocol exclusively.

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

Implementors