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

@@ -39,7 +39,26 @@ use super::PeerSet;
 
 type PeerChange = Result<Change<SocketAddr, peer::Client>, 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<S>(
     config: Config,
     inbound_service: S,

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()