[−][src]Trait libp2p_core::transport::Transport
A transport provides connection-oriented communication between two peers through ordered streams of data (i.e. connections).
Connections are established either by listening
or dialing on a Transport
. A peer that
obtains a connection by listening is often referred to as the listener and the
peer that initiated the connection through dialing as the dialer, in
contrast to the traditional roles of server and client.
Most transports also provide a form of reliable delivery on the established connections but the precise semantics of these guarantees depend on the specific transport.
This trait is implemented for concrete connection-oriented transport protocols like TCP or Unix Domain Sockets, but also on wrappers that add additional functionality to the dialing or listening process (e.g. name resolution via the DNS).
Additional protocols can be layered on top of the connections established
by a Transport
through an upgrade mechanism that is initiated via
with_upgrade
and optionally followed by further upgrades
through chaining calls to with_upgrade
and
and_then
. Thereby every upgrade yields a new Transport
whose connection setup incorporates all earlier upgrades followed by the new upgrade,
i.e. the order of the upgrades is significant.
Note: The methods of this trait use
self
and not&self
or&mut self
. In other words, listening or dialing consumes the transport object. This has been designed so that you would implement this trait on&Foo
or&mut Foo
instead of directly onFoo
.
Associated Types
type Output
The result of a connection setup process, including protocol upgrades.
Typically the output contains at least a handle to a data stream (i.e. a connection or a substream multiplexer on top of a connection) that provides APIs for sending and receiving data through the connection.
type Error: Error
An error that occurred during connection setup.
type Listener: Stream<Item = ListenerEvent<Self::ListenerUpgrade>, Error = Self::Error>
A stream of Output
s for inbound connections.
An item should be produced whenever a connection is received at the lowest level of the
transport stack. The item must be a ListenerUpgrade
future
that resolves to an Output
value once all protocol upgrades
have been applied.
type ListenerUpgrade: Future<Item = Self::Output, Error = Self::Error>
A pending Output
for an inbound connection,
obtained from the Listener
stream.
After a connection has been accepted by the transport, it may need to go through
asynchronous post-processing (i.e. protocol upgrade negotiations). Such
post-processing should not block the Listener
from producing the next
connection, hence further connection setup proceeds asynchronously.
Once a ListenerUpgrade
future resolves it yields the Output
of the connection setup process.
type Dial: Future<Item = Self::Output, Error = Self::Error>
Required methods
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>> where
Self: Sized,
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>> where
Self: Sized,
Listens on the given Multiaddr
, producing a stream of pending, inbound connections
and addresses this transport is listening on (cf. ListenerEvent
).
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>> where
Self: Sized,
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>> where
Self: Sized,
Dials the given Multiaddr
, returning a future for a pending outbound connection.
If TransportError::MultiaddrNotSupported
is returned, it may be desirable to
try an alternative Transport
, if available.
Provided methods
fn boxed(self) -> Boxed<Self::Output, Self::Error> where
Self: Sized + Clone + Send + Sync + 'static,
Self::Dial: Send + 'static,
Self::Listener: Send + 'static,
Self::ListenerUpgrade: Send + 'static,
Self: Sized + Clone + Send + Sync + 'static,
Self::Dial: Send + 'static,
Self::Listener: Send + 'static,
Self::ListenerUpgrade: Send + 'static,
Turns this Transport
into an abstract boxed transport.
fn map<F, O>(self, map: F) -> Map<Self, F> where
Self: Sized,
F: FnOnce(Self::Output, ConnectedPoint) -> O + Clone,
Self: Sized,
F: FnOnce(Self::Output, ConnectedPoint) -> O + Clone,
Applies a function on the connections created by the transport.
fn map_err<F, TNewErr>(self, map_err: F) -> MapErr<Self, F> where
Self: Sized,
F: FnOnce(Self::Error) -> TNewErr + Clone,
Self: Sized,
F: FnOnce(Self::Error) -> TNewErr + Clone,
Applies a function on the errors generated by the futures of the transport.
fn or_transport<T>(self, other: T) -> OrTransport<Self, T> where
Self: Sized,
Self: Sized,
Builds a new transport that falls back to another transport when encountering errors on dialing or listening for connections.
The returned transport will act like self
, except that if listen_on
or dial
return an error then other
will be tried.
fn with_upgrade<U, O, E>(self, upgrade: U) -> Upgrade<Self, U> where
Self: Sized,
Self::Output: AsyncRead + AsyncWrite,
U: InboundUpgrade<Self::Output, Output = O, Error = E>,
U: OutboundUpgrade<Self::Output, Output = O, Error = E>,
Self: Sized,
Self::Output: AsyncRead + AsyncWrite,
U: InboundUpgrade<Self::Output, Output = O, Error = E>,
U: OutboundUpgrade<Self::Output, Output = O, Error = E>,
Wraps this transport inside an Upgrade
.
Whenever an inbound or outbound connection is established by this
transport, the upgrade is applied on the current state of the
connection (which may have already gone through previous upgrades)
as an upgrade::InboundUpgrade
or upgrade::OutboundUpgrade
,
respectively.
fn and_then<C, F, O>(self, upgrade: C) -> AndThen<Self, C> where
Self: Sized,
C: FnOnce(Self::Output, ConnectedPoint) -> F + Clone,
F: IntoFuture<Item = O>,
Self: Sized,
C: FnOnce(Self::Output, ConnectedPoint) -> F + Clone,
F: IntoFuture<Item = O>,
Applies a function producing an asynchronous result to every connection created by this transport.
This function can be used for ad-hoc protocol upgrades on a transport or for processing or adapting the output of an earlier upgrade before applying the next upgrade.
fn with_timeout(self, timeout: Duration) -> TransportTimeout<Self> where
Self: Sized,
Self: Sized,
Adds a timeout to the connection setup (including upgrades) for all inbound and outbound connection attempts.
fn with_outbound_timeout(self, timeout: Duration) -> TransportTimeout<Self> where
Self: Sized,
Self: Sized,
Adds a timeout to the connection setup (including upgrades) for all outbound connection attempts.
fn with_inbound_timeout(self, timeout: Duration) -> TransportTimeout<Self> where
Self: Sized,
Self: Sized,
Adds a timeout to the connection setup (including upgrades) for all inbound connection attempts.
Implementors
impl Transport for MemoryTransport
[src]
type Output = Channel<Bytes>
type Error = MemoryTransportError
type Listener = Listener
type ListenerUpgrade = FutureResult<Self::Output, Self::Error>
type Dial = DialFuture
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<DialFuture, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<DialFuture, TransportError<Self::Error>>
impl<A, B> Transport for OrTransport<A, B> where
B: Transport,
A: Transport,
[src]
B: Transport,
A: Transport,
type Output = EitherOutput<A::Output, B::Output>
type Error = EitherError<A::Error, B::Error>
type Listener = EitherListenStream<A::Listener, B::Listener>
type ListenerUpgrade = EitherFuture<A::ListenerUpgrade, B::ListenerUpgrade>
type Dial = EitherFuture<A::Dial, B::Dial>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
impl<D, U, O, TUpgrErr> Transport for Upgrade<D, U> where
D: Transport,
D::Output: AsyncRead + AsyncWrite,
D::Error: 'static,
U: InboundUpgrade<D::Output, Output = O, Error = TUpgrErr>,
U: OutboundUpgrade<D::Output, Output = O, Error = TUpgrErr> + Clone,
TUpgrErr: Error + Send + Sync + 'static,
[src]
D: Transport,
D::Output: AsyncRead + AsyncWrite,
D::Error: 'static,
U: InboundUpgrade<D::Output, Output = O, Error = TUpgrErr>,
U: OutboundUpgrade<D::Output, Output = O, Error = TUpgrErr> + Clone,
TUpgrErr: Error + Send + Sync + 'static,
type Output = O
type Error = TransportUpgradeError<D::Error, TUpgrErr>
type Listener = ListenerStream<D::Listener, U>
type ListenerUpgrade = ListenerUpgradeFuture<D::ListenerUpgrade, U>
type Dial = DialUpgradeFuture<D::Dial, U>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
impl<InnerTrans> Transport for TransportTimeout<InnerTrans> where
InnerTrans: Transport,
InnerTrans::Error: 'static,
[src]
InnerTrans: Transport,
InnerTrans::Error: 'static,
type Output = InnerTrans::Output
type Error = TransportTimeoutError<InnerTrans::Error>
type Listener = TimeoutListener<InnerTrans::Listener>
type ListenerUpgrade = TokioTimerMapErr<Timeout<InnerTrans::ListenerUpgrade>>
type Dial = TokioTimerMapErr<Timeout<InnerTrans::Dial>>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
impl<O, E> Transport for Boxed<O, E> where
E: Error,
[src]
E: Error,
type Output = O
type Error = E
type Listener = Listener<O, E>
type ListenerUpgrade = ListenerUpgrade<O, E>
type Dial = Dial<O, E>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
impl<T> Transport for OptionalTransport<T> where
T: Transport,
[src]
T: Transport,
type Output = T::Output
type Error = T::Error
type Listener = T::Listener
type ListenerUpgrade = T::ListenerUpgrade
type Dial = T::Dial
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
impl<T, C, F, O> Transport for AndThen<T, C> where
T: Transport,
C: FnOnce(T::Output, ConnectedPoint) -> F + Clone,
F: IntoFuture<Item = O>,
F::Error: Error,
[src]
T: Transport,
C: FnOnce(T::Output, ConnectedPoint) -> F + Clone,
F: IntoFuture<Item = O>,
F::Error: Error,
type Output = O
type Error = EitherError<T::Error, F::Error>
type Listener = AndThenStream<T::Listener, C>
type ListenerUpgrade = AndThenFuture<T::ListenerUpgrade, C, F::Future>
type Dial = AndThenFuture<T::Dial, C, F::Future>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
impl<T, F, D> Transport for Map<T, F> where
T: Transport,
F: FnOnce(T::Output, ConnectedPoint) -> D + Clone,
[src]
T: Transport,
F: FnOnce(T::Output, ConnectedPoint) -> D + Clone,
type Output = D
type Error = T::Error
type Listener = MapStream<T::Listener, F>
type ListenerUpgrade = MapFuture<T::ListenerUpgrade, F>
type Dial = MapFuture<T::Dial, F>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
impl<T, F, TErr> Transport for MapErr<T, F> where
T: Transport,
F: FnOnce(T::Error) -> TErr + Clone,
TErr: Error,
[src]
T: Transport,
F: FnOnce(T::Error) -> TErr + Clone,
TErr: Error,
type Output = T::Output
type Error = TErr
type Listener = MapErrListener<T, F>
type ListenerUpgrade = MapErrListenerUpgrade<T, F>
type Dial = MapErrDial<T, F>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
impl<TOut> Transport for DummyTransport<TOut>
[src]
type Output = TOut
type Error = Error
type Listener = Empty<ListenerEvent<Self::ListenerUpgrade>, Error>
type ListenerUpgrade = Empty<Self::Output, Error>
type Dial = Empty<Self::Output, Error>
fn listen_on(
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Listener, TransportError<Self::Error>>
fn dial(
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>
[src]
self,
addr: Multiaddr
) -> Result<Self::Dial, TransportError<Self::Error>>