swarm: Split off "keep alive" functionality from `DummyConnectionHand…

…ler` (#2859)

Previously, the `DummyConnectionHandler` offered a "keep alive" functionality,
i.e. it allowed users to set the value of what is returned from
`ConnectionHandler::keep_alive`. This handler is primarily used in tests or
`NetworkBehaviour`s that don't open any connections (like mDNS). In all of these
cases, it is statically known whether we want to keep connections alive. As
such, this functionality is better represented by a static
`KeepAliveConnectionHandler` that always returns `KeepAlive::Yes` and a
`DummyConnectionHandler` that always returns `KeepAlive::No`.

To follow the naming conventions described in
#2217, we introduce a top-level
`keep_alive` and `dummy` behaviour in `libp2p-swarm` that contains both the
`NetworkBehaviour` and `ConnectionHandler` implementation for either case.

examples/ping.rs

@@ -42,7 +42,8 @@
 
 use futures::prelude::*;
 use libp2p::swarm::{Swarm, SwarmEvent};
-use libp2p::{identity, ping, Multiaddr, PeerId};
+use libp2p::{identity, ping, Multiaddr, NetworkBehaviour, PeerId};
+use libp2p_swarm::keep_alive;
 use std::error::Error;
 
 #[async_std::main]
@@ -53,14 +54,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     let transport = libp2p::development_transport(local_key).await?;
 
-    // Create a ping network behaviour.
-    //
-    // For illustrative purposes, the ping protocol is configured to
-    // keep the connection alive, so a continuous sequence of pings
-    // can be observed.
-    let behaviour = ping::Behaviour::new(ping::Config::new().with_keep_alive(true));
-
-    let mut swarm = Swarm::new(transport, behaviour, local_peer_id);
+    let mut swarm = Swarm::new(transport, Behaviour::default(), local_peer_id);
 
     // Tell the swarm to listen on all interfaces and a random, OS-assigned
     // port.
@@ -82,3 +76,13 @@ async fn main() -> Result<(), Box<dyn Error>> {
         }
     }
 }
+
+/// Our network behaviour.
+///
+/// For illustrative purposes, this includes the [`KeepAlive`](behaviour::KeepAlive) behaviour so a continuous sequence of
+/// pings can be observed.
+#[derive(NetworkBehaviour, Default)]
+struct Behaviour {
+    keep_alive: keep_alive::Behaviour,
+    ping: ping::Behaviour,
+}

misc/metrics/CHANGELOG.md

@@ -1,7 +1,5 @@
 # 0.10.0 [unreleased]
 
-- Update to `libp2p-kad` `v0.41.0`.
-
 - Update to `libp2p-swarm` `v0.40.0`.
 
 - Update to `libp2p-dcutr` `v0.7.0`.
@@ -12,6 +10,8 @@
 
 - Update to `libp2p-relay` `v0.13.0`.
 
+- Update to `libp2p-kad` `v0.41.0`.
+
 - Update to `libp2p-core` `v0.37.0`.
 
 - Update to `libp2p-gossipsub` `v0.42.0`.

misc/metrics/examples/metrics/main.rs

@@ -48,19 +48,19 @@
 //! You should see a long list of metrics printed to the terminal. Check the
 //! `libp2p_ping` metrics, they should be `>0`.
 
+use env_logger::Env;
 use futures::executor::block_on;
 use futures::stream::StreamExt;
 use libp2p::core::Multiaddr;
 use libp2p::metrics::{Metrics, Recorder};
-use libp2p::ping;
 use libp2p::swarm::SwarmEvent;
-use libp2p::{identity, PeerId, Swarm};
+use libp2p::{identity, ping, NetworkBehaviour, PeerId, Swarm};
+use libp2p_swarm::keep_alive;
+use log::info;
 use prometheus_client::registry::Registry;
 use std::error::Error;
 use std::thread;
 
