From 193163bca67ed17cab78b710ed50fd69d6e4b5fe Mon Sep 17 00:00:00 2001
From: JMARyA <jmarya@hydrar.de>
Date: Tue, 16 Apr 2024 16:39:08 +0200
Subject: [PATCH] docs

---
 src/config.rs |  6 ++++++
 src/proxy.rs  | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/src/config.rs b/src/config.rs
index 4762904..6f8040e 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -2,12 +2,18 @@ use serde::Deserialize;
 
 use crate::proxy::Mirror;
 
+/// Mirrord configuration
 #[derive(Debug, Deserialize, Clone)]
 pub struct Config {
+    /// List of mirror hosts to fetch data from.
     pub mirrors: Vec<String>,
+    /// Directory path where cached data will be stored.
     pub cache_dir: String,
+    /// Regex for which paths should never use cache
     pub no_cache: String,
+    /// Time-to-live (TTL) duration for cached data in minutes
     pub ttl: usize,
+    /// Regex for allowing only specific path requests
     pub only_allow: Option<String>,
 }
 
diff --git a/src/proxy.rs b/src/proxy.rs
index 412ece5..d408005 100644
--- a/src/proxy.rs
+++ b/src/proxy.rs
@@ -7,6 +7,10 @@ use std::{
 
 use crate::config::Config;
 
+// todo : download from many mirrors and compare results if one acts badly
+// todo : better logging
+// todo : better cache management
+
 pub struct Mirror {
     mirrors: Vec<Arc<String>>,
     data_dir: String,
@@ -59,6 +63,15 @@ impl Mirror {
         }
     }
 
+    /// Checks if the cached data at the specified path is invalid based on the TTL (time-to-live) setting.
+    ///
+    /// # Arguments
+    ///
+    /// * `p` - A reference to the path of the cached data file.
+    ///
+    /// # Returns
+    ///
+    /// * `true` if the cached data is invalid (older than TTL), `false` otherwise.
     pub fn is_cache_invalid(&self, p: &Path) -> bool {
         let try_is_cache_invalid = || {
             let modified = p.metadata().ok()?.modified().ok()?;
@@ -128,6 +141,16 @@ impl Mirror {
         }
     }
 
+    /// Asynchronously fetches cached data from the specified path and returns an HTTP response if the data exists.
+    ///
+    /// # Arguments
+    ///
+    /// * `p` - A reference to the path of the cached data file.
+    /// * `req` - A reference to the HTTP request associated with the fetch operation.
+    ///
+    /// # Returns
+    ///
+    /// An optional HTTP response containing the fetched data if it exists, or `None` if the data does not exist.
     pub async fn fetch_cache(&self, p: &PathBuf, req: &HttpRequest) -> Option<HttpResponse> {
         if p.exists() {
             if p.is_dir() {
@@ -148,6 +171,16 @@ impl Mirror {
         None
     }
 
+    /// Asynchronously fetches data from network mirrors and returns an HTTP response if successful.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The path of the resource to fetch from network mirrors.
+    /// * `local` - A reference to the local path where the fetched data will be stored.
+    ///
+    /// # Returns
+    ///
+    /// An optional HTTP response containing the fetched data if successful, or `None` if fetching fails.
     pub async fn fetch_network(&self, path: &str, local: &PathBuf) -> Option<HttpResponse> {
         let mut mirrors = self.mirrors.clone();
         mirrors.shuffle(&mut rand::thread_rng());