[−][src]Trait libp2p_core::protocols_handler::ProtocolsHandler

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;
    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 connection_keep_alive(&self) -> bool;

    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,
    { ... }
}

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.

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.

Loading content...

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
)

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
)

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>
)

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>

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

Loading content...

Provided methods

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.

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.

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.

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.

fn into_node_handler(self) -> NodeHandlerWrapper<Self> where
    Self: Sized, 

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<TProtoHandler, TMap, TNewIn> ProtocolsHandler for MapInEvent<TProtoHandler, TNewIn, TMap> where
    TProtoHandler: ProtocolsHandler,
    TMap: Fn(TNewIn) -> Option<TProtoHandler::InEvent>, 
[src]

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 map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where
    Self: Sized,
    TMap: Fn(&TNewIn) -> Option<&Self::InEvent>, 
[src]

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

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

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

fn into_node_handler(self) -> NodeHandlerWrapper<Self> where
    Self: Sized, 
[src]

Deprecated:

Use into_node_handler_builder instead

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

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 map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where
    Self: Sized,
    TMap: Fn(&TNewIn) -> Option<&Self::InEvent>, 
[src]

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

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

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

fn into_node_handler(self) -> NodeHandlerWrapper<Self> where
    Self: Sized, 
[src]

Deprecated:

Use into_node_handler_builder instead

impl<TSubstream> ProtocolsHandler for DummyProtocolsHandler<TSubstream> where
    TSubstream: AsyncRead + AsyncWrite, 
[src]

type InEvent = Void

type OutEvent = Void

type Error = Void

type Substream = TSubstream

type InboundProtocol = DeniedUpgrade

type OutboundProtocol = DeniedUpgrade

type OutboundOpenInfo = Void

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

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

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

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

fn into_node_handler(self) -> NodeHandlerWrapper<Self> where
    Self: Sized, 
[src]

Deprecated:

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]

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 map_in_event<TNewIn, TMap>(self, map: TMap) -> MapInEvent<Self, TNewIn, TMap> where
    Self: Sized,
    TMap: Fn(&TNewIn) -> Option<&Self::InEvent>, 
[src]

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

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

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

fn into_node_handler(self) -> NodeHandlerWrapper<Self> where
    Self: Sized, 
[src]

Deprecated:

Use into_node_handler_builder instead

Loading content...