From d9d0ba14c45278c405691d4be882e2c618addbbc Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Wed, 28 Dec 2022 20:36:53 +0100
Subject: [PATCH] docs: add outgoing request diagram (#630)

---
 crates/net/network/src/fetch/client.rs | 37 ++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/crates/net/network/src/fetch/client.rs b/crates/net/network/src/fetch/client.rs
index 1168b5b0ce..5dc17bb0ac 100644
--- a/crates/net/network/src/fetch/client.rs
+++ b/crates/net/network/src/fetch/client.rs
@@ -15,6 +15,43 @@ use reth_primitives::{PeerId, WithPeerId, H256};
 use tokio::sync::{mpsc::UnboundedSender, oneshot};
 
 /// Front-end API for fetching data from the network.
+///
+/// Following diagram illustrates how a request, See [`HeadersClient::get_headers`] and
+/// [`BodiesClient::get_block_bodies`] is handled internally.
+#[cfg_attr(doc, aquamarine::aquamarine)]
+/// ```mermaid
+/// sequenceDiagram
+//     participant Client as FetchClient
+//     participant Fetcher as StateFetcher
+//     participant State as NetworkState
+//     participant Session as Active Peer Session
+//     participant Peers as PeerManager
+//     loop Send Request, retry if retriable and remaining retries
+//         Client->>Fetcher: DownloadRequest{GetHeaders, GetBodies}
+//         Note over Client,Fetcher: Request and oneshot Sender sent via `request_tx` channel
+//         loop Process buffered requests
+//             State->>Fetcher: poll action
+//             Fetcher->>Fetcher: Select Available Peer
+//             Note over Fetcher: Peer is available if it's currently idle, no inflight requests
+//             Fetcher->>State: FetchAction::BlockDownloadRequest
+//             State->>Session: Delegate Request
+//             Note over State,Session: Request and oneshot Sender sent via `to_session_tx` channel
+//         end
+//         Session->>Session: Send Request to remote
+//         Session->>Session: Enforce Request timeout
+//         Session-->>State: Send Response Result via channel
+//         State->>Fetcher: Delegate Response
+//         Fetcher-->>Client: Send Response via channel
+//         opt Bad Response
+//             Client->>Peers: Penalize Peer
+//         end
+//         Peers->>Peers: Apply Reputation Change
+//         opt reputation dropped below threshold
+//             Peers->>State: Disconnect Session
+//             State->>Session: Delegate Disconnect
+//         end
+//     end
+/// ```
 #[derive(Debug)]
 pub struct FetchClient {
     /// Sender half of the request channel.