From c117d4b44f63de8821160510cf9d492be9dc25b6 Mon Sep 17 00:00:00 2001 From: Matthias Seitz Date: Sat, 10 Dec 2022 18:19:25 +0100 Subject: [PATCH] docs(net): add example docs and fix links (#375) --- crates/net/network/Cargo.toml | 3 +- crates/net/network/src/config.rs | 17 +++++++++- crates/net/network/src/eth_requests.rs | 2 +- crates/net/network/src/lib.rs | 40 ++++++++++++++++++++++-- crates/net/network/src/manager.rs | 24 ++++++++------ crates/net/network/src/network.rs | 7 +++-- crates/net/network/src/session/config.rs | 4 +-- crates/net/network/src/transactions.rs | 4 +-- 8 files changed, 79 insertions(+), 22 deletions(-) diff --git a/crates/net/network/Cargo.toml b/crates/net/network/Cargo.toml index 69dac7634f..9ca90571dc 100644 --- a/crates/net/network/Cargo.toml +++ b/crates/net/network/Cargo.toml @@ -38,7 +38,7 @@ async-trait = "0.1" bytes = "1.2" either = "1.8" linked_hash_set = "0.1" - +rand = "0.8" secp256k1 = { version = "0.24", features = [ "global-context", "rand-std", @@ -51,5 +51,4 @@ reth-interfaces = { path = "../../interfaces", features = ["test-utils"] } reth-provider = { path = "../../storage/provider", features = ["test-utils"] } reth-tracing = { path = "../../tracing" } -rand = "0.8" diff --git a/crates/net/network/src/config.rs b/crates/net/network/src/config.rs index 4c6db50a57..a0d575312d 100644 --- a/crates/net/network/src/config.rs +++ b/crates/net/network/src/config.rs @@ -1,3 +1,5 @@ +//! Network config support + use crate::{ import::{BlockImport, ProofOfStakeBlockImport}, peers::PeersConfig, @@ -12,6 +14,19 @@ use std::{ sync::Arc, }; +/// reexports for convenience +#[doc(hidden)] +mod __reexport { + pub use reth_discv4::bootnodes::*; + pub use secp256k1::SecretKey; +} +pub use __reexport::*; + +/// Convenience function to create a new random [`SecretKey`] +pub fn rng_secret_key() -> SecretKey { + SecretKey::new(&mut rand::thread_rng()) +} + /// All network related initialization settings. pub struct NetworkConfig { /// The client type that can interact with the chain. @@ -28,7 +43,7 @@ pub struct NetworkConfig { pub listener_addr: SocketAddr, /// How to instantiate peer manager. pub peers_config: PeersConfig, - /// How to configure the [`SessionManager`] + /// How to configure the [SessionManager](crate::session::SessionManager). pub sessions_config: SessionsConfig, /// A fork identifier as defined by EIP-2124. /// Serves as the chain compatibility identifier. diff --git a/crates/net/network/src/eth_requests.rs b/crates/net/network/src/eth_requests.rs index 56ad31dc34..52e3af428d 100644 --- a/crates/net/network/src/eth_requests.rs +++ b/crates/net/network/src/eth_requests.rs @@ -54,7 +54,7 @@ pub struct EthRequestHandler { #[allow(unused)] // TODO use to report spammers peers: PeersHandle, - /// Incoming request from the [`NetworkManager`]. + /// Incoming request from the [NetworkManager](crate::NetworkManager). incoming_requests: UnboundedReceiverStream, } diff --git a/crates/net/network/src/lib.rs b/crates/net/network/src/lib.rs index 3b0f471575..66214ba43f 100644 --- a/crates/net/network/src/lib.rs +++ b/crates/net/network/src/lib.rs @@ -1,5 +1,6 @@ #![warn(missing_docs)] -#![deny(unused_must_use, rust_2018_idioms)] +#![deny(unused_must_use, rust_2018_idioms, rustdoc::broken_intra_doc_links)] +#![allow(rustdoc::private_intra_doc_links)] #![doc(test( no_crate_inject, attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables)) @@ -12,9 +13,44 @@ //! In order for a node to join the ethereum p2p network it needs to know what nodes are already //! port of that network. This includes public identities (public key) and addresses (where to reach //! them). +//! +//! ## Usage +//! +//! ### Configure and launch the network +//! +//! The [`NetworkConfig`] is used to configure the network. +//! It requires an instance of [`BlockProvider`](reth_provider::BlockProvider). +//! +//! +//! ``` +//! # async fn launch() { +//! use std::sync::Arc; +//! use reth_network::config::{rng_secret_key, mainnet_nodes}; +//! use reth_network::{NetworkConfig, NetworkManager}; +//! use reth_provider::test_utils::TestApi; +//! +//! // This block provider implementation is used for testing purposes. +//! let client = Arc::new(TestApi::default()); +//! +//! // The key that's used for encrypting sessions and to identify our node. +//! let local_key = rng_secret_key(); +//! +//! let config = NetworkConfig::builder(client, local_key).boot_nodes( +//! mainnet_nodes() +//! ).build(); +//! +//! // create the network instance +//! let network = NetworkManager::new(config).await.unwrap(); +//! +//! // keep a handle to the network and spawn it +//! let handle = network.handle().clone(); +//! tokio::task::spawn(network); +//! +//! # } +//! ``` mod cache; -mod config; +pub mod config; mod discovery; pub mod error; pub mod eth_requests; diff --git a/crates/net/network/src/manager.rs b/crates/net/network/src/manager.rs index dbfa1b43ba..a29412f688 100644 --- a/crates/net/network/src/manager.rs +++ b/crates/net/network/src/manager.rs @@ -1,7 +1,7 @@ //! High level network management. //! -//! The [`Network`] contains the state of the network as a whole. It controls how connections are -//! handled and keeps track of connections to peers. +//! The [`NetworkManager`] contains the state of the network as a whole. It controls how connections +//! are handled and keeps track of connections to peers. //! //! ## Capabilities //! @@ -86,11 +86,13 @@ pub struct NetworkManager { from_handle_rx: UnboundedReceiverStream, /// Handles block imports according to the `eth` protocol. block_import: Box, - /// All listeners for [`Network`] events. + /// All listeners for high level network events. event_listeners: NetworkEventListeners, - /// Sender half to send events to the [`TransactionsManager`] task, if configured. + /// Sender half to send events to the + /// [`TransactionsManager`](crate::transactions::TransactionsManager) task, if configured. to_transactions_manager: Option>, - /// Sender half to send events to the [`EthRequestHandler`] task, if configured. + /// Sender half to send events to the + /// [`EthRequestHandler`](crate::eth_requests::EthRequestHandler) task, if configured. to_eth_request_handler: Option>, /// Tracks the number of active session (connected peers). /// @@ -167,12 +169,14 @@ where }) } - /// Sets the dedicated channel for events indented for the [`TransactionsManager`] + /// Sets the dedicated channel for events indented for the + /// [`TransactionsManager`](crate::transactions::TransactionsManager). pub fn set_transactions(&mut self, tx: mpsc::UnboundedSender) { self.to_transactions_manager = Some(tx); } - /// Sets the dedicated channel for events indented for the [`EthRequestHandler`] + /// Sets the dedicated channel for events indented for the + /// [`EthRequestHandler`](crate::eth_requests::EthRequestHandler). pub fn set_eth_request_handler(&mut self, tx: mpsc::UnboundedSender) { self.to_eth_request_handler = Some(tx); } @@ -232,14 +236,16 @@ where .apply_reputation_change(&peer_id, ReputationChangeKind::BadProtocol); } - /// Sends an event to the [`TransactionsManager`] if configured + /// Sends an event to the [`TransactionsManager`](crate::transactions::TransactionsManager) if + /// configured. fn notify_tx_manager(&self, event: NetworkTransactionEvent) { if let Some(ref tx) = self.to_transactions_manager { let _ = tx.send(event); } } - /// Sends an event to the [`EthRequestManager`] if configured + /// Sends an event to the [`EthRequestManager`](crate::eth_requests::EthRequestHandler) if + /// configured. fn delegate_eth_request(&self, event: IncomingEthRequest) { if let Some(ref reqs) = self.to_eth_request_handler { let _ = reqs.send(event); diff --git a/crates/net/network/src/network.rs b/crates/net/network/src/network.rs index 73fe36af1d..12427e21da 100644 --- a/crates/net/network/src/network.rs +++ b/crates/net/network/src/network.rs @@ -109,13 +109,14 @@ impl NetworkHandle { self.send_message(NetworkHandleMessage::AnnounceBlock(block, hash)) } - /// Sends a message to the [`NetworkManager`] to add a peer to the known set + /// Sends a message to the [`NetworkManager`](crate::NetworkManager) to add a peer to the known + /// set pub fn add_peer(&self, peer: PeerId, addr: SocketAddr) { let _ = self.inner.to_manager_tx.send(NetworkHandleMessage::AddPeerAddress(peer, addr)); } - /// Sends a message to the [`NetworkManager`] to disconnect an existing connection to the given - /// peer. + /// Sends a message to the [`NetworkManager`](crate::NetworkManager) to disconnect an existing + /// connection to the given peer. pub fn disconnect_peer(&self, peer: PeerId) { self.send_message(NetworkHandleMessage::DisconnectPeer(peer)) } diff --git a/crates/net/network/src/session/config.rs b/crates/net/network/src/session/config.rs index 2b96bdb48f..7b157cef22 100644 --- a/crates/net/network/src/session/config.rs +++ b/crates/net/network/src/session/config.rs @@ -1,4 +1,4 @@ -//! Configuration types for [`SessionsManager`] +//! Configuration types for [SessionManager](crate::session::SessionManager). use crate::session::{Direction, ExceedsSessionLimit}; use std::time::Duration; @@ -6,7 +6,7 @@ use std::time::Duration; /// Default request timeout. pub const REQUEST_TIMEOUT: Duration = Duration::from_millis(500u64); -/// Configuration options when creating a [`SessionsManager`]. +/// Configuration options when creating a [SessionManager](crate::session::SessionManager). pub struct SessionsConfig { /// Size of the session command buffer (per session task). pub session_command_buffer: usize, diff --git a/crates/net/network/src/transactions.rs b/crates/net/network/src/transactions.rs index 376c924be2..804eda2b76 100644 --- a/crates/net/network/src/transactions.rs +++ b/crates/net/network/src/transactions.rs @@ -99,7 +99,7 @@ pub struct TransactionsManager { command_rx: UnboundedReceiverStream, /// Incoming commands from [`TransactionsHandle`]. pending_transactions: ReceiverStream, - /// Incoming events from the [`NetworkManager`] + /// Incoming events from the [`NetworkManager`](crate::NetworkManager). transaction_events: UnboundedReceiverStream, } @@ -112,7 +112,7 @@ where { /// Sets up a new instance. /// - /// Note: This expects an existing [`NetworkManager`] instance. + /// Note: This expects an existing [`NetworkManager`](crate::NetworkManager) instance. pub fn new( network: NetworkHandle, pool: Pool,