Move swarm and protocols handler into swarm crate. (#1188)

Move swarm and protocols handler into swarm crate.

swarm/src/behaviour.rs

@@ -0,0 +1,221 @@
+// Copyright 2019 Parity Technologies (UK) Ltd.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the "Software"),
+// to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+// and/or sell copies of the Software, and to permit persons to whom the
+// Software is furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+use crate::protocols_handler::{IntoProtocolsHandler, ProtocolsHandler};
+use libp2p_core::{ConnectedPoint, Multiaddr, PeerId};
+use futures::prelude::*;
+use std::error;
+
+/// A behaviour for the network. Allows customizing the swarm.
+///
+/// This trait has been designed to be composable. Multiple implementations can be combined into
+/// one that handles all the behaviours at once.
+pub trait NetworkBehaviour {
+    /// Handler for all the protocols the network behaviour supports.
+    type ProtocolsHandler: IntoProtocolsHandler;
+
+    /// Event generated by the `NetworkBehaviour` and that the swarm will report back.
+    type OutEvent;
+
+    /// Creates a new `ProtocolsHandler` for a connection with a peer.
+    ///
+    /// Every time an incoming connection is opened, and every time we start dialing a node, this
+    /// method is called.
+    ///
+    /// The returned object is a handler for that specific connection, and will be moved to a
+    /// background task dedicated to that connection.
+    ///
+    /// The network behaviour (ie. the implementation of this trait) and the handlers it has
+    /// spawned (ie. the objects returned by `new_handler`) can communicate by passing messages.
+    /// Messages sent from the handler to the behaviour are injected with `inject_node_event`, and
+    /// the behaviour can send a message to the handler by making `poll` return `SendEvent`.
+    fn new_handler(&mut self) -> Self::ProtocolsHandler;
+
+    /// Addresses that this behaviour is aware of for this specific peer, and that may allow
+    /// reaching the peer.
+    ///
+    /// The addresses will be tried in the order returned by this function, which means that they
+    /// should be ordered by decreasing likelihood of reachability. In other words, the first
+    /// 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.
+    ///
+    /// 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);
+
+    /// 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.
+    ///
+    /// 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);
+
+    /// Indicates the behaviour that we replace the connection from the node with another.
+    ///
+    /// The handler that used to be dedicated to this node has been destroyed and replaced with a
+    /// new one. Any event that has been sent to it may or may not have been processed.
+    ///
+    /// The default implementation of this method calls `inject_disconnected` followed with
+    /// `inject_connected`. This is a logically safe way to implement this behaviour. However, you
+    /// may want to overwrite this method in the situations where this isn't appropriate.
+    fn inject_replaced(&mut self, peer_id: PeerId, closed_endpoint: ConnectedPoint, new_endpoint: ConnectedPoint) {
+        self.inject_disconnected(&peer_id, closed_endpoint);
+        self.inject_connected(peer_id, new_endpoint);
+    }
+
+    /// Informs the behaviour about an event generated by the handler dedicated to the peer identified by `peer_id`.
+    /// for the behaviour.
+    ///
+    /// The `peer_id` is guaranteed to be in a connected state. In other words, `inject_connected`
+    /// has previously been called with this `PeerId`.
+    fn inject_node_event(
+        &mut self,
+        peer_id: PeerId,
+        event: <<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::OutEvent
+    );
+
+    /// Indicates to the behaviour that we tried to reach an address, but failed.
+    ///
+    /// If we were trying to reach a specific node, its ID is passed as parameter. If this is the
+    /// last address to attempt for the given node, then `inject_dial_failure` is called afterwards.
+    fn inject_addr_reach_failure(&mut self, _peer_id: Option<&PeerId>, _addr: &Multiaddr, _error: &dyn error::Error) {
+    }
+
+    /// Indicates to the behaviour that we tried to dial all the addresses known for a node, but
+    /// failed.
+    ///
+    /// The `peer_id` is guaranteed to be in a disconnected state. In other words,
+    /// `inject_connected` has not been called, or `inject_disconnected` has been called since then.
+    fn inject_dial_failure(&mut self, _peer_id: &PeerId) {
+    }
+
+    /// Indicates to the behaviour that we have started listening on a new multiaddr.
+    fn inject_new_listen_addr(&mut self, _addr: &Multiaddr) {
+    }
+
+    /// Indicates to the behaviour that a new multiaddr we were listening on has expired,
+    /// which means that we are no longer listening in it.
+    fn inject_expired_listen_addr(&mut self, _addr: &Multiaddr) {
+    }
+
+    /// Indicates to the behaviour that we have discovered a new external address for us.
+    fn inject_new_external_addr(&mut self, _addr: &Multiaddr) {
+    }
+
+    /// Polls for things that swarm should do.
+    ///
+    /// This API mimics the API of the `Stream` trait. The method may register the current task in
+    /// order to wake it up at a later point in time.
+    fn poll(&mut self, params: &mut impl PollParameters)
+        -> Async<NetworkBehaviourAction<<<Self::ProtocolsHandler as IntoProtocolsHandler>::Handler as ProtocolsHandler>::InEvent, Self::OutEvent>>;
+}
+
+/// Parameters passed to `poll()`, that the `NetworkBehaviour` has access to.
+pub trait PollParameters {
+    /// Iterator returned by [`supported_protocols`].
+    type SupportedProtocolsIter: ExactSizeIterator<Item = Vec<u8>>;
+    /// Iterator returned by [`listened_addresses`].
+    type ListenedAddressesIter: ExactSizeIterator<Item = Multiaddr>;
+    /// Iterator returned by [`external_addresses`].
+    type ExternalAddressesIter: ExactSizeIterator<Item = Multiaddr>;
+
+    /// Returns the list of protocol the behaviour supports when a remote negotiates a protocol on
+    /// an inbound substream.
+    ///
+    /// The iterator's elements are the ASCII names as reported on the wire.
+    ///
+    /// Note that the list is computed once at initialization and never refreshed.
+    fn supported_protocols(&self) -> Self::SupportedProtocolsIter;
+
+    /// Returns the list of the addresses we're listening on.
+    fn listened_addresses(&self) -> Self::ListenedAddressesIter;
+
+    /// Returns the list of the addresses nodes can use to reach us.
+    fn external_addresses(&self) -> Self::ExternalAddressesIter;
+
+    /// Returns the peer id of the local node.
+    fn local_peer_id(&self) -> &PeerId;
+}
+
+/// Used when deriving `NetworkBehaviour`. When deriving `NetworkBehaviour`, must be implemented
+/// for all the possible event types generated by the various fields.
+// TODO: document how the custom behaviour works and link this here
+pub trait NetworkBehaviourEventProcess<TEvent> {
+    /// Called when one of the fields of the type you're deriving `NetworkBehaviour` on generates
+    /// an event.
+    fn inject_event(&mut self, event: TEvent);
+}
+
+/// An action that a [`NetworkBehaviour`] can trigger in the [`Swarm`]
+/// in whose context it is executing.
+#[derive(Debug, Clone)]
+pub enum NetworkBehaviourAction<TInEvent, TOutEvent> {
+    /// Instructs the `Swarm` to return an event when it is being polled.
+    GenerateEvent(TOutEvent),
+
+    /// Instructs the swarm to dial the given multiaddress, with no knowledge of the `PeerId` that
+    /// may be reached.
+    DialAddress {
+        /// The address to dial.
+        address: Multiaddr,
+    },
+
+    /// Instructs the swarm to dial a known `PeerId`.
+    ///
+    /// The `addresses_of_peer` method is called to determine which addresses to attempt to reach.
+    ///
+    /// If we were already trying to dial this node, the addresses that are not yet in the queue of
+    /// addresses to try are added back to this queue.
+    ///
+    /// On success, [`NetworkBehaviour::inject_connected`] is invoked.
+    /// On failure, [`NetworkBehaviour::inject_dial_failure`] is invoked.
+    DialPeer {
+        /// The peer to try reach.
+        peer_id: PeerId,
+    },
+
+    /// Instructs the `Swarm` to send a message to the handler dedicated to the connection with the peer.
+    ///
+    /// If the `Swarm` is connected to the peer, the message is delivered to the remote's
+    /// protocol handler. If there is no connection to the peer, the message is ignored.
+    /// To ensure delivery, the `NetworkBehaviour` must keep track of connected peers.
+    ///
+    /// Note that even if the peer is currently connected, connections can get closed
+    /// at any time and thus the message may not reach its destination.
+    SendEvent {
+        /// The peer to which to send the message.
+        peer_id: PeerId,
+        /// The message to send.
+        event: TInEvent,
+    },
+
+    /// Informs the `Swarm` about a multi-address observed by a remote for
+    /// the local node.
+    ///
+    /// It is advisable to issue `ReportObservedAddr` actions at a fixed frequency
+    /// per node. This way address information will be more accurate over time
+    /// and individual outliers carry less weight.
+    ReportObservedAddr {
+        /// The observed address of the local node.
+        address: Multiaddr,
+    },
+}