doc(crate): add documentation for functions and interfaces

src/app.rs

@@ -5,6 +5,12 @@ use hyper::server::conn;
 
 use crate::{config, error, routes, storage};
 
+///
+/// AppState:
+///
+///
+/// The state that is passed
+///
 #[derive(Clone)]
 pub struct AppState {
     pub db: storage::Storage,

src/config.rs

@@ -25,6 +25,7 @@ pub struct Secrets {
     pub master_key: Vec<u8>,
 }
 
+/// Function to deserialize hex -> Vec<u8> this is used in case of non KMS decryption
 fn deserialize_hex<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
 where
     D: serde::Deserializer<'de>,
@@ -39,6 +40,7 @@ where
     Ok(bytes)
 }
 
+/// Get the origin directory of the project
 pub fn workspace_path() -> PathBuf {
     if let Ok(manifest_dir) = std::env::var("CARGO_MANIFEST_DIR") {
         let path = PathBuf::from(manifest_dir);
@@ -49,10 +51,12 @@ pub fn workspace_path() -> PathBuf {
 }
 
 impl Config {
+    /// Function to build the configuration by picking it from default locations
     pub fn new() -> Result<Self, config::ConfigError> {
         Self::new_with_config_path(None)
     }
 
+    /// Function to build the configuration by picking it from default locations
     pub fn new_with_config_path(
         explicit_config_path: Option<PathBuf>,
     ) -> Result<Self, config::ConfigError> {

src/crypto.rs

@@ -1,3 +1,8 @@
+///
+/// Encryption
+///
+/// A trait to be used internally for maintaining and managing encryption algorithms
+///
 pub trait Encryption<I, O> {
     type ReturnType<T>;
     fn encrypt(&self, input: I) -> Self::ReturnType<O>;

src/crypto/aes.rs

@@ -2,6 +2,13 @@ use crate::error;
 use error_stack::ResultExt;
 use ring::aead::{self, BoundKey};
 
+
+///
+/// GcmAes256
+///
+/// The algorithm use to perform GcmAes256 encryption/decryption. This is implemented for data
+/// Vec<u8>
+///
 pub struct GcmAes256 {
     secret: Vec<u8>,
 }

src/routes/data.rs

@@ -16,13 +16,19 @@ use crate::{
 mod transformers;
 mod types;
 
+
+/// 
+/// Function for creating the server that is specifically handling the cards api
+///
 pub fn serve() -> axum::Router<AppState> {
     axum::Router::new()
         .route("/add", post(add_card))
         .route("/delete", post(delete_card))
         .route("/retrieve", get(retrieve_card))
 }
 
+
+/// `/data/add` handling the requirement of storing cards
 pub async fn add_card(
     extract::State(state): extract::State<AppState>,
     Json(request): Json<types::StoreCardRequest>,
@@ -53,6 +59,7 @@ pub async fn add_card(
     Ok(Json(card.into()))
 }
 
+/// `/data/delete` handling the requirement of deleting cards
 pub async fn delete_card(
     extract::State(state): extract::State<AppState>,
     Json(request): Json<types::DeleteCardRequest>,
@@ -89,6 +96,7 @@ pub async fn delete_card(
     }))
 }
 
+/// `/data/retrieve` handling the requirement of retrieving cards
 pub async fn retrieve_card(
     extract::State(state): extract::State<AppState>,
     Json(request): Json<types::RetrieveCardRequest>,

src/storage.rs

@@ -19,6 +19,7 @@ pub mod types;
 
 pub trait State {}
 
+/// Storage State that is to be passed though the application
 #[derive(Clone)]
 pub struct Storage {
     pg_pool: Arc<Pool<AsyncPgConnection>>,
@@ -27,6 +28,7 @@ pub struct Storage {
 type DeadPoolConnType = Object<AsyncPgConnection>;
 
 impl Storage {
+    /// Create a new storage interface from configuration
     pub async fn new(database_url: String) -> error_stack::Result<Self, error::StorageError> {
         let config =
             pooled_connection::AsyncDieselConnectionManager::<AsyncPgConnection>::new(database_url);
@@ -38,6 +40,7 @@ impl Storage {
         })
     }
 
+    /// Get connection from database pool for accessing data
     pub async fn get_conn(&self) -> error_stack::Result<DeadPoolConnType, error::StorageError> {
         self.pg_pool
             .get()
@@ -46,33 +49,48 @@ impl Storage {
     }
 }
 
+/// 
+/// MerchantInterface:
+/// 
+/// Interface providing functional to interface with the merchant table in database
 #[async_trait::async_trait]
 pub trait MerchantInterface {
     type Algorithm: Encryption<Vec<u8>, Vec<u8>>;
 
+    /// find merchant from merchant table with `merchant_id` and `tenant_id` with key as master key
     async fn find_by_merchant_id(
         &self,
         merchant_id: String,
         tenant_id: String,
         key: &Self::Algorithm,
     ) -> CustomResult<types::Merchant, error::StorageError>;
 
+    /// find merchant from merchant table with `merchant_id` and `tenant_id` with key as master key
+    /// and if not found create a new merchant
     async fn find_or_create_by_merchant_id(
         &self,
         merchant_id: String,
         tenant_id: String,
         key: &Self::Algorithm,
     ) -> CustomResult<types::Merchant, error::StorageError>;
+
+    /// Insert a new merchant in the database by encrypting the dek with `master_key`
     async fn insert_merchant(
         &self,
         new: types::MerchantNew,
         key: &Self::Algorithm,
     ) -> CustomResult<types::Merchant, error::StorageError>;
 }
 
+
+///
+/// LockerInterface:
+///
+/// Interface for interacting with the locker database table
 #[async_trait::async_trait]
 pub trait LockerInterface {
     type Algorithm: Encryption<Vec<u8>, Vec<u8>>;
+    /// Fetch payment data from locker table by decrypting with `dek`
     async fn find_by_locker_id_merchant_id_customer_id(
         &self,
         locker_id: Secret<String>,
@@ -81,12 +99,16 @@ pub trait LockerInterface {
         customer_id: String,
         key: &Self::Algorithm,
     ) -> CustomResult<types::Locker, error::StorageError>;
+
+
+    /// Insert payment data from locker table by decrypting with `dek`
     async fn insert_or_get_from_locker(
         &self,
         new: types::LockerNew,
         key: &Self::Algorithm,
     ) -> CustomResult<types::Locker, error::StorageError>;
 
+    /// Delete card from the locker, without access to the `dek`
     async fn delete_from_locker(
         &self,
         locker_id: Secret<String>,

src/storage/db.rs

@@ -12,6 +12,7 @@ use super::types::StorageDecryption;
 use super::types::StorageEncryption;
 use super::{schema, types, CustomResult, LockerInterface, MerchantInterface, Storage};
 
+
 #[async_trait::async_trait]
 impl MerchantInterface for Storage {
     type Algorithm = GcmAes256;