From 170f588ffbbab0973c3c9b24a95f524bae7644a8 Mon Sep 17 00:00:00 2001 From: Henry de Valence Date: Fri, 18 Sep 2020 12:37:01 -0700 Subject: [PATCH] network: document load-shedding behavior This was part of the original design and is described in the Connection internals, but we never documented it externally. --- zebra-network/src/peer_set/initialize.rs | 21 ++++++++++++++++++++- zebrad/src/commands/start.rs | 4 +++- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/zebra-network/src/peer_set/initialize.rs b/zebra-network/src/peer_set/initialize.rs index b52487b6..f0e51eb8 100644 --- a/zebra-network/src/peer_set/initialize.rs +++ b/zebra-network/src/peer_set/initialize.rs @@ -39,7 +39,26 @@ use super::PeerSet; type PeerChange = Result, BoxError>; -/// Initialize a peer set with the given `config`, forwarding peer requests to the `inbound_service`. +/// Initialize a peer set. +/// +/// The peer set abstracts away peer management to provide a +/// [`tower::Service`] representing "the network" that load-balances requests +/// over available peers. The peer set automatically crawls the network to +/// find more peer addresses and opportunistically connects to new peers. +/// +/// Each peer connection's message handling is isolated from other +/// connections, unlike in `zcashd`. The peer connection first attempts to +/// interpret inbound messages as part of a response to a previously-issued +/// request. Otherwise, inbound messages are interpreted as requests and sent +/// to the supplied `inbound_service`. +/// +/// Wrapping the `inbound_service` in [`tower::load_shed`] middleware will +/// cause the peer set to shrink when the inbound service is unable to keep up +/// with the volume of inbound requests. +/// +/// In addition to returning a service for outbound requests, this method +/// returns a shared [`AddressBook`] updated with last-seen timestamps for +/// connected peers. pub async fn init( config: Config, inbound_service: S, diff --git a/zebrad/src/commands/start.rs b/zebrad/src/commands/start.rs index e61c0ebe..d6443298 100644 --- a/zebrad/src/commands/start.rs +++ b/zebrad/src/commands/start.rs @@ -57,7 +57,9 @@ impl StartCmd { info!("initializing network"); - // The service that our node uses to respond to requests by peers + // The service that our node uses to respond to requests by peers. The + // load_shed middleware ensures that we reduce the size of the peer set + // in response to excess load. let (setup_tx, setup_rx) = oneshot::channel(); let inbound = ServiceBuilder::new() .load_shed()