feat(swarm): rename associated types for message passing

Previously, the associated types on `NetworkBehaviour` and `ConnectionHandler` carried generic names like `InEvent` and `OutEvent`. These names are _correct_ in that `OutEvent`s are passed out and `InEvent`s are passed in but they don't help users understand how these types are used.

In theory, a `ConnectionHandler` could be used separately from `NetworkBehaviour`s but that is highly unlikely. Thus, we rename these associated types to indicate, where the message is going to be sent to:

- `NetworkBehaviour::OutEvent` is renamed to `ToSwarm`: It describes the message(s) a `NetworkBehaviour` can emit to the `Swarm`. The user is going to receive those in `SwarmEvent::Behaviour`.
- `ConnectionHandler::InEvent` is renamed to `FromBehaviour`: It describes the message(s) a `ConnectionHandler` can receive from its behaviour via `ConnectionHandler::on_swarm_event`. The `NetworkBehaviour` can send it via the `ToSwarm::NotifyHandler` command.
- `ConnectionHandler::OutEvent` is renamed to `ToBehaviour`: It describes the message(s) a `ConnectionHandler` can send back to the behaviour via the now also renamed `ConnectionHandlerEvent::NotifyBehaviour` (previously `ConnectionHandlerEvent::Custom`)

Resolves: #2854.

Pull-Request: #3848.

Author: tcoratger

Cargo.lock

@@ -104,7 +104,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     .boxed();
 
     #[derive(NetworkBehaviour)]
