Trait libp2p_swarm::handler::ConnectionHandler
source · pub trait ConnectionHandler: Send + 'static {
type InEvent: Debug + Send + 'static;
type OutEvent: Debug + Send + 'static;
type Error: Error + Debug + Send + 'static;
type InboundProtocol: InboundUpgradeSend;
type OutboundProtocol: OutboundUpgradeSend;
type InboundOpenInfo: Send + 'static;
type OutboundOpenInfo: Send + 'static;
Show 14 methods
// Required methods
fn listen_protocol(
&self
) -> SubstreamProtocol<Self::InboundProtocol, Self::InboundOpenInfo>;
fn connection_keep_alive(&self) -> KeepAlive;
fn poll(
&mut self,
cx: &mut Context<'_>
) -> Poll<ConnectionHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent, Self::Error>>;
// Provided methods
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_address_change(&mut self, new_address: &Multiaddr) { ... }
fn inject_dial_upgrade_error(
&mut self,
info: Self::OutboundOpenInfo,
error: ConnectionHandlerUpgrErr<<Self::OutboundProtocol as OutboundUpgradeSend>::Error>
) { ... }
fn inject_listen_upgrade_error(
&mut self,
info: Self::InboundOpenInfo,
error: ConnectionHandlerUpgrErr<<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
) -> ConnectionHandlerSelect<Self, TProto2>
where Self: Sized { ... }
fn on_behaviour_event(&mut self, _event: Self::InEvent) { ... }
fn on_connection_event(
&mut self,
_event: ConnectionEvent<'_, Self::InboundProtocol, Self::OutboundProtocol, Self::InboundOpenInfo, Self::OutboundOpenInfo>
) { ... }
}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:
-
Dialing by initiating a new outbound substream. In order to do so,
ConnectionHandler::poll()must return anConnectionHandlerEvent::OutboundSubstreamRequest, providing an instance oflibp2p_core::upgrade::OutboundUpgradethat is used to negotiate the protocol(s). Upon success,ConnectionHandler::on_connection_eventis called withConnectionEvent::FullyNegotiatedOutboundtranslating the final output of the upgrade. -
Listening by accepting a new inbound substream. When a new inbound substream is created on a connection,
ConnectionHandler::listen_protocolis called to obtain an instance oflibp2p_core::upgrade::InboundUpgradethat is used to negotiate the protocol(s). Upon success,ConnectionHandler::on_connection_eventis called withConnectionEvent::FullyNegotiatedInboundtranslating the final output of the upgrade.
Connection Keep-Alive
A ConnectionHandler can influence the lifetime of the underlying connection
through ConnectionHandler::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§
sourcetype OutEvent: Debug + Send + 'static
type OutEvent: Debug + Send + 'static
Custom event that can be produced by the handler and that will be returned to the outside.
sourcetype Error: Error + Debug + Send + 'static
type Error: Error + Debug + Send + 'static
The type of errors returned by ConnectionHandler::poll.
sourcetype InboundProtocol: InboundUpgradeSend
type InboundProtocol: InboundUpgradeSend
The inbound upgrade for the protocol(s) used by the handler.
sourcetype OutboundProtocol: OutboundUpgradeSend
type OutboundProtocol: OutboundUpgradeSend
The outbound upgrade for the protocol(s) used by the handler.
sourcetype InboundOpenInfo: Send + 'static
type InboundOpenInfo: Send + 'static
The type of additional information returned from listen_protocol.
sourcetype OutboundOpenInfo: Send + 'static
type OutboundOpenInfo: Send + 'static
The type of additional information passed to an OutboundSubstreamRequest.
Required Methods§
sourcefn listen_protocol(
&self
) -> SubstreamProtocol<Self::InboundProtocol, Self::InboundOpenInfo>
fn listen_protocol( &self ) -> SubstreamProtocol<Self::InboundProtocol, Self::InboundOpenInfo>
The InboundUpgrade to apply on inbound
substreams to negotiate the desired protocols.
Note: The returned
InboundUpgradeshould 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.
sourcefn connection_keep_alive(&self) -> KeepAlive
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
ConnectionHandler::poll to determine if the connection and the associated
ConnectionHandlers 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
ConnectionHandler::pollreturns an error. Furthermore, the connection may be closed for reasons outside of the control of the handler.
sourcefn poll(
&mut self,
cx: &mut Context<'_>
) -> Poll<ConnectionHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent, Self::Error>>
fn poll( &mut self, cx: &mut Context<'_> ) -> Poll<ConnectionHandlerEvent<Self::OutboundProtocol, Self::OutboundOpenInfo, Self::OutEvent, Self::Error>>
Should behave like Stream::poll().
Provided Methods§
sourcefn inject_fully_negotiated_inbound(
&mut self,
protocol: <Self::InboundProtocol as InboundUpgradeSend>::Output,
info: Self::InboundOpenInfo
)
fn inject_fully_negotiated_inbound( &mut self, protocol: <Self::InboundProtocol as InboundUpgradeSend>::Output, info: Self::InboundOpenInfo )
ConnectionEvent::FullyNegotiatedInbound on ConnectionHandler::on_connection_event instead.
The default implemention of this inject_* method delegates to it.Injects the output of a successful upgrade on a new inbound substream.
Note that it is up to the ConnectionHandler implementation to manage the lifetime of the
negotiated inbound substreams. E.g. the implementation has to enforce a limit on the number
of simultaneously open negotiated inbound substreams. In other words it is up to the
ConnectionHandler implementation to stop a malicious remote node to open and keep alive
an excessive amount of inbound substreams.
sourcefn inject_fully_negotiated_outbound(
&mut self,
protocol: <Self::OutboundProtocol as OutboundUpgradeSend>::Output,
info: Self::OutboundOpenInfo
)
fn inject_fully_negotiated_outbound( &mut self, protocol: <Self::OutboundProtocol as OutboundUpgradeSend>::Output, info: Self::OutboundOpenInfo )
ConnectionEvent::FullyNegotiatedOutbound on ConnectionHandler::on_connection_event instead.
The default implemention of this inject_* method delegates to it.Injects the output of a successful upgrade on a new outbound substream.
The second argument is the information that was previously passed to
ConnectionHandlerEvent::OutboundSubstreamRequest.
sourcefn inject_event(&mut self, event: Self::InEvent)
fn inject_event(&mut self, event: Self::InEvent)
ConnectionHandler::on_behaviour_event instead. The default implementation of inject_event delegates to it.Injects an event coming from the outside in the handler.
sourcefn inject_address_change(&mut self, new_address: &Multiaddr)
fn inject_address_change(&mut self, new_address: &Multiaddr)
ConnectionEvent::AddressChange on ConnectionHandler::on_connection_event instead.
The default implemention of this inject_* method delegates to it.Notifies the handler of a change in the address of the remote.
sourcefn inject_dial_upgrade_error(
&mut self,
info: Self::OutboundOpenInfo,
error: ConnectionHandlerUpgrErr<<Self::OutboundProtocol as OutboundUpgradeSend>::Error>
)
fn inject_dial_upgrade_error( &mut self, info: Self::OutboundOpenInfo, error: ConnectionHandlerUpgrErr<<Self::OutboundProtocol as OutboundUpgradeSend>::Error> )
ConnectionEvent::DialUpgradeError on ConnectionHandler::on_connection_event instead.
The default implemention of this inject_* method delegates to it.Indicates to the handler that upgrading an outbound substream to the given protocol has failed.
sourcefn inject_listen_upgrade_error(
&mut self,
info: Self::InboundOpenInfo,
error: ConnectionHandlerUpgrErr<<Self::InboundProtocol as InboundUpgradeSend>::Error>
)
fn inject_listen_upgrade_error( &mut self, info: Self::InboundOpenInfo, error: ConnectionHandlerUpgrErr<<Self::InboundProtocol as InboundUpgradeSend>::Error> )
ConnectionEvent::ListenUpgradeError on ConnectionHandler::on_connection_event instead.
The default implemention of this inject_* method delegates to it.Indicates to the handler that upgrading an inbound substream to the given protocol has failed.
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
) -> ConnectionHandlerSelect<Self, TProto2>where
Self: Sized,
fn select<TProto2>( self, other: TProto2 ) -> ConnectionHandlerSelect<Self, TProto2>where Self: Sized,
Creates a new ConnectionHandler that selects either this handler or
other by delegating methods calls appropriately.
Note: The largest
KeepAlivereturned by the two handlers takes precedence, i.e. is returned fromConnectionHandler::connection_keep_aliveby the returned handler.
sourcefn on_behaviour_event(&mut self, _event: Self::InEvent)
fn on_behaviour_event(&mut self, _event: Self::InEvent)
Informs the handler about an event from the NetworkBehaviour.
fn on_connection_event( &mut self, _event: ConnectionEvent<'_, Self::InboundProtocol, Self::OutboundProtocol, Self::InboundOpenInfo, Self::OutboundOpenInfo> )
Implementations on Foreign Types§
source§impl<L, R> ConnectionHandler for Either<L, R>where
L: ConnectionHandler,
R: ConnectionHandler,
impl<L, R> ConnectionHandler for Either<L, R>where L: ConnectionHandler, R: ConnectionHandler,
Implementation of a ConnectionHandler that represents either of two ConnectionHandler
implementations.