Struct libp2p_tcp::GenTcpConfig

source · [−]
pub struct GenTcpConfig<T> { /* private fields */ }
Expand description

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

Creates a new configuration for a TCP/IP transport:

Configures the IP_TTL option for new sockets.

Configures the TCP_NODELAY option for new sockets.

Configures the listen backlog for new listen sockets.

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

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.

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

An error that occurred during connection setup.

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

A stream of Outputs for inbound connections. Read more

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

Listens on the given Multiaddr, producing a stream of pending, inbound connections and addresses this transport is listening on (cf. ListenerEvent). Read more

Dials the given Multiaddr, returning a future for a pending outbound connection. Read more

Boxes the transport, including custom transport errors.

Applies a function on the connections created by the transport.

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

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

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

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

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.