chore: adding doc to topos-tce

Signed-off-by: Simon Paitrault <[email protected]>

crates/topos-tce/src/app_context.rs

@@ -1,7 +1,6 @@
 //!
 //! Application logic glue
 //!
-use crate::events::Events;
 use futures::{Stream, StreamExt};
 use prometheus::HistogramTimer;
 use std::collections::HashMap;
@@ -37,18 +36,19 @@ pub(crate) mod protocol;
 /// config+data as input and runs app returning data as output
 ///
 pub struct AppContext {
-    pub is_validator: bool,
-    pub events: mpsc::Sender<Events>,
-    pub tce_cli: ReliableBroadcastClient,
-    pub network_client: NetworkClient,
-    pub api_client: ApiClient,
-    pub pending_storage: StorageClient,
-    pub gatekeeper: GatekeeperClient,
-
-    pub delivery_latency: HashMap<CertificateId, HistogramTimer>,
-
-    pub validator_store: Arc<ValidatorStore>,
-    pub api_context: RuntimeContext,
+    pub(crate) is_validator: bool,
+    pub(crate) tce_cli: ReliableBroadcastClient,
+    pub(crate) network_client: NetworkClient,
+    pub(crate) api_client: ApiClient,
+    pub(crate) pending_storage: StorageClient,
+    pub(crate) gatekeeper: GatekeeperClient,
+
+    pub(crate) delivery_latency: HashMap<CertificateId, HistogramTimer>,
+
+    pub(crate) validator_store: Arc<ValidatorStore>,
+    // Hold the api context, cleaning up when Drop
+    #[allow(unused)]
+    pub(crate) api_context: RuntimeContext,
 }
 
 impl AppContext {
@@ -68,23 +68,18 @@ impl AppContext {
         gatekeeper: GatekeeperClient,
         validator_store: Arc<ValidatorStore>,
         api_context: RuntimeContext,
-    ) -> (Self, mpsc::Receiver<Events>) {
-        let (events, receiver) = mpsc::channel(100);
-        (
-            Self {
-                is_validator,
-                events,
-                tce_cli,
-                network_client,
-                api_client,
-                pending_storage,
-                gatekeeper,
-                delivery_latency: Default::default(),
-                validator_store,
-                api_context,
-            },
-            receiver,
-        )
+    ) -> Self {
+        Self {
+            is_validator,
+            tce_cli,
+            network_client,
+            api_client,
+            pending_storage,
+            gatekeeper,
+            delivery_latency: Default::default(),
+            validator_store,
+            api_context,
+        }
     }
 
     /// Main processing loop

crates/topos-tce/src/app_context/api.rs

@@ -11,7 +11,7 @@ use tracing::debug;
 use tracing::{error, warn};
 
 impl AppContext {
-    pub async fn on_api_event(&mut self, event: ApiEvent) {
+    pub(crate) async fn on_api_event(&mut self, event: ApiEvent) {
         match event {
             ApiEvent::CertificateSubmitted {
                 certificate,

crates/topos-tce/src/app_context/network.rs

@@ -15,7 +15,7 @@ use topos_core::uci;
 use crate::AppContext;
 
 impl AppContext {
-    pub async fn on_net_event(&mut self, evt: NetEvent) {
+    pub(crate) async fn on_net_event(&mut self, evt: NetEvent) {
         trace!(
             "on_net_event: peer: {} event {:?}",
             &self.network_client.local_peer_id,

crates/topos-tce/src/app_context/protocol.rs

@@ -5,7 +5,7 @@ use tracing::{error, info, warn};
 use crate::AppContext;
 
 impl AppContext {
-    pub async fn on_protocol_event(&mut self, evt: ProtocolEvents) {
+    pub(crate) async fn on_protocol_event(&mut self, evt: ProtocolEvents) {
         match evt {
             ProtocolEvents::Broadcast { certificate_id } => {
                 info!("Broadcasting certificate {}", certificate_id);

crates/topos-tce/src/lib.rs

@@ -1,3 +1,40 @@
+//! This library is the entry point for the TCE node. It is responsible for setting up the
+//! different components of the TCE node and starting them.
+//!
+//! The TCE node is composed of the following components:
+//! - P2P network: [topos_p2p]
+//! - Reliable Broadcast: [topos_tce_broadcast]
+//! - Synchronizer: [topos_tce_synchronizer]
+//! - Storage: [topos_tce_storage]
+//! - APIs: [topos_tce_api]
+//! - Gatekeeper: [topos_tce_gatekeeper]
+//!
+//! This library exposes a single function `launch` that takes a [TceConfig] and a [CancellationToken]
+//! and returns a [Future] that resolves to an [ExitStatus] when the TCE node is shut down.
+//!
+//! ## Interactions
+//!
+//! The `topos_tce` crate is responsible for connecting all the different components of the TCE node
+//! together. Different flow are managed by the `AppContext` struct:
+//!
+//!<picture>
+//!  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/topos-protocol/topos/assets/1394604/02e7f208-e6af-4280-85e3-5e1df8506bd4">
+//!  <img alt="Text changing depending on mode. Light: 'So light!' Dark: 'So dark!'" src="https://github.com/topos-protocol/topos/assets/1394604/70f9a3f8-bd52-4856-bf62-d5ed4b70ff09">
+//!</picture>
+//!
+//! #### P2P layer
+//!
+//! After setting up the P2P layer, the `AppContext` will listen for incoming events and dispatch
+//! them to the different components of the TCE node.
+//!
+//! The [AppContext] is listening for [topos_p2p::Event] on a channel. Based on those events the
+//! [AppContext] will decide to forward them to the [topos_tce_broadcast] after checking for state
+//! in the [topos_tce_storage].
+//!
+//! The [AppContext] will also send message to [topos_p2p] when the [topos_tce_broadcast] is
+//! producing events, those messages are published on the network to support the Topos Protocol.
+//!
+//!
 use futures::{Future, StreamExt};
 use opentelemetry::global;
 use std::process::ExitStatus;
@@ -21,7 +58,7 @@ use topos_tce_synchronizer::SynchronizerService;
 use tracing::{debug, info, warn};
 
 mod app_context;
-pub mod events;
+
 #[cfg(test)]
 mod tests;
 
@@ -57,7 +94,7 @@ pub async fn launch(
     Ok(ExitStatus::default())
 }
 
-pub async fn run(
+async fn run(
     config: &TceConfig,
     shutdown: (CancellationToken, mpsc::Sender<()>),
 ) -> Result<impl Future<Output = ()>, Box<dyn std::error::Error>> {
@@ -205,7 +242,7 @@ pub async fn run(
 
     spawn(synchronizer_runtime.into_future());
     // setup transport-tce-storage-api connector
-    let (app_context, _tce_stream) = AppContext::new(
+    let app_context = AppContext::new(
         is_validator,
         storage_client,
         tce_cli,

crates/topos-tce/src/tests/mod.rs

@@ -132,7 +132,7 @@ pub async fn setup_test(
 
     let (gatekeeper_client, _) = Gatekeeper::builder().into_future().await.unwrap();
 
-    let (context, _) = AppContext::new(
+    let context = AppContext::new(
         is_validator,
         StorageClient::new(validator_store.clone()),
         tce_cli,

crates/topos-test-sdk/src/tce/mod.rs

@@ -34,7 +34,7 @@ use topos_core::types::ValidatorId;
 use topos_core::uci::SubnetId;
 use topos_crypto::messages::MessageSigner;
 use topos_p2p::{error::P2PError, Event, GrpcRouter, NetworkClient, Runtime};
-use topos_tce::{events::Events, AppContext};
+use topos_tce::AppContext;
 use topos_tce_storage::StorageClient;
 use topos_tce_synchronizer::SynchronizerService;
 use tracing::info;
@@ -57,7 +57,6 @@ pub mod synchronizer;
 #[derive(Debug)]
 pub struct TceContext {
     pub node_config: NodeConfig,
-    pub event_stream: mpsc::Receiver<Events>,
     pub peer_id: PeerId, // P2P ID
     pub api_entrypoint: String,
     pub api_grpc_client: ApiServiceClient<Channel>, // GRPC Client for this peer (tce node)
@@ -278,7 +277,7 @@ pub async fn start_node(
     .in_current_span()
     .await;
 
-    let (app, event_stream) = AppContext::new(
+    let app = AppContext::new(
         is_validator,
         storage_client,
         tce_cli,
@@ -308,7 +307,6 @@ pub async fn start_node(
 
     TceContext {
         node_config: config,
-        event_stream,
         peer_id,
         api_entrypoint: api_context.entrypoint,
         api_grpc_client: api_context.api_client,