swarm/src/behaviour: Deprecate NetworkBehaviourEventProcess

swarm/CHANGELOG.md

@@ -1,8 +1,72 @@
 # 0.38.0 [unreleased]
 
-- Update dial address concurrency factor to `8`, thus dialing up to 8 addresses concurrently for a single connection attempt. See `Swarm::dial_concurrency_factor` and [PR 2741].
+- Remove `NetworkBehaviourEventProcess`. When deriving `NetworkBehaviour` on a custom `struct` users
+  should either bring their own `OutEvent` via `#[behaviour(out_event = "MyBehaviourEvent")]` or,
+  when not specified, have the derive macro generate one for the user.
 
-- Update to `libp2p-core` `v0.35.0`.
+  See [`NetworkBehaviour`
+  documentation](https://docs.rs/libp2p/latest/libp2p/swarm/trait.NetworkBehaviour.html) for
+  details.
+
+  Previously
+
+  ``` rust
+  #[derive(NetworkBehaviour)]
+  #[behaviour(event_process = true)]
+  struct MyBehaviour {
+      floodsub: Gossipsub,
+      mdns: Mdns,
+  }
+
+  impl NetworkBehaviourEventProcess<Gossipsub> for MyBehaviour {
+      fn inject_event(&mut self, message: GossipsubEvent) {
+        todo!("Handle event")
+      }
+  }
+
+  impl NetworkBehaviourEventProcess<MdnsEvent> for MyBehaviour {
+      fn inject_event(&mut self, message: MdnsEvent) {
+        todo!("Handle event")
+      }
+  }
+  ```
+
+  Now
+
+  ``` rust
+  #[derive(NetworkBehaviour)]
+  #[behaviour(out_event = "MyBehaviourEvent")]
+  struct MyBehaviour {
+      floodsub: Gossipsub,
+      mdns: Mdns,
+  }
+
+  enum MyBehaviourEvent {
+      Floodsub(FloodsubEvent),
+      Mdns(MdnsEvent),
+  }
+
+  impl From<GossipsubEvent> for MyBehaviourEvent {
+      fn from(event: GossipsubEvent) -> Self {
+          MyBehaviourEvent::Gossipsub(event)
+      }
+  }
+
+  impl From<MdnsEvent> for MyBehaviourEvent {
+      fn from(event: MdnsEvent) -> Self {
+          MyBehaviourEvent::Mdns(event)
+      }
+  }
+
+  match swarm.next().await.unwrap() {
+    SwarmEvent::Behaviour(MyBehaviourEvent::Gossipsub(event)) => {
+      todo!("Handle event")
+    }
+    SwarmEvent::Behaviour(MyBehaviourEvent::Mdns(event)) => {
+      todo!("Handle event")
+    }
+  }
+  ```
 
 - When deriving `NetworkBehaviour` on a custom `struct` where the user does not specify their own
   `OutEvent` via `#[behaviour(out_event = "MyBehaviourEvent")]` and where the user does not enable
@@ -13,6 +77,10 @@
   documentation](https://docs.rs/libp2p/latest/libp2p/swarm/trait.NetworkBehaviour.html) for
   details.
 
+- Update dial address concurrency factor to `8`, thus dialing up to 8 addresses concurrently for a single connection attempt. See `Swarm::dial_concurrency_factor` and [PR 2741].
+
+- Update to `libp2p-core` `v0.35.0`.
+
 [PR 2741]: https://github.com/libp2p/rust-libp2p/pull/2741/
 
 # 0.37.0

swarm/src/behaviour.rs

@@ -85,9 +85,9 @@ pub(crate) type THandlerOutEvent<THandler> =
 /// "MyCustomOutEvent")]`. If the user does not specify an `out_event`, the derive macro generates
 /// the event definition itself, naming it `<STRUCT_NAME>Event`.
 ///
-/// When setting a custom `out_event`, the aforementioned conversion of each of the event types
-/// generated by the struct members to the custom `out_event` is handled by [`From`]
-/// implementations the user needs to provide.
+/// The aforementioned conversion of each of the event types generated by the struct members to the
+/// custom `out_event` is handled by [`From`] implementations which the user needs to define in
+/// addition to the event `enum` itself.
 ///
 /// ``` rust
 /// # use libp2p::identify::{Identify, IdentifyEvent};
@@ -327,6 +327,13 @@ pub trait PollParameters {
 ///
 /// You can opt out of this behaviour through `#[behaviour(event_process = false)]`. See the
 /// documentation of [`NetworkBehaviour`] for details.
+#[deprecated(
+    since = "0.38.0",
+    note = "Use `#[behaviour(out_event = \"MyBehaviourEvent\")]` instead. See \
+            https://github.com/libp2p/rust-libp2p/blob/master/swarm/CHANGELOG.md#0380 \
+            for instructions on how to migrate. Will be removed with \
+            https://github.com/libp2p/rust-libp2p/pull/2751."
+)]
 pub trait NetworkBehaviourEventProcess<TEvent> {
     /// Called when one of the fields of the type you're deriving `NetworkBehaviour` on generates
     /// an event.

swarm/src/behaviour/either.rs

@@ -19,10 +19,9 @@
 // DEALINGS IN THE SOFTWARE.
 
 use crate::handler::{either::IntoEitherHandler, ConnectionHandler, IntoConnectionHandler};
-use crate::{
-    DialError, NetworkBehaviour, NetworkBehaviourAction, NetworkBehaviourEventProcess,
-    PollParameters,
-};
+#[allow(deprecated)]
+pub use crate::NetworkBehaviourEventProcess;
+use crate::{DialError, NetworkBehaviour, NetworkBehaviourAction, PollParameters};
 use either::Either;
 use libp2p_core::{
     connection::ConnectionId, transport::ListenerId, ConnectedPoint, Multiaddr, PeerId,
@@ -237,6 +236,7 @@ where
     }
 }
 
