feat(upnp): emit local listen address when a port is mapped

This PR aims to expose the local listen address for a corresponding successful port-map to the end user. It would be great to know which local adapter was successfully mapped, when the user has multiple local adapters that they're listening on.

Note: #6127 and #6128 were part of the original PR.

Pull-Request: #6121.

Author: RolandSherwin

Cargo.lock

@@ -108,7 +108,7 @@ libp2p-swarm-test = { version = "0.6.0", path = "swarm-test" }
 libp2p-tcp = { version = "0.44.0", path = "transports/tcp" }
 libp2p-tls = { version = "0.6.2", path = "transports/tls" }
 libp2p-uds = { version = "0.43.0", path = "transports/uds" }
-libp2p-upnp = { version = "0.5.1", path = "protocols/upnp" }
+libp2p-upnp = { version = "0.6.0", path = "protocols/upnp" }
 libp2p-webrtc = { version = "0.9.0-alpha.2", path = "transports/webrtc" }
 libp2p-webrtc-utils = { version = "0.4.0", path = "misc/webrtc-utils" }
 libp2p-webrtc-websys = { version = "0.4.0", path = "transports/webrtc-websys" }

Cargo.toml

@@ -57,8 +57,11 @@ async fn main() -> Result<(), Box<dyn Error>> {
     loop {
         match swarm.select_next_some().await {
             SwarmEvent::NewListenAddr { address, .. } => println!("Listening on {address:?}"),
-            SwarmEvent::Behaviour(upnp::Event::NewExternalAddr(addr)) => {
-                println!("New external address: {addr}");
+            SwarmEvent::Behaviour(upnp::Event::NewExternalAddr {
+                external_addr,
+                local_addr: _,
+            }) => {
+                println!("New external address: {external_addr}");
             }
             SwarmEvent::Behaviour(upnp::Event::GatewayNotFound) => {
                 println!("Gateway does not support UPnP");

examples/upnp/src/main.rs

@@ -1,3 +1,12 @@
+## 0.6.0
+
+- Change `Event::NewExternalAddr` and `Event::ExpiredExternalAddr` from tuple variants to struct variants 
+  that include both local and external addresses. This allows users to correlate which local listen 
+  address was mapped to which external address.
+  - `Event::NewExternalAddr` now contains `local_addr` and `external_addr` fields
+  - `Event::ExpiredExternalAddr` now contains `local_addr` and `external_addr` fields
+  See [PR 6121](https://github.com/libp2p/rust-libp2p/pull/6121).
+
 ## 0.5.1
 
 - Skip port mapping when an active port mapping is present.

protocols/upnp/CHANGELOG.md

@@ -3,7 +3,7 @@ name = "libp2p-upnp"
 edition.workspace = true
 rust-version.workspace = true
 description = "UPnP support for libp2p transports"
-version = "0.5.1"
+version = "0.6.0"
 license = "MIT"
 repository = "https://github.com/libp2p/rust-libp2p"
 keywords = ["peer-to-peer", "libp2p", "networking"]

protocols/upnp/Cargo.toml

@@ -158,9 +158,19 @@ enum GatewayState {
 #[derive(Debug)]
 pub enum Event {
     /// The multiaddress is reachable externally.
-    NewExternalAddr(Multiaddr),
+    NewExternalAddr {
+        /// The local listen address that was mapped.
+        local_addr: Multiaddr,
+        /// The external address that is reachable.
+        external_addr: Multiaddr,
+    },
     /// The renewal of the multiaddress on the gateway failed.
-    ExpiredExternalAddr(Multiaddr),
+    ExpiredExternalAddr {
+        /// The local listen address that failed to renew.
+        local_addr: Multiaddr,
+        /// The external address that is no longer reachable.
+        external_addr: Multiaddr,
+    },
     /// The IGD gateway was not found.
     GatewayNotFound,
     /// The Gateway is not exposed directly to the public network.
@@ -475,9 +485,10 @@ impl NetworkBehaviour for Behaviour {
                                     MappingState::Pending { .. } => {
                                         let external_multiaddr =
                                             mapping.external_addr(gateway.external_addr);
-                                        self.pending_events.push_back(Event::NewExternalAddr(
-                                            external_multiaddr.clone(),
-                                        ));
+                                        self.pending_events.push_back(Event::NewExternalAddr {
+                                            local_addr: mapping.multiaddr,
+                                            external_addr: external_multiaddr.clone(),
+                                        });
                                         tracing::debug!(
                                             address=%mapping.internal_addr,
                                             protocol=%mapping.protocol,
@@ -543,9 +554,10 @@ impl NetworkBehaviour for Behaviour {
                                     );
                                     let external_multiaddr =
                                         mapping.external_addr(gateway.external_addr);
-                                    self.pending_events.push_back(Event::ExpiredExternalAddr(
-                                        external_multiaddr.clone(),
-                                    ));
+                                    self.pending_events.push_back(Event::ExpiredExternalAddr {
+                                        local_addr: mapping.multiaddr,
+                                        external_addr: external_multiaddr.clone(),
+                                    });
                                     return Poll::Ready(ToSwarm::ExternalAddrExpired(
                                         external_multiaddr,
                                     ));