-    #[behaviour(out_event = "Event", event_process = false)]
+    #[behaviour(to_swarm = "Event", event_process = false)]
     struct Behaviour {
         relay_client: relay::client::Behaviour,
         ping: ping::Behaviour,

examples/dcutr/src/main.rs

@@ -11,4 +11,4 @@ async-trait = "0.1"
 env_logger = "0.10"
 futures = "0.3.28"
 libp2p = { path = "../../libp2p", features = ["async-std", "dns", "kad", "mdns", "noise", "macros", "tcp", "websocket", "yamux"] }
-multiaddr = { version = "0.17.1" }
+multiaddr = { version = "0.17.1" }

examples/distributed-key-value-store/Cargo.toml

@@ -71,7 +71,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     // We create a custom network behaviour that combines Kademlia and mDNS.
     #[derive(NetworkBehaviour)]
-    #[behaviour(out_event = "MyBehaviourEvent")]
+    #[behaviour(to_swarm = "MyBehaviourEvent")]
     struct MyBehaviour {
         kademlia: Kademlia<MemoryStore>,
         mdns: mdns::async_io::Behaviour,

examples/distributed-key-value-store/src/main.rs

@@ -408,7 +408,7 @@ impl EventLoop {
 }
 
 #[derive(NetworkBehaviour)]
-#[behaviour(out_event = "ComposedEvent")]
+#[behaviour(to_swarm = "ComposedEvent")]
 struct ComposedBehaviour {
     request_response: request_response::Behaviour<FileExchangeCodec>,
     kademlia: Kademlia<MemoryStore>,

examples/file-sharing/src/network.rs

@@ -145,7 +145,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
 
     // We create a custom network behaviour that combines gossipsub, ping and identify.
     #[derive(NetworkBehaviour)]
-    #[behaviour(out_event = "MyBehaviourEvent")]
+    #[behaviour(to_swarm = "MyBehaviourEvent")]
     struct MyBehaviour {
         gossipsub: gossipsub::Behaviour,
         identify: identify::Behaviour,

examples/ipfs-private/src/main.rs

@@ -9,9 +9,12 @@
   This newtype enforces additional variants like a leading forward-slash.
   We encourage users to use `StreamProtocol` when implementing `UpgradeInfo`.
   See [PR 3746].
+  
+- Rename `NetworkBehaviour::OutEvent` to `NetworkBehaviour::ToSwarm`, `ConnectionHandler::InEvent` to `ConnectionHandler::FromBehaviour`, `ConnectionHandler::OutEvent` to `ConnectionHandler::ToBehaviour`. See [PR 3848].
 
 [PR 3746]: https://github.com/libp2p/rust-libp2p/pull/3746
 [PR 3715]: https://github.com/libp2p/rust-libp2p/pull/3715
+[PR 3848]: https://github.com/libp2p/rust-libp2p/pull/3848
 
 ## 0.51.3
 

libp2p/CHANGELOG.md

@@ -191,7 +191,7 @@ where
     S: Enforce,
 {
     type ConnectionHandler = dummy::ConnectionHandler;
-    type OutEvent = Void;
+    type ToSwarm = Void;
 
     fn handle_established_inbound_connection(
         &mut self,
@@ -261,7 +261,7 @@ where
         &mut self,
         cx: &mut Context<'_>,
         _: &mut impl PollParameters,
-    ) -> Poll<ToSwarm<Self::OutEvent, THandlerInEvent<Self>>> {
+    ) -> Poll<ToSwarm<Self::ToSwarm, THandlerInEvent<Self>>> {
         if let Some(peer) = self.close_connections.pop_front() {
             return Poll::Ready(ToSwarm::CloseConnection {
                 peer_id: peer,

misc/allow-block-list/src/lib.rs

@@ -201,7 +201,7 @@ impl ConnectionLimits {
 
 impl NetworkBehaviour for Behaviour {
     type ConnectionHandler = dummy::ConnectionHandler;
-    type OutEvent = Void;
+    type ToSwarm = Void;
 
     fn handle_pending_inbound_connection(
         &mut self,
@@ -355,7 +355,7 @@ impl NetworkBehaviour for Behaviour {
         &mut self,
         _: &mut Context<'_>,
         _: &mut impl PollParameters,
-    ) -> Poll<ToSwarm<Self::OutEvent, THandlerInEvent<Self>>> {
+    ) -> Poll<ToSwarm<Self::ToSwarm, THandlerInEvent<Self>>> {
         Poll::Pending
     }
 }

misc/connection-limits/src/lib.rs

@@ -209,7 +209,7 @@ pub struct Behaviour {
 
     last_probe: Option<Instant>,
 
-    pending_actions: VecDeque<ToSwarm<<Self as NetworkBehaviour>::OutEvent, THandlerInEvent<Self>>>,
+    pending_actions: VecDeque<ToSwarm<<Self as NetworkBehaviour>::ToSwarm, THandlerInEvent<Self>>>,
 
     probe_id: ProbeId,
 
@@ -427,7 +427,7 @@ impl Behaviour {
 impl NetworkBehaviour for Behaviour {
     type ConnectionHandler =
         <request_response::Behaviour<AutoNatCodec> as NetworkBehaviour>::ConnectionHandler;
-    type OutEvent = Event;
+    type ToSwarm = Event;
 
     fn poll(&mut self, cx: &mut Context<'_>, params: &mut impl PollParameters) -> Poll<Action> {
         loop {
@@ -594,7 +594,7 @@ impl NetworkBehaviour for Behaviour {
     }
 }
 
-type Action = ToSwarm<<Behaviour as NetworkBehaviour>::OutEvent, THandlerInEvent<Behaviour>>;
+type Action = ToSwarm<<Behaviour as NetworkBehaviour>::ToSwarm, THandlerInEvent<Behaviour>>;
 
 // Trait implemented for `AsClient` and `AsServer` to handle events from the inner [`request_response::Behaviour`] Protocol.
 trait HandleInnerEvent {

protocols/autonat/src/behaviour.rs

@@ -237,7 +237,7 @@ impl NetworkBehaviour for Behaviour {
         handler::relayed::Handler,
         Either<handler::direct::Handler, dummy::ConnectionHandler>,
     >;
-    type OutEvent = Event;
+    type ToSwarm = Event;
 
     fn handle_established_inbound_connection(
         &mut self,
@@ -415,7 +415,7 @@ impl NetworkBehaviour for Behaviour {
         &mut self,
         _cx: &mut Context<'_>,
         _: &mut impl PollParameters,
-    ) -> Poll<ToSwarm<Self::OutEvent, THandlerInEvent<Self>>> {
+    ) -> Poll<ToSwarm<Self::ToSwarm, THandlerInEvent<Self>>> {
         if let Some(event) = self.queued_events.pop_front() {
             return Poll::Ready(event);
         }

protocols/dcutr/src/behaviour_impl.rs

@@ -39,8 +39,8 @@ pub struct Handler {
 }
 
 impl ConnectionHandler for Handler {
-    type InEvent = void::Void;
-    type OutEvent = Event;
+    type FromBehaviour = void::Void;
+    type ToBehaviour = Event;
     type Error = StreamUpgradeError<std::io::Error>;
     type InboundProtocol = DeniedUpgrade;
     type OutboundProtocol = DeniedUpgrade;
@@ -51,7 +51,7 @@ impl ConnectionHandler for Handler {
         SubstreamProtocol::new(DeniedUpgrade, ())
     }
 
-    fn on_behaviour_event(&mut self, _: Self::InEvent) {}
+    fn on_behaviour_event(&mut self, _: Self::FromBehaviour) {}
 
     fn connection_keep_alive(&self) -> KeepAlive {
         KeepAlive::No
@@ -64,7 +64,7 @@ impl ConnectionHandler for Handler {
         ConnectionHandlerEvent<
             Self::OutboundProtocol,
             Self::OutboundOpenInfo,
-            Self::OutEvent,
+            Self::ToBehaviour,
             Self::Error,
         >,
     > {

protocols/dcutr/src/handler/direct.rs

@@ -135,7 +135,7 @@ pub struct Handler {
         ConnectionHandlerEvent<
             <Self as ConnectionHandler>::OutboundProtocol,
             <Self as ConnectionHandler>::OutboundOpenInfo,
-            <Self as ConnectionHandler>::OutEvent,
+            <Self as ConnectionHandler>::ToBehaviour,
             <Self as ConnectionHandler>::Error,
         >,
     >,
@@ -254,8 +254,8 @@ impl Handler {
 }
 
 impl ConnectionHandler for Handler {
-    type InEvent = Command;
-    type OutEvent = Event;
+    type FromBehaviour = Command;
+    type ToBehaviour = Event;
     type Error = StreamUpgradeError<
         Either<protocol::inbound::UpgradeError, protocol::outbound::UpgradeError>,
     >;
@@ -280,7 +280,7 @@ impl ConnectionHandler for Handler {
         }
     }
 
-    fn on_behaviour_event(&mut self, event: Self::InEvent) {
+    fn on_behaviour_event(&mut self, event: Self::FromBehaviour) {
         match event {
             Command::Connect { obs_addrs } => {
                 self.queued_events
@@ -323,7 +323,7 @@ impl ConnectionHandler for Handler {
         ConnectionHandlerEvent<
             Self::OutboundProtocol,
             Self::OutboundOpenInfo,
-            Self::OutEvent,
+            Self::ToBehaviour,
             Self::Error,
         >,
     > {

protocols/dcutr/src/handler/relayed.rs

@@ -137,7 +137,7 @@ fn build_client() -> Swarm<Client> {
 
 #[derive(NetworkBehaviour)]
 #[behaviour(
-    out_event = "ClientEvent",
+    to_swarm = "ClientEvent",
     event_process = false,
     prelude = "libp2p_swarm::derive_prelude"
 )]

protocols/dcutr/tests/lib.rs

@@ -329,7 +329,7 @@ impl Floodsub {
 
 impl NetworkBehaviour for Floodsub {
     type ConnectionHandler = OneShotHandler<FloodsubProtocol, FloodsubRpc, InnerMessage>;
-    type OutEvent = FloodsubEvent;
+    type ToSwarm = FloodsubEvent;
 
     fn handle_established_inbound_connection(
         &mut self,
@@ -470,7 +470,7 @@ impl NetworkBehaviour for Floodsub {
         &mut self,
         _: &mut Context<'_>,
         _: &mut impl PollParameters,
-    ) -> Poll<ToSwarm<Self::OutEvent, THandlerInEvent<Self>>> {
+    ) -> Poll<ToSwarm<Self::ToSwarm, THandlerInEvent<Self>>> {
         if let Some(event) = self.events.pop_front() {
             return Poll::Ready(event);
         }

protocols/floodsub/src/layer.rs

@@ -3307,7 +3307,7 @@ where
     F: Send + 'static + TopicSubscriptionFilter,
 {
     type ConnectionHandler = Handler;
-    type OutEvent = Event;
+    type ToSwarm = Event;
 
     fn handle_established_inbound_connection(
         &mut self,
@@ -3465,7 +3465,7 @@ where
         &mut self,
         cx: &mut Context<'_>,
         _: &mut impl PollParameters,
-    ) -> Poll<ToSwarm<Self::OutEvent, THandlerInEvent<Self>>> {
+    ) -> Poll<ToSwarm<Self::ToSwarm, THandlerInEvent<Self>>> {
         if let Some(event) = self.events.pop_front() {
             return Poll::Ready(event);
         }

protocols/gossipsub/src/behaviour.rs

@@ -225,7 +225,7 @@ impl EnabledHandler {
         ConnectionHandlerEvent<
             <Handler as ConnectionHandler>::OutboundProtocol,
             <Handler as ConnectionHandler>::OutboundOpenInfo,
-            <Handler as ConnectionHandler>::OutEvent,
+            <Handler as ConnectionHandler>::ToBehaviour,
             <Handler as ConnectionHandler>::Error,
         >,
     > {
@@ -393,8 +393,8 @@ impl EnabledHandler {
 }
 
 impl ConnectionHandler for Handler {
-    type InEvent = HandlerIn;
-    type OutEvent = HandlerEvent;
+    type FromBehaviour = HandlerIn;
+    type ToBehaviour = HandlerEvent;
     type Error = Void;
     type InboundOpenInfo = ();
     type InboundProtocol = either::Either<ProtocolConfig, DeniedUpgrade>;
@@ -457,7 +457,7 @@ impl ConnectionHandler for Handler {
         ConnectionHandlerEvent<
             Self::OutboundProtocol,
             Self::OutboundOpenInfo,
-            Self::OutEvent,
+            Self::ToBehaviour,
             Self::Error,
         >,
     > {

protocols/gossipsub/src/handler.rs

@@ -234,7 +234,7 @@ impl Behaviour {
 
 impl NetworkBehaviour for Behaviour {
     type ConnectionHandler = Handler;
-    type OutEvent = Event;
+    type ToSwarm = Event;
 
     #[allow(deprecated)]
     fn handle_established_inbound_connection(
@@ -319,7 +319,7 @@ impl NetworkBehaviour for Behaviour {
         &mut self,
         _cx: &mut Context<'_>,
         _: &mut impl PollParameters,
-    ) -> Poll<ToSwarm<Self::OutEvent, THandlerInEvent<Self>>> {
+    ) -> Poll<ToSwarm<Self::ToSwarm, THandlerInEvent<Self>>> {
         if let Some(event) = self.events.pop_front() {
             return Poll::Ready(event);
         }