+#[allow(deprecated)]
 impl<TEvent, TBehaviourLeft, TBehaviourRight> NetworkBehaviourEventProcess<TEvent>
     for Either<TBehaviourLeft, TBehaviourRight>
 where

swarm/src/behaviour/toggle.rs

@@ -23,10 +23,9 @@ use crate::handler::{
     KeepAlive, SubstreamProtocol,
 };
 use crate::upgrade::{InboundUpgradeSend, OutboundUpgradeSend, SendWrapper};
-use crate::{
-    DialError, NetworkBehaviour, NetworkBehaviourAction, NetworkBehaviourEventProcess,
-    PollParameters,
-};
+#[allow(deprecated)]
+pub use crate::NetworkBehaviourEventProcess;
+use crate::{DialError, NetworkBehaviour, NetworkBehaviourAction, PollParameters};
 use either::Either;
 use libp2p_core::{
     connection::ConnectionId,
@@ -233,6 +232,7 @@ where
     }
 }
 
+#[allow(deprecated)]
 impl<TEvent, TBehaviour> NetworkBehaviourEventProcess<TEvent> for Toggle<TBehaviour>
 where
     TBehaviour: NetworkBehaviourEventProcess<TEvent>,

swarm/src/lib.rs

@@ -63,9 +63,10 @@ pub mod behaviour;
 pub mod dial_opts;
 pub mod handler;
 
+#[allow(deprecated)]
+pub use behaviour::NetworkBehaviourEventProcess;
 pub use behaviour::{
-    CloseConnection, NetworkBehaviour, NetworkBehaviourAction, NetworkBehaviourEventProcess,
-    NotifyHandler, PollParameters,
+    CloseConnection, NetworkBehaviour, NetworkBehaviourAction, NotifyHandler, PollParameters,
 };
 pub use connection::{
     ConnectionCounters, ConnectionError, ConnectionLimit, ConnectionLimits, PendingConnectionError,