Remove background task. Enhance documentation.

To avoid spawning a background task and thread within
`TcpConfig::new()`, with communication via unbounded channels,
a `TcpConfig` now keeps track of the listening addresses
for port reuse in an `Arc<RwLock>`. Furthermore, an `IfWatcher`
is only used by a `TcpListenStream` if it listens on any interface
and directly polls the `IfWatcher` both for initialisation and
new events.

Includes some documentation and test enhancements.

Author: Roman S. Borschel

core/src/connection/listeners.rs

@@ -41,12 +41,10 @@ use std::{collections::VecDeque, fmt, pin::Pin};
 /// # Example
 ///
 /// ```no_run
-/// # #[async_std::main]
-/// # async fn main() {
 /// use futures::prelude::*;
 /// use libp2p_core::connection::{ListenersEvent, ListenersStream};
 ///
-/// let mut listeners = ListenersStream::new(libp2p_tcp::TcpConfig::new().await.unwrap());
+/// let mut listeners = ListenersStream::new(libp2p_tcp::TcpConfig::new());
 ///
 /// // Ask the `listeners` to start listening on the given multiaddress.
 /// listeners.listen_on("/ip4/0.0.0.0/tcp/0".parse().unwrap()).unwrap();
@@ -76,7 +74,6 @@ use std::{collections::VecDeque, fmt, pin::Pin};
 ///         }
 ///     }
 /// })
-/// # }
 /// ```
 pub struct ListenersStream<TTrans>
 where

core/src/network.rs

@@ -175,22 +175,18 @@ where
         self.listeners.listen_addrs()
     }
 
-    /// Call this function in order to know which address remotes should dial to
-    /// access your local node.
+    /// Maps the given `observed_addr`, representing an address of the local
+    /// node observed by a remote peer, onto the locally known listen addresses
+    /// to yield one or more addresses of the local node that may be publicly
+    /// reachable.
     ///
-    /// When receiving an observed address on a tcp connection that we initiated, the observed
-    /// address contains our tcp dial port, not our tcp listen port. We know which port we are
-    /// listening on, thereby we can replace the port within the observed address.
-    ///
-    /// When receiving an observed address on a tcp connection that we did **not** initiated, the
-    /// observed address should contain our listening port. In case it differs from our listening
-    /// port there might be a proxy along the path.
-    ///
-    /// # Arguments
-    ///
-    /// * `observed_addr` - should be an address a remote observes you as, which can be obtained for
-    /// example with the identify protocol.
+    /// I.e. this method incorporates the view of other peers into the listen
+    /// addresses seen by the local node to account for possible IP and port
+    /// mappings performed by intermediate network devices in an effort to
+    /// obtain addresses for the local peer that are also reachable for peers
+    /// other than the peer who reported the `observed_addr`.
     ///
+    /// The translation is transport-specific. See [`Transport::address_translation`].
     pub fn address_translation<'a>(&'a self, observed_addr: &'a Multiaddr)
         -> impl Iterator<Item = Multiaddr> + 'a
     where

core/src/transport.rs

