From 2dea51cd3b97cf127ce442422ccfbfaca39b12e2 Mon Sep 17 00:00:00 2001
From: Pierre Krieger <pierre.krieger1708@gmail.com>
Date: Mon, 6 May 2019 13:10:37 +0200
Subject: [PATCH] Add some crate-level documentation to network-libp2p (#2483)
---
substrate/core/network-libp2p/src/lib.rs | 84 +++++++++++++++++++++++-
1 file changed, 83 insertions(+), 1 deletion(-)
diff --git a/substrate/core/network-libp2p/src/lib.rs b/substrate/core/network-libp2p/src/lib.rs
index 3876ac9e5fb..6e4b2e4784a 100644
--- a/substrate/core/network-libp2p/src/lib.rs
+++ b/substrate/core/network-libp2p/src/lib.rs
@@ -16,7 +16,89 @@
//! Networking layer of Substrate.
//!
-//! **Important**: This crate is unstable and the API and usage may change.
+//! # Overview
+//!
+//! This crate handles the following network mechanisms:
+//!
+//! - Discovering nodes that are part of the network.
+//! - Connecting to said nodes and accepting incoming connections.
+//! - Encrypting communications between nodes.
+//! - Ensure that nodes are really the `PeerId` that they pretend to be.
+//! - Ensuring that the nodes belong to the same chain as us before reporting a new connection.
+//!
+//! From the point of view of our node, each other node on the network has a reputation value in
+//! the form of an `i32`. We try to establish connections towards nodes with a higher reputation
+//! over nodes with a lower reputation.
+//!
+//! Establishing connections to other nodes is automatically performed by this crate, and there is
+//! no way to influence this, except by adjusting reputations.
+//!
+//! ## About the term "connecting"
+//!
+//! The documentation of this crate uses the words "connected" and "disconnected". It is important
+//! to note that this doesn't correspond to actual TCP/IP connections and disconnections. Libp2p
+//! will maintain connections that aren't reported by the API of this crate, and TCP/IP connections
+//! can be kept alive even after we have reported a disconnect in order to potentially reuse them.
+//!
+//! # Usage
+//!
+//! > **Important**: This crate is unstable and the API and usage may change.
+//!
+//! The first step is to crate a [`RegisteredProtocol`] describing the protocol, and a
+//! [`NetworkConfiguration`] describing the network. Then call [`start_service`] with them, which
+//! returns a [`Service`] object and a [`substrate_peerset::PeersetHandle`].
+//!
+//! The former allows you to know what happens on the network and to send messages, while the
+//! latter can be used to adjust the reputations of nodes.
+//!
+//! You must call the `poll` method of [`Service`] in order to make the network progress and in
+//! order to update the internal state of the [`Service`]. Calling `poll` will produce
+//! [`ServiceEvent`]s, which inform you of what happened on the network.
+//!
+//! Please keep in mind that the state of the [`Service`] only updates itself in a way
+//! corresponding to the [`ServiceEvent`] that `poll` returns.
+//!
+//! Illustration:
+//!
+//! - You call [`Service::connected_peers`] to get the list of nodes we are connected to.
+//! - If you then call [`Service::connected_peers`] again, the returned list will always be the
+//! same, no matter what happened on the wire.
+//! - If you then call [`Service::poll`] and a [`ServiceEvent::OpenedCustomProtocol`] event is
+//! returned, then the concerned node, and only the concerned node, will be added to the list of
+//! nodes we are connected to.
+//! - Similarly, if [`Service::poll`] produces a [`ServiceEvent::ClosedCustomProtocol`] event, then
+//! only the concerned node will disappear from the list.
+//! - And if [`Service::poll`] returns neither [`ServiceEvent::OpenedCustomProtocol`] nor
+//! [`ServiceEvent::ClosedCustomProtocol`], then the list of connected nodes doesn't change.
+//!
+//! ## Example
+//!
+//! ```no_run
+//! # use futures::prelude::*;
+//! use substrate_network_libp2p::ServiceEvent;
+//!
+//! let proto = substrate_network_libp2p::RegisteredProtocol::new(&b"hello"[..], &[0]);
+//! let config = substrate_network_libp2p::NetworkConfiguration::default();
+//! let (mut service, _peerset) = substrate_network_libp2p::start_service(config, proto).unwrap();
+//!
+//! tokio::run(futures::future::poll_fn(move || {
+//! loop {
+//! match service.poll().unwrap() {
+//! Async::NotReady => return Ok(Async::NotReady),
+//! Async::Ready(Some(ServiceEvent::OpenedCustomProtocol { peer_id, .. })) => {
+//! println!("now connected to {:?}", peer_id);
+//! service.send_custom_message(&peer_id, b"hello world!".to_vec());
+//! }
+//! Async::Ready(Some(ServiceEvent::ClosedCustomProtocol { peer_id, .. })) =>
+//! println!("now disconnected from {:?}", peer_id),
+//! Async::Ready(Some(ServiceEvent::CustomMessage { peer_id, message })) =>
+//! println!("received message from {:?}: {:?}", peer_id, message),
+//! Async::Ready(None) => return Ok(Async::Ready(())),
+//! _ => {}
+//! }
+//! }
+//! }));
+//! ```
//!
mod behaviour;
--
GitLab