feat(kad): report automatic changes to kad mode

Cargo.toml

@@ -83,7 +83,7 @@ libp2p-floodsub = { version = "0.43.0", path = "protocols/floodsub" }
 libp2p-gossipsub = { version = "0.45.1", path = "protocols/gossipsub" }
 libp2p-identify = { version = "0.43.0", path = "protocols/identify" }
 libp2p-identity = { version = "0.2.3" }
-libp2p-kad = { version = "0.44.5", path = "protocols/kad" }
+libp2p-kad = { version = "0.45.0", path = "protocols/kad" }
 libp2p-mdns = { version = "0.44.0", path = "protocols/mdns" }
 libp2p-memory-connection-limits = { version = "0.1.0", path = "misc/memory-connection-limits" }
 libp2p-metrics = { version = "0.13.1", path = "misc/metrics" }

protocols/kad/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.45.0
+- Emit `ModeChanged` event whenever we automatically reconfigure the mode.
+  See [PR 4503].
+
+[PR 4503]: https://github.com/libp2p/rust-libp2p/pull/4503
+
 ## 0.44.5
 - Migrate to `quick-protobuf-codec` crate for codec logic.
   See [PR 4501].

protocols/kad/Cargo.toml

@@ -3,7 +3,7 @@ name = "libp2p-kad"
 edition = "2021"
 rust-version = { workspace = true }
 description = "Kademlia protocol for libp2p"
-version = "0.44.5"
+version = "0.45.0"
 authors = ["Parity Technologies <[email protected]>"]
 license = "MIT"
 repository = "https://github.com/libp2p/rust-libp2p"

protocols/kad/src/behaviour.rs

@@ -1048,6 +1048,8 @@ where
     }
 
     fn determine_mode_from_external_addresses(&mut self) {
+        let old_mode = self.mode;
+
         self.mode = match (self.external_addresses.as_slice(), self.mode) {
             ([], Mode::Server) => {
                 log::debug!("Switching to client-mode because we no longer have any confirmed external addresses");
@@ -1082,6 +1084,13 @@ where
         };
 
         self.reconfigure_mode();
+
+        if old_mode != self.mode {
+            self.queued_events
+                .push_back(ToSwarm::GenerateEvent(KademliaEvent::ModeChanged {
+                    new_mode: self.mode,
+                }));
+        }
     }
 
     /// Processes discovered peers from a successful request in an iterative `Query`.
@@ -2674,6 +2683,12 @@ pub enum KademliaEvent {
     /// See [`Kademlia::kbucket`] for insight into the contents of
     /// the k-bucket of `peer`.
     PendingRoutablePeer { peer: PeerId, address: Multiaddr },
+
+    /// This peer's mode has been updated automatically.
+    ///
+    /// This happens in response to an external
+    /// address being added or removed.
+    ModeChanged { new_mode: Mode },
 }
 
 /// Information about progress events.

protocols/kad/src/behaviour/test.rs

@@ -1066,6 +1066,7 @@ fn exceed_jobs_max_queries() {
                             result: QueryResult::GetClosestPeers(Ok(r)),
                             ..
                         }) => break assert!(r.peers.is_empty()),
+                        SwarmEvent::Behaviour(KademliaEvent::ModeChanged { .. }) => {}
                         SwarmEvent::Behaviour(e) => panic!("Unexpected event: {e:?}"),
                         _ => {}
                     }
@@ -1393,6 +1394,7 @@ fn get_providers_single() {
                     result: QueryResult::StartProviding(Ok(_)),
                     ..
                 }) => {}
+                SwarmEvent::Behaviour(KademliaEvent::ModeChanged { .. }) => {}
                 SwarmEvent::Behaviour(e) => panic!("Unexpected event: {e:?}"),
                 _ => {}
             }

protocols/kad/tests/client_mode.rs

@@ -88,9 +88,11 @@ async fn adding_an_external_addresses_activates_server_mode_on_existing_connecti
 
     use MyBehaviourEvent::*;
 
-    // Do the usual identify send/receive dance.
+    // Do the usual identify send/receive dance. This triggers a mode change to Mode::Client.
     match libp2p_swarm_test::drive(&mut client, &mut server).await {
-        ([Identify(_), Identify(_)], [Identify(_), Identify(_)]) => {}
+        ([Identify(_), Identify(_)], [Kad(ModeChanged { new_mode }), Identify(_), Identify(_)]) => {
+            assert_eq!(new_mode, Mode::Client);
+        }
         other => panic!("Unexpected events: {other:?}"),
     }
 
@@ -99,12 +101,13 @@ async fn adding_an_external_addresses_activates_server_mode_on_existing_connecti
     // Server learns its external address (this could be through AutoNAT or some other mechanism).
     server.add_external_address(memory_addr);
 
-    // The server reconfigured its connection to the client to be in server mode, pushes that information to client which as a result updates its routing table.
+    // The server reconfigured its connection to the client to be in server mode, pushes that information to client which as a result updates its routing table and triggers a mode change to Mode::Server.
     match libp2p_swarm_test::drive(&mut client, &mut server).await {
         (
             [Identify(identify::Event::Received { .. }), Kad(RoutingUpdated { peer: peer1, .. })],
-            [Identify(identify::Event::Pushed { .. })],
+            [Kad(ModeChanged { new_mode }), Identify(identify::Event::Pushed { .. })],
         ) => {
+            assert_eq!(new_mode, Mode::Server);
             assert_eq!(peer1, server_peer_id);
         }
         other => panic!("Unexpected events: {other:?}"),