Merge pull request #13 from darksoil-studio/viktor

missed adding the commented rust files in the last commit.

crates/roles_types/src/lib.rs

@@ -1,18 +1,21 @@
 use hdi::prelude::holo_hash::AgentPubKeyB64;
 use hdi::prelude::*;
 
+///App properties (progenitor info)
 #[derive(Serialize, Deserialize, Debug, SerializedBytes)]
 pub struct Properties {
     pub progenitors: Vec<AgentPubKeyB64>,
 }
 
+///RoleClaim structure
 #[derive(Clone, PartialEq)]
 #[hdk_entry_helper]
 pub struct RoleClaim {
     pub role: String,
     pub assign_role_create_link_hash: ActionHash,
 }
 
+///Validate that agents had acces to the role at the time of the action (an undeleted claim earlier in source chain)
 pub fn validate_agent_had_undeleted_role_claim_at_the_time(
     agent: &AgentPubKey,
     chain_top: &ActionHash,
@@ -38,7 +41,7 @@ pub fn validate_agent_had_undeleted_role_claim_at_the_time(
         ZomeIndex::new(roles_zome_index as u8),
     )
 }
-
+///Validate that agents had acces to the role at the time (with zome index)
 pub fn validate_agent_had_undeleted_role_claim_at_the_time_with_zome_index(
     agent: &AgentPubKey,
     chain_top: &ActionHash,

zomes/coordinator/roles/src/assignees.rs

@@ -6,19 +6,22 @@ use crate::{
     utils::{delete_link_relaxed, delete_relaxed},
 };
 
+///Input structure for assigning roles
 #[derive(Serialize, Deserialize, Debug)]
 pub struct AssignRoleInput {
     pub role: String,
     pub assignees: Vec<AgentPubKey>,
 }
 
+///Inpur structure for unassigning roles
 #[derive(Serialize, Deserialize, Debug)]
 pub struct RequestUnassignRoleInput {
     pub role: String,
     pub assignee: AgentPubKey,
 }
 
-// Just to be able to call this from init
+
+/// Assign role function used in init function
 pub fn assign_role_to_single_agent(
     role: String,
     assignee: AgentPubKey,
@@ -33,6 +36,7 @@ pub fn assign_role_to_single_agent(
     )
 }
 
+///Assigning roles to agents 
 #[hdk_extern]
 pub fn assign_role(input: AssignRoleInput) -> ExternResult<()> {
     let path = role_path(&input.role)?;
@@ -56,10 +60,12 @@ pub fn assign_role(input: AssignRoleInput) -> ExternResult<()> {
     Ok(())
 }
 
+///Generating path to pending_unassignments
 fn pending_unassignments_path() -> Path {
     Path::from("pending_unassignments")
 }
 
+///Creating requests for people to unassign roles
 #[hdk_extern]
 pub fn request_unassign_role(input: RequestUnassignRoleInput) -> ExternResult<()> {
     create_link(
@@ -72,6 +78,7 @@ pub fn request_unassign_role(input: RequestUnassignRoleInput) -> ExternResult<()
     Ok(())
 }
 
+///Agents call this function to unassign their own roles
 #[hdk_extern]
 pub fn unassign_my_role(pending_unassignment_link: ActionHash) -> ExternResult<()> {
     let Some(record) = get(pending_unassignment_link.clone(), GetOptions::network())? else {
@@ -122,6 +129,7 @@ pub fn unassign_my_role(pending_unassignment_link: ActionHash) -> ExternResult<(
     Ok(())
 }
 
+///Get pending unassignments to see if I should unassign of if someone should but haven't
 #[hdk_extern]
 pub fn get_pending_unassignments() -> ExternResult<Vec<Link>> {
     get_links(
@@ -133,6 +141,7 @@ pub fn get_pending_unassignments() -> ExternResult<Vec<Link>> {
     )
 }
 
+///Get all agents that have been assigned a role
 #[hdk_extern]
 pub fn get_assignees_for_role(role: String) -> ExternResult<Vec<Link>> {
     let path = role_path(&role)?;

zomes/coordinator/roles/src/lib.rs

@@ -7,6 +7,7 @@ pub mod assignees;
 pub mod role_claim;
 pub mod utils;
 
+///initial function called when entering happ (if Agent is progenitor then Admin role is claimed)
 #[hdk_extern]
 pub fn init(_: ()) -> ExternResult<InitCallbackResult> {
     // If I'm a progenitor, automatically claim the admin role
@@ -25,6 +26,7 @@ pub fn init(_: ()) -> ExternResult<InitCallbackResult> {
     Ok(InitCallbackResult::Pass)
 }
 
+///Signals available in the module
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(tag = "type")]
 pub enum Signal {
@@ -52,6 +54,7 @@ pub enum Signal {
     },
 }
 
+///Commiting an action to the source chain
 #[hdk_extern(infallible)]
 pub fn post_commit(committed_actions: Vec<SignedActionHashed>) {
     for action in committed_actions {
@@ -61,6 +64,7 @@ pub fn post_commit(committed_actions: Vec<SignedActionHashed>) {
     }
 }
 
+///Generate signals to handle all the actions made with module
 fn signal_action(action: SignedActionHashed) -> ExternResult<()> {
     match action.hashed.content.clone() {
         Action::Create(_create) => {
@@ -128,6 +132,7 @@ fn signal_action(action: SignedActionHashed) -> ExternResult<()> {
     }
 }
 
+///Retrieve entry for a specific action
 fn get_entry_for_action(action_hash: &ActionHash) -> ExternResult<Option<EntryTypes>> {
     let record = match get_details(action_hash.clone(), GetOptions::default())? {
         Some(Details::Record(record_details)) => record_details.record,

zomes/coordinator/roles/src/role_claim.rs

@@ -3,12 +3,14 @@ use roles_integrity::*;
 
 use crate::utils::create_relaxed;
 
+///Claiming a role on agents source chain
 #[hdk_extern]
 pub fn create_role_claim(role_claim: RoleClaim) -> ExternResult<()> {
     create_relaxed(EntryTypes::RoleClaim(role_claim.clone()))?;
     Ok(())
 }
 
+///Get a role claim
 #[hdk_extern]
 pub fn get_role_claim(role_claim_hash: ActionHash) -> ExternResult<Option<Record>> {
     let Some(details) = get_details(role_claim_hash, GetOptions::default())? else {
@@ -22,6 +24,7 @@ pub fn get_role_claim(role_claim_hash: ActionHash) -> ExternResult<Option<Record
     }
 }
 
+///Find undeleted role claims for a role
 #[hdk_extern]
 pub fn query_undeleted_role_claims_for_role(role: String) -> ExternResult<Vec<Record>> {
     let filter = ChainQueryFilter::new()
@@ -60,10 +63,12 @@ pub fn query_undeleted_role_claims_for_role(role: String) -> ExternResult<Vec<Re
     Ok(records_for_role)
 }
 
+///Delete role claim (removing role)
 pub fn delete_role_claim(original_role_claim_hash: ActionHash) -> ExternResult<ActionHash> {
     delete_entry(original_role_claim_hash)
 }
 
+///Find all deletions for role claim
 #[hdk_extern]
 pub fn get_all_deletes_for_role_claim(
     original_role_claim_hash: ActionHash,

zomes/coordinator/roles/src/utils.rs

@@ -1,6 +1,7 @@
 use hdk::prelude::*;
 use roles_integrity::*;
 
+///Allow other processes to get commited to source chain before commiting the commit
 pub fn create_relaxed(entry_type: EntryTypes) -> ExternResult<()> {
     HDK.with(|h| {
         let index = ScopedEntryDefIndex::try_from(&entry_type)?;
@@ -21,6 +22,7 @@ pub fn create_relaxed(entry_type: EntryTypes) -> ExternResult<()> {
     Ok(())
 }
 
+///Allowing other links to be created and commited before commiting link
 pub fn create_link_relaxed<T, E>(
     base_address: impl Into<AnyLinkableHash>,
     target_address: impl Into<AnyLinkableHash>,
@@ -49,6 +51,7 @@ where
     Ok(())
 }
 
+///Allowing for other operations to commit before committing link deletion
 pub fn delete_link_relaxed(address: ActionHash) -> ExternResult<()> {
     HDK.with(|h| {
         h.borrow()
@@ -58,6 +61,7 @@ pub fn delete_link_relaxed(address: ActionHash) -> ExternResult<()> {
     Ok(())
 }
 
+///Allowing for other operations to commit before deleting an entry
 pub fn delete_relaxed(address: ActionHash) -> ExternResult<()> {
     HDK.with(|h| {
         h.borrow()

zomes/integrity/roles/src/admins.rs

@@ -1,8 +1,10 @@
 use hdi::prelude::*;
 use roles_types::validate_agent_had_undeleted_role_claim_at_the_time_with_zome_index;
 
+///Hardcoded admin role need for creating other roles
 pub const ADMIN_ROLE: &'static str = "admin";
 
+///Validating that the Agent had a claim of the ADMIN_ROLE in their source chain prior to some action
 pub fn validate_agent_was_admin_at_the_time(
     agent: &AgentPubKey,
     chain_top: &ActionHash,

zomes/integrity/roles/src/assignees.rs

@@ -2,6 +2,7 @@ use hdi::prelude::*;
 
 use crate::{progenitors, role_path, validate_agent_was_admin_at_the_time, LinkTypes, RoleClaim};
 
+/// Validation of the link that assignees use to claim roles, checks entrytypes, paths and that issuer was admin
 pub fn validate_create_link_role_to_assignee(
     action_hash: &ActionHash,
     action: CreateLink,
@@ -57,6 +58,7 @@ pub fn validate_create_link_role_to_assignee(
     Ok(ValidateCallbackResult::Valid)
 }
 
+///Validates the links that trigger assignees to delete claims to a role
 pub fn validate_delete_link_role_to_assignee(
     action: DeleteLink,
     original_action: CreateLink,
@@ -97,6 +99,7 @@ pub fn validate_delete_link_role_to_assignee(
     Ok(ValidateCallbackResult::Valid)
 }
 
+///Validates links created for unassignments pending (agents that should delete their claims to roles)
 pub fn validate_create_link_pending_unassignments(
     action_hash: &ActionHash,
     action: CreateLink,
@@ -120,6 +123,7 @@ pub fn validate_create_link_pending_unassignments(
     Ok(ValidateCallbackResult::Valid)
 }
 
+///Validates deletions of the pending unassignment links (link integrity and that assignees must be the ones to unassign and delete)
 pub fn validate_delete_link_pending_unassigments(
     action: DeleteLink,
     original_action: CreateLink,

zomes/integrity/roles/src/lib.rs

@@ -15,6 +15,7 @@ pub use progenitors::*;
 pub mod assignees;
 pub use assignees::*;
 
+
 #[derive(Serialize, Deserialize)]
 #[serde(tag = "type")]
 #[hdk_entry_types]
@@ -23,6 +24,7 @@ pub enum EntryTypes {
     RoleClaim(RoleClaim),
 }
 
+///LinkTypes available in the module
 #[derive(Serialize, Deserialize)]
 #[hdk_link_types]
 pub enum LinkTypes {
@@ -44,13 +46,14 @@ pub fn genesis_self_check(_data: GenesisSelfCheckData) -> ExternResult<ValidateC
     Ok(ValidateCallbackResult::Valid)
 }
 
+///Checking the membrane proof of joining agent
 pub fn validate_agent_joining(
     _agent_pub_key: AgentPubKey,
     _membrane_proof: &Option<MembraneProof>,
 ) -> ExternResult<ValidateCallbackResult> {
     Ok(ValidateCallbackResult::Valid)
 }
-
+///Finding the appropriate action for an action hash
 pub fn action_hash(op: &Op) -> &ActionHash {
     match op {
         Op::StoreRecord(StoreRecord { record }) => record.action_address(),
@@ -63,6 +66,7 @@ pub fn action_hash(op: &Op) -> &ActionHash {
     }
 }
 
+///Validate operation
 #[hdk_extern]
 pub fn validate(op: Op) -> ExternResult<ValidateCallbackResult> {
     match op.flattened::<EntryTypes, LinkTypes>()? {

zomes/integrity/roles/src/progenitors.rs

@@ -1,6 +1,7 @@
 use hdi::prelude::*;
 use roles_types::*;
 
+///Returns progenitors 
 #[hdk_extern]
 pub fn progenitors() -> ExternResult<Vec<AgentPubKey>> {
     let properties = dna_info()?.modifiers.properties;

zomes/integrity/roles/src/role_claim.rs

@@ -3,6 +3,7 @@ pub use roles_types::{validate_agent_had_undeleted_role_claim_at_the_time, RoleC
 
 use crate::{role_path, LinkTypes};
 
+///Validate the creation of a role claim for an agent
 pub fn validate_create_role_claim(
     action: EntryCreationAction,
     role_claim: RoleClaim,
@@ -123,6 +124,7 @@ pub fn validate_create_role_claim(
     Ok(ValidateCallbackResult::Valid)
 }
 
+///Validate the update role claim
 pub fn validate_update_role_claim(
     _action: Update,
     _role_claim: RoleClaim,
@@ -134,6 +136,7 @@ pub fn validate_update_role_claim(
     ))
 }
 
+///Validate the deletion of a role claim for an Agent
 pub fn validate_delete_role_claim(
     _action: Delete,
     _original_action: EntryCreationAction,

zomes/integrity/roles/src/roles.rs

@@ -2,22 +2,25 @@ use hdi::prelude::*;
 
 use crate::LinkTypes;
 
+///Generate the all_roles path
 pub fn all_roles_path() -> ExternResult<TypedPath> {
     Path::from("all_roles").typed(LinkTypes::RolesPath)
 }
 
+///Generate the path to role (from all_roles)
 pub fn role_path(role: &String) -> ExternResult<TypedPath> {
     let all_roles = all_roles_path()?;
     let mut components = all_roles.path.0;
     components.push(Component::from(role));
     Path::from(components).typed(LinkTypes::RolesPath)
 }
 
+///Generate the base address for a role based on path
 #[hdk_extern]
 pub fn role_base_address(role: String) -> ExternResult<EntryHash> {
     role_path(&role)?.path_entry_hash()
 }
-
+///Validate the creation correct link paths for role links
 pub fn validate_create_link_roles_path(
     _action: CreateLink,
     base_address: AnyLinkableHash,
@@ -68,6 +71,7 @@ pub fn validate_create_link_roles_path(
     Ok(ValidateCallbackResult::Valid)
 }
 
+///Validate the path of delete links
 pub fn validate_delete_link_roles_path(
     _action: DeleteLink,
     _original_action: CreateLink,