swarm/behaviour: Replace inject_* with on_event (#3011)

swarm/src/behaviour.rs

@@ -153,39 +153,90 @@ pub trait NetworkBehaviour: 'static {
         vec![]
     }
 
+    /// Informs the behaviour about an event from the [`Swarm`](crate::Swarm).
+    fn on_swarm_event(&mut self, _event: FromSwarm<Self::ConnectionHandler>) {}
+
+    /// Informs the behaviour about an event generated by the [`ConnectionHandler`] dedicated to the
+    /// peer identified by `peer_id`. for the behaviour.
+    ///
+    /// The [`PeerId`] is guaranteed to be in a connected state. In other words,
+    /// [`FromSwarm::ConnectionEstablished`] has previously been received with this [`PeerId`].
+    fn on_connection_handler_event(
+        &mut self,
+        _peer_id: PeerId,
+        _connection_id: ConnectionId,
+        _event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as
+        ConnectionHandler>::OutEvent,
+    ) {
+    }
+
     /// Informs the behaviour about a newly established connection to a peer.
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::ConnectionEstablished` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
     fn inject_connection_established(
         &mut self,
-        _peer_id: &PeerId,
-        _connection_id: &ConnectionId,
-        _endpoint: &ConnectedPoint,
-        _failed_addresses: Option<&Vec<Multiaddr>>,
-        _other_established: usize,
+        peer_id: &PeerId,
+        connection_id: &ConnectionId,
+        endpoint: &ConnectedPoint,
+        failed_addresses: Option<&Vec<Multiaddr>>,
+        other_established: usize,
     ) {
+        self.on_swarm_event(FromSwarm::ConnectionEstablished(ConnectionEstablished {
+            peer_id: *peer_id,
+            connection_id: *connection_id,
+            endpoint,
+            failed_addresses: failed_addresses
+                .map(|v| v.as_slice())
+                .unwrap_or_else(|| &[]),
+            other_established,
+        }));
     }
 
     /// Informs the behaviour about a closed connection to a peer.
     ///
     /// A call to this method is always paired with an earlier call to
     /// [`NetworkBehaviour::inject_connection_established`] with the same peer ID, connection ID and endpoint.
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::ConnectionClosed` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
     fn inject_connection_closed(
         &mut self,
-        _: &PeerId,
-        _: &ConnectionId,
-        _: &ConnectedPoint,
-        _: <Self::ConnectionHandler as IntoConnectionHandler>::Handler,
-        _remaining_established: usize,
+        peer_id: &PeerId,
+        connection_id: &ConnectionId,
+        endpoint: &ConnectedPoint,
+        handler: <Self::ConnectionHandler as IntoConnectionHandler>::Handler,
+        remaining_established: usize,
     ) {
+        self.on_swarm_event(FromSwarm::ConnectionClosed(ConnectionClosed {
+            peer_id: *peer_id,
+            connection_id: *connection_id,
+            endpoint,
+            handler,
+            remaining_established,
+        }));
     }
 
     /// Informs the behaviour that the [`ConnectedPoint`] of an existing connection has changed.
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::AddressChange` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
     fn inject_address_change(
         &mut self,
-        _: &PeerId,
-        _: &ConnectionId,
-        _old: &ConnectedPoint,
-        _new: &ConnectedPoint,
+        peer_id: &PeerId,
+        connection_id: &ConnectionId,
+        old: &ConnectedPoint,
+        new: &ConnectedPoint,
     ) {
+        self.on_swarm_event(FromSwarm::AddressChange(AddressChange {
+            peer_id: *peer_id,
+            connection_id: *connection_id,
+            old,
+            new,
+        }));
     }
 
     /// Informs the behaviour about an event generated by the handler dedicated to the peer identified by `peer_id`.
@@ -193,20 +244,35 @@ pub trait NetworkBehaviour: 'static {
     ///
     /// The `peer_id` is guaranteed to be in a connected state. In other words,
     /// [`NetworkBehaviour::inject_connection_established`] has previously been called with this `PeerId`.
+    #[deprecated(
+        since = "0.40.2",
+        note = "Implement `NetworkBehaviour::on_connection_handler_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
     fn inject_event(
         &mut self,
         peer_id: PeerId,
         connection: ConnectionId,
         event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent,
-    );
+    ) {
+        self.on_connection_handler_event(peer_id, connection, event);
+    }
 
     /// Indicates to the behaviour that the dial to a known or unknown node failed.
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `InEvent::DialFailure` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
     fn inject_dial_failure(
         &mut self,
-        _peer_id: Option<PeerId>,
-        _handler: Self::ConnectionHandler,
-        _error: &DialError,
+        peer_id: Option<PeerId>,
+        handler: Self::ConnectionHandler,
+        error: &DialError,
     ) {
+        self.on_swarm_event(FromSwarm::DialFailure(DialFailure {
+            peer_id,
+            handler,
+            error,
+        }));
     }
 
     /// Indicates to the behaviour that an error happened on an incoming connection during its
