fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-06-16 03:21:22 +00:00
Code Issues Projects Releases Wiki Activity

src: Move introduction to new tutorial.rs (#2018)

Browse Source 
This commit extends the ping example in `src/tutorial.rs, by walking a
newcomer through the implementation of a simple ping node step-by-step,
introducing all the core libp2p concepts along the way.

With the ping tutorial in place, there is no need for the lengthy libp2p
crate level introduction, which is thus removed with this commit.

Co-authored-by: Roman Borschel <romanb@users.noreply.github.com>
This commit is contained in:
Max Inden
2021-04-01 15:46:41 +02:00
committed by GitHub
parent a0bdc206dc
commit a2e774992d
3 changed files with 394 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
src/lib.rs
View File

@ -18,138 +18,17 @@
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//! Libp2p is a peer-to-peer framework.
//! libp2p is a modular peer-to-peer networking framework.
//!
//! # Major libp2p concepts
//! To learn more about the general libp2p multi-language framework visit
//! [libp2p.io](https://libp2p.io/).
//!
//! Here is a list of all the major concepts of libp2p.
//! To get started with this libp2p implementation in Rust, please take a look
//! at the [`tutorial`](crate::tutorial). Further examples can be found in the
//! [examples] directory.
//!
//! ## Multiaddr
//!
//! A [`Multiaddr`] is a self-describing network address and protocol stack
//! that is used to establish connections to peers. Some examples:
//!
//! * `/ip4/80.123.90.4/tcp/5432`
//! * `/ip6/[::1]/udp/10560/quic`
//! * `/unix//path/to/socket`
//!
//! ## Transport
//!
//! [`Transport`] is a trait for types that provide connection-oriented communication channels
//! based on dialing to or listening on a [`Multiaddr`]. To that end a transport
//! produces as output a type of data stream that varies depending on the concrete type of
//! transport.
//!
//! An implementation of transport typically supports only certain multi-addresses.
//! For example, the [`TcpConfig`] only supports multi-addresses of the format
//! `/ip4/.../tcp/...`.
//!
//! Example (Dialing a TCP/IP multi-address):
//!
//! ```rust
//! use libp2p::{Multiaddr, Transport, tcp::TcpConfig};
//! let tcp = TcpConfig::new();
//! let addr: Multiaddr = "/ip4/98.97.96.95/tcp/20500".parse().expect("invalid multiaddr");
//! let _conn = tcp.dial(addr);
//! ```
//! In the above example, `_conn` is a [`Future`] that needs to be polled in order for
//! the dialing to take place and eventually resolve to a connection. Polling
//! futures is typically done through a [tokio] runtime.
//!
//! The easiest way to create a transport is to use [`development_transport`].
//! This function provides support for the most common protocols but it is also
//! subject to change over time and should thus not be used in production
//! configurations.
//!
//! Example (Creating a development transport):
//!
//! ```rust
//! let keypair = libp2p::identity::Keypair::generate_ed25519();
//! let _transport = libp2p::development_transport(keypair);
//! // _transport.await?.dial(...);
//! ```
//!
//! The keypair that is passed as an argument in the above example is used
//! to set up transport-layer encryption using a newly generated long-term
//! identity keypair. The public key of this keypair uniquely identifies
//! the node in the network in the form of a [`PeerId`].
//!
//! See the documentation of the [`Transport`] trait for more details.
//!
//! ### Connection Upgrades
//!
//! Once a connection has been established with a remote through a [`Transport`], it can be
//! *upgraded*. Upgrading a transport is the process of negotiating an additional protocol
//! with the remote, mediated through a negotiation protocol called [`multistream-select`].
//!
//! Example ([`noise`] + [`yamux`] Protocol Upgrade):
//!
//! ```rust
//! # #[cfg(all(not(any(target_os = "emscripten", target_os = "wasi", target_os = "unknown")), feature = "tcp-async-io", feature = "noise", feature = "yamux"))] {
//! use libp2p::{Transport, core::upgrade, tcp::TcpConfig, noise, identity::Keypair, yamux};
//! let tcp = TcpConfig::new();
//! let id_keys = Keypair::generate_ed25519();
//! let noise_keys = noise::Keypair::<noise::X25519Spec>::new().into_authentic(&id_keys).unwrap();
//! let noise = noise::NoiseConfig::xx(noise_keys).into_authenticated();
//! let yamux = yamux::YamuxConfig::default();
//! let transport = tcp.upgrade(upgrade::Version::V1).authenticate(noise).multiplex(yamux);
//! # }
//! ```
//! In this example, `transport` is a new [`Transport`] that negotiates the
//! noise and yamux protocols on all connections.
//!
//! ## Network Behaviour
//!
//! The [`NetworkBehaviour`] trait is implemented on types that provide some capability to the
//! network. Examples of network behaviours include:
//!
//! * Periodically pinging other nodes on established connections.
//! * Periodically asking for information from other nodes.
//! * Querying information from a DHT and propagating it to other nodes.
//!
//! ## Swarm
//!
//! A [`Swarm`] manages a pool of connections established through a [`Transport`]
//! and drives a [`NetworkBehaviour`] through emitting events triggered by activity
//! on the managed connections. Creating a [`Swarm`] thus involves combining a
//! [`Transport`] with a [`NetworkBehaviour`].
//!
//! See the documentation of the [`core`] module for more details about swarms.
//!
//! # Using libp2p
//!
//! The easiest way to get started with libp2p involves the following steps:
//!
//! 1. Creating an identity [`Keypair`] for the local node, obtaining the local
//! [`PeerId`] from the [`PublicKey`].
//! 2. Creating an instance of a base [`Transport`], e.g. [`TcpConfig`], upgrading it with
//! all the desired protocols, such as for transport security and multiplexing.
//! In order to be usable with a [`Swarm`] later, the [`Output`](Transport::Output)
//! of the final transport must be a tuple of a [`PeerId`] and a value whose type
//! implements [`StreamMuxer`] (e.g. [`Yamux`]). The peer ID must be the
//! identity of the remote peer of the established connection, which is
//! usually obtained through a transport encryption protocol such as
//! [`noise`] that authenticates the peer. See the implementation of
//! [`development_transport`] for an example.
//! 3. Creating a struct that implements the [`NetworkBehaviour`] trait and combines all the
//! desired network behaviours, implementing the event handlers as per the
//! desired application's networking logic.
//! 4. Instantiating a [`Swarm`] with the transport, the network behaviour and the
//! local peer ID from the previous steps.
//!
//! The swarm instance can then be polled e.g. with the [tokio] library, in order to
//! continuously drive the network activity of the program.
//!
//! [`Keypair`]: identity::Keypair
//! [`PublicKey`]: identity::PublicKey
//! [`Future`]: futures::Future
//! [`TcpConfig`]: tcp::TcpConfig
//! [`NetworkBehaviour`]: swarm::NetworkBehaviour
//! [`StreamMuxer`]: core::muxing::StreamMuxer
//! [`Yamux`]: yamux::Yamux
//!
//! [tokio]: https://tokio.rs
//! [`multistream-select`]: https://github.com/multiformats/multistream-select
//! [examples]: https://github.com/libp2p/rust-libp2p/tree/master/examples
//! [ping tutorial]: https://github.com/libp2p/rust-libp2p/tree/master/examples/ping.rs
#![doc(html_logo_url = "https://libp2p.io/img/logo_small.png")]
#![doc(html_favicon_url = "https://libp2p.io/img/favicon.png")]
@ -252,6 +131,9 @@ mod transport_ext;
pub mod bandwidth;
pub mod simple;
#[cfg(doc)]
pub mod tutorial;
pub use self::core::{
identity,
PeerId,