Struct libp2p_tcp::GenTcpConfig

pub struct GenTcpConfig<T> { /* fields omitted */ }

The configuration for a TCP/IP transport capability for libp2p.

A GenTcpConfig implements the Transport interface and thus is consumed on Transport::listen_on and Transport::dial. However, the config can be cheaply cloned to perform multiple such operations with the same config.

Implementations

impl<T> GenTcpConfig<T> where
    T: Provider + Send, 

pub fn new() -> Self

Creates a new configuration for a TCP/IP transport:

• Nagle's algorithm, i.e. TCP_NODELAY, is enabled. See GenTcpConfig::nodelay.
• Reuse of listening ports is disabled. See GenTcpConfig::port_reuse.
• No custom IP_TTL is set. The default of the OS TCP stack applies. See GenTcpConfig::ttl.
• The size of the listen backlog for new listening sockets is 1024. See GenTcpConfig::listen_backlog.

pub fn ttl(self, value: u32) -> Self

Configures the IP_TTL option for new sockets.

pub fn nodelay(self, value: bool) -> Self

Configures the TCP_NODELAY option for new sockets.

pub fn listen_backlog(self, backlog: u32) -> Self

Configures the listen backlog for new listen sockets.

pub fn port_reuse(self, port_reuse: bool) -> Self

Configures port reuse for local sockets, which implies reuse of listening ports for outgoing connections to enhance NAT traversal capabilities.

Please refer to e.g. RFC 4787 section 4 and 5 for some of the NAT terminology used here.

There are two main use-cases for port reuse among local sockets:

1. Creating multiple listening sockets for the same address and port to allow accepting connections on multiple threads without having to synchronise access to a single listen socket.

2. Creating outgoing connections whose local socket is bound to the same address and port as a listening socket. In the rare case of simple NATs with both endpoint-independent mapping and endpoint-independent filtering, this can on its own already permit NAT traversal by other nodes sharing the observed external address of the local node. For the common case of NATs with address-dependent or address and port-dependent filtering, port reuse for outgoing connections can facilitate further TCP hole punching techniques for NATs that perform endpoint-independent mapping. Port reuse cannot facilitate NAT traversal in the presence of "symmetric" NATs that employ both address/port-dependent mapping and filtering, unless there is some means of port prediction.

Both use-cases are enabled when port reuse is enabled, with port reuse for outgoing connections (2. above) always being implied.

Note: Due to the identification of a TCP socket by a 4-tuple of source IP address, source port, destination IP address and destination port, with port reuse enabled there can be only a single outgoing connection to a particular address and port of a peer per local listening socket address.

If enabled, the returned GenTcpConfig and all of its Clones keep track of the listen socket addresses as they are reported by polling TcpListenStreams obtained from GenTcpConfig::listen_on().

In contrast, two GenTcpConfigs constructed separately via GenTcpConfig::new() maintain these addresses independently. It is thus possible to listen on multiple addresses, enabling port reuse for each, knowing exactly which listen address is reused when dialing with a specific GenTcpConfig, as in the following example:

#[cfg(feature = "async-io")]
#[async_std::main]
async fn main() -> std::io::Result<()> {
use libp2p_tcp::TcpConfig;

let listen_addr1: Multiaddr = "/ip4/127.0.0.1/tcp/9001".parse().unwrap();
let listen_addr2: Multiaddr = "/ip4/127.0.0.1/tcp/9002".parse().unwrap();

let tcp1 = TcpConfig::new().port_reuse(true);
let mut listener1 = tcp1.clone().listen_on(listen_addr1.clone()).expect("listener");
match listener1.next().await.expect("event")? {
    ListenerEvent::NewAddress(listen_addr) => {
        println!("Listening on {:?}", listen_addr);
        let mut stream = tcp1.dial(listen_addr2.clone()).unwrap().await?;
        // `stream` has `listen_addr1` as its local socket address.
    }
    _ => {}
}

let tcp2 = TcpConfig::new().port_reuse(true);
let mut listener2 = tcp2.clone().listen_on(listen_addr2).expect("listener");
match listener2.next().await.expect("event")? {
    ListenerEvent::NewAddress(listen_addr) => {
        println!("Listening on {:?}", listen_addr);
        let mut socket = tcp2.dial(listen_addr1).unwrap().await?;
        // `stream` has `listen_addr2` as its local socket address.
    }
    _ => {}
}
Ok(())
}

If a single GenTcpConfig is used and cloned for the creation of multiple listening sockets or a wildcard listen socket address is used to listen on any interface, there can be multiple such addresses registered for port reuse. In this case, one is chosen whose IP protocol version and loopback status is the same as that of the remote address. Consequently, for maximum control of the local listening addresses and ports that are used for outgoing connections, a new GenTcpConfig should be created for each listening socket, avoiding the use of wildcard addresses which bind a socket to all network interfaces.

When this option is enabled on a unix system, the socket option SO_REUSEPORT is set, if available, to permit reuse of listening ports for multiple sockets.

Trait Implementations

impl<T: Clone> Clone for GenTcpConfig<T>

fn clone(&self) -> GenTcpConfig<T>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for GenTcpConfig<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Transport for GenTcpConfig<T> where
    T: Provider + Send + 'static,
    T::Listener: Unpin,
    T::IfWatcher: Unpin,
    T::Stream: Unpin, 

type Output = T::Stream

The result of a connection setup process, including protocol upgrades.

type Error = Error

An error that occurred during connection setup.

type Dial = Pin<Box<dyn Future<Output = Result<Self::Output, Self::Error>> + Send>>

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

type Listener = TcpListenStream<T>

A stream of Outputs for inbound connections.

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

A pending Output for an inbound connection, obtained from the Listener stream.

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

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

Dials the given [Multiaddr], returning a future for a pending outbound connection.

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

When port reuse is disabled and hence ephemeral local ports are used for outgoing connections, the returned address is the observed address with the port replaced by the port of the listen address.

If port reuse is enabled, Some(observed) is returned, as there is a chance that the observed address and port are reachable for other peers if there is a NAT in the way that does endpoint- independent filtering. Furthermore, even if that is not the case and TCP hole punching techniques must be used for NAT traversal, the observed address is still the one that a remote should connect to for the purpose of the hole punching procedure, as it represents the mapped IP and port of the NAT device in front of the local node.

None is returned if one of the given addresses is not a TCP/IP address.

pub fn boxed(self) -> Boxed<Self::Output> where
    Self: Transport + Clone + Send + Sync + 'static,
    Self::Dial: Send,
    Self::Dial: 'static,
    Self::Listener: Send,
    Self::Listener: 'static,
    Self::ListenerUpgrade: Send,
    Self::ListenerUpgrade: 'static,
    Self::Error: Send,
    Self::Error: Sync, 

Boxes the transport, including custom transport errors.

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

Applies a function on the connections created by the transport.

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

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

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

Adds a fallback transport that is used when encountering errors while establishing inbound or outbound connections.

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

Applies a function producing an asynchronous result to every connection created by this transport.

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

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