@@ -214,36 +280,98 @@ pub trait NetworkBehaviour: 'static {
     ///
     /// This can include, for example, an error during the handshake of the encryption layer, or the
     /// connection unexpectedly closed.
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::ListenFailure` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
     fn inject_listen_failure(
         &mut self,
-        _local_addr: &Multiaddr,
-        _send_back_addr: &Multiaddr,
-        _handler: Self::ConnectionHandler,
+        local_addr: &Multiaddr,
+        send_back_addr: &Multiaddr,
+        handler: Self::ConnectionHandler,
     ) {
+        self.on_swarm_event(FromSwarm::ListenFailure(ListenFailure {
+            local_addr,
+            send_back_addr,
+            handler,
+        }));
     }
 
     /// Indicates to the behaviour that a new listener was created.
-    fn inject_new_listener(&mut self, _id: ListenerId) {}
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::NewListener` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
+    fn inject_new_listener(&mut self, id: ListenerId) {
+        self.on_swarm_event(FromSwarm::NewListener(NewListener { listener_id: id }));
+    }
 
     /// Indicates to the behaviour that we have started listening on a new multiaddr.
-    fn inject_new_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr) {}
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::NewListenAddr` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
+    fn inject_new_listen_addr(&mut self, id: ListenerId, addr: &Multiaddr) {
+        self.on_swarm_event(FromSwarm::NewListenAddr(NewListenAddr {
+            listener_id: id,
+            addr,
+        }));
+    }
 
     /// Indicates to the behaviour that a multiaddr we were listening on has expired,
-    /// which means that we are no longer listening in it.
-    fn inject_expired_listen_addr(&mut self, _id: ListenerId, _addr: &Multiaddr) {}
+    /// which means that we are no longer listening on it.
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::ExpiredListenAddr` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
+    fn inject_expired_listen_addr(&mut self, id: ListenerId, addr: &Multiaddr) {
+        self.on_swarm_event(FromSwarm::ExpiredListenAddr(ExpiredListenAddr {
+            listener_id: id,
+            addr,
+        }));
+    }
 
     /// A listener experienced an error.
