pub trait Transport {
    type Output;
    type Error: Error;
    type ListenerUpgrade: Future<Output = Result<Self::Output, Self::Error>>;
    type Dial: Future<Output = Result<Self::Output, Self::Error>>;

    // Required methods
    fn listen_on(
        &mut self,
        addr: Multiaddr
    ) -> Result<ListenerId, TransportError<Self::Error>>;
    fn remove_listener(&mut self, id: ListenerId) -> bool;
    fn dial(
        &mut self,
        addr: Multiaddr
    ) -> Result<Self::Dial, TransportError<Self::Error>>;
    fn dial_as_listener(
        &mut self,
        addr: Multiaddr
    ) -> Result<Self::Dial, TransportError<Self::Error>>;
    fn poll(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>
    ) -> Poll<TransportEvent<Self::ListenerUpgrade, Self::Error>>;
    fn address_translation(
        &self,
        listen: &Multiaddr,
        observed: &Multiaddr
    ) -> Option<Multiaddr>;

    // Provided methods
    fn boxed(self) -> Boxed<Self::Output>
       where Self: Sized + Send + Unpin + 'static,
             Self::Dial: 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 { ... }
    fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
       where Self: Sized,
             F: FnOnce(Self::Error) -> E { ... }
    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,
             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 for implementors: Futures returned by Transport::dial should only do work once polled for the first time. E.g. in the case of TCP, connecting to the remote should not happen immediately on Transport::dial but only once the returned Future is polled. The caller of Transport::dial may call the method multiple times with a set of addresses, racing a subset of the returned dials to success concurrently.

Required Associated Types§

source

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.

source

type Error: Error

An error that occurred during connection setup.

source

type ListenerUpgrade: Future<Output = Result<Self::Output, Self::Error>>

A pending Output for an inbound connection, obtained from the Transport 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.

source

type Dial: Future<Output = Result<Self::Output, Self::Error>>

A pending Output for an outbound connection, obtained from dialing.

Required Methods§

source

fn listen_on( &mut self, addr: Multiaddr ) -> Result<ListenerId, TransportError<Self::Error>>

Listens on the given Multiaddr for inbound connections.

source

fn remove_listener(&mut self, id: ListenerId) -> bool

Remove a listener.

Return true if there was a listener with this Id, false otherwise.

source

fn dial( &mut self, addr: Multiaddr ) -> Result<Self::Dial, TransportError<Self::Error>>

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.

source

fn dial_as_listener( &mut self, addr: Multiaddr ) -> Result<Self::Dial, TransportError<Self::Error>>

As Transport::dial but has the local node act as a listener on the outgoing connection.

This option is needed for NAT and firewall hole punching.

See ConnectedPoint::Dialer for related option.

source

fn poll( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<TransportEvent<Self::ListenerUpgrade, Self::Error>>

Poll for TransportEvents.

A TransportEvent::Incoming 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.

Transports are expected to produce TransportEvent::Incoming events only for listen addresses which have previously been announced via a TransportEvent::NewAddress event and which have not been invalidated by an TransportEvent::AddressExpired event yet.

source

fn address_translation( &self, listen: &Multiaddr, observed: &Multiaddr ) -> Option<Multiaddr>

Performs a transport-specific mapping of an address observed by a remote onto a local listen address to yield an address for the local node that may be reachable for other peers.

This is relevant for transports where Network Address Translation (NAT) can occur so that e.g. the peer is observed at a different IP than the IP of the local listening address. See also address_translation.

Within libp2p::Swarm this is used when extending the listening addresses of the local peer with external addresses observed by remote peers. On transports where this is not relevant (i.e. no NATs are present) None should be returned for the sake of de-duplication.

Note: if the listen or observed address is not a valid address of this transport, None should be returned as well.

Provided Methods§

source

fn boxed(self) -> Boxed<Self::Output>where Self: Sized + Send + Unpin + 'static, Self::Dial: Send + 'static, Self::ListenerUpgrade: Send + 'static, Self::Error: Send + Sync,

Boxes the transport, including custom transport errors.

source

fn map<F, O>(self, f: F) -> Map<Self, F>where Self: Sized, F: FnOnce(Self::Output, ConnectedPoint) -> O,

Applies a function on the connections created by the transport.

source

fn map_err<F, E>(self, f: F) -> MapErr<Self, F>where Self: Sized, F: FnOnce(Self::Error) -> E,

Applies a function on the errors generated by the futures of the transport.

source

fn or_transport<U>(self, other: U) -> OrTransport<Self, U>where Self: Sized, U: Transport, <U as Transport>::Error: 'static,

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.

source

fn and_then<C, F, O>(self, f: C) -> AndThen<Self, C>where Self: Sized, C: FnOnce(Self::Output, ConnectedPoint) -> F, F: TryFuture<Ok = O>, <F as TryFuture>::Error: Error + 'static,

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.

source

fn upgrade(self, version: Version) -> Builder<Self>where Self: Sized, Self::Error: 'static,

Begins a series of protocol upgrades via an upgrade::Builder.

Implementors§

source§

impl Transport for MemoryTransport

source§

impl<A, B> Transport for EitherTransport<A, B>where B: Transport, A: Transport,

source§

impl<A, B> Transport for OrTransport<A, B>where B: Transport, A: Transport,

source§

impl<InnerTrans> Transport for TransportTimeout<InnerTrans>where InnerTrans: Transport, InnerTrans::Error: 'static,

§

type Output = <InnerTrans as Transport>::Output

§

type Error = TransportTimeoutError<<InnerTrans as Transport>::Error>

§

type ListenerUpgrade = Timeout<<InnerTrans as Transport>::ListenerUpgrade>

§

type Dial = Timeout<<InnerTrans as Transport>::Dial>

source§

impl<O> Transport for Boxed<O>

§

type Output = O

§

type Error = Error

§

type ListenerUpgrade = Pin<Box<dyn Future<Output = Result<O, Error>> + Send, Global>>

§

type Dial = Pin<Box<dyn Future<Output = Result<O, Error>> + Send, Global>>

source§

impl<T> Transport for OptionalTransport<T>where T: Transport,

source§

impl<T> Transport for Multiplexed<T>where T: Transport,

source§

impl<T, C, D, U, E> Transport for Upgrade<T, U>where T: Transport<Output = (PeerId, C)>, T::Error: 'static, C: AsyncRead + AsyncWrite + Unpin, U: InboundUpgrade<Negotiated<C>, Output = D, Error = E> + OutboundUpgrade<Negotiated<C>, Output = D, Error = E> + Clone, E: Error + 'static,

source§

impl<T, C, F, O> Transport for AndThen<T, C>where T: Transport, C: FnOnce(T::Output, ConnectedPoint) -> F + Clone, F: TryFuture<Ok = O>, F::Error: Error,

source§

impl<T, F, D> Transport for Map<T, F>where T: Transport, F: FnOnce(T::Output, ConnectedPoint) -> D + Clone,

source§

impl<T, F, TErr> Transport for MapErr<T, F>where T: Transport, F: FnOnce(T::Error) -> TErr + Clone, TErr: Error,

§

type Output = <T as Transport>::Output

§

type Error = TErr

§

type ListenerUpgrade = MapErrListenerUpgrade<T, F>

§

type Dial = MapErrDial<T, F>

source§

impl<TOut> Transport for DummyTransport<TOut>