Merge remote-tracking branch 'origin/master' into streaming-response-…

…protocol

CHANGELOG.md

@@ -54,6 +54,7 @@
     - `libp2p-relay`
     - `libp2p-request-response`
     - `libp2p-swarm`
+    - `libp2p-wasm-ext`
 
 ## Version 0.36.0 [2021-03-17]
 

Cargo.toml

@@ -82,7 +82,7 @@ libp2p-streaming-response = { version = "0.1.0", path = "protocols/streaming-res
 libp2p-swarm = { version = "0.29.0", path = "swarm" }
 libp2p-swarm-derive = { version = "0.22.0", path = "swarm-derive" }
 libp2p-uds = { version = "0.28.0", path = "transports/uds", optional = true }
-libp2p-wasm-ext = { version = "0.28.0", path = "transports/wasm-ext", default-features = false, optional = true }
+libp2p-wasm-ext = { version = "0.28.1", path = "transports/wasm-ext", default-features = false, optional = true }
 libp2p-yamux = { version = "0.31.0", path = "muxers/yamux", optional = true }
 multiaddr = { package = "parity-multiaddr", version = "0.11.2", path = "misc/multiaddr" }
 parking_lot = "0.11.0"

README.md

@@ -52,6 +52,21 @@ The main components of this repository are structured as follows:
   * `examples/`: Worked examples of built-in application protocols (see `protocols/`)
     with common `Transport` configurations.
 
+## Community Guidelines
+
+The libp2p project operates under the [IPFS Code of
+Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+
+> tl;dr
+>
+> - Be respectful.
+> - We're here to help: abuse@ipfs.io
+> - Abusive behavior is never tolerated.
+> - Violations of this code may result in swift and permanent expulsion from the
+>   IPFS [and libp2p] community.
+> - "Too long, didn't read" is not a valid excuse for not knowing what is in
+>   this document.
+
 ## Notable users
 
 (open a pull request if you want your project to be added here)

examples/ping.rs

@@ -18,7 +18,9 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-//! A basic example demonstrating some core APIs and concepts of libp2p.
+//! Ping example
+//!
+//! See ../src/tutorial.rs for a step-by-step guide building the example below.
 //!
 //! In the first terminal window, run:
 //!
@@ -38,22 +40,20 @@
 //! The two nodes establish a connection, negotiate the ping protocol
 //! and begin pinging each other.
 
-use async_std::task;
-use futures::{future, prelude::*};
-use libp2p::{identity, PeerId, ping::{Ping, PingConfig}, Swarm};
-use std::{error::Error, task::{Context, Poll}};
-
-#[async_std::main]
-async fn main() -> Result<(), Box<dyn Error>> {
-    env_logger::init();
+use futures::executor::block_on;
+use futures::prelude::*;
+use libp2p::ping::{Ping, PingConfig};
+use libp2p::swarm::Swarm;
+use libp2p::{identity, PeerId};
+use std::error::Error;
+use std::task::Poll;
 
-    // Create a random PeerId.
-    let id_keys = identity::Keypair::generate_ed25519();
-    let peer_id = PeerId::from(id_keys.public());
-    println!("Local peer id: {:?}", peer_id);
+fn main() -> Result<(), Box<dyn Error>> {
+    let local_key = identity::Keypair::generate_ed25519();
+    let local_peer_id = PeerId::from(local_key.public());
+    println!("Local peer id: {:?}", local_peer_id);
 
-    // Create a transport.
-    let transport = libp2p::development_transport(id_keys).await?;
+    let transport = block_on(libp2p::development_transport(local_key))?;
 
     // Create a ping network behaviour.
     //
@@ -62,9 +62,11 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // can be observed.
     let behaviour = Ping::new(PingConfig::new().with_keep_alive(true));
 
-    // Create a Swarm that establishes connections through the given transport
-    // and applies the ping behaviour on each connection.
-    let mut swarm = Swarm::new(transport, behaviour, peer_id);
+    let mut swarm = Swarm::new(transport, behaviour, local_peer_id);
+
+    // Tell the swarm to listen on all interfaces and a random, OS-assigned
+    // port.
+    swarm.listen_on("/ip4/0.0.0.0/tcp/0".parse()?)?;
 
     // Dial the peer identified by the multi-address given as the second
     // command-line argument, if any.
@@ -74,24 +76,19 @@ async fn main() -> Result<(), Box<dyn Error>> {
         println!("Dialed {}", addr)
     }
 
-    // Tell the swarm to listen on all interfaces and a random, OS-assigned port.
-    swarm.listen_on("/ip4/0.0.0.0/tcp/0".parse()?)?;
-
     let mut listening = false;
-    task::block_on(future::poll_fn(move |cx: &mut Context<'_>| {
-        loop {
-            match swarm.poll_next_unpin(cx) {
-                Poll::Ready(Some(event)) => println!("{:?}", event),
-                Poll::Ready(None) => return Poll::Ready(()),
-                Poll::Pending => {
-                    if !listening {
-                        for addr in Swarm::listeners(&swarm) {
-                            println!("Listening on {}", addr);
-                            listening = true;
-                        }
+    block_on(future::poll_fn(move |cx| loop {
+        match swarm.poll_next_unpin(cx) {
+            Poll::Ready(Some(event)) => println!("{:?}", event),
+            Poll::Ready(None) => return Poll::Ready(()),
+            Poll::Pending => {
+                if !listening {
+                    for addr in Swarm::listeners(&swarm) {
+                        println!("Listening on {}", addr);
+                        listening = true;
                     }
-                    return Poll::Pending
                 }
+                return Poll::Pending;
             }
         }
     }));

protocols/gossipsub/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 - Update `libp2p-swarm`.
 
+- Update dependencies.
+
 # 0.29.0 [2021-03-17]
 
 - Update `libp2p-swarm`.

protocols/gossipsub/Cargo.toml

@@ -37,7 +37,7 @@ libp2p-mplex = { path = "../../muxers/mplex" }
 libp2p-noise = { path = "../../transports/noise" }
 quickcheck = "0.9.2"
 hex = "0.4.2"
-derive_builder = "0.9.0"
+derive_builder = "0.10.0"
 
 [build-dependencies]
 prost-build = "0.7"

src/lib.rs

@@ -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,