feat(swarm)!: introduce ListenError (#3375)

In case an error happens for an outgoing connection, `Pool` reports an `OutgoingConnectionError`. This one is mapped to a `DialError` and reported via `SwarmEvent::OutgoingConnectionError` and `FromSwarm::DialFailure`.

For incoming connections, we didn't quite do the same thing. For one, `SwarmEvent::IncomingConnectionError` directly contained a `PendingInboundConnectionError`. Two, `FromSwarm::ListenFailure` did not include an error at all.

With this patch, we now introduce a `ListenError` enum which we use in `SwarmEvent::IncomingConnectionError` and we pass a reference to it along in `FromSwarm::ListenFailure`.

swarm/src/lib.rs

@@ -221,7 +221,7 @@ pub enum SwarmEvent<TBehaviourOutEvent, THandlerErr> {
         /// Address used to send back data to the remote.
         send_back_addr: Multiaddr,
     },
-    /// An error happened on a connection during its initial handshake.
+    /// An error happened on an inbound connection during its initial handshake.
     ///
     /// This can include, for example, an error during the handshake of the encryption layer, or
     /// the connection unexpectedly closed.
@@ -233,9 +233,9 @@ pub enum SwarmEvent<TBehaviourOutEvent, THandlerErr> {
         /// Address used to send back data to the remote.
         send_back_addr: Multiaddr,
         /// The error that happened.
-        error: PendingInboundConnectionError,
+        error: ListenError,
     },
-    /// Outgoing connection attempt failed.
+    /// An error happened on an outbound connection.
     OutgoingConnectionError {
         /// If known, [`PeerId`] of the peer we tried to reach.
         peer_id: Option<PeerId>,
@@ -850,11 +850,14 @@ where
                 error,
                 handler,
             } => {
+                let error = error.into();
+
                 log::debug!("Incoming connection failed: {:?}", error);
                 self.behaviour
                     .on_swarm_event(FromSwarm::ListenFailure(ListenFailure {
                         local_addr: &local_addr,
                         send_back_addr: &send_back_addr,
+                        error: &error,
                         handler,
                     }));
                 return Some(SwarmEvent::IncomingConnectionError {
@@ -970,10 +973,13 @@ where
                         });
                     }
                     Err((connection_limit, handler)) => {
+                        let error = ListenError::ConnectionLimit(connection_limit);
+
                         self.behaviour
                             .on_swarm_event(FromSwarm::ListenFailure(ListenFailure {
                                 local_addr: &local_addr,
                                 send_back_addr: &send_back_addr,
+                                error: &error,
                                 handler,
                             }));
                         log::warn!("Incoming connection rejected: {:?}", connection_limit);
@@ -1572,7 +1578,7 @@ where
     }
 }
 
-/// The possible failures of dialing.
+/// Possible errors when trying to establish or upgrade an outbound connection.
 #[derive(Debug)]
 pub enum DialError {
     /// The peer is currently banned.
@@ -1681,6 +1687,80 @@ impl error::Error for DialError {
     }
 }
 
+/// Possible errors when upgrading an inbound connection.
+#[derive(Debug)]
+pub enum ListenError {
+    /// The configured limit for simultaneous outgoing connections
+    /// has been reached.
+    ConnectionLimit(ConnectionLimit),
+    /// Pending connection attempt has been aborted.
+    Aborted,
+    /// The peer identity obtained on the connection did not match the one that was expected.
+    WrongPeerId {
+        obtained: PeerId,
+        endpoint: ConnectedPoint,
+    },
+    /// The peer identity obtained on the connection did not match the one that was expected.
+    LocalPeerId { endpoint: ConnectedPoint },
+    /// An error occurred while negotiating the transport protocol(s) on a connection.
+    Transport(TransportError<io::Error>),
+}
+
+impl From<PendingInboundConnectionError> for ListenError {
+    fn from(error: PendingInboundConnectionError) -> Self {
+        match error {
+            PendingInboundConnectionError::Transport(inner) => ListenError::Transport(inner),
+            PendingInboundConnectionError::ConnectionLimit(inner) => {
+                ListenError::ConnectionLimit(inner)
+            }
+            PendingInboundConnectionError::Aborted => ListenError::Aborted,
+            PendingInboundConnectionError::WrongPeerId { obtained, endpoint } => {
+                ListenError::WrongPeerId { obtained, endpoint }
+            }
+            PendingInboundConnectionError::LocalPeerId { endpoint } => {
+                ListenError::LocalPeerId { endpoint }
+            }
+        }
+    }
+}
+
+impl fmt::Display for ListenError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ListenError::ConnectionLimit(_) => write!(f, "Listen error"),
+            ListenError::Aborted => write!(
+                f,
+                "Listen error: Pending connection attempt has been aborted."
+            ),
+            ListenError::WrongPeerId { obtained, endpoint } => write!(
+                f,
+                "Listen error: Unexpected peer ID {obtained} at {endpoint:?}."
+            ),
+            ListenError::Transport(_) => {
+                write!(f, "Listen error: Failed to negotiate transport protocol(s)")
+            }
+            ListenError::LocalPeerId { endpoint } => {
+                write!(
+                    f,
+                    "Listen error: Pending connection: Local peer ID at {endpoint:?}."
+                )
+            }
+        }
+    }
+}
+
+impl error::Error for ListenError {
+    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
+        match self {
+            ListenError::ConnectionLimit(err) => Some(err),
+            ListenError::WrongPeerId { .. } => None,
+            ListenError::Transport(err) => Some(err),
+            ListenError::Aborted => None,
+            ListenError::LocalPeerId { .. } => None,
+        }
+    }
+}
+
 /// Information about the connections obtained by [`Swarm::network_info()`].
 #[derive(Clone, Debug)]
 pub struct NetworkInfo {
@@ -2327,7 +2407,7 @@ mod tests {
                                 network_1_established = true;
                             }
                             Poll::Ready(Some(SwarmEvent::IncomingConnectionError {
-                                error: PendingConnectionError::ConnectionLimit(err),
+                                error: ListenError::ConnectionLimit(err),
                                 ..
                             })) => {
                                 assert_eq!(err.limit, limit);