fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-06-20 13:26:34 +00:00
Code Issues Projects Releases Wiki Activity

Documentation updates (#1005)

Browse Source 
* Documentation updates:

  * libp2p: Update the top-level module documentation, already including
    intra-rustdoc links, removing outdated documentation, updating examples and
    polishing the text.

  * libp2p-core: Update the transport documentation to clarify that a `Transport`
    is really an abstraction only for connection-oriented transports.

* More links

* Fix typo.

* Address review comments.

* More doc tweaks.

  * Mention the necessity of creating an identity keypair.
  * Remove another mention of the removed Topology trait.
This commit is contained in:
Roman Borschel
2019-03-19 12:45:57 +01:00
committed by GitHub
parent 463e1a5837
commit 9575fa6c08
6 changed files with 193 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
core/src/lib.rs
View File

@ -42,8 +42,6 @@
//! - Use the `NetworkBehaviour` trait to customize the behaviour of a `Swarm`. It is the
//! `NetworkBehaviour` that controls what happens on the network. Multiple types that implement
//! `NetworkBehaviour` can be composed into a single behaviour.
//! - 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 `StreamMuxer` trait is implemented on structs that hold a connection to a remote and can
//! subdivide this connection into multiple substreams. See the `muxing` module.
//! - The `UpgradeInfo`, `InboundUpgrade` and `OutboundUpgrade` traits define how to upgrade each
@ -58,8 +56,7 @@
//!
//! - 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`.
//! - The high-level APIs include the concepts of `Swarm`, `ProtocolsHandler` and `NetworkBehaviour`.
/// Multi-address re-export.

17
core/src/swarm.rs
View File

@ -20,22 +20,21 @@
//! High level manager of the network.
//!
//! The `Swarm` struct contains the state of the network as a whole. The entire behaviour of a
//! A [`Swarm`] 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.
//! 1. A network identity of the local node in form of a [`PeerId`].
//! 2. 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.
//! 3. 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.
//!
//! # Network behaviour
//! # 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.

164
core/src/transport/mod.rs
View File

@ -18,13 +18,12 @@
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//! Handles entering a connection with a peer.
//! Connection-oriented communication channels.
//!
//! The main element of this module is the `Transport` trait. It is implemented on objects that
//! allow dialing and listening.
//!
//! 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.
//! The main entity of this module is the [`Transport`] trait, which provides an
//! interface for establishing connections with other nodes, thereby negotiating
//! any desired protocols. The rest of the module defines combinators for
//! modifying a transport through composition with other transports or protocol upgrades.
use crate::{InboundUpgrade, OutboundUpgrade, nodes::raw_swarm::ConnectedPoint};
use futures::prelude::*;
@ -47,73 +46,103 @@ pub use self::choice::OrTransport;
pub use self::memory::MemoryTransport;
pub use self::upgrade::Upgrade;
/// A transport is an object that can be used to produce connections by listening or dialing a
/// peer.
/// A transport provides connection-oriented communication between two peers
/// through ordered streams of data (i.e. connections).
///
/// This trait is implemented on concrete transports (e.g. TCP, UDP, etc.), but also on wrappers
/// around them.
/// Connections are established either by [listening](Transport::listen_on)
/// or [dialing](Transport::dial) on a [`Transport`]. A peer that
/// obtains a connection by listening is often referred to as the *listener* and the
/// peer that initiated the connection through dialing as the *dialer*, in
/// contrast to the traditional roles of *server* and *client*.
///
/// Most transports also provide a form of reliable delivery on the established
/// connections but the precise semantics of these guarantees depend on the
/// specific transport.
///
/// This trait is implemented for concrete connection-oriented transport protocols
/// like TCP or Unix Domain Sockets, but also on wrappers that add additional
/// functionality to the dialing or listening process (e.g. name resolution via
/// the DNS).
///
/// Additional protocols can be layered on top of the connections established
/// by a [`Transport`] through an upgrade mechanism that is initiated via
/// [`with_upgrade`](Transport::with_upgrade) and optionally followed by further upgrades
/// through chaining calls to [`with_upgrade`](Transport::with_upgrade) and
/// [`and_then`](Transport::and_then). Thereby every upgrade yields a new [`Transport`]
/// whose connection setup incorporates all earlier upgrades followed by the new upgrade,
/// i.e. the order of the upgrades is significant.
///
/// > **Note**: The methods of this trait use `self` and not `&self` or `&mut self`. In other
/// > words, listening or dialing consumes the transport object. This has been designed
/// > so that you would implement this trait on `&Foo` or `&mut Foo` instead of directly
/// > on `Foo`.
pub trait Transport {
/// The raw connection to a peer.
/// The result of a connection setup process, including protocol upgrades.
///
/// Typically the output contains at least a handle to a data stream (i.e. a
/// connection or a substream multiplexer on top of a connection) that
/// provides APIs for sending and receiving data through the connection.
type Output;
/// Error that can happen when dialing or listening.
/// An error that occurred during connection setup.
type Error: error::Error;
/// The listener produces incoming connections.
/// A stream of [`Output`](Transport::Output)s for inbound connections.
///
/// An item should be produced whenever a connection is received at the lowest level of the
/// transport stack. The item is a `Future` that is signalled once some pre-processing has
/// taken place, and that connection has been upgraded to the wanted protocols.
/// transport stack. The item must be a [`ListenerUpgrade`](Transport::ListenerUpgrade) future
/// that resolves to an [`Output`](Transport::Output) value once all protocol upgrades
/// have been applied.
type Listener: Stream<Item = (Self::ListenerUpgrade, Multiaddr), Error = Self::Error>;
/// After a connection has been received, we may need to do some asynchronous pre-processing
/// on it (e.g. an intermediary protocol negotiation). While this pre-processing takes place,
/// we want to be able to continue polling on the listener.
/// A pending [`Output`](Transport::Output) for an inbound connection,
/// obtained from the [`Listener`](Transport::Listener) stream.
///
/// After a connection has been accepted by the transport, it may need to go through
/// asynchronous post-processing (i.e. protocol upgrade negotiations). Such
/// post-processing should not block the `Listener` from producing the next
/// connection, hence further connection setup proceeds asynchronously.
/// Once a `ListenerUpgrade` future resolves it yields the [`Output`](Transport::Output)
/// of the connection setup process.
type ListenerUpgrade: Future<Item = Self::Output, Error = Self::Error>;
/// A future which indicates that we are currently dialing to a peer.
/// A pending [`Output`](Transport::Output) for an outbound connection,
/// obtained from [dialing](Transport::dial).
type Dial: Future<Item = Self::Output, Error = Self::Error>;
/// Listen on the given multiaddr. Returns a stream of incoming connections, plus a modified
/// version of the `Multiaddr`. This new `Multiaddr` is the one that that should be advertised
/// to other nodes, instead of the one passed as parameter.
/// Listens on the given [`Multiaddr`], producing a stream of pending, inbound connections.
///
/// > **Note**: The reason why we need to change the `Multiaddr` on success is to handle
/// > situations such as turning `/ip4/127.0.0.1/tcp/0` into
/// > `/ip4/127.0.0.1/tcp/<actual port>`.
/// > **Note**: The new [`Multiaddr`] that is returned alongside the connection stream
/// > is the address that should be advertised to other nodes, as the given address
/// > may be subject to changes such as an OS-assigned port number.
fn listen_on(self, addr: Multiaddr) -> Result<(Self::Listener, Multiaddr), TransportError<Self::Error>>
where
Self: Sized;
/// Dial the given multi-addr.
/// Dials the given [`Multiaddr`], returning a future for a pending outbound connection.
///
/// Returns either a future which may resolve to a connection.
///
/// If `MultiaddrNotSupported` is returned, then caller can try another implementation of
/// `Transport` if there is any. If instead an error is returned, then we assume that there is
/// no point in trying another `Transport`.
/// If [`TransportError::MultiaddrNotSupported`] is returned, it may be desirable to
/// try an alternative [`Transport`], if available.
fn dial(self, addr: Multiaddr) -> Result<Self::Dial, TransportError<Self::Error>>
where
Self: Sized;
/// Takes a multiaddress we're listening on (`server`), and tries to convert it to an
/// externally-visible multiaddress. In order to do so, we pass an `observed` address which
/// a remote node observes for one of our dialers.
/// Takes a [`Multiaddr`] that represents a listening address together with an
/// an address observed by another node and tries to incoporate information
/// from the observed address into the listening address, yielding an
/// externally-visible address.
///
/// For example, if `server` is `/ip4/0.0.0.0/tcp/3000` and `observed` is
/// `/ip4/80.81.82.83/tcp/29601`, then we should return `/ip4/80.81.82.83/tcp/3000`.
/// In order to do so, `observed` must be an address that a remote node observes on an
/// inbound connection from the local node. Each [`Transport`] implementation is only
/// responsible for handling the protocols it supports and should only consider the
/// prefix of `observed` necessary to perform the address translation
/// (e.g. `/ip4/80.81.82.83`) but should otherwise preserve `server` as is. For example,
/// if `server` is the address `/ip4/0.0.0.0/tcp/3000` and `observed` is the address
/// `/ip4/80.81.82.83/tcp/29601`, then the address `/ip4/80.81.82.83/tcp/3000` should be
/// returned.
///
/// Each implementation of `Transport` is only responsible for handling the protocols it
/// supports and should only consider the prefix of `observed` necessary to perform the
/// address translation (e.g. `/ip4/80.81.82.83`) but should otherwise preserve `server`
/// as is.
///
/// Returns `None` if nothing can be determined. This happens if this trait implementation
/// doesn't recognize the protocols, or if `server` and `observed` are not related.
/// Returns `None` if the transport does not recognize a protocol, or if `server` and
/// `observed` are unrelated addresses.
fn nat_traversal(&self, server: &Multiaddr, observed: &Multiaddr) -> Option<Multiaddr>;
/// Turns this `Transport` into an abstract boxed transport.
@ -127,7 +156,7 @@ pub trait Transport {
boxed::boxed(self)
}
/// Applies a function on the output of the `Transport`.
/// Applies a function on the connections created by the transport.
#[inline]
fn map<F, O>(self, map: F) -> map::Map<Self, F>
where
@ -137,7 +166,7 @@ pub trait Transport {
map::Map::new(self, map)
}
/// Applies a function on the errors generated by the futures of the `Transport`.
/// Applies a function on the errors generated by the futures of the transport.
#[inline]
fn map_err<F, TNewErr>(self, map_err: F) -> map_err::MapErr<Self, F>
where
@ -147,9 +176,10 @@ pub trait Transport {
map_err::MapErr::new(self, map_err)
}
/// Builds a new struct that implements `Transport` that contains both `self` and `other`.
/// Builds a new transport that falls back to another transport when
/// encountering errors on dialing or listening for connections.
///
/// The returned object will redirect its calls to `self`, except that if `listen_on` or `dial`
/// The returned transport will act like `self`, except that if `listen_on` or `dial`
/// return an error then `other` will be tried.
#[inline]
fn or_transport<T>(self, other: T) -> OrTransport<Self, T>
@ -159,11 +189,13 @@ pub trait Transport {
OrTransport::new(self, other)
}
/// Wraps this transport inside an upgrade. Whenever a connection that uses this transport
/// is established, it is wrapped inside the upgrade.
/// Wraps this transport inside an [`Upgrade`].
///
/// > **Note**: The concept of an *upgrade* for example includes middlewares such *secio*
/// > (communication encryption), *multiplex*, but also a protocol handler.
/// Whenever an inbound or outbound connection is established by this
/// transport, the upgrade is applied on the current state of the
/// connection (which may have already gone through previous upgrades)
/// as an [`upgrade::InboundUpgrade`] or [`upgrade::OutboundUpgrade`],
/// respectively.
#[inline]
fn with_upgrade<U, O, E>(self, upgrade: U) -> Upgrade<Self, U>
where
@ -175,11 +207,12 @@ pub trait Transport {
Upgrade::new(self, upgrade)
}
/// Wraps this transport inside an upgrade. Whenever a connection that uses this transport
/// is established, it is wrapped inside the upgrade.
/// Applies a function producing an asynchronous result to every connection
/// created by this transport.
///
/// > **Note**: The concept of an *upgrade* for example includes middlewares such *secio*
/// > (communication encryption), *multiplex*, but also a protocol handler.
/// This function can be used for ad-hoc protocol upgrades on a transport or
/// for processing or adapting the output of an earlier upgrade before
/// applying the next upgrade.
#[inline]
fn and_then<C, F, O>(self, upgrade: C) -> and_then::AndThen<Self, C>
where
@ -190,8 +223,8 @@ pub trait Transport {
and_then::AndThen::new(self, upgrade)
}
/// Adds a timeout to the connection and upgrade steps for all the sockets created by
/// the transport.
/// Adds a timeout to the connection setup (including upgrades) for all inbound
/// and outbound connection attempts.
#[inline]
fn with_timeout(self, timeout: Duration) -> timeout::TransportTimeout<Self>
where
@ -200,8 +233,8 @@ pub trait Transport {
timeout::TransportTimeout::new(self, timeout)
}
/// Adds a timeout to the connection and upgrade steps for all the outgoing sockets created
/// by the transport.
/// Adds a timeout to the connection setup (including upgrades) for all outbound
/// connection attempts.
#[inline]
fn with_outbound_timeout(self, timeout: Duration) -> timeout::TransportTimeout<Self>
where
@ -210,8 +243,8 @@ pub trait Transport {
timeout::TransportTimeout::with_outgoing_timeout(self, timeout)
}
/// Adds a timeout to the connection and upgrade steps for all the incoming sockets created
/// by the transport.
/// Adds a timeout to the connection setup (including upgrades) for all inbound
/// connection attempts.
#[inline]
fn with_inbound_timeout(self, timeout: Duration) -> timeout::TransportTimeout<Self>
where
@ -221,20 +254,21 @@ pub trait Transport {
}
}
/// Error that can happen when dialing or listening.
/// An error during [dialing][Transport::dial] or [listening][Transport::listen_on]
/// on a [`Transport`].
#[derive(Debug, Clone)]
pub enum TransportError<TErr> {
/// The `Multiaddr` passed as parameter is not supported.
/// The [`Multiaddr`] passed as parameter is not supported.
///
/// Contains back the same address.
MultiaddrNotSupported(Multiaddr),
/// Any other error that the `Transport` may produce.
/// Any other error that a [`Transport`] may produce.
Other(TErr),
}
impl<TErr> TransportError<TErr> {
/// Applies a map to the `Other` variant.
/// Applies a function to the the error in [`TransportError::Other`].
#[inline]
pub fn map<TNewErr>(self, map: impl FnOnce(TErr) -> TNewErr) -> TransportError<TNewErr> {
match self {

12
core/src/transport/timeout.rs
View File

@ -18,9 +18,10 @@
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//! Wraps around a `Transport` and adds a timeout to all the incoming and outgoing connections.
//! Transports with timeouts on the connection setup.
//!
//! The timeout includes the upgrading process.
//! The connection setup includes all protocol upgrades applied on the
//! underlying `Transport`.
// TODO: add example
use crate::{Multiaddr, Transport, transport::TransportError};
@ -30,10 +31,11 @@ use std::{error, fmt, time::Duration};
use tokio_timer::Timeout;
use tokio_timer::timeout::Error as TimeoutError;
/// Wraps around a `Transport` and adds a timeout to all the incoming and outgoing connections.
/// A `TransportTimeout` is a `Transport` that wraps another `Transport` and adds
/// timeouts to all inbound and outbound connection attempts.
///
/// The timeout includes the upgrade. There is no timeout on the listener or on stream of incoming
/// substreams.
/// **Note**: `listen_on` is never subject to a timeout, only the setup of each
/// individual accepted connection.
#[derive(Debug, Copy, Clone)]
pub struct TransportTimeout<InnerTrans> {
inner: InnerTrans,

2
muxers/yamux/src/lib.rs
View File

@ -127,8 +127,6 @@ where
}
}
#[derive(Clone)]
pub struct Config(yamux::Config);

136
src/lib.rs
View File

@ -26,7 +26,8 @@
//!
//! ## Multiaddr
//!
//! A `Multiaddr` is a way to reach a node. Examples:
//! 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`
@ -34,100 +35,119 @@
//!
//! ## Transport
//!
//! `Transport` is a trait that represents an object capable of dialing multiaddresses or
//! listening on multiaddresses. The `Transport` produces an output which varies depending on the
//! object that implements the trait.
//! [`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.
//!
//! Each implementation of `Transport` typically supports only some multiaddresses. For example
//! the `TcpConfig` type (which implements `Transport`) only supports multiaddresses of the format
//! An implementation of transport typically supports only certain multi-addresses.
//! For example, the [`TcpConfig`] only supports multi-addresses of the format
//! `/ip4/.../tcp/...`.
//!
//! Example:
//! 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 _outgoing_connec = tcp.dial(addr);
//! // Note that `_outgoing_connec` is a `Future`, and therefore doesn't do anything by itself
//! // unless it is run through a tokio runtime.
//! 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 the `build_development_transport` function.
//! This function provides support for the most common protocols.
//! The easiest way to create a transport is to use [`build_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:
//! Example (Creating a development transport):
//!
//! ```rust
//! let key = libp2p::identity::Keypair::generate_ed25519();
//! let _transport = libp2p::build_development_transport(key);
//! let keypair = libp2p::identity::Keypair::generate_ed25519();
//! let _transport = libp2p::build_development_transport(keypair);
//! // _transport.dial(...);
//! ```
//!
//! See the documentation of the `libp2p-core` crate for more details about transports.
//! 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`].
//!
//! # Connection upgrades
//! See the documentation of the [`Transport`] trait for more details.
//!
//! 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 a negotiation protocol
//! `multistream-select`), and applying that protocol on the socket.
//! ### Connection Upgrades
//!
//! Example:
//! 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 ([`secio`] Protocol Upgrade):
//!
//! ```rust
//! # #[cfg(all(any(target_os = "emscripten", target_os = "unknown"), feature = "libp2p-secio"))] {
//! use libp2p::{Transport, tcp::TcpConfig, secio::{SecioConfig, SecioKeyPair}};
//! # #[cfg(all(not(any(target_os = "emscripten", target_os = "unknown")), feature = "libp2p-secio"))] {
//! use libp2p::{Transport, tcp::TcpConfig, secio::SecioConfig, identity::Keypair};
//! let tcp = TcpConfig::new();
//! let secio_upgrade = SecioConfig::new(SecioKeyPair::ed25519_generated().unwrap());
//! let with_security = tcp.with_upgrade(secio_upgrade);
//! // let _ = with_security.dial(...);
//! // `with_security` also implements the `Transport` trait, and all the connections opened
//! // through it will automatically negotiate the `secio` protocol.
//! let secio_upgrade = SecioConfig::new(Keypair::generate_ed25519());
//! let tcp_secio = tcp.with_upgrade(secio_upgrade);
//! // let _ = tcp_secio.dial(...);
//! # }
//! ```
//! In this example, `tcp_secio` is a new [`Transport`] that negotiates the secio protocol
//! on all connections.
//!
//! See the documentation of the `libp2p-core` crate for more details about upgrades.
//! ## Network Behaviour
//!
//! ## Topology
//! The [`NetworkBehaviour`] trait is implemented on types that provide some capability to the
//! network. Examples of network behaviours include:
//!
//! 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.
//! * 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
//!
//! The `Swarm` struct contains all active and pending connections to remotes and manages the
//! state of all the substreams that have been opened, and all the upgrades that were built upon
//! these substreams.
//! 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`].
//!
//! 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 [`core`] module for more details about swarms.
//!
//! # Using libp2p
//!
//! This section contains details about how to use libp2p in practice.
//! The easiest way to get started with libp2p involves the following steps:
//!
//! The most simple way to use libp2p consists in 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
//! [`secio`] that authenticates the peer. See the implementation of
//! [`build_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.
//!
//! - 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.
//! - Create a struct that implements the `NetworkBehaviour` trait and that combines all the
//! network behaviours that you want.
//! - Create and implement the `Topology` trait that to store the topology of the network.
//! - Create a swarm that combines your base transport, the network behaviour, and the topology.
//! - This swarm can now be polled with the `tokio` library in order to start the network.
//! The swarm instance can then be polled 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`]: core::swarm::NetworkBehaviour
//! [`StreamMuxer`]: core::muxing::StreamMuxer
//! [`Yamux`]: yamux::Yamux
//!
//! [tokio]: https://tokio.rs
//! [`multistream-select`]: https://github.com/multiformats/multistream-select
#![doc(html_logo_url = "https://libp2p.io/img/logo_small.png")]
#![doc(html_favicon_url = "https://libp2p.io/img/favicon.png")]