[ADD] documentation

README.md

@@ -0,0 +1,42 @@
+# sirius
+
+## SIRIUS
+Sirius is an api that use to list and modify kratos identity.
+
+### routes
+
+``/api/iam/project``:
+This route is used to add or list projects in the identity 
+send a GET request with a kratos cookie to list the projects.
+send a POST request with a kratos cookie and the projects to add.
+
+``/api/iam/group``:
+This route is used to list groups in an identity or add projects to a group
+send a GET request with a kratos cookie to list the groups in the identity.
+send a POST request with a kratos cookie and the projects or users to add.
+
+``/api/iam/organisation``:
+This route is used to list organisations in an identity or add  to a group
+send a GET request with a kratos cookie to list the organizations in the identity.
+send a POST request with a kratos cookie and the projects, groups or users to add.
+
+In all the POST case you must use the payload json:
+```json
+{
+    "id" = "string"
+    "resource_type" = "string"
+    "ressource_id" = "string"
+    "value" = json value
+}
+```
+The id field represent the id of the identity to modify(can be anid or an email
+depending on the route).
+
+The resource_type field represent the type of permission to modify:
+- user
+- group
+- organization
+
+The ressource id represent the id of resource to modify.
+
+the value field represent the data to modify the identity with

src/config.rs

@@ -23,7 +23,7 @@ use crate::permission::iam_client::IamClient;
 
 pub const CONFIG_FALLBACK: &str = "test/config.toml";
 
