docs: internal_api & main

Signed-off-by: WoodenMaiden <[email protected]>

agent/lib/src/internal_api/model.rs

@@ -2,6 +2,13 @@ use std::path::PathBuf;
 
 use serde::{Deserialize, Serialize};
 
+/// A struct to represent a file in the request message
+///
+/// # Attributes
+///
+/// * `path` - The path of the file
+/// * `file_name` - The name of the file
+/// * `content` - The content of the file
 #[derive(Deserialize, Serialize, Debug)]
 pub struct FileModel {
     pub path: PathBuf,
@@ -19,6 +26,13 @@ impl FileModel {
     }
 }
 
+/// A struct to represent the result of a command
+///
+/// # Attributes
+///
+/// * `stdout` - The stdout of the command
+/// * `stderr` - The stderr of the command
+/// * `exit_code` - The exit code of the command
 #[derive(Deserialize, Serialize, Debug)]
 pub struct CodeReturn {
     pub stdout: String,

agent/lib/src/internal_api/service.rs

@@ -12,17 +12,33 @@ use std::{
     process::Command,
 };
 
+/// The path where the workspace will be created
 const WORKSPACE_PATH: &str = "/tmp";
 
+/// The internal API
 pub struct InternalApi {
     pub request_message: RequestMessage,
 }
 
 impl InternalApi {
+    /// Create a new instance of InternalApi
+    ///
+    /// # Arguments
+    ///
+    /// * `request_message` - The request message
+    ///
+    /// # Returns
+    ///
+    /// * `Self` - The new instance of InternalApi
     pub fn new(request_message: RequestMessage) -> Self {
         Self { request_message }
     }
 
+    /// Create the workspace for the code execution
+    ///
+    /// # Returns
+    ///
+    /// * `Result<()>` - Nothing or an error
     pub fn create_workspace(&mut self) -> Result<()> {
         info!("Creating workspace for code execution");
 
@@ -101,6 +117,11 @@ impl InternalApi {
         Ok(())
     }
 
+    /// Run all the steps of the request message
+    ///
+    /// # Returns
+    ///
+    /// * `Result<ResponseMessage>` - The response message or an error
     pub fn run(&mut self) -> Result<ResponseMessage> {
         info!("Running all steps");
         let mut steps: Vec<ResponseStep> = Vec::new();
@@ -135,6 +156,15 @@ impl InternalApi {
         Ok(response_message)
     }
 
+    /// Run a command
+    ///
+    /// # Arguments
+    ///
+    /// * `command` - The command to run
+    ///
+    /// # Returns
+    ///
+    /// * `Result<CodeReturn>` - The code return or an error
     pub fn run_one(&mut self, command: &str) -> Result<CodeReturn> {
         info!("Running command : {}", command);
 
@@ -167,6 +197,15 @@ mod tests {
     use std::fs::File;
     use std::io::Read;
 
+    /// Generate a random integer
+    ///
+    /// # Arguments
+    ///
+    /// * `max` - The maximum value
+    ///
+    /// # Returns
+    ///
+    /// * `usize` - The random integer
     fn random_usize(max: usize) -> usize {
         let mut f = File::open("/dev/urandom").unwrap();
         let mut buf = [0u8; 1];
@@ -180,6 +219,15 @@ mod tests {
         }
     }
 
+    /// Generate a random string
+    ///
+    /// # Arguments
+    ///
+    /// * `len` - The length of the string
+    ///
+    /// # Returns
+    ///
+    /// * `String` - The random string
     fn native_rand_string(len: usize) -> String {
         let chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890";
         let mut string = String::new();
@@ -191,6 +239,7 @@ mod tests {
         string
     }
 
+    /// Test the creation of a file
     #[test]
     fn workload_runs_correctly() {
         let files: Vec<FileModel> = Vec::new();
@@ -218,6 +267,7 @@ mod tests {
         assert!(res.data.steps[0].enable_output);
     }
 
+    /// Test the execution of a command with a workspace
     #[test]
     fn workspace_created_sucessfully() {
         let mut base_dir = PathBuf::from(WORKSPACE_PATH);

agent/src/main.rs

@@ -5,6 +5,7 @@ use anyhow::{anyhow, Result};
 use clap::Parser;
 use log::{debug, info, trace};
 
+/// Agent CLI options
 #[derive(Parser)]
 #[clap(
     version = "0.1",
@@ -17,28 +18,45 @@ pub struct AgentOpts {
     config: String,
 }
 
+/// Main function
 fn main() -> Result<()> {
+    // Initialize logger
     env_logger::init();
+
     info!("Starting agent");
 
+    // Parse CLI options
     let options = AgentOpts::parse();
 
     debug!("loading config file at {}", options.config);
+
+    // Load config file
     let config = AgentConfig::load(options.config.as_str())?;
 
     trace!(
         "config file loaded successfully with content: {:#?}",
         config
     );
 
+    // Initialize external API
     let mut external_api = ExternalApi::new(config.serial.path, config.serial.baud_rate);
 
+    // Send status message to serial port
     external_api.send_status_message()?;
 
+    // Read request message from serial port
     let request_message = external_api.read_from_serial()?;
+
+    // Initialize internal API
     let mut internal_api = InternalApi::new(request_message);
+
+    // Create the workspace
     internal_api.create_workspace()?;
+
+    // Run the steps of the request message
     let response_message = internal_api.run().map_err(|e| anyhow!("{:?}", e))?;
+
+    // Send response message to serial port
     external_api.send_response_message(response_message)?;
 
     info!("Stopping agent");