Struct libp2p_tcp::GenTcpConfig

source · [−]

pub struct GenTcpConfig { /* private fields */ }

Expand description

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

Implementations

source

impl GenTcpConfig

source

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.

source

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

Configures the IP_TTL option for new sockets.

source

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

Configures the TCP_NODELAY option for new sockets.

source

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

Configures the listen backlog for new listen sockets.

source

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:

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

GenTcpTransport keeps track of the listen socket addresses as they are reported by polling it. It is possible to listen on multiple addresses, enabling port reuse for each, knowing exactly which listen address is reused when dialing with a specific GenTcpTransport, as in the following example:

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

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 mut tcp1 = TcpTransport::new(GenTcpConfig::new().port_reuse(true)).boxed();
tcp1.listen_on( listen_addr1.clone()).expect("listener");
match tcp1.select_next_some().await {
    TransportEvent::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 mut tcp2 = TcpTransport::new(GenTcpConfig::new().port_reuse(true)).boxed();
tcp2.listen_on( listen_addr2).expect("listener");
match tcp2.select_next_some().await {
    TransportEvent::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 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 GenTcpTransport 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.