-///structure containing kafka consumer data
+/// Structure representing kafka producer config.
 #[derive(Deserialize, Clone, Default)]
 pub struct Producer {
     pub topics: Vec<String>,
@@ -41,7 +41,7 @@ impl fmt::Debug for Producer {
 }
 
 impl Producer {
-    ///update the producer Producers if needed.
+    /// Update the producer if needed.
     pub fn update(&mut self, broker: &str) -> Result<()> {
         let mut new_producer = HashMap::new();
         let producer = match self.clients {
@@ -61,6 +61,7 @@ impl Producer {
     }
 }
 
+/// Structure representing the kafka config.
 #[derive(Deserialize, Clone, Default, Debug)]
 pub struct Kafka {
     pub broker: String,
@@ -74,32 +75,36 @@ impl Kafka {
     }
 }
 
+/// Structure representing the service port config.
 #[derive(Deserialize, Clone, Default, Debug)]
 pub struct Ports {
     pub main: String,
     pub health: String,
 }
 
+/// Structure representing the service config.
 #[derive(Deserialize, Clone, Default, Debug)]
 pub struct Service {
     pub addr: String,
     pub ports: Ports,
 }
 
+/// Structure representing the iam connection config.
 #[derive(Deserialize, Clone, Default, Debug)]
 pub struct Iam {
     pub service: Service,
     #[serde(skip)]
     pub client: Option<IamClient<Channel>>,
 }
 
+/// Structure representing the opa connection config.
 #[derive(Deserialize, Clone, Default, Debug)]
 pub struct Opa {
     pub addr: String,
     pub mode: String,
 }
 
-///structure containing the configuaration of the application
+/// Structure containing the configuaration of the application.
 #[derive(Deserialize, Clone, Default, Debug)]
 pub struct SiriusConfig {
     // pub prefix: String,

src/controller/list.rs

@@ -8,6 +8,7 @@ use tracing::{debug, error, info};
 
 use crate::config::SiriusConfig;
 
+/// Populate the projects id HashSet with the given data.
 fn populate_set(projects: &mut HashSet<String>, mut data: Value) -> Result<()> {
     let data = data.take();
     match data {
@@ -33,6 +34,7 @@ fn populate_set(projects: &mut HashSet<String>, mut data: Value) -> Result<()> {
     Ok(())
 }
 
+/// Extract the projects id from the identity and store them in the projects hashset.
 fn extract_projects(projects: &mut HashSet<String>, mut data: Value) -> Result<()> {
     debug!("{data:?}");
     let data = data
@@ -48,6 +50,8 @@ fn extract_projects(projects: &mut HashSet<String>, mut data: Value) -> Result<(
     Ok(())
 }
 
+/// extract projects id from the identity in project, group and organisation and returns them in a
+/// hashset.
 pub async fn list_project_controller(
     identity: Identity,
     config: &SiriusConfig,
@@ -81,6 +85,8 @@ pub async fn list_project_controller(
     Ok(projects)
 }
 
+/// Extract the ask data type of a given identity.
+/// Where it recuperate them is configured with mode in the opa section of te config file.
 pub async fn list_controller(
     identity: Identity,
     data_type: &str,
@@ -99,7 +105,7 @@ pub async fn list_controller(
         bail!("no metadata in this user!")
     };
     if let Some(data) = metadata.get(data_type) {
-        info!("estracting: {data_type}");
+        info!("extracting: {data_type}");
         let data = data
             .as_object()
             .ok_or_else(|| anyhow!("this should be a map!"))?;

src/controller/sync.rs

@@ -11,7 +11,14 @@ use crate::{
     permission::{Input, Mode},
     utils::{error::send_error, kafka::send_to_kafka},
 };
+/// Enum representing the diferent sync mode.
+#[derive(Debug)]
+pub enum SyncMode {
+    User(Vec<(String, Value)>),
+    Project(Vec<String>),
+}
 
+/// Extract all the id needing synchronization/
 fn extract_sync_id(
     identity: &mut Identity,
     sync_type: &str,
@@ -43,12 +50,6 @@ fn extract_sync_id(
     Ok(ret)
 }
 
-#[derive(Debug)]
-pub enum SyncMode {
-    User(Vec<(String, Value)>),
-    Project(Vec<String>),
-}
-
 pub async fn sync_groups(
     config: Arc<SiriusConfig>,
     identity: &Identity,
@@ -117,6 +118,8 @@ pub async fn sync_user(
         }
     }
 }
+
+/// Send data to iam to replace data in an identity.
 async fn send_to_iam(
     config: &Arc<SiriusConfig>,
     id: &str,
@@ -148,6 +151,7 @@ async fn send_to_iam(
     Ok(())
 }
 
+/// Extract project ids already present in the identity.
 fn extract_old_project(meta: &mut Value) -> Result<Vec<String>> {
     let old_projects = match meta.get_mut("project") {
         Some(proj) => proj,
@@ -179,6 +183,8 @@ fn extract_old_project(meta: &mut Value) -> Result<Vec<String>> {
     Ok(projects)
 }
 
+/// Sync user metadata, group metadata and organisation metadata.
+/// The mode dermine the type of metadata to sync.
 pub async fn sync(
     config: &Arc<SiriusConfig>,
     mut identity: Identity,

src/controller/update.rs

@@ -17,7 +17,7 @@ use crate::{
     router::{Data, IDType},
 };
 
-///get an identities form kratos by mail
+/// Get an identities from kratos by mail.
 async fn get_identity_by_mail(client: &Configuration, id: &str) -> Result<Identity> {
     let mut addr = format!("{}/admin/identities", client.base_path);
     addr = addr + "?credentials_identifier=" + id;
@@ -32,6 +32,7 @@ async fn get_identity_by_mail(client: &Configuration, id: &str) -> Result<Identi
     Ok(identity)
 }
 
+/// Get an identity from kratos.
 async fn get_kratos_identity(config: &SiriusConfig, id: &IDType) -> Result<Identity> {
     let Some(client) = &config.kratos.client else {
         bail!("kratos client not initialized")
@@ -43,6 +44,7 @@ async fn get_kratos_identity(config: &SiriusConfig, id: &IDType) -> Result<Ident
     Ok(identity)
 }
 
+/// Send data to iam to add permition to an identity.
 async fn send_to_iam(identity: Arc<Identity>, config: Arc<SiriusConfig>, data: Data) -> Result<()> {
     let mut client = config
         .iam
@@ -71,7 +73,7 @@ async fn send_to_iam(identity: Arc<Identity>, config: Arc<SiriusConfig>, data: D
     Ok(())
 }
 
-///send a call to iam to update an identity metadata
+/// Send a call to iam to update an identity metadata.
 pub async fn update_controller(
     config: Arc<SiriusConfig>,
     payload: Vec<Data>,

src/handelers.rs

@@ -4,7 +4,8 @@ use tokio::signal;
 use tracing::{error, info};
 
 #[cfg(not(tarpaulin_include))]
-///handle the shutdown signal
+/// This function hold a channel, when a shut down signal is intercepted it drop
+/// this channel completing a future that trigger the graceful shutdown of the app.
 pub async fn shutdown_signal_trigger(trigger: Trigger) {
     let ctrl_c = async {
         signal::ctrl_c()
@@ -32,14 +33,14 @@ pub async fn shutdown_signal_trigger(trigger: Trigger) {
     drop(trigger);
 }
 
+/// This function await for the message to complete to trigger the graceful shutdown.
 #[cfg(not(tarpaulin_include))]
-///handle the shutdown signal
 pub async fn shutdown_signal(shutdown: Tripwire) {
     shutdown.await;
 }
 
 #[cfg(not(tarpaulin_include))]
-///handle fallback
+/// Handle fallback uri.
 pub async fn fallback(uri: Uri) -> (StatusCode, String) {
     error!("route not found: {uri}");
     (StatusCode::NOT_FOUND, format!("No route for {uri}"))

src/router.rs

@@ -21,6 +21,7 @@ use crate::{
     utils::error::send_error,
 };
 
+/// Enum representing  the type of id to use to get the kratos identity.
 #[derive(Deserialize, Clone, Debug)]
 #[serde(untagged)]
 pub enum IDType {
@@ -37,6 +38,7 @@ impl Display for IDType {
     }
 }
 
+/// Structure representing the payload data.
 #[derive(Deserialize, Clone, Debug)]
 pub struct Data {
     //id :can be the email or the uuid depending of the endpoint
@@ -86,6 +88,8 @@ async fn update_organisation_handler(
     }
     Ok(())
 }
+
+/// This route is used to update the groups of an organization them sync the groups and the users.
 #[tracing::instrument]
 #[axum_macros::debug_handler]
 pub async fn update_organisation(
@@ -163,6 +167,8 @@ async fn update_groups_handler(
     }
     Ok(())
 }
+
+/// This route is used to update a group then sync the users groups and projects.
 #[tracing::instrument]
 #[axum_macros::debug_handler]
 pub async fn update_groups(
@@ -205,6 +211,7 @@ async fn update_projects_handler(
     Ok(())
 }
 
+/// This route is used to update an user projects.
 #[tracing::instrument]
 #[axum_macros::debug_handler]
 pub async fn update_projects(
@@ -243,6 +250,8 @@ async fn list_projects_handler(
     let resp = serde_json::to_string(&data)?;
     Ok(resp)
 }
+
+///This route list all the projects from an identity in the configured mode (public, admin or trait).
 #[tracing::instrument]
 #[axum_macros::debug_handler]
 pub async fn list_projects(
@@ -279,6 +288,7 @@ async fn list_groups_handler(
     Ok(resp)
 }
 
+///This route list the groups from an identity in the configured mode (public, admin or trait).
 #[tracing::instrument]
 #[axum_macros::debug_handler]
 pub async fn list_groups(
@@ -315,6 +325,7 @@ async fn list_orga_handler(
     Ok(resp)
 }
 
+///This route list all the organisations from an identity in the configured mode (public, admin or trait).
 #[tracing::instrument]
 #[axum_macros::debug_handler]
 pub async fn list_orga(

src/utils/error.rs

@@ -3,13 +3,14 @@ use serde::Serialize;
 
 use crate::{config::Kafka, utils::kafka::send_to_kafka};
 
+/// Repesentation of the data to send to the error kafka topic.
 #[derive(Serialize)]
 pub struct ErrorData<'a> {
     code: &'a str,
     message: String,
 }
 
-///send error to the given kafka topic
+///Send error to the given kafka topic.
 #[cfg(not(tarpaulin_include))]
 pub async fn send_error<T>(config: &Kafka, topic: &str, data: T, correlation_id: &str) -> Result<()>
 where

src/utils/kafka.rs

@@ -10,7 +10,7 @@ use tracing::info;
 
 use crate::config::Kafka;
 
-///Send data to kafka.
+/// Send data to kafka.
 #[cfg(not(tarpaulin_include))]
 pub async fn send_to_kafka<T: Serialize>(
     _config: &Kafka,

src/utils/opa.rs

@@ -5,6 +5,7 @@ use rs_utils::kratos::Identity;
 
 use crate::config::SiriusConfig;
 
+/// Structure representing the input part of the structure to esnd to opa.
 #[derive(Deserialize, Serialize)]
 struct Input<'a> {
     uri: &'a str,
@@ -13,12 +14,15 @@ struct Input<'a> {
     resource: &'a str,
 }
 
+/// Structure representing the data to send to opa.
 #[derive(Deserialize, Serialize)]
 struct OpaData<'a> {
     #[serde(borrow)]
     input: Input<'a>,
     data: Identity,
 }
+
+/// Call the opa api to validate the role.
 pub async fn validate_roles(
     config: &SiriusConfig,
     identity: &Identity,