pub trait Transport {
type Output;
type Error: Error;
type Listener: Stream<Item = Result<ListenerEvent<Self::ListenerUpgrade, Self::Error>, Self::Error>>;
type ListenerUpgrade: Future<Output = Result<Self::Output, Self::Error>>;
type Dial: Future<Output = Result<Self::Output, Self::Error>>;
// Required methods
fn listen_on(
self,
addr: Multiaddr,
) -> Result<Self::Listener, TransportError<Self::Error>>
where Self: Sized;
fn dial(
self,
addr: Multiaddr,
) -> Result<Self::Dial, TransportError<Self::Error>>
where Self: Sized;
fn address_translation(
&self,
listen: &Multiaddr,
observed: &Multiaddr,
) -> Option<Multiaddr>;
// Provided methods
fn boxed(self) -> Boxed<Self::Output>
where Self: Transport + Sized + Clone + Send + Sync + 'static,
Self::Dial: Send + 'static,
Self::Listener: Send + 'static,
Self::ListenerUpgrade: Send + 'static,
Self::Error: Send + Sync { ... }
fn map<F, O>(self, f: F) -> Map<Self, F>
where Self: Sized,
F: FnOnce(Self::Output, ConnectedPoint) -> O + Clone { ... }
fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
where Self: Sized,
F: FnOnce(Self::Error) -> E + Clone { ... }
fn or_transport<U>(self, other: U) -> OrTransport<Self, U>
where Self: Sized,
U: Transport,
<U as Transport>::Error: 'static { ... }
fn and_then<C, F, O>(self, f: C) -> AndThen<Self, C>
where Self: Sized,
C: FnOnce(Self::Output, ConnectedPoint) -> F + Clone,
F: TryFuture<Ok = O>,
<F as TryFuture>::Error: Error + 'static { ... }
fn upgrade(self, version: Version) -> Builder<Self>
where Self: Sized,
Self::Error: 'static { ... }
}Expand description
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
upgrade.
Note: The methods of this trait use
selfand not&selfor&mut self. In other words, listening or dialing consumes the transport object. This has been designed so that you would implement this trait on&Fooor&mut Fooinstead of directly onFoo.
Required Associated Types§
Sourcetype Output
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.
Sourcetype Listener: Stream<Item = Result<ListenerEvent<Self::ListenerUpgrade, Self::Error>, Self::Error>>
type Listener: Stream<Item = Result<ListenerEvent<Self::ListenerUpgrade, Self::Error>, Self::Error>>
A stream of Outputs 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.
If this stream produces an error, it is considered fatal and the listener is killed. It
is possible to report non-fatal errors by producing a ListenerEvent::Error.
Sourcetype ListenerUpgrade: Future<Output = Result<Self::Output, Self::Error>>
type ListenerUpgrade: Future<Output = Result<Self::Output, 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.
Required Methods§
Sourcefn listen_on(
self,
addr: Multiaddr,
) -> Result<Self::Listener, TransportError<Self::Error>>where
Self: Sized,
fn listen_on(
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).
Returning an error from the stream is considered fatal. The listener can also report
non-fatal errors by producing a ListenerEvent::Error.
Sourcefn dial(
self,
addr: Multiaddr,
) -> Result<Self::Dial, TransportError<Self::Error>>where
Self: Sized,
fn dial(
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§
Sourcefn map<F, O>(self, f: F) -> Map<Self, F>
fn map<F, O>(self, f: F) -> Map<Self, F>
Applies a function on the connections created by the transport.
Sourcefn map_err<F, E>(self, f: F) -> MapErr<Self, F>
fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
Applies a function on the errors generated by the futures of the transport.
Sourcefn or_transport<U>(self, other: U) -> OrTransport<Self, U>
fn or_transport<U>(self, other: U) -> OrTransport<Self, U>
Adds a fallback transport that is used when encountering errors while establishing inbound or outbound connections.
The returned transport will act like self, except that if listen_on or dial
return an error then other will be tried.
Sourcefn and_then<C, F, O>(self, f: C) -> AndThen<Self, C>
fn and_then<C, F, O>(self, f: C) -> AndThen<Self, C>
Applies a function producing an asynchronous result to every connection created by this transport.
This function can be used for ad-hoc protocol upgrades or for processing or adapting the output for following configurations.
For the high-level transport upgrade procedure, see Transport::upgrade.