doc(libfuse): enhance overlay documentation with architecture, data structure, and flow diagrams

Author: Ricky-Daxia

project/libfuse-fs/overlay.md

@@ -1,32 +1,225 @@
+## High level architecture
+
+```mermaid
+graph TD
+    subgraph User Space
+        A[Application] -- Mounts FS --> B(libfuse-fs)
+        subgraph libfuse-fs
+            C(Server) -- Dispatches Requests --> D{Filesystem Trait}
+            D -- Implemented by --> E[PassthroughFS]
+            D -- Implemented by --> F[OverlayFS]
+            F -- Accesses --> E
+        end
+        E -- Accesses --> G[Underlying Filesystem]
+        B -- Uses --> H[rfuse3]
+    end
+
+    subgraph Kernel Space
+        I[VFS] -- File Operations --> J[FUSE Kernel Driver]
+    end
+
+    H -- Communicates via /dev/fuse --> J
+
+    style B fill:#f9f,stroke:#333,stroke-width:2px
+    style C fill:#ccf,stroke:#333,stroke-width:2px
+    style D fill:#ccf,stroke:#333,stroke-width:2px
+    style E fill:#cfc,stroke:#333,stroke-width:2px
+    style F fill:#cfc,stroke:#333,stroke-width:2px
+```
+
+## Key data structures
+
+```mermaid
+classDiagram
+    direction TB
+
+    class OverlayFs {
+        <<Struct>>
+        - config: Config
+        - upper_layer: PassthroughFs
+        - lower_layers: Vec&lt;PassthroughFs&gt;
+        - inode_store: InodeStore
+        - handles: Map&lt;u64, HandleData&gt;
+        + new(config, upper, lowers)
+        + lookup()
+        + read()
+        + write()
+    }
+
+    class InodeStore {
+        <<Struct>>
+        - inodes: Map&lt;u64, OverlayInode&gt;
+        - next_ino: u64
+        + get_inode(inode) OverlayInode
+        + add_inode(inode) u64
+    }
+
+    class OverlayInode {
+        <<Struct>>
+        + inode: u64
+        + real_inodes: Vec&lt;RealInode&gt;
+        + children: Map&lt;String, OverlayInode&gt;
+        + parent: OverlayInode
+    }
+
+    class RealInode {
+        <<Struct>>
+        + layer: PassthroughFs
+        + in_upper_layer: bool
+        + whiteout: bool
+        + opaque: bool
+        # Represents one inode object in specific layer
+    }
+
+    class HandleData {
+        <<Struct>>
+        + node: OverlayInode
+        + real_handle: Option&lt;RealHandle&gt;
+        # Data for an opened file
+    }
+
+    class RealHandle {
+        <<Struct>>
+        + layer: PassthroughFs
+        + in_upper_layer: bool
+        + inode: u64
+        + handle: AtomicU64
+        # A wrapper of one inode in specific layer
+	}
+	
+    class Config {
+        <<Struct>>
+        + mountpoint: PathBuf
+        + do_import: bool
+        + writeback: bool
+        + no_open: bool
+        + cache_policy: CachePolicy
+        # Configuration for OverlayFs
+    }
+    
+   namespace passthrough {
+        class PassthroughFs {
+            <<Struct>>
+            + inode_map: passthrough.InodeStore
+            + handle_map: HandleMap
+            + cfg: passthrough::Config
+            + writeback: bool
+            + no_open: bool
+            # A file system that simply "passes through" all requests it receives to the underlying file system
+        }
+    
+        class passthrough.InodeStore {
+            <<Struct>>
+            - data: Map&lt;u64, InodeData&gt;
+            - by_id: Map&lt;u64, u64&gt;
+            - by_handle: Map&lt;FileHandle, u64&gt;
+            # Data structures to manage accessed inodes
+        }
+
+        class InodeData {
+            <<Struct>>
+            + inode: u64
+            + handle: InodeHandle
+            + id: InodeId
+            + refcount: AtomicU64
+            # Represents an inode in PassthroughFs
+        }
+
+        class HandleMap {
+            <<Struct>>
+            - map: Map&lt;u64, HandleData&gt;
+        }
+        
+        class passthrough.HandleData {
+        	<<struct>>
+        	- inode: u64
+        	- file: std::fs::File
+        	- open_flags: u32
+        }
+
+        class FileHandle {
+            <<Struct>>
+            + mnt_id: u64
+            + handle: CFileHandle
+            # Struct to maintain information for a file handle
+        }
+    }
+
+    Relationships
+    OverlayFs "1" *-- "1" Config : contains
+    OverlayFs "1" *-- "1" PassthroughFs : has upper layer
+    OverlayFs "1" *-- "n" PassthroughFs : has lower layers
+    OverlayFs "1" *-- "1" InodeStore : manages
+    OverlayFs "1" *-- "n" HandleData : manages handles
+
+    InodeStore "1" *-- "*" OverlayInode : stores
+
+    OverlayInode "1" *-- "n" RealInode : aggregates
+
+    HandleData "1" *-- "1" RealHandle : contains
+    HandleData ..> OverlayInode : references
+
+    RealInode ..> PassthroughFs : associated with
+    RealHandle ..> PassthroughFs : associated with
+    
+    PassthroughFs "1" *-- "1" passthrough.InodeStore : manages
+    PassthroughFs "1" *-- "1" HandleMap : manages
+
+    passthrough.InodeStore "1" *-- "*" InodeData : stores
+    HandleMap "1" *-- "*" passthrough.HandleData : stores
+
+    InodeData ..> FileHandle : (via InodeHandle) references
+```
+
+## File read flow
+
 ```mermaid
-graph LR
-    classDef process fill:#E5F6FF,stroke:#73A6FF,stroke-width:2px
-
-    OverlayFs([OverlayFs]):::process
-    OverlayInode([OverlayInode]):::process
-    RealInode([RealInode]):::process
-    RealHandle([RealHandle]):::process
-    HandleData([HandleData]):::process
-    InodeStore([InodeStore]):::process
-    Config([Config]):::process
-    PassthroughFs([PassthroughFs]):::process
-
-    OverlayFs -->|including| Config
-    OverlayFs -->|includes multiple| lower_layers(PassthroughFs)
-    OverlayFs -->|includes one| upper_layer(PassthroughFs)
-    OverlayFs -->|manages| InodeStore
-    OverlayFs -->|manages| handles(HandleData)
-
-    OverlayInode -->|includes multiple| RealInode
-    OverlayInode -->|parent| OverlayInode
-    OverlayInode -->|child| OverlayInode
-
-    RealInode -->|associated with| PassthroughFs
-    RealHandle -->|associated with| PassthroughFs
-    HandleData -->|includes| OverlayInode
-    HandleData -->|includes| RealHandle
-
-    OverlayFs -->|operations involve| OverlayInode
-    InodeStore -->|stores| OverlayInode
+sequenceDiagram
+    actor User
+    participant Kernel
+    participant rfuse3 as rfuse3::Session
+    participant Server as OverlayFs
+    participant PassthroughFS
+    participant UnderlyingFS as Underlying Filesystem
+
+    %% -- Initialization (Conceptual) --
+    %% Server->>rfuse3: Create Session(mountpoint, PassthroughFS)
+    %% Server->>rfuse3: session.run()
+
+    %% -- Read Operation Flow --
+    User->>Kernel: cat a_file.txt (read operation)
+    Kernel->>rfuse3: FUSE_READ Request (raw bytes via /dev/fuse)
+    activate rfuse3
+
+    rfuse3->>rfuse3: loop: read_request() & dispatch(bytes)
+    note right of rfuse3: 1. Reads raw bytes from kernel.<br>2. `dispatch` decodes header,<br>identifies FUSE_READ op.
+
+    %% This call is conceptual. In reality, rfuse3 calls the trait method directly.
+    %% The 'Server' role here represents the application logic layer that rfuse3 serves.
+    rfuse3->>Server: Calls Filesystem trait method
+    activate Server
+    note left of Server: rfuse3 invokes the registered<br>Filesystem implementation.
+
+    Server->>PassthroughFS: read(req, ino, fh, offset, size, reply)
+    activate PassthroughFS
+    note over PassthroughFS: Your business logic is executed.
+
+    PassthroughFS->>PassthroughFS: Get FileHandle from fh
+    PassthroughFS->>UnderlyingFS: pread(file_descriptor, buffer, offset)
+    activate UnderlyingFS
+
+    UnderlyingFS-->>PassthroughFS: Returns data
+    deactivate UnderlyingFS
+
+    PassthroughFS-->>Server: reply.data(data)
+    deactivate PassthroughFS
+    note over Server, PassthroughFS: The reply object is used to<br>pass the result back up the chain.
+
+    Server-->>rfuse3: (via reply object) Response is ready
+    deactivate Server
+
+    rfuse3->>Kernel: FUSE_READ Response (formatted bytes)
+    deactivate rfuse3
 
+    Kernel-->>User: Displays content of a_file.txt
 ```