-use env_logger::Env;
-use log::info;
 mod http_service;
 
 fn main() -> Result<(), Box<dyn Error>> {
@@ -72,7 +72,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     let mut swarm = Swarm::new(
         block_on(libp2p::development_transport(local_key))?,
-        ping::Behaviour::new(ping::Config::new().with_keep_alive(true)),
+        Behaviour::default(),
         local_peer_id,
     );
 
@@ -91,7 +91,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     block_on(async {
         loop {
             match swarm.select_next_some().await {
-                SwarmEvent::Behaviour(ping_event) => {
+                SwarmEvent::Behaviour(BehaviourEvent::Ping(ping_event)) => {
                     info!("{:?}", ping_event);
                     metrics.record(&ping_event);
                 }
@@ -104,3 +104,13 @@ fn main() -> Result<(), Box<dyn Error>> {
     });
     Ok(())
 }
+
+/// Our network behaviour.
+///
+/// For illustrative purposes, this includes the [`keep_alive::Behaviour`]) behaviour so the ping actually happen
+/// and can be observed via the metrics.
+#[derive(NetworkBehaviour, Default)]
+struct Behaviour {
+    keep_alive: keep_alive::Behaviour,
+    ping: ping::Behaviour,
+}

misc/multistream-select/tests/transport.rs

@@ -28,7 +28,7 @@ use libp2p::core::{
 };
 use libp2p::mplex::MplexConfig;
 use libp2p::plaintext::PlainText2Config;
-use libp2p::swarm::{DummyBehaviour, Swarm, SwarmEvent};
+use libp2p::swarm::{dummy, Swarm, SwarmEvent};
 use rand::random;
 use std::task::Poll;
 
@@ -61,8 +61,8 @@ fn transport_upgrade() {
 
         let listen_addr = Multiaddr::from(Protocol::Memory(random::<u64>()));
 
-        let mut dialer = Swarm::new(dialer_transport, DummyBehaviour::default(), dialer_id);
-        let mut listener = Swarm::new(listener_transport, DummyBehaviour::default(), listener_id);
+        let mut dialer = Swarm::new(dialer_transport, dummy::Behaviour, dialer_id);
+        let mut listener = Swarm::new(listener_transport, dummy::Behaviour, listener_id);
 
         listener.listen_on(listen_addr).unwrap();
         let (addr_sender, addr_receiver) = oneshot::channel();

protocols/dcutr/src/handler.rs

@@ -23,7 +23,7 @@ use either::Either;
 use libp2p_core::connection::ConnectionId;
 use libp2p_core::upgrade::{self, DeniedUpgrade};
 use libp2p_core::{ConnectedPoint, PeerId};
-use libp2p_swarm::handler::DummyConnectionHandler;
+use libp2p_swarm::dummy;
 use libp2p_swarm::handler::SendWrapper;
 use libp2p_swarm::{ConnectionHandler, IntoConnectionHandler};
 
@@ -44,15 +44,15 @@ pub enum Role {
 }
 
 impl IntoConnectionHandler for Prototype {
-    type Handler = Either<relayed::Handler, Either<direct::Handler, DummyConnectionHandler>>;
+    type Handler = Either<relayed::Handler, Either<direct::Handler, dummy::ConnectionHandler>>;
 
     fn into_handler(self, _remote_peer_id: &PeerId, endpoint: &ConnectedPoint) -> Self::Handler {
         match self {
             Self::UnknownConnection => {
                 if endpoint.is_relayed() {
                     Either::Left(relayed::Handler::new(endpoint.clone()))
                 } else {
-                    Either::Right(Either::Right(DummyConnectionHandler::default()))
+                    Either::Right(Either::Right(dummy::ConnectionHandler))
                 }
             }
             Self::DirectConnection {

protocols/mdns/src/behaviour.rs

@@ -31,8 +31,7 @@ use if_watch::{IfEvent, IfWatcher};
 use libp2p_core::transport::ListenerId;
 use libp2p_core::{Multiaddr, PeerId};
 use libp2p_swarm::{
-    handler::DummyConnectionHandler, ConnectionHandler, NetworkBehaviour, NetworkBehaviourAction,
-    PollParameters,
+    dummy, ConnectionHandler, NetworkBehaviour, NetworkBehaviourAction, PollParameters,
 };
 use smallvec::SmallVec;
 use std::collections::hash_map::{Entry, HashMap};
@@ -120,11 +119,11 @@ where
     T: Builder + Stream,
     S: AsyncSocket,
 {
-    type ConnectionHandler = DummyConnectionHandler;
+    type ConnectionHandler = dummy::ConnectionHandler;
     type OutEvent = MdnsEvent;
 
     fn new_handler(&mut self) -> Self::ConnectionHandler {
-        DummyConnectionHandler::default()
+        dummy::ConnectionHandler
     }
 
     fn addresses_of_peer(&mut self, peer_id: &PeerId) -> Vec<Multiaddr> {
@@ -168,7 +167,7 @@ where
         &mut self,
         cx: &mut Context<'_>,
         params: &mut impl PollParameters,
-    ) -> Poll<NetworkBehaviourAction<Self::OutEvent, DummyConnectionHandler>> {
+    ) -> Poll<NetworkBehaviourAction<Self::OutEvent, dummy::ConnectionHandler>> {
         // Poll ifwatch.
         while let Poll::Ready(event) = Pin::new(&mut self.if_watch).poll(cx) {
             match event {

protocols/ping/CHANGELOG.md

@@ -8,8 +8,11 @@
 
 - Update to `libp2p-swarm` `v0.40.0`.
 
+- Deprecate `Config::with_keep_alive`. See [PR 2859].
+
 [PR 2857]: https://github.com/libp2p/rust-libp2p/pull/2857
 [PR 2937]: https://github.com/libp2p/rust-libp2p/pull/2937
+[PR 2859]: https://github.com/libp2p/rust-libp2p/pull/2859/
 
 # 0.39.0
 

protocols/ping/src/handler.rs

@@ -111,6 +111,10 @@ impl Config {
     /// If the maximum number of allowed ping failures is reached, the
     /// connection is always terminated as a result of [`ConnectionHandler::poll`]
     /// returning an error, regardless of the keep-alive setting.
+    #[deprecated(
+        since = "0.40.0",
+        note = "Use `libp2p::swarm::behaviour::KeepAlive` if you need to keep connections alive unconditionally."
+    )]
     pub fn with_keep_alive(mut self, b: bool) -> Self {
         self.keep_alive = b;
         self