Feature/diagrams (#207)

* First draft of mount

* First draft for change_pass

* Draft for open_file

* Tryout of online rendering

* Incomplete read

* Update change pass to mermaid

* More context into read

* Cleanup with mermaid

* Migrate to mermaid

* Cleanup

* Add write

* Draft for create file

* Draft for search

* Draft close

* Update close

* Convert open to mermaid

* Fix styling

* Update with mount

* Draft idea for lib usage

* Update lib usage

* Included encryptedfs usage

* Rename doc to docs

* Fix formatting

* Add cli usage doc

* Update readme

---------

Co-authored-by: Sorin Zamfir <[email protected]>

README.md

@@ -80,8 +80,12 @@ In progress:
   changes. This makes the write operations atomic.
 - Multiple writes in parallel to the same file, ideal for torrent like applications.
 
+# Docs
+
 [![rencfs](website/resources/layers.png)](website/resources/layers.png)
 
+For detailed description of the various sequence flows please look into [Flows](docs/flows.md). 
+
 # Stack
 
 - it's fully async built upon [tokio](https://crates.io/crates/tokio) and [fuse3](https://crates.io/crates/fuse3)

docs/flows.md

@@ -0,0 +1,22 @@
+
+# Sequence flow diagrams
+
+The following diagrams depict the main flows supported by the current implementation. They depict the high-level interactions between the various components of the filesystem which means some details have been omitted. 
+
+> [!WARNING] 
+> The single source of truth for in-depth interactions is the source code itself.  
+
+- [Mount](uml/mount.md)
+- [Change Password](uml/change_pass.md)
+- [Open File](uml/open_file.md)
+- [Close File](uml/close_file.md)
+- [Read](uml/read.md)
+- [Write](uml/write.md)
+- [Create File](uml/create_file.md)
+- [Search File](uml/search_file.md)
+
+Usage flows:
+
+- [Cli usage](uml/cli_usage.md)
+- [Rencfs as a lib](uml/lib_rencfs_usage.md)
+- [Encryptedfs as a lib](uml/lib_encryptedfs_usage.md)

docs/uml/change_pass.md

@@ -0,0 +1,43 @@
+```mermaid
+sequenceDiagram
+    box run.rs 
+        participant rn_chng_pass as run_change_password
+    end
+
+    box encryptedfs.rs
+        participant encfs_passwd as EncryptedF::passwd
+        participant chk_stucture as check_structure
+    end
+
+    box crypto.rs
+        participant der_key as derive_key
+        participant cr_read as create_read
+        participant atomic_enc_ser as atomic_serialize_encrypt_into
+    end
+
+    box  bincode [external]
+        participant des_from as deserialize_from
+        participant ser_into as serialize_into
+    end
+
+    rn_chng_pass -->> encfs_passwd : 
+    encfs_passwd --> chk_stucture : 
+    chk_stucture -->> encfs_passwd : 
+    encfs_passwd -->> des_from : get [key_salt]
+    des_from -->> encfs_passwd : [key_salt]
+
+    encfs_passwd -->> der_key : [old_pass,cypher,key_salt]
+    der_key -->> encfs_passwd : [current key]
+
+    encfs_passwd -->> cr_read:  get [encryption_key]
+    cr_read -->> encfs_passwd: [encryption_key] 
+
+    encfs_passwd --> der_key : [new-pass,cypher,key_salt]
+    der_key -->> encfs_passwd : [new_key]
+
+    encfs_passwd -->> atomic_enc_ser : [new_key,cypher,encryption_key]
+    atomic_enc_ser -->> ser_into : 
+    ser_into -->> atomic_enc_ser : 
+    atomic_enc_ser -->> encfs_passwd : 
+    encfs_passwd -->> rn_chng_pass : 
+```

docs/uml/cli_usage.md

@@ -0,0 +1,32 @@
+```mermaid
+sequenceDiagram 
+    actor user
+    participant rencfs as rencfs-cli
+    participant filesystem
+
+    user -->> rencfs : --data-dir /home/user/data <br> --mount-point /home/user/mnt
+    rencfs -->> user : password ?
+    user -->> rencfs : 1234
+    rencfs -->> filesystem : create /home/user/data <br> create /home/user/mnt
+    create participant /home/user/mnt 
+    filesystem -->> /home/user/mnt : 
+    create participant /home/user/data
+    filesystem -->> /home/user/data : 
+    filesystem -->> rencfs : 
+    rencfs -->> filesystem : mount /home/user/data <br> under /home/user/mnt
+    filesystem -->> rencfs : 
+    user -->> /home/user/mnt : create file
+    /home/user/mnt -->> rencfs : create file
+    rencfs -->> rencfs : create encrypted file and metadata
+    rencfs -->> /home/user/data : store encrypted file and medatada
+    /home/user/data -->> rencfs : 
+    rencfs -->> /home/user/mnt : file created 
+    /home/user/mnt -->> user : file created
+    user -->> rencfs : ctrl+c
+    rencfs -->> filesystem : unmount /home/user/data <br> from /home/user/mnt
+    filesystem--x/home/user/mnt : 
+    filesystem--x/home/user/data : 
+    filesystem -->> rencfs : 
+    rencfs --x rencfs : exit
+```
+

docs/uml/close_file.md

@@ -0,0 +1,33 @@
+```mermaid
+sequenceDiagram
+    box fuse3[external]
+        participant ext_release as release
+    end 
+
+    box linux.rs
+        participant release as EncryptedFsFuse3::release
+    end  
+
+    box encyrptedfs.rs
+        participant enc_release as EncryptedFs::release
+        participant enc_flush as EncryptedFs::flush
+        participant enc_getattr as EncryptedFs::get_attr
+        participant enc_setattr as EncryptedFs::set_attr
+    end  
+
+    ext_release -->> release : [file_inode,file_handle,flags,lock_owner,flush]
+    opt flush true
+        release -->> enc_flush : [file_handle]
+        enc_flush -->> release : 
+    end
+    release -->> enc_release : [file_handle]
+    enc_release -->> release : 
+    opt file_handle write opened
+        release -->> enc_getattr : [file_inode]
+        enc_getattr -->> release : [file_attributes]
+        release -->> release : clear special permissions
+        release -->> enc_setattr : [file_inode,file_attributes]
+        enc_setattr -->> release : 
+    end
+    release -->> ext_release : 
+```

docs/uml/create_file.md

@@ -0,0 +1,42 @@
+```mermaid
+sequenceDiagram
+    box fuse3[external]
+        participant ext_create as create
+    end
+
+    box linux.rs
+        participant lnx_create as EncryptedFsFuse3::create
+        participant nod_create as EncryptedFsFuse3::create_nod
+        participant chk_access as check_access 
+    end
+
+    box encryptedfs.rs
+        participant enc_create as EncryptedFs::create
+        participant get_attr as EncryptedFs::get_attr
+    end
+
+    box std::fs[external]
+        participant file_open as File::open
+        participant create_dir as fs::create_directory
+    end
+
+
+    ext_create -->> lnx_create : [parent_inode,name,mode,flags]
+    lnx_create -->> nod_create : [parent_inode,name,mode,read_flag,write_flag]
+    nod_create -->> get_attr : [parent_inode]
+    get_attr -->> nod_create : [parent_attributes]
+    nod_create -->> chk_access : [parent_attributes]
+    chk_access -->> nod_create : 
+    nod_create -->> enc_create : [parent_inode,attributes,read_flag,write_flag]
+        alt is file 
+            enc_create -->> file_open : 
+            file_open -->> enc_create : [file_handle,attributes]
+        else is directory
+            enc_create -->> create_dir : 
+            create_dir -->> enc_create : [file_handle=0 ,attributes]
+        end
+    enc_create -->> nod_create : [file_handle,attributes]
+    nod_create -->> lnx_create : [file_handle,attributes]
+    lnx_create -->> ext_create : [file_handle,attributes]
+
+```

docs/uml/lib_encryptedfs_usage.md

@@ -0,0 +1,35 @@
+```mermaid
+sequenceDiagram
+    participant application
+    participant enc_new as EncryptedFs::new
+
+    application -->> enc_new : data_dir,password_provider,cipher,read_only
+    create participant EncryptedFs
+    enc_new -->> EncryptedFs : 
+    enc_new -->> application : EncryptedFs
+    Note left of application : create file under root_inode <br> and open for read and/or write
+    application -->> EncryptedFs : create(root_inode,file_name,file_attributes,read_flag,write_flag)
+    Note left of application : extract file_inode from file_attributes
+    EncryptedFs -->> application : (file_handle, file_attributes)
+    Note left of application : write data buffer into file at offset
+    application -->> EncryptedFs : write(file_inode,offset,data_buffer,file_handle)
+    EncryptedFs -->> application : bytes_written
+    Note left of application : flush file contents on storage
+    application -->> EncryptedFs : flush(file_handle) 
+    EncryptedFs -->> application : 
+    Note left of application : close the file
+    application -->> EncryptedFs : release(file_handle)
+    EncryptedFs -->> application : 
+    Note left of application : open the file with file_inode <br> for read and/or write
+    application -->> EncryptedFs : open(file_inode,read,write)
+    EncryptedFs -->> application : file_handle
+    Note left of application : read from file with file_inode <br> at offset into data buffer
+    application -->> EncryptedFs : read(file_inode,offset,data_buffer,file_handle)
+    EncryptedFs -->> application : read_bytes
+    Note left of application : close the file
+    application -->> EncryptedFs : release(file_handle)
+    EncryptedFs -->> application : 
+    application --x application : exit
+```
+
+Further details about the internals of create, open, close, read and write flows can be found in [flows](../flows.md).

docs/uml/lib_rencfs_usage.md

@@ -0,0 +1,37 @@
+```mermaid
+sequenceDiagram
+    participant stdio as std::io
+    participant vfs as kernel::vfs
+    participant fuse as kernel::fuse
+    participant fuse3 as fuse3
+    application -->> rencfs : create_mount_point(mount_path,data_path,...)
+    create participant MountPoint 
+    rencfs -->> MountPoint : 
+    MountPoint -->> application : MountPoint
+    application -->> MountPoint : mount()
+    create participant MountHandle 
+    MountPoint -->> MountHandle : 
+    MountHandle -->> application : MountHandle
+    application -->> stdio : File::create(mount_path/file)
+    stdio -->> vfs : create 
+    vfs -->> fuse : create 
+    fuse -->> fuse3 : create 
+    fuse3 -->> rencfs : create
+    rencfs -->> rencfs : create
+    rencfs -->> fuse3 : (file_handle, attributes)
+    fuse3 -->> fuse : (file_handle, attributes)
+    fuse -->> vfs : (file_handle, attributes)
+    vfs -->> stdio : (file_handle, attributes)
+    stdio -->> application : file_handle
+    Note over stdio,application :  file operations (e.g. read/write/close)
+    application -->> MountHandle : unmount()
+    MountHandle -->> application : 
+    destroy MountHandle 
+    rencfs --x MountHandle : 
+    destroy MountPoint
+    rencfs --x MountPoint : 
+    application --x application : exit
+
+```
+
+Further details about the create sequence can be found in [Create](create_file.md).

docs/uml/mount.md

@@ -0,0 +1,53 @@
+```mermaid
+sequenceDiagram
+    box run.rs
+        participant rn_mnt as run_mount
+    end
+    
+    box mount.rs
+        participant cr_mp as create_mount_point
+    end
+    
+    box linux.rs
+        participant mnt_point_impl_new as MountPointImpl::new
+        participant mnt_point_impl_mount as MountPointImpl::mount
+        participant mnt_fuse as mount_fuse
+        participant enc_fs_fuse3 as EncryptedFsFuse3::new
+    end
+    
+    box encryptedfs.rs
+        participant enc_fs as EncryptedFs::new
+        participant ensure_fs_created as ensure_structure_created
+        participant ensure_root as EncryptedFs::ensure_root_exists
+    end
+
+    box fuse3/session.rs[external]
+        participant session_new as Session::new
+        participant mnt_with_unpriv as Session::mount_with_unpriviliged
+    end
+    
+    rn_mnt -->> cr_mp : [mount_point,data_dir,password_provider,cipher ...]
+    cr_mp -->> mnt_point_impl_new : [mount_point,data_dir,password_provider,cipher ...]
+    mnt_point_impl_new -->> cr_mp : [mount_point] 
+    cr_mp -->> rn_mnt :  [mount_point]
+    
+    rn_mnt -->> mnt_point_impl_mount : [mount_point,data_dir,password_provider,cipher,...]  
+    mnt_point_impl_mount -->> mnt_fuse: [mount_point,data_dir,password_provider,cipher,...]  
+    mnt_fuse -->> session_new : [mount_options]
+    session_new -->> mnt_fuse : [fuse3_session]  
+    mnt_fuse -->> enc_fs_fuse3 : [data_dir,password_provider,cipher,...]
+    enc_fs_fuse3 -->> enc_fs : [data_dir,password_provider,cipher,...] 
+    enc_fs -->> ensure_fs_created :  [data_dir]
+    
+    ensure_fs_created -->> enc_fs :  
+    enc_fs -->> ensure_root : 
+    ensure_root -->> enc_fs :  
+    
+    enc_fs -->> enc_fs_fuse3 : [EncryptedFs]
+    enc_fs_fuse3 -->> mnt_fuse : [EncryptedFsFuse3] 
+    mnt_fuse -->> mnt_with_unpriv : [EncryptedFsFuse3, mount_path]
+    mnt_with_unpriv -->> mnt_fuse:  [mount_handle]
+    mnt_fuse -->> mnt_point_impl_mount : [mount_handle] 
+    mnt_point_impl_mount -->> rn_mnt : [mount_handle]  
+
+```

docs/uml/open_file.md

@@ -0,0 +1,50 @@
+```mermaid
+sequenceDiagram
+
+    box fuse3[external]
+        participant ext_open_file as open_file 
+    end 
+
+    box linux.rs 
+        participant open_file as EncryptedFsFuse3::open 
+    end 
+
+    box encryptedfs.rs
+        participant get_attr as EncryptedFs::get_attr 
+        participant set_len as EncryptedFs::set_len 
+        participant open as EncryptedFs::open 
+        participant do_with_read as EncryptedFs::do_with_read_handle 
+        participant do_with_write as EncryptedFs::do_with_write_handle 
+        participant chk_acc as check_access 
+    end 
+
+    ext_open_file -->> open_file : 
+    open_file -->> get_attr : [file_inode]
+    get_attr -->> open_file : [file_attr]
+    open_file -->> chk_acc : [file_attr]
+
+    alt file access allowed
+        chk_acc -->> open_file : true
+        opt truncate mode true
+            open_file -->> set_len : 
+            set_len -->> open_file : 
+        end
+        open_file -->> open : [file_inode,rw mode]
+        alt read mode true
+            open -->> do_with_read : 
+            do_with_read -->> open : 
+            opt write mode true
+                open -->> do_with_write : 
+                do_with_write -->> open : 
+            end
+            open -->> open_file : [file_handle]
+            open_file -->> ext_open_file : [file_handle]
+        else neither read nor write mode
+            open -->> open_file : 
+            open_file -->> ext_open_file : [Err:EIO]
+        end
+    else file access not allowed
+        chk_acc -->> open_file : [false]
+        open_file -->> ext_open_file : [Err:EACCES]
+    end
+```