From f3c9326c0c64195d637e2002bff4533f4aa7e5b0 Mon Sep 17 00:00:00 2001
From: Jef Roosens <roosensjef@gmail.com>
Date: Fri, 26 Nov 2021 23:11:03 +0100
Subject: [PATCH] Added some comments

---
 src/proxy.rs | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/src/proxy.rs b/src/proxy.rs
index 2667aad..912eeea 100644
--- a/src/proxy.rs
+++ b/src/proxy.rs
@@ -1,3 +1,4 @@
+//! This file is heavily inspired by the FileServer implementation in Rocket
 use std::path::{Path, PathBuf};
 
 use futures::stream::TryStreamExt;
@@ -87,7 +88,9 @@ impl Handler for ProxyServer
         use rocket::http::uri::fmt::Path;
 
         // ROCKET REQUEST -> REQWEST REQUEST
-        // Path
+
+        // We first parse the path & prepend it with the prefix. If we can't parse it, we return a
+        // BadRequest.
         let allow_dotfiles = self.options.contains(Options::DotFiles);
         let path = req.segments::<Segments<'_, Path>>(0..).ok()
             .and_then(|segments| segments.to_path_buf(allow_dotfiles).ok())
@@ -97,13 +100,14 @@ impl Handler for ProxyServer
             return Outcome::Failure(Status::BadRequest);
         }
 
-        let path = path.unwrap();
-        let path_str = path.to_str(); // Unwrap is safe because we check for is_none() beforehand
+        let path = path.unwrap(); // Unwrap is safe because we check for is_none() beforehand
+        let path_str = path.to_str();
 
         if path_str.is_none() {
             return Outcome::Failure(Status::BadRequest);
         }
 
+        // After confirming we can parse the path, we check if it needs to be normalized
         if self.options.contains(Options::NormalizeDirs) && !req.uri().path().ends_with('/') {
             let normal = req.uri().map_path(|p| format!("{}/", p))
                 .expect("adding a trailing slash to a known good path => valid path")
@@ -112,6 +116,7 @@ impl Handler for ProxyServer
             return Outcome::from_or_forward(req, data, Redirect::permanent(normal));
         }
 
+        // Finally, we create our new URL by combining the root, path & query
         let path_str = path_str.unwrap();
 
         let query_part = req
@@ -126,7 +131,7 @@ impl Handler for ProxyServer
             query_part
         );
 
-        // Headers
+        // Here, we convert the Rocket headers into a HeaderMap that reqwest can use.
         let mut headers = HeaderMap::new();
 
         for header in req.headers().iter() {
@@ -142,14 +147,14 @@ impl Handler for ProxyServer
             headers.insert(name, value);
         }
 
-        // Method
+        // Each method needs to be matched against the other's version
         let method = match req.method() {
             Method::Delete => ReqMethod::DELETE,
             Method::Get => ReqMethod::GET,
             Method::Patch => ReqMethod::PATCH,
             Method::Post => ReqMethod::POST,
             Method::Put => ReqMethod::PUT,
-            _ => todo!(),
+            _ => todo!(), // This should never be reached as the proxy only mounts on these five routes
         };
 
         // And finally, the data