From 177aaf0798451e8f762f8cd335a90116be30635a Mon Sep 17 00:00:00 2001
From: Itay Tsabary <itayt@starkware.co>
Date: Thu, 6 Jun 2024 12:23:51 +0300
Subject: [PATCH] docs: add documentation for component server

commit-id:a2509b74
---
 crates/mempool_infra/src/component_server.rs | 99 ++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/crates/mempool_infra/src/component_server.rs b/crates/mempool_infra/src/component_server.rs
index d11396ef2..e6ed57235 100644
--- a/crates/mempool_infra/src/component_server.rs
+++ b/crates/mempool_infra/src/component_server.rs
@@ -19,6 +19,105 @@ use crate::component_definitions::{
 };
 use crate::component_runner::ComponentStarter;
 
+/// The `ComponentServer` struct is a generic server that handles requests and responses for a
+/// specified component. It receives requests, processes them using the provided component, and
+/// sends back responses. The server needs to be started using the `start` function, which runs
+/// indefinitely.
+///
+/// # Type Parameters
+///
+/// - `Component`: The type of the component that will handle the requests. This type must implement
+///   the `ComponentRequestHandler` trait, which defines how the component processes requests and
+///   generates responses.
+/// - `Request`: The type of requests that the component will handle. This type must implement the
+///   `Send` and `Sync` traits to ensure safe concurrency.
+/// - `Response`: The type of responses that the component will generate. This type must implement
+///   the `Send` and `Sync` traits to ensure safe concurrency.
+///
+/// # Fields
+///
+/// - `component`: The component responsible for handling the requests and generating responses.
+/// - `rx`: A receiver that receives incoming requests along with a sender to send back the
+///   responses. This receiver is of type ` Receiver<ComponentRequestAndResponseSender<Request,
+///   Response>>`.
+///
+/// # Example
+/// ```rust
+/// // Example usage of the ComponentServer
+/// use std::sync::mpsc::{channel, Receiver};
+///
+/// use async_trait::async_trait;
+/// use starknet_mempool_infra::component_runner::{ComponentStartError, ComponentStarter};
+/// use tokio::task;
+///
+/// use crate::starknet_mempool_infra::component_definitions::{
+///     ComponentRequestAndResponseSender, ComponentRequestHandler,
+/// };
+/// use crate::starknet_mempool_infra::component_server::{
+///     ComponentServer, ComponentServerStarter,
+/// };
+///
+/// // Define your component
+/// struct MyComponent {}
+///
+/// #[async_trait]
+/// impl ComponentStarter for MyComponent {
+///     async fn start(&mut self) -> Result<(), ComponentStartError> {
+///         Ok(())
+///     }
+/// }
+///
+/// // Define your request and response types
+/// struct MyRequest {
+///     pub content: String,
+/// }
+///
+/// struct MyResponse {
+///     pub content: String,
+/// }
+///
+/// // Define your request processing logic
+/// #[async_trait]
+/// impl ComponentRequestHandler<MyRequest, MyResponse> for MyComponent {
+///     async fn handle_request(&mut self, request: MyRequest) -> MyResponse {
+///         MyResponse { content: request.content.clone() + " processed" }
+///     }
+/// }
+///
+/// #[tokio::main]
+/// async fn main() {
+///     // Create a channel for sending requests and receiving responses
+///     let (tx, rx) = tokio::sync::mpsc::channel::<
+///         ComponentRequestAndResponseSender<MyRequest, MyResponse>,
+///     >(100);
+///
+///     // Instantiate the component.
+///     let component = MyComponent {};
+///
+///     // Instantiate the server.
+///     let mut server = ComponentServer::new(component, rx);
+///
+///     // Start the server in a new task.
+///     task::spawn(async move {
+///         server.start().await;
+///     });
+///
+///     // Ensure the server starts running.
+///     task::yield_now().await;
+///
+///     // Create the request and the response channel.
+///     let (res_tx, mut res_rx) = tokio::sync::mpsc::channel::<MyResponse>(1);
+///     let request = MyRequest { content: "request example".to_string() };
+///     let request_and_res_tx = ComponentRequestAndResponseSender { request, tx: res_tx };
+///
+///     // Send the request.
+///     tx.send(request_and_res_tx).await.unwrap();
+///
+///     // Receive the response.
+///     let response = res_rx.recv().await.unwrap();
+///     assert!(response.content == "request example processed".to_string(), "Unexpected response");
+/// }
+/// ```
 pub struct ComponentServer<Component, Request, Response>
 where
     Component: ComponentRequestHandler<Request, Response> + ComponentStarter,