From 5d9ab5150660b373f4a63aa7fa278e161170198c Mon Sep 17 00:00:00 2001 From: Nishant Joshi Date: Wed, 25 Oct 2023 14:41:58 +0530 Subject: [PATCH] doc(crate): add documentation for functions and interfaces --- src/app.rs | 6 ++++++ src/config.rs | 4 ++++ src/crypto.rs | 5 +++++ src/crypto/aes.rs | 7 +++++++ src/routes/data.rs | 8 ++++++++ src/storage.rs | 22 ++++++++++++++++++++++ src/storage/db.rs | 1 + 7 files changed, 53 insertions(+) diff --git a/src/app.rs b/src/app.rs index aac8429..46154e9 100644 --- a/src/app.rs +++ b/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, diff --git a/src/config.rs b/src/config.rs index b07d613..54c8e95 100644 --- a/src/config.rs +++ b/src/config.rs @@ -25,6 +25,7 @@ pub struct Secrets { pub master_key: Vec, } +/// Function to deserialize hex -> Vec this is used in case of non KMS decryption fn deserialize_hex<'de, D>(deserializer: D) -> Result, 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::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, ) -> Result { diff --git a/src/crypto.rs b/src/crypto.rs index a97dd2e..d353d0e 100644 --- a/src/crypto.rs +++ b/src/crypto.rs @@ -1,3 +1,8 @@ +/// +/// Encryption +/// +/// A trait to be used internally for maintaining and managing encryption algorithms +/// pub trait Encryption { type ReturnType; fn encrypt(&self, input: I) -> Self::ReturnType; diff --git a/src/crypto/aes.rs b/src/crypto/aes.rs index d7510cb..bfa639e 100644 --- a/src/crypto/aes.rs +++ b/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 +/// pub struct GcmAes256 { secret: Vec, } diff --git a/src/routes/data.rs b/src/routes/data.rs index 3e62c5c..7b672f9 100644 --- a/src/routes/data.rs +++ b/src/routes/data.rs @@ -16,6 +16,10 @@ use crate::{ mod transformers; mod types; + +/// +/// Function for creating the server that is specifically handling the cards api +/// pub fn serve() -> axum::Router { axum::Router::new() .route("/add", post(add_card)) @@ -23,6 +27,8 @@ pub fn serve() -> axum::Router { .route("/retrieve", get(retrieve_card)) } + +/// `/data/add` handling the requirement of storing cards pub async fn add_card( extract::State(state): extract::State, Json(request): Json, @@ -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, Json(request): Json, @@ -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, Json(request): Json, diff --git a/src/storage.rs b/src/storage.rs index 2275f7d..a8add1c 100644 --- a/src/storage.rs +++ b/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>, @@ -27,6 +28,7 @@ pub struct Storage { type DeadPoolConnType = Object; impl Storage { + /// Create a new storage interface from configuration pub async fn new(database_url: String) -> error_stack::Result { let config = pooled_connection::AsyncDieselConnectionManager::::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 { self.pg_pool .get() @@ -46,10 +49,15 @@ 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>; + /// 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, @@ -57,12 +65,16 @@ pub trait MerchantInterface { key: &Self::Algorithm, ) -> CustomResult; + /// 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; + + /// Insert a new merchant in the database by encrypting the dek with `master_key` async fn insert_merchant( &self, new: types::MerchantNew, @@ -70,9 +82,15 @@ pub trait MerchantInterface { ) -> CustomResult; } + +/// +/// LockerInterface: +/// +/// Interface for interacting with the locker database table #[async_trait::async_trait] pub trait LockerInterface { type Algorithm: Encryption, Vec>; + /// Fetch payment data from locker table by decrypting with `dek` async fn find_by_locker_id_merchant_id_customer_id( &self, locker_id: Secret, @@ -81,12 +99,16 @@ pub trait LockerInterface { customer_id: String, key: &Self::Algorithm, ) -> CustomResult; + + + /// 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; + /// Delete card from the locker, without access to the `dek` async fn delete_from_locker( &self, locker_id: Secret, diff --git a/src/storage/db.rs b/src/storage/db.rs index 94a912f..2c81993 100644 --- a/src/storage/db.rs +++ b/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;