Full support for multiple connections per peer in libp2p-swarm. (#1519)

* [libp2p-swarm] Make the multiple connections per peer first-class.

This commit makes the notion of multiple connections per peer
first-class in the API of libp2p-swarm, introducing the new
callbacks `inject_connection_established` and
`inject_connection_closed`. The `endpoint` parameter from
`inject_connected` and `inject_disconnected` is removed,
since the first connection to open may not be the last
connection to close, i.e. it cannot be guaranteed,
as was previously the case, that the endpoints passed
to these callbacks match up.

* Have identify track all addresses.

So that identify requests can be answered with the correct
observed address of the connection on which the request
arrives.

* Cleanup

* Cleanup

* Improve the `Peer` state API.

* Remove connection ID from `SwarmEvent::Dialing`.

* Mark `DialPeerCondition` non-exhaustive.

* Re-encapsulate `NetworkConfig`.

To retain the possibility of not re-exposing all
network configuration choices, thereby providing
a more convenient API on the \`SwarmBuilder\`.

* Rework Swarm::dial API.

* Update CHANGELOG.

* Doc formatting tweaks.

swarm/src/behaviour.rs

@@ -72,18 +72,34 @@ pub trait NetworkBehaviour: Send + 'static {
     /// address should be the most likely to be reachable.
     fn addresses_of_peer(&mut self, peer_id: &PeerId) -> Vec<Multiaddr>;
 
-    /// Indicates the behaviour that we connected to the node with the given peer id through the
-    /// given endpoint.
+    /// Indicates the behaviour that we connected to the node with the given peer id.
     ///
     /// This node now has a handler (as spawned by `new_handler`) running in the background.
-    fn inject_connected(&mut self, peer_id: PeerId, endpoint: ConnectedPoint);
+    ///
+    /// This method is only called when the connection to the peer is
+    /// established, preceded by `inject_connection_established`.
+    fn inject_connected(&mut self, peer_id: &PeerId);
 
-    /// Indicates the behaviour that we disconnected from the node with the given peer id. The
-    /// endpoint is the one we used to be connected to.
+    /// Indicates the behaviour that we disconnected from the node with the given peer id.
     ///
     /// There is no handler running anymore for this node. Any event that has been sent to it may
     /// or may not have been processed by the handler.
-    fn inject_disconnected(&mut self, peer_id: &PeerId, endpoint: ConnectedPoint);
+    ///
+    /// This method is only called when the last established connection to the peer
+    /// is closed, preceded by `inject_connection_closed`.
+    fn inject_disconnected(&mut self, peer_id: &PeerId);
+
+    /// Informs the behaviour about a newly established connection to a peer.
+    fn inject_connection_established(&mut self, _: &PeerId, _: &ConnectionId, _: &ConnectedPoint)
+    {}
+
+    /// Informs the behaviour about a closed connection to a peer.
+    ///
+    /// A call to this method is always paired with an earlier call to
+    /// `inject_connection_established` with the same peer ID, connection ID and
+    /// endpoint.
+    fn inject_connection_closed(&mut self, _: &PeerId, _: &ConnectionId, _: &ConnectedPoint)
+    {}
 
     /// Informs the behaviour about an event generated by the handler dedicated to the peer identified by `peer_id`.
     /// for the behaviour.
@@ -204,6 +220,8 @@ pub enum NetworkBehaviourAction<TInEvent, TOutEvent> {
     DialPeer {
         /// The peer to try reach.
         peer_id: PeerId,
+        /// The condition for initiating a new dialing attempt.
+        condition: DialPeerCondition,
     },
 
     /// Instructs the `Swarm` to send an event to the handler dedicated to a
@@ -253,3 +271,37 @@ pub enum NotifyHandler {
     All
 }
 
+/// The available conditions under which a new dialing attempt to
+/// a peer is initiated when requested by [`NetworkBehaviourAction::DialPeer`].
+#[derive(Debug, Copy, Clone)]
+#[non_exhaustive]
+pub enum DialPeerCondition {
+    /// A new dialing attempt is initiated _only if_ the peer is currently
+    /// considered disconnected, i.e. there is no established connection
+    /// and no ongoing dialing attempt.
+    ///
+    /// If there is an ongoing dialing attempt, the addresses reported by
+    /// [`NetworkBehaviour::addresses_of_peer`] are added to the ongoing
+    /// dialing attempt, ignoring duplicates.
+    Disconnected,
+    /// A new dialing attempt is initiated _only if_ there is currently
+    /// no ongoing dialing attempt, i.e. the peer is either considered
+    /// disconnected or connected but without an ongoing dialing attempt.
+    ///
+    /// If there is an ongoing dialing attempt, the addresses reported by
+    /// [`NetworkBehaviour::addresses_of_peer`] are added to the ongoing
+    /// dialing attempt, ignoring duplicates.
+    ///
+    /// This condition implies [`DialPeerCondition::Disconnected`].
+    NotDialing,
+    // TODO: Once multiple dialing attempts per peer are permitted.
+    //       See https://github.com/libp2p/rust-libp2p/pull/1506.
+    // Always,
+}
+
+impl Default for DialPeerCondition {
+    fn default() -> Self {
+        DialPeerCondition::Disconnected
+    }
+}
+