added commentation

WatcherAgent/src/api.rs

@@ -1,3 +1,17 @@
+
+
+//! # API Module
+//!
+//! This module provides all HTTP communication between WatcherAgent and the backend server.
+//!
+//! ## Responsibilities
+//! - **Registration:** Registers the agent with the backend and retrieves its server ID and IP address.
+//! - **Heartbeat:** Periodically sends heartbeat signals to indicate liveness.
+//! - **Metrics Reporting:** Sends collected hardware and network metrics to the backend.
+//! - **Command Listening:** Polls for and executes remote commands from the backend (e.g., update image, restart container).
+//!
+//! ## Usage
+//! These functions are called from the main agent loop and background tasks. All network operations are asynchronous and robust to transient failures.
 use std::time::Duration;
 
 use crate::hardware::HardwareInfo;
@@ -11,6 +25,18 @@ use tokio::time::sleep;
 
 use bollard::Docker;
 
+/// Registers this agent with the backend server and retrieves its server ID and IP address.
+///
+/// This function collects local hardware information, prepares a registration payload, and sends it to the backend. It will retry registration until successful, handling network errors and server-side failures gracefully.
+///
+/// # Arguments
+/// * `base_url` - The base URL of the backend server (e.g., `https://server.example.com`).
+///
+/// # Returns
+/// * `Result<(i32, String), Box<dyn Error + Send + Sync>>` - Tuple of server ID and registered IP address on success.
+///
+/// # Errors
+/// Returns an error if unable to register after repeated attempts.
 pub async fn register_with_server(
     base_url: &str,
 ) -> Result<(i32, String), Box<dyn Error + Send + Sync>> {
@@ -64,6 +90,16 @@ pub async fn register_with_server(
     }
 }
 
+/// Looks up the server ID for the given IP address from the backend server.
+///
+/// This function will retry until a valid response is received, handling network errors and server-side failures.
+///
+/// # Arguments
+/// * `base_url` - The base URL of the backend server.
+/// * `ip` - The local IP address to look up.
+///
+/// # Returns
+/// * `Result<(i32, String), Box<dyn Error + Send + Sync>>` - Tuple of server ID and registered IP address.
 async fn get_server_id_by_ip(
     base_url: &str,
     ip: &str,
@@ -115,6 +151,16 @@ async fn get_server_id_by_ip(
     }
 }
 
+/// Periodically sends heartbeat signals to the backend server to indicate agent liveness.
+///
+/// This function runs in a background task and will retry on network errors.
+///
+/// # Arguments
+/// * `base_url` - The base URL of the backend server.
+/// * `ip` - The IP address of the agent.
+///
+/// # Returns
+/// * `Result<(), Box<dyn Error + Send + Sync>>` - Ok if heartbeats are sent successfully.
 pub async fn heartbeat_loop(base_url: &str, ip: &str) -> Result<(), Box<dyn Error + Send + Sync>> {
     let client = Client::builder()
         .danger_accept_invalid_certs(true)
@@ -138,6 +184,16 @@ pub async fn heartbeat_loop(base_url: &str, ip: &str) -> Result<(), Box<dyn Erro
     }
 }
 
+/// Sends collected hardware and network metrics to the backend server.
+///
+/// This function is called periodically from the metrics collection loop. It logs the result and retries on network errors.
+///
+/// # Arguments
+/// * `base_url` - The base URL of the backend server.
+/// * `metrics` - The metrics data to send (see [`MetricDto`]).
+///
+/// # Returns
+/// * `Result<(), Box<dyn Error + Send + Sync>>` - Ok if metrics are sent successfully.
 pub async fn send_metrics(
     base_url: &str,
     metrics: &MetricDto,
@@ -158,6 +214,16 @@ pub async fn send_metrics(
     Ok(())
 }
 
+/// Polls the backend server for remote commands and executes them.
+///
+/// This function runs in a background task, polling the server for new messages. It acknowledges receipt and execution of each command, and handles errors gracefully.
+///
+/// # Arguments
+/// * `docker` - Reference to a Bollard Docker client.
+/// * `base_url` - The base URL of the backend server.
+///
+/// # Returns
+/// * `Result<(), Box<dyn Error + Send + Sync>>` - Ok if commands are handled successfully.
 pub async fn listening_to_server(docker: &Docker, base_url: &str) -> Result<(), Box<dyn Error + Send + Sync>> {
     let url = format!("{}/api/message", base_url);
     let client = reqwest::Client::new();
@@ -210,6 +276,19 @@ pub async fn listening_to_server(docker: &Docker, base_url: &str) -> Result<(),
     }
 }
 
+/// Sends an acknowledgment to the backend server for a received or executed command message.
+///
+/// This function is used internally by [`listening_to_server`] to confirm receipt and execution status of commands.
+///
+/// # Arguments
+/// * `client` - Reference to a reqwest HTTP client.
+/// * `base_url` - The base URL of the backend server.
+/// * `message_id` - The ID of the message being acknowledged.
+/// * `status` - Status string (e.g., "received", "success", "error").
+/// * `details` - Additional details about the acknowledgment.
+///
+/// # Returns
+/// * `Result<(), Box<dyn Error + Send + Sync>>` - Ok if acknowledgment is sent successfully.
 async fn send_acknowledgment(
     client: &reqwest::Client,
     base_url: &str,