feat: add docs

Author: dancixx

src/extractors/cookie.rs

@@ -0,0 +1,97 @@
+/// This module provides functionality for extracting and managing cookies in HTTP requests.
+/// It includes a `CookieJar` struct that wraps the `cookie` crate's `CookieJar`
+/// and integrates with the application's request lifecycle.
+use anyhow::Result;
+use cookie::{Cookie, CookieJar as RawJar};
+use http::{HeaderMap, header::COOKIE};
+
+use crate::{extractors::FromRequest, types::Request};
+
+/// A wrapper around the `cookie::CookieJar` that provides methods for managing cookies
+/// in HTTP requests and responses.
+///
+/// This struct allows adding, removing, and retrieving cookies, as well as creating
+/// a `CookieJar` instance from HTTP headers.
+pub struct CookieJar(RawJar);
+
+impl CookieJar {
+    /// Creates a new, empty `CookieJar` instance.
+    ///
+    /// # Returns
+    /// A new `CookieJar` with no cookies.
+    pub fn new() -> Self {
+        Self(RawJar::new())
+    }
+
+    /// Creates a `CookieJar` instance from the `Cookie` header in the provided HTTP headers.
+    ///
+    /// # Parameters
+    /// - `headers`: A reference to the HTTP headers containing the `Cookie` header.
+    ///
+    /// # Returns
+    /// A `CookieJar` populated with cookies parsed from the `Cookie` header.
+    pub fn from_headers(headers: &HeaderMap) -> Self {
+        let mut jar = RawJar::new();
+
+        if let Some(val) = headers.get(COOKIE).and_then(|v| v.to_str().ok()) {
+            for s in val.split(';') {
+                if let Ok(c) = Cookie::parse(s.trim()) {
+                    jar.add_original(c.into_owned());
+                }
+            }
+        }
+
+        Self(jar)
+    }
+
+    /// Adds a cookie to the `CookieJar`.
+    ///
+    /// # Parameters
+    /// - `cookie`: The cookie to add.
+    pub fn add(&mut self, cookie: Cookie<'static>) {
+        self.0.add(cookie);
+    }
+
+    /// Removes a cookie from the `CookieJar` by its name.
+    ///
+    /// # Parameters
+    /// - `name`: The name of the cookie to remove.
+    pub fn remove(&mut self, name: &str) {
+        self.0.remove(Cookie::from(name.to_owned()));
+    }
+
+    /// Retrieves a cookie from the `CookieJar` by its name.
+    ///
+    /// # Parameters
+    /// - `name`: The name of the cookie to retrieve.
+    ///
+    /// # Returns
+    /// An `Option` containing a reference to the cookie if it exists, or `None` otherwise.
+    pub fn get(&self, name: &str) -> Option<&Cookie<'_>> {
+        self.0.get(name)
+    }
+
+    /// Returns an iterator over all cookies in the `CookieJar`.
+    ///
+    /// # Returns
+    /// An iterator yielding references to the cookies.
+    pub fn iter(&self) -> impl Iterator<Item = &Cookie<'static>> {
+        self.0.iter()
+    }
+}
+
+impl<'a> FromRequest<'a> for CookieJar {
+    /// Extracts a `CookieJar` from an HTTP request.
+    ///
+    /// This implementation reads the `Cookie` header from the request and populates
+    /// the `CookieJar` with the parsed cookies.
+    ///
+    /// # Parameters
+    /// - `req`: A reference to the HTTP request.
+    ///
+    /// # Returns
+    /// A `Result` containing the `CookieJar` if successful.
+    fn from_request(req: &'a Request) -> Result<Self> {
+        Ok(CookieJar::from_headers(req.headers()))
+    }
+}

src/extractors/cookie_jar.rs

@@ -1,3 +1,5 @@
+/// This module provides middleware for handling JWT authentication in a web application.
+/// It supports multiple algorithms for verifying JWTs and integrates with the application's request/response lifecycle.
 use std::{collections::HashMap, future::Future, pin::Pin, sync::Arc};
 
 use http::{StatusCode, header::AUTHORIZATION};
@@ -10,6 +12,8 @@ use crate::{
     types::{Request, Response},
 };
 
+/// Represents a verification key for various JWT algorithms.
+/// This enum supports multiple algorithms, including HMAC, RSA, and EdDSA.
 pub enum AnyVerifyKey {
     HS256(Arc<HS256Key>),
     HS384(Arc<HS384Key>),
@@ -32,6 +36,10 @@ pub enum AnyVerifyKey {
 }
 
 impl AnyVerifyKey {
+    /// Returns the algorithm identifier for the verification key.
+    ///
+    /// # Returns
+    /// A static string representing the algorithm (e.g., "HS256", "RS256").
     pub fn alg_id(&self) -> &'static str {
         match self {
             Self::HS256(_) => "HS256",
@@ -55,6 +63,13 @@ impl AnyVerifyKey {
         }
     }
 
+    /// Verifies a JWT token using the current verification key.
+    ///
+    /// # Parameters
+    /// - `token`: The JWT token to verify.
+    ///
+    /// # Returns
+    /// A `Result` containing the decoded claims if verification succeeds, or an error otherwise.
     pub fn verify<C>(&self, token: &str) -> Result<JWTClaims<C>, jwt_simple::Error>
     where
         C: Serialize + DeserializeOwned,
@@ -83,6 +98,10 @@ impl AnyVerifyKey {
     }
 }
 
+/// Middleware for handling JWT authentication.
+///
+/// This struct allows configuring multiple verification keys for different algorithms
+/// and integrates with the application's middleware chain.
 pub struct JwtAuth<T>
 where
     T: DeserializeOwned + Send + Sync + 'static,
@@ -95,6 +114,14 @@ impl<T> JwtAuth<T>
 where
     T: DeserializeOwned + Send + Sync + 'static,
 {
+    /// Creates a new instance of `JwtAuth` with the provided verification keys.
+    ///
+    /// # Parameters
+    /// - `keys`: A `HashMap` where the key is the algorithm identifier (e.g., "HS256")
+    ///   and the value is the corresponding verification key.
+    ///
+    /// # Returns
+    /// A new `JwtAuth` instance.
     pub fn new(keys: HashMap<&'static str, AnyVerifyKey>) -> Self {
         Self {
             keys: Arc::new(keys),
@@ -107,6 +134,13 @@ impl<T> IntoMiddleware for JwtAuth<T>
 where
     T: Clone + Serialize + DeserializeOwned + Send + Sync + 'static,
 {
+    /// Converts the `JwtAuth` instance into a middleware function.
+    ///
+    /// The middleware extracts the JWT token from the `Authorization` header,
+    /// verifies it using the configured keys, and injects the claims into the request's extensions.
+    ///
+    /// # Returns
+    /// A closure that represents the middleware function.
     fn into_middleware(
         self,
     ) -> impl Fn(Request, Next) -> Pin<Box<dyn Future<Output = Response> + Send + 'static>>