-    fn inject_listener_error(&mut self, _id: ListenerId, _err: &(dyn std::error::Error + 'static)) {
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::ListenerError` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
+    fn inject_listener_error(&mut self, id: ListenerId, err: &(dyn std::error::Error + 'static)) {
+        self.on_swarm_event(FromSwarm::ListenerError(ListenerError {
+            listener_id: id,
+            err,
+        }));
     }
 
     /// A listener closed.
-    fn inject_listener_closed(&mut self, _id: ListenerId, _reason: Result<(), &std::io::Error>) {}
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::ListenerClosed` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
+    fn inject_listener_closed(&mut self, id: ListenerId, reason: Result<(), &std::io::Error>) {
+        self.on_swarm_event(FromSwarm::ListenerClosed(ListenerClosed {
+            listener_id: id,
+            reason,
+        }));
+    }
 
     /// Indicates to the behaviour that we have discovered a new external address for us.
-    fn inject_new_external_addr(&mut self, _addr: &Multiaddr) {}
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::NewExternalAddr` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
+    fn inject_new_external_addr(&mut self, addr: &Multiaddr) {
+        self.on_swarm_event(FromSwarm::NewExternalAddr(NewExternalAddr { addr }));
+    }
 
     /// Indicates to the behaviour that an external address was removed.
-    fn inject_expired_external_addr(&mut self, _addr: &Multiaddr) {}
+    #[deprecated(
+        since = "0.40.2",
+        note = "Handle `FromSwarm::ExpiredExternalAddr` in `NetworkBehaviour::on_swarm_event` instead. The default implementation of this `inject_*` method delegates to it."
+    )]
+    fn inject_expired_external_addr(&mut self, addr: &Multiaddr) {
+        self.on_swarm_event(FromSwarm::ExpiredExternalAddr(ExpiredExternalAddr { addr }));
+    }
 
     /// Polls for things that swarm should do.
     ///
@@ -722,3 +850,364 @@ impl Default for CloseConnection {
         CloseConnection::All
     }
 }
+
+/// Enumeration with the list of the possible events
+/// to pass to [`on_swarm_event`](NetworkBehaviour::on_swarm_event).
+pub enum FromSwarm<'a, Handler: IntoConnectionHandler> {
+    /// Informs the behaviour about a newly established connection to a peer.
+    ConnectionEstablished(ConnectionEstablished<'a>),
+    /// Informs the behaviour about a closed connection to a peer.
+    ///
+    /// This event is always paired with an earlier
+    /// [`FromSwarm::ConnectionEstablished`] with the same peer ID, connection ID
+    /// and endpoint.
+    ConnectionClosed(ConnectionClosed<'a, Handler>),
+    /// Informs the behaviour that the [`ConnectedPoint`] of an existing
+    /// connection has changed.
+    AddressChange(AddressChange<'a>),
+    /// Informs the behaviour that the dial to a known
+    /// or unknown node failed.
+    DialFailure(DialFailure<'a, Handler>),
+    /// Informs the behaviour that an error
+    /// happened on an incoming connection during its initial handshake.
+    ///
+    /// This can include, for example, an error during the handshake of the encryption layer, or the
+    /// connection unexpectedly closed.
+    ListenFailure(ListenFailure<'a, Handler>),
+    /// Informs the behaviour that a new listener was created.
+    NewListener(NewListener),
+    /// Informs the behaviour that we have started listening on a new multiaddr.
+    NewListenAddr(NewListenAddr<'a>),
+    /// Informs the behaviour that a multiaddr
+    /// we were listening on has expired,
+    /// which means that we are no longer listening on it.
+    ExpiredListenAddr(ExpiredListenAddr<'a>),
+    /// Informs the behaviour that a listener experienced an error.
+    ListenerError(ListenerError<'a>),
+    /// Informs the behaviour that a listener closed.
+    ListenerClosed(ListenerClosed<'a>),
+    /// Informs the behaviour that we have discovered a new external address for us.
+    NewExternalAddr(NewExternalAddr<'a>),
+    /// Informs the behaviour that an external address was removed.
+    ExpiredExternalAddr(ExpiredExternalAddr<'a>),
+}
+
+/// [`FromSwarm`] variant that informs the behaviour about a newly established connection to a peer.
+#[derive(Clone, Copy)]
+pub struct ConnectionEstablished<'a> {
+    pub peer_id: PeerId,
+    pub connection_id: ConnectionId,
+    pub endpoint: &'a ConnectedPoint,
+    pub failed_addresses: &'a [Multiaddr],
+    pub other_established: usize,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour about a closed connection to a peer.
+///
+/// This event is always paired with an earlier
+/// [`FromSwarm::ConnectionEstablished`] with the same peer ID, connection ID
+/// and endpoint.
+pub struct ConnectionClosed<'a, Handler: IntoConnectionHandler> {
+    pub peer_id: PeerId,
+    pub connection_id: ConnectionId,
+    pub endpoint: &'a ConnectedPoint,
+    pub handler: <Handler as IntoConnectionHandler>::Handler,
+    pub remaining_established: usize,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that the [`ConnectedPoint`] of an existing
+/// connection has changed.
+#[derive(Clone, Copy)]
+pub struct AddressChange<'a> {
+    pub peer_id: PeerId,
+    pub connection_id: ConnectionId,
+    pub old: &'a ConnectedPoint,
+    pub new: &'a ConnectedPoint,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that the dial to a known
+/// or unknown node failed.
+#[derive(Clone, Copy)]
+pub struct DialFailure<'a, Handler> {
+    pub peer_id: Option<PeerId>,
+    pub handler: Handler,
+    pub error: &'a DialError,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that an error
+/// happened on an incoming connection during its initial handshake.
+///
+/// This can include, for example, an error during the handshake of the encryption layer, or the
+/// connection unexpectedly closed.
+#[derive(Clone, Copy)]
+pub struct ListenFailure<'a, Handler> {
+    pub local_addr: &'a Multiaddr,
+    pub send_back_addr: &'a Multiaddr,
+    pub handler: Handler,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that a new listener was created.
+#[derive(Clone, Copy)]
+pub struct NewListener {
+    pub listener_id: ListenerId,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour
+/// that we have started listening on a new multiaddr.
+#[derive(Clone, Copy)]
+pub struct NewListenAddr<'a> {
+    pub listener_id: ListenerId,
+    pub addr: &'a Multiaddr,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that a multiaddr
+/// we were listening on has expired,
+/// which means that we are no longer listening on it.
+#[derive(Clone, Copy)]
+pub struct ExpiredListenAddr<'a> {
+    pub listener_id: ListenerId,
+    pub addr: &'a Multiaddr,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that a listener experienced an error.
+#[derive(Clone, Copy)]
+pub struct ListenerError<'a> {
+    pub listener_id: ListenerId,
+    pub err: &'a (dyn std::error::Error + 'static),
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that a listener closed.
+#[derive(Clone, Copy)]
+pub struct ListenerClosed<'a> {
+    pub listener_id: ListenerId,
+    pub reason: Result<(), &'a std::io::Error>,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour
+/// that we have discovered a new external address for us.
+#[derive(Clone, Copy)]
+pub struct NewExternalAddr<'a> {
+    pub addr: &'a Multiaddr,
+}
+
+/// [`FromSwarm`] variant that informs the behaviour that an external address was removed.
+#[derive(Clone, Copy)]
+pub struct ExpiredExternalAddr<'a> {
+    pub addr: &'a Multiaddr,
+}
+
+impl<'a, Handler: IntoConnectionHandler> FromSwarm<'a, Handler> {
+    fn map_handler<NewHandler>(
+        self,
+        map_into_handler: impl FnOnce(Handler) -> NewHandler,
+        map_handler: impl FnOnce(
+            <Handler as IntoConnectionHandler>::Handler,
+        ) -> <NewHandler as IntoConnectionHandler>::Handler,
+    ) -> FromSwarm<'a, NewHandler>
+    where
+        NewHandler: IntoConnectionHandler,
+    {
+        self.maybe_map_handler(|h| Some(map_into_handler(h)), |h| Some(map_handler(h)))
+            .expect("To return Some as all closures return Some.")
+    }
+
+    fn maybe_map_handler<NewHandler>(
+        self,
+        map_into_handler: impl FnOnce(Handler) -> Option<NewHandler>,
+        map_handler: impl FnOnce(
+            <Handler as IntoConnectionHandler>::Handler,
+        ) -> Option<<NewHandler as IntoConnectionHandler>::Handler>,
+    ) -> Option<FromSwarm<'a, NewHandler>>
+    where
+        NewHandler: IntoConnectionHandler,
+    {
+        match self {
+            FromSwarm::ConnectionClosed(ConnectionClosed {
+                peer_id,
+                connection_id,
+                endpoint,
+                handler,
+                remaining_established,
+            }) => Some(FromSwarm::ConnectionClosed(ConnectionClosed {
+                peer_id,
+                connection_id,
+                endpoint,
+                handler: map_handler(handler)?,
+                remaining_established,
+            })),
+            FromSwarm::ConnectionEstablished(ConnectionEstablished {
+                peer_id,
+                connection_id,
+                endpoint,
+                failed_addresses,
+                other_established,
+            }) => Some(FromSwarm::ConnectionEstablished(ConnectionEstablished {
+                peer_id,
+                connection_id,
+                endpoint,
+                failed_addresses,
+                other_established,
+            })),
+            FromSwarm::AddressChange(AddressChange {
+                peer_id,
+                connection_id,
+                old,
+                new,
+            }) => Some(FromSwarm::AddressChange(AddressChange {
+                peer_id,
+                connection_id,
+                old,
+                new,
+            })),
+            FromSwarm::DialFailure(DialFailure {
+                peer_id,
+                handler,
+                error,
+            }) => Some(FromSwarm::DialFailure(DialFailure {
+                peer_id,
+                handler: map_into_handler(handler)?,
+                error,
+            })),
+            FromSwarm::ListenFailure(ListenFailure {
+                local_addr,
+                send_back_addr,
+                handler,
+            }) => Some(FromSwarm::ListenFailure(ListenFailure {
+                local_addr,
+                send_back_addr,
+                handler: map_into_handler(handler)?,
+            })),
+            FromSwarm::NewListener(NewListener { listener_id }) => {
+                Some(FromSwarm::NewListener(NewListener { listener_id }))
+            }
+            FromSwarm::NewListenAddr(NewListenAddr { listener_id, addr }) => {
+                Some(FromSwarm::NewListenAddr(NewListenAddr {
+                    listener_id,
+                    addr,
+                }))
+            }
+            FromSwarm::ExpiredListenAddr(ExpiredListenAddr { listener_id, addr }) => {
+                Some(FromSwarm::ExpiredListenAddr(ExpiredListenAddr {
+                    listener_id,
+                    addr,
+                }))
+            }
+            FromSwarm::ListenerError(ListenerError { listener_id, err }) => {
+                Some(FromSwarm::ListenerError(ListenerError { listener_id, err }))
+            }
+            FromSwarm::ListenerClosed(ListenerClosed {
+                listener_id,
+                reason,
+            }) => Some(FromSwarm::ListenerClosed(ListenerClosed {
+                listener_id,
+                reason,
+            })),
+            FromSwarm::NewExternalAddr(NewExternalAddr { addr }) => {
+                Some(FromSwarm::NewExternalAddr(NewExternalAddr { addr }))
+            }
+            FromSwarm::ExpiredExternalAddr(ExpiredExternalAddr { addr }) => {
+                Some(FromSwarm::ExpiredExternalAddr(ExpiredExternalAddr { addr }))
+            }
+        }
+    }
+}
+
+/// Helper function to call [`NetworkBehaviour`]'s `inject_*` methods given a `FromSwarm.
+/// TODO: Remove this function when we remove the remaining `inject_*` calls
+/// from [`Either`] and [`Toggle`].
+pub(crate) fn inject_from_swarm<T: NetworkBehaviour>(
+    behaviour: &mut T,
+    event: FromSwarm<T::ConnectionHandler>,
+) {
+    match event {
+        FromSwarm::ConnectionEstablished(ConnectionEstablished {
+            peer_id,
+            connection_id,
+            endpoint,
+            failed_addresses,
+            other_established,
+        }) => {
+            #[allow(deprecated)]
+            behaviour.inject_connection_established(
+                &peer_id,
+                &connection_id,
+                endpoint,
+                Some(&failed_addresses.into()),
+                other_established,
+            );
+        }
+        FromSwarm::ConnectionClosed(ConnectionClosed {
+            peer_id,
+            connection_id,
+            endpoint,
+            handler,
+            remaining_established,
+        }) => {
+            #[allow(deprecated)]
+            behaviour.inject_connection_closed(
+                &peer_id,
+                &connection_id,
+                endpoint,
+                handler,
+                remaining_established,
+            );
+        }
+        FromSwarm::AddressChange(AddressChange {
+            peer_id,
+            connection_id,
+            old,
+            new,
+        }) => {
+            #[allow(deprecated)]
+            behaviour.inject_address_change(&peer_id, &connection_id, old, new);
+        }
+        FromSwarm::DialFailure(DialFailure {
+            peer_id,
+            handler,
+            error,
+        }) => {
+            #[allow(deprecated)]
+            behaviour.inject_dial_failure(peer_id, handler, error);
+        }
+        FromSwarm::ListenFailure(ListenFailure {
+            local_addr,
+            send_back_addr,
+            handler,
+        }) => {
+            #[allow(deprecated)]
+            behaviour.inject_listen_failure(local_addr, send_back_addr, handler);
+        }
+        FromSwarm::NewListener(NewListener { listener_id }) => {
+            #[allow(deprecated)]
+            behaviour.inject_new_listener(listener_id);
+        }
+        FromSwarm::NewListenAddr(NewListenAddr { listener_id, addr }) => {
+            #[allow(deprecated)]
+            behaviour.inject_new_listen_addr(listener_id, addr);
+        }
+        FromSwarm::ExpiredListenAddr(ExpiredListenAddr { listener_id, addr }) => {
+            #[allow(deprecated)]
+            behaviour.inject_expired_listen_addr(listener_id, addr);
+        }
+        FromSwarm::ListenerError(ListenerError { listener_id, err }) => {
+            #[allow(deprecated)]
+            behaviour.inject_listener_error(listener_id, err);
+        }
+        FromSwarm::ListenerClosed(ListenerClosed {
+            listener_id,
+            reason,
+        }) => {
+            #[allow(deprecated)]
+            behaviour.inject_listener_closed(listener_id, reason);
+        }
+        FromSwarm::NewExternalAddr(NewExternalAddr { addr }) => {
+            #[allow(deprecated)]
+            behaviour.inject_new_external_addr(addr);
+        }
+        FromSwarm::ExpiredExternalAddr(ExpiredExternalAddr { addr }) =>
+        {
+            #[allow(deprecated)]
+            behaviour.inject_expired_external_addr(addr)
+        }
+    }
+}