@@ -128,8 +128,10 @@ pub trait Transport {
     where
         Self: Sized;
 
-    /// Perform transport specific multiaddr translation.
-    fn address_translation(&self, _server: &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.
+    fn address_translation(&self, listen: &Multiaddr, observed: &Multiaddr) -> Option<Multiaddr>;
 
     /// Boxes the transport, including custom transport errors.
     fn boxed(self) -> boxed::Boxed<Self::Output>

core/tests/util.rs

@@ -31,8 +31,7 @@ pub fn test_network(cfg: NetworkConfig) -> TestNetwork {
     let local_key = identity::Keypair::generate_ed25519();
     let local_public_key = local_key.public();
     let noise_keys = noise::Keypair::<noise::X25519Spec>::new().into_authentic(&local_key).unwrap();
-    let transport: TestTransport = async_std::task::block_on(tcp::TcpConfig::new())
-        .unwrap()
+    let transport: TestTransport = tcp::TcpConfig::new()
         .upgrade(upgrade::Version::V1)
         .authenticate(noise::NoiseConfig::xx(noise_keys).into_authenticated())
         .multiplex(mplex::MplexConfig::new())

examples/chat.rs

@@ -63,8 +63,7 @@ use libp2p::{
 };
 use std::{error::Error, task::{Context, Poll}};
 
-#[async_std::main]
-async fn main() -> Result<(), Box<dyn Error>> {
+fn main() -> Result<(), Box<dyn Error>> {
     env_logger::init();
 
     // Create a random PeerId
@@ -73,7 +72,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     println!("Local peer id: {:?}", local_peer_id);
 
     // Set up a an encrypted DNS-enabled TCP Transport over the Mplex and Yamux protocols
-    let transport = libp2p::build_development_transport(local_key).await?;
+    let transport = libp2p::build_development_transport(local_key)?;
 
     // Create a Floodsub topic
     let floodsub_topic = floodsub::Topic::new("chat");

examples/distributed-key-value-store.rs

@@ -65,16 +65,15 @@ use libp2p::{
 };
 use std::{error::Error, task::{Context, Poll}};
 
-#[async_std::main]
-async fn main() -> Result<(), Box<dyn Error>> {
+fn main() -> Result<(), Box<dyn Error>> {
     env_logger::init();
 
     // Create a random key for ourselves.
     let local_key = identity::Keypair::generate_ed25519();
     let local_peer_id = PeerId::from(local_key.public());
 
     // Set up a an encrypted DNS-enabled TCP Transport over the Mplex protocol.
-    let transport = build_development_transport(local_key).await?;
+    let transport = build_development_transport(local_key)?;
 
     // We create a custom network behaviour that combines Kademlia and mDNS.
     #[derive(NetworkBehaviour)]

examples/gossipsub-chat.rs

@@ -60,8 +60,7 @@ use std::{
     task::{Context, Poll},
 };
 
-#[async_std::main]
-async fn main() -> Result<(), Box<dyn Error>> {
+fn main() -> Result<(), Box<dyn Error>> {
     Builder::from_env(Env::default().default_filter_or("info")).init();
 
     // Create a random PeerId
@@ -70,7 +69,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     println!("Local peer id: {:?}", local_peer_id);
 
     // Set up an encrypted TCP Transport over the Mplex and Yamux protocols
-    let transport = libp2p::build_development_transport(local_key.clone()).await?;
+    let transport = libp2p::build_development_transport(local_key.clone())?;
 
     // Create a Gossipsub topic
     let topic = Topic::new("test-net".into());

examples/ipfs-kad.rs

@@ -40,16 +40,15 @@ use libp2p::kad::{
 use libp2p::kad::record::store::MemoryStore;
 use std::{env, error::Error, time::Duration};
 
-#[async_std::main]
-async fn main() -> Result<(), Box<dyn Error>> {
+fn main() -> Result<(), Box<dyn Error>> {
     env_logger::init();
 
     // Create a random key for ourselves.
     let local_key = identity::Keypair::generate_ed25519();
     let local_peer_id = PeerId::from(local_key.public());
 
     // Set up a an encrypted DNS-enabled TCP Transport over the Mplex protocol
-    let transport = build_development_transport(local_key).await?;
+    let transport = build_development_transport(local_key)?;
 
     // Create a swarm to manage peers and events.
     let mut swarm = {

examples/ipfs-private.rs

@@ -58,7 +58,7 @@ use std::{
 };
 
 /// Builds the transport that serves as a common ground for all connections.
-pub async fn build_transport(
+pub fn build_transport(
     key_pair: identity::Keypair,
     psk: Option<PreSharedKey>,
 ) -> transport::Boxed<(PeerId, StreamMuxerBox)>
@@ -67,7 +67,7 @@ pub async fn build_transport(
     let noise_config = noise::NoiseConfig::xx(noise_keys).into_authenticated();
     let yamux_config = YamuxConfig::default();
 
-    let base_transport = TcpConfig::new().await.unwrap().nodelay(true);
+    let base_transport = TcpConfig::new().nodelay(true);
     let maybe_encrypted = match psk {
         Some(psk) => EitherTransport::Left(
             base_transport.and_then(move |socket, _| PnetConfig::new(psk).handshake(socket)),
@@ -136,8 +136,7 @@ fn parse_legacy_multiaddr(text: &str) -> Result<Multiaddr, Box<dyn Error>> {
     Ok(res)
 }
 
-#[async_std::main]
-async fn main() -> Result<(), Box<dyn Error>> {
+fn main() -> Result<(), Box<dyn Error>> {
     env_logger::init();
 
     let ipfs_path: Box<Path> = get_ipfs_path();
@@ -155,7 +154,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     }
 
     // Set up a an encrypted DNS-enabled TCP Transport over and Yamux protocol
-    let transport = build_transport(local_key.clone(), psk).await;
+    let transport = build_transport(local_key.clone(), psk);
 
     // Create a Gosspipsub topic
     let gossipsub_topic = gossipsub::Topic::new("chat".into());

examples/ping.rs

@@ -43,8 +43,7 @@ use futures::{future, prelude::*};
 use libp2p::{identity, PeerId, ping::{Ping, PingConfig}, Swarm};
 use std::{error::Error, task::{Context, Poll}};
 
-#[async_std::main]
-async fn main() -> Result<(), Box<dyn Error>> {
+fn main() -> Result<(), Box<dyn Error>> {
     env_logger::init();
 
     // Create a random PeerId.
@@ -53,7 +52,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     println!("Local peer id: {:?}", peer_id);
 
     // Create a transport.
-    let transport = libp2p::build_development_transport(id_keys).await?;
+    let transport = libp2p::build_development_transport(id_keys)?;
 
     // Create a ping network behaviour.
     //