diff --git a/core/src/lib.rs b/core/src/lib.rs index 9d1cab6c..c0a8160c 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -52,6 +52,14 @@ //! how to handle incoming substreams, which protocols are supported, when to open a new //! outbound substream, etc. See the `protocols_handler` trait. //! +//! # High-level APIs vs low-level APIs +//! +//! This crate provides two sets of APIs: +//! +//! - The low-level APIs are contained within the `nodes` module. See the documentation for more +//! information. +//! - The high-level APIs include the concepts of `Swarm`, `ProtocolsHandler`, `NetworkBehaviour` +//! and `Topology`. /// Multi-address re-export. diff --git a/core/src/nodes/listeners.rs b/core/src/nodes/listeners.rs index c37d806c..5190f541 100644 --- a/core/src/nodes/listeners.rs +++ b/core/src/nodes/listeners.rs @@ -18,6 +18,8 @@ // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER // DEALINGS IN THE SOFTWARE. +//! Manage listening on multiple multiaddresses at once. + use futures::prelude::*; use std::fmt; use void::Void; diff --git a/core/src/nodes/mod.rs b/core/src/nodes/mod.rs index 1d78ea7b..a5d74d33 100644 --- a/core/src/nodes/mod.rs +++ b/core/src/nodes/mod.rs @@ -18,6 +18,14 @@ // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER // DEALINGS IN THE SOFTWARE. +//! Low-level networking primitives. +//! +//! Contains structs that are aiming at providing very precise control over what happens over the +//! network. +//! +//! The more complete and highest-level struct is the `RawSwarm`. The `RawSwarm` directly or +//! indirectly uses all the other structs of this module. + pub mod collection; pub mod handled_node; pub mod handled_node_tasks; diff --git a/core/src/protocols_handler/mod.rs b/core/src/protocols_handler/mod.rs index 1fd5795d..0741b2c3 100644 --- a/core/src/protocols_handler/mod.rs +++ b/core/src/protocols_handler/mod.rs @@ -18,6 +18,21 @@ // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER // DEALINGS IN THE SOFTWARE. +//! Once we are connected to a node, a *protocols handler* handles one or more specific protocols +//! on this connection. +//! +//! This includes: how to handle incoming substreams, which protocols are supported, when to open +//! a new outbound substream, and so on. +//! +//! Each implementation of the `ProtocolsHandler` trait handles one or more specific protocols. +//! Two `ProtocolsHandler`s can be combined together with the `select()` method in order to build +//! a `ProtocolsHandler` that combines both. This can be repeated multiple times in order to create +//! a handler that handles all the protocols that you wish. +//! +//! > **Note**: A `ProtocolsHandler` handles one or more protocols in relation to a specific +//! > connection with a remote. In order to handle a protocol that requires knowledge of +//! > the network as a whole, see the `NetworkBehaviour` trait. + use crate::upgrade::{ InboundUpgrade, OutboundUpgrade, @@ -49,14 +64,15 @@ mod select; /// Communication with a remote over a set of protocols opened in two different ways: /// /// - Dialing, which is a voluntary process. In order to do so, make `poll()` return an -/// `OutboundSubstreamRequest` variant containing the connection upgrade to use to start using a protocol. +/// `OutboundSubstreamRequest` variant containing the connection upgrade to use to start using a +/// protocol. /// - Listening, which is used to determine which protocols are supported when the remote wants /// to open a substream. The `listen_protocol()` method should return the upgrades supported when /// listening. /// /// The upgrade when dialing and the upgrade when listening have to be of the same type, but you -/// are free to return for example an `OrUpgrade` enum, or an enum of your own, containing the upgrade -/// you want depending on the situation. +/// are free to return for example an `OrUpgrade` enum, or an enum of your own, containing the +/// upgrade you want depending on the situation. /// /// # Shutting down /// @@ -72,19 +88,6 @@ mod select; /// might already be closed or unresponsive. They should therefore not rely on being able to /// deliver messages. /// -/// # Relationship with `NodeHandler`. -/// -/// This trait is very similar to the `NodeHandler` trait. The fundamental differences are: -/// -/// - The `NodeHandler` trait gives you more control and is therefore more difficult to implement. -/// - The `NodeHandler` trait is designed to have exclusive ownership of the connection to a -/// node, while the `ProtocolsHandler` trait is designed to handle only a specific set of -/// protocols. Two or more implementations of `ProtocolsHandler` can be combined into one that -/// supports all the protocols together, which is not possible with `NodeHandler`. -/// -// TODO: add a "blocks connection closing" system, so that we can gracefully close a connection -// when it's no longer needed, and so that for example the periodic pinging system does not -// keep the connection alive forever pub trait ProtocolsHandler { /// Custom event that can be received from the outside. type InEvent; diff --git a/core/src/swarm.rs b/core/src/swarm.rs index 24b76dee..46a6e124 100644 --- a/core/src/swarm.rs +++ b/core/src/swarm.rs @@ -18,6 +18,29 @@ // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER // DEALINGS IN THE SOFTWARE. +//! High level manager of the network. +//! +//! The `Swarm` struct contains the state of the network as a whole. The entire behaviour of a +//! libp2p network can be controlled through the `Swarm`. +//! +//! # Initializing a Swarm +//! +//! Creating a `Swarm` requires three things: +//! +//! - An implementation of the `Transport` trait. This is the type that will be used in order to +//! reach nodes on the network based on their address. See the `transport` module for more +//! information. +//! - An implementation of the `NetworkBehaviour` trait. This is a state machine that defines how +//! the swarm should behave once it is connected to a node. +//! - An implementation of the `Topology` trait. This is a container that holds the list of nodes +//! that we think are part of the network. See the `topology` module for more information. +//! +//! # Network behaviour +//! +//! The `NetworkBehaviour` trait is implemented on types that indicate to the swarm how it should +//! behave. This includes which protocols are supported and which nodes to try to connect to. +//! + use crate::{ Transport, Multiaddr, PublicKey, PeerId, InboundUpgrade, OutboundUpgrade, UpgradeInfo, ProtocolName, muxing::StreamMuxer, @@ -347,7 +370,7 @@ pub trait NetworkBehaviourEventProcess { fn inject_event(&mut self, event: TEvent); } -/// Parameters passed to `poll()` that the `NetworkBehaviour` has access to. +/// Parameters passed to `poll()`, that the `NetworkBehaviour` has access to. // TODO: #[derive(Debug)] pub struct PollParameters<'a, TTopology: 'a> { topology: &'a mut TTopology, diff --git a/core/src/topology/mod.rs b/core/src/topology/mod.rs index 466da486..a7bb2afe 100644 --- a/core/src/topology/mod.rs +++ b/core/src/topology/mod.rs @@ -18,6 +18,19 @@ // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER // DEALINGS IN THE SOFTWARE. +//! A *network topology* is a collection of nodes that are part of the network or that we think +//! are part of the network. In other words, it is essentially a container whose layout is +//! optimized for certain operations. +//! +//! In libp2p, a *topology* is any struct that implements at least the `Topology` trait. In order +//! to build a `Swarm`, you have to give to it ownership of a type that implements this trait. +//! +//! In order to use some protocols defined outside of `libp2p-core` (such as Kademlia) in your +//! `Swarm`, you will have to implement additional traits on your topology. +//! +//! While the `MemoryTopology` is provided as a ready-to-go topology that is suitable for quick +//! prototyping, it shouldn't be used in an actual high-performance production software. + use std::collections::HashMap; use crate::{Multiaddr, PeerId, PublicKey}; diff --git a/core/src/transport/mod.rs b/core/src/transport/mod.rs index 75b10486..1bf56e37 100644 --- a/core/src/transport/mod.rs +++ b/core/src/transport/mod.rs @@ -20,14 +20,11 @@ //! Handles entering a connection with a peer. //! -//! The two main elements of this module are the `Transport` and `ConnectionUpgrade` traits. -//! `Transport` is implemented on objects that allow dialing and listening. `ConnectionUpgrade` is -//! implemented on objects that make it possible to upgrade a connection (for example by adding an -//! encryption middleware to the connection). +//! The main element of this module is the `Transport` trait. It is implemented on objects that +//! allow dialing and listening. //! -//! Thanks to the `Transport::or_transport`, `Transport::with_upgrade` and -//! `UpgradedNode::or_upgrade` methods, you can combine multiple transports and/or upgrades -//! together in a complex chain of protocols negotiation. +//! The rest of the module holds combinators that allow tweaking an implementation of `Transport`, +//! combine multiple transports together, or combine a transport with an upgrade. use crate::{InboundUpgrade, OutboundUpgrade, nodes::raw_swarm::ConnectedPoint}; use futures::prelude::*;