fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-07-02 11:11:36 +00:00
Code Issues Projects Releases Wiki Activity

Some changes to the main libp2p doc (#710)

Browse Source 
* Some changes to the main libp2p doc

* Update src/lib.rs

Co-Authored-By: tomaka <pierre.krieger1708@gmail.com>
This commit is contained in:
Pierre Krieger
2018-12-04 13:33:07 +01:00
committed by GitHub
parent b5d12e0afc
commit b727cad62a
1 changed files with 29 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
src/lib.rs
View File

@ -29,7 +29,7 @@
//! A `Multiaddr` is a way to reach a node. Examples: //! A `Multiaddr` is a way to reach a node. Examples:
//! //!
//! * `/ip4/80.123.90.4/tcp/5432` //! * `/ip4/80.123.90.4/tcp/5432`
//! * `/ip6/[::1]/udp/10560` //! * `/ip6/[::1]/udp/10560/quic`
//! * `/unix//path/to/socket` //! * `/unix//path/to/socket`
//! //!
//! ## Transport //! ## Transport
@ -69,22 +69,8 @@
//! # Connection upgrades //! # Connection upgrades
//! //!
//! Once a connection has been opened with a remote through a `Transport`, it can be *upgraded*. //! Once a connection has been opened with a remote through a `Transport`, it can be *upgraded*.
//! This consists in negotiating a protocol with the remote (through the `multistream-select` //! This consists in negotiating a protocol with the remote (through a negotiation protocol
//! protocol), and applying that protocol on the socket. //! `multistream-select`), and applying that protocol on the socket.
//!
//! Example upgrades:
//!
//! - Adding a security layer on top of the connection.
//! - Applying multiplexing, so that a connection can be split into multiple substreams.
//! - Negotiating a specific protocol, such as *ping* or *kademlia*.
//!
//! A potential connection upgrade is represented with the `ConnectionUpgrade` trait. The trait
//! consists in a protocol name plus a method that turns the socket into an `Output` object whose
//! nature and type is specific to each upgrade. For example, if you upgrade a connection with a
//! security layer, the output might contain an encrypted stream and the public key of the remote.
//!
//! You can combine a `Transport` with a compatible `ConnectionUpgrade` in order to obtain another
//! `Transport` that yields the output of the upgrade.
//! //!
//! Example: //! Example:
//! //!
@ -102,12 +88,29 @@
//! //!
//! See the documentation of the `libp2p-core` crate for more details about upgrades. //! See the documentation of the `libp2p-core` crate for more details about upgrades.
//! //!
//! ## Topology
//!
//! The `Topology` trait is implemented for types that hold the layout of a network. When other
//! components need the network layout to operate, they are passed an instance of a `Topology`.
//!
//! The most basic implementation of `Topology` is the `MemoryTopology`, which is essentially a
//! `HashMap`. Creating your own `Topology` makes it possible to add for example a reputation
//! system.
//!
//! ## Network behaviour
//!
//! The `NetworkBehaviour` trait is implemented on types that provide some capability to the
//! network. Examples of network behaviours include: periodically ping the nodes we are connected
//! to, periodically ask for information from the nodes we are connected to, connect to a DHT and
//! make queries to it, propagate messages to the nodes we are connected to (pubsub), and so on.
//!
//! ## Swarm //! ## Swarm
//! //!
//! Once you have created an object that implements the `Transport` trait, you can put it in a //! The `Swarm` struct contains all active and pending connections to remotes and manages the
//! *swarm*. This is done by calling the `swarm()` freestanding function with the transport //! state of all the substreams that have been opened, and all the upgrades that were built upon
//! alongside with a function or a closure that will turn the output of the upgrade (usually an //! these substreams.
//! actual protocol, as explained above) into a `Future` producing `()`. //!
//! It combines a `Transport`, a `NetworkBehaviour` and a `Topology` together.
//! //!
//! See the documentation of the `libp2p-core` crate for more details about creating a swarm. //! See the documentation of the `libp2p-core` crate for more details about creating a swarm.
//! //!
@ -119,15 +122,11 @@
//! //!
//! - Create a *base* implementation of `Transport` that combines all the protocols you want and //! - Create a *base* implementation of `Transport` that combines all the protocols you want and
//! the upgrades you want, such as the security layer and multiplexing. //! the upgrades you want, such as the security layer and multiplexing.
//! - Create structs that implement the `ConnectionUpgrade` trait for the protocols you want to //! - Create a struct that implements the `NetworkBehaviour` trait and that combines all the
//! create, or use the protocols provided by the `libp2p` crate. //! network behaviours that you want.
//! - Create a swarm that combines your base transport and all the upgrades and that handles the //! - Create and implement the `Topology` trait that to store the topology of the network.
//! behaviour that happens. //! - Create a swarm that combines your base transport, the network behaviour, and the topology.
//! - Use this swarm to dial and listen. //! - This swarm can now be polled with the `tokio` library in order to start the network.
//!
//! You probably also want to have some sort of nodes discovery mechanism, so that you
//! automatically connect to nodes of the network. The details of this haven't been fleshed out
//! in libp2p and will be written later.
//! //!
pub extern crate bytes; pub extern crate bytes;