refactor(swarm)!: deprecate PollParameters where possible (#3153)

This patch deprecates 3 out of 4 functions on `PollParameters`:

- `local_peer_id`
- `listened_addresses`
- `external_addresses`

The addresses can be obtained by inspecting the `FromSwarm` event. To make this easier, we introduce two utility structs in `libp2p-swarm`:

- `ExternalAddresses`
- `ListenAddresses`

A node's `PeerId` is always known to the caller, thus we can require them to pass it in.

Related: #3124.

swarm/src/behaviour.rs

@@ -19,8 +19,13 @@
 // DEALINGS IN THE SOFTWARE.
 
 mod either;
+mod external_addresses;
+mod listen_addresses;
 pub mod toggle;
 
+pub use external_addresses::ExternalAddresses;
+pub use listen_addresses::ListenAddresses;
+
 use crate::dial_opts::DialOpts;
 use crate::handler::{ConnectionHandler, IntoConnectionHandler};
 use crate::{AddressRecord, AddressScore, DialError};
@@ -402,12 +407,24 @@ pub trait PollParameters {
     fn supported_protocols(&self) -> Self::SupportedProtocolsIter;
 
     /// Returns the list of the addresses we're listening on.
+    #[deprecated(
+        since = "0.42.0",
+        note = "Use `libp2p_swarm::ListenAddresses` instead."
+    )]
     fn listened_addresses(&self) -> Self::ListenedAddressesIter;
 
     /// Returns the list of the addresses nodes can use to reach us.
+    #[deprecated(
+        since = "0.42.0",
+        note = "Use `libp2p_swarm::ExternalAddresses` instead."
+    )]
     fn external_addresses(&self) -> Self::ExternalAddressesIter;
 
     /// Returns the peer id of the local node.
+    #[deprecated(
+        since = "0.42.0",
+        note = "Pass the node's `PeerId` into the behaviour instead."
+    )]
     fn local_peer_id(&self) -> &PeerId;
 }
 

swarm/src/behaviour/external_addresses.rs

@@ -0,0 +1,50 @@
+use crate::behaviour::{ExpiredExternalAddr, FromSwarm, NewExternalAddr};
+use crate::IntoConnectionHandler;
+use libp2p_core::Multiaddr;
+use std::collections::HashSet;
+
+/// The maximum number of local external addresses. When reached any
+/// further externally reported addresses are ignored. The behaviour always
+/// tracks all its listen addresses.
+const MAX_LOCAL_EXTERNAL_ADDRS: usize = 20;
+
+/// Utility struct for tracking the external addresses of a [`Swarm`](crate::Swarm).
+#[derive(Debug, Clone)]
+pub struct ExternalAddresses {
+    addresses: HashSet<Multiaddr>,
+    limit: usize,
+}
+
+impl Default for ExternalAddresses {
+    fn default() -> Self {
+        Self {
+            addresses: Default::default(),
+            limit: MAX_LOCAL_EXTERNAL_ADDRS,
+        }
+    }
+}
+
+impl ExternalAddresses {
+    /// Returns an [`Iterator`] over all external addresses.
+    pub fn iter(&self) -> impl ExactSizeIterator<Item = &Multiaddr> {
+        self.addresses.iter()
+    }
+
+    /// Feed a [`FromSwarm`] event to this struct.
+    pub fn on_swarn_event<THandler>(&mut self, event: &FromSwarm<THandler>)
+    where
+        THandler: IntoConnectionHandler,
+    {
+        match event {
+            FromSwarm::NewExternalAddr(NewExternalAddr { addr, .. }) => {
+                if self.addresses.len() < self.limit {
+                    self.addresses.insert((*addr).clone());
+                }
+            }
+            FromSwarm::ExpiredExternalAddr(ExpiredExternalAddr { addr, .. }) => {
+                self.addresses.insert((*addr).clone());
+            }
+            _ => {}
+        }
+    }
+}

swarm/src/behaviour/listen_addresses.rs

@@ -0,0 +1,33 @@
+use crate::behaviour::{ExpiredListenAddr, FromSwarm, NewListenAddr};
+use crate::IntoConnectionHandler;
+use libp2p_core::Multiaddr;
+use std::collections::HashSet;
+
+/// Utility struct for tracking the addresses a [`Swarm`](crate::Swarm) is listening on.
+#[derive(Debug, Default, Clone)]
+pub struct ListenAddresses {
+    addresses: HashSet<Multiaddr>,
+}
+
+impl ListenAddresses {
+    /// Returns an [`Iterator`] over all listen addresses.
+    pub fn iter(&self) -> impl ExactSizeIterator<Item = &Multiaddr> {
+        self.addresses.iter()
+    }
+
+    /// Feed a [`FromSwarm`] event to this struct.
+    pub fn on_swarm_event<THandler>(&mut self, event: &FromSwarm<THandler>)
+    where
+        THandler: IntoConnectionHandler,
+    {
+        match event {
+            FromSwarm::NewListenAddr(NewListenAddr { addr, .. }) => {
+                self.addresses.insert((*addr).clone());
+            }
+            FromSwarm::ExpiredListenAddr(ExpiredListenAddr { addr, .. }) => {
+                self.addresses.insert((*addr).clone());
+            }
+            _ => {}
+        }
+    }
+}

swarm/src/lib.rs

@@ -101,7 +101,8 @@ pub mod derive_prelude {
 }
 
 pub use behaviour::{
-    CloseConnection, NetworkBehaviour, NetworkBehaviourAction, NotifyHandler, PollParameters,
+    CloseConnection, ExternalAddresses, ListenAddresses, NetworkBehaviour, NetworkBehaviourAction,
+    NotifyHandler, PollParameters,
 };
 pub use connection::pool::{ConnectionCounters, ConnectionLimits};
 pub use connection::{