protocols/: Add documentation on peer discovery (#2465)

Co-authored-by: Max Inden <mail@max-inden.de>
This commit is contained in:
Frederik-Baetens 2022-02-09 15:54:07 +01:00 committed by GitHub
parent 0bb8ee98d5
commit 5a95a46cd3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 34 additions and 0 deletions

View File

@ -51,6 +51,18 @@
//! integers. They are chosen at random in this implementation of gossipsub, but are sequential in
//! the current go implementation.
//!
//! # Peer Discovery
//!
//! Gossipsub does not provide peer discovery by itself. Peer discovery is the process by which
//! peers in a p2p network exchange information about each other among other reasons to become resistant
//! against the failure or replacement of the
//! [boot nodes](https://docs.libp2p.io/reference/glossary/#boot-node) of the network.
//!
//! Peer
//! discovery can e.g. be implemented with the help of the [Kademlia](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) protocol
//! in combination with the [Identify](https://github.com/libp2p/specs/tree/master/identify) protocol. See the
//! Kademlia implementation documentation for more information.
//!
//! # Using Gossipsub
//!
//! ## GossipsubConfig

View File

@ -26,6 +26,13 @@
//! At least one identification request is sent on a newly established
//! connection, beyond which the behaviour does not keep connections alive.
//!
//! # Important Discrepancies
//!
//! - **Using Identify with other protocols** Unlike some other libp2p implementations,
//! rust-libp2p does not treat Identify as a core protocol. This means that other protocols cannot
//! rely upon the existence of Identify, and need to be manually hooked up to Identify in order to
//! make use of its capabilities.
//!
//! # Usage
//!
//! The [`Identify`] struct implements a `NetworkBehaviour` that negotiates

View File

@ -19,6 +19,21 @@
// DEALINGS IN THE SOFTWARE.
//! Implementation of the libp2p-specific Kademlia protocol.
//!
//! See [specification](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) for details.
//!
//! # Important Discrepancies
//!
//! - **Peer Discovery with Identify** In other libp2p implementations, the
//! [Identify](https://github.com/libp2p/specs/tree/master/identify) protocol might be seen as a core protocol. Rust-libp2p
//! tries to stay as generic as possible, and does not make this assumption.
//! This means that the Identify protocol must be manually hooked up to Kademlia through calls
//! to [`Kademlia::add_address`].
//! If you choose not to use the Identify protocol, and do not provide an alternative peer
//! discovery mechanism, a Kademlia node will not discover nodes beyond the network's
//! [boot nodes](https://docs.libp2p.io/reference/glossary/#boot-node). Without the Identify protocol,
//! existing nodes in the kademlia network cannot obtain the listen addresses
//! of nodes querying them, and thus will not be able to add them to their routing table.
// TODO: we allow dead_code for now because this library contains a lot of unused code that will
// be useful later for record store