docs: complete architecture documentation (dev-sys-do#9)

jorisvilardell · web-flow · commit 38b4218a1d03 · 2025-10-30T20:38:56.000+01:00
* fix(network): improve error handling in ProtocolMessage parsing and TcpListener binding
refactor(storage): simplify filename sanitization and directory creation logic

* docs(README): update CLI example to recommend a minimal block size of 2048 bytes

* docs(architecture): add flow diagrams for FerrisShare protocol (v1 and v2)

* docs(README): clarify purpose of README and link to architecture documentation
diff --git a/README.md b/README.md
@@ -2,8 +2,7 @@
 
 Ferrisshare is a small Rust peer-to-peer file transfer toy used for a systems programming project.
 It implements a tiny text-based protocol over TCP to send a single file from a sender (CLI) to a receiver (listener).
-
-This README is intentionally short — it explains what the project is and how to run the listener and the CLI sender locally for development.
+For a detailed protocol and architecture overview, see [docs/architecture.md](docs/architecture.md).
 
 ## What it is
 
@@ -35,9 +34,13 @@ Send a file with the CLI (sender). Example: send the repository `README.md` to l
 
 ```bash
 # In another terminal
-cargo run --bin cli -- send --addr 127.0.0.1:9000 --file README.md --block-size 1024
+cargo run --bin cli -- send --addr 127.0.0.1:9000 --file README.md --block-size 2048
 ```
 
+**Recommended minimal block size**
+
+We recommend using a minimal block size of 2048 bytes (as shown in the example above). Larger blocks reduce protocol overhead and typically improve throughput for local transfers. Be aware larger blocks use more memory and may be less forgiving on very unreliable networks — adjust down if you see timeouts or memory pressure.
+
 Logs printed to both terminals show the protocol exchange (HELLO, OK, YEET blocks, OK-HOUSTEN responses, MISSION-ACCOMPLISHED, SUCCESS, BYE-RIS).
 
 ## Notes and troubleshooting
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -16,38 +16,50 @@ The primary goals of this project are:
 4. **Reliability**: Implement a simple protocol with handshake verification to ensure successful transfers
 5. **Simplicity**: Provide a straightforward CLI interface similar to common networking tools
 
-### Non-Goals
-
-- **Discovery Protocol**: The sender must know the receiver's IP address (no automatic peer discovery)
-- **Encryption**: File transfers are not encrypted (local network trust assumed)
 - **Resume Support**: Interrupted transfers cannot be resumed
 - **Multi-file Transfers**: Each transfer handles exactly one file
 
-## **Choice of Dependencies**
+### 1.1 **Choice of Dependencies**
 
-### Tokyo
+This project uses a small set of well-established crates chosen to support an async, networked CLI tool implemented in Rust. Below are the main dependencies and why they were selected.
 
-The project uses **Tokio**, an asynchronous runtime for Rust, to manage networking operations and concurrency. Tokio provides powerful primitives such as `TcpStream`, `TcpListener`, and asynchronous task spawning (`tokio::spawn`), allowing efficient, non-blocking I/O.
+#### Tokio
 
-This choice is motivated by several reasons:
+Tokio is the async runtime and is central to the project. Reasons for using Tokio include:
 
-1. **Asynchronous I/O efficiency** – Tokio leverages Rust’s `async/await` syntax to handle thousands of simultaneous client connections without blocking threads.
+1. **Asynchronous I/O efficiency** – Tokio leverages Rust’s `async/await` syntax to handle many simultaneous client connections without blocking threads.
 2. **Task scheduling and runtime** – Tokio includes a lightweight task scheduler that runs asynchronous functions concurrently on a single or multi-threaded runtime.
-3. **Ecosystem integration** – Many crates (like `warp`, `hyper`, `reqwest`, `tokio-tungstenite`) are built on top of Tokio, ensuring good compatibility and extensibility.
-4. **Fine-grained control** – Tokio allows precise management of I/O events, making it suitable for custom protocol implementations, chunked file transfer, and streaming optimizations.
-5. **Performance and safety** – The runtime is highly optimized for low-latency operations, while maintaining Rust’s guarantees of memory safety and thread safety.
+3. **Ecosystem integration** – Many crates (like `warp`, `hyper`, `reqwest`, `tokio-tungstenite`) are built on top of Tokio, ensuring compatibility and extensibility.
+4. **Performance and safety** – The runtime is optimized for low-latency operations while preserving Rust’s memory- and thread-safety guarantees.
+
+Practical notes for this repo:
+
+- Tokio primitives used: `TcpListener`, `TcpStream`, `tokio::spawn`, `tokio::fs`, and `tokio::sync::mpsc`.
+- The code creates an `mpsc::channel::<TcpStream>(1)` in `src/main.rs` and sends accepted `TcpStream`s from the listener to the handler task. This decouples socket acceptance from protocol handling, provides backpressure (buffer size 1), and keeps a clear service boundary between network IO and command processing.
+- When changing concurrency or channel buffer sizes, review the places that consume the channel (network handler) and tests that rely on the current backpressure semantics.
+
+#### clap
+
+`clap` (with the `derive` feature) is used for command-line parsing. It provides ergonomic derive-based parsing for flags and subcommands used by the binaries (see `src/cli/main.rs`). Use `clap` to add user-facing options, help text, and subcommands. Keep CLI changes backward-compatible where possible.
+
+#### dotenv
 
-Without Tokio, the implementation would require manually managing threads and blocking I/O, which would be less efficient, harder to scale, and more error-prone.
+`dotenv` is used in `src/main.rs` to load local environment variables from a `.env` file during development. The project uses environment variables for configuration keys (see `src/application/config.rs`): `FERRIS_BASE_PATH`, `FERRIS_PORT`, and `FERRIS_HOST`. `Config::from_env()` provides sensible defaults when vars are absent.
 
-## **FerrisShare File Transfer Protocol**
+Other dependencies
 
-### **Overview**
+- `async-trait` — used to express async traits for domain ports/interfaces implemented by infra repositories.
+- `anyhow` — convenience error handling for higher-level paths or tooling code.
+
+If you add dependencies, prefer small, widely-used crates and keep Tokio feature flags minimal to avoid pulling unnecessary code.
+
+### 1.2 **Overview**
 
 The protocol defines a simple, **text-based command layer** over TCP for transferring a single file between two peers on the same network. It relies on TCP for reliable, ordered delivery, while adding **application-level commands** to coordinate the transfer, manage file chunks, and confirm completion. The connection is **bi-directional**, allowing the receiver to respond directly through the same TCP stream.
 
-FerrisShare uses an asynchronous channel (`mpsc::channel`) to transmit accepted TCP connections from the network listener to the handler responsible for processing protocol commands. This mechanism decouples the management of incoming connections from the business logic, ensures synchronization between asynchronous tasks, and guarantees that only one active connection is handled at a time. The channel thus facilitates internal communication and enhances the modularity of the network service.
+![FerrisShare protocol flow](./ferrisshare_logigramme_v1.png)
 
-### **Protocol Commands**
+#### **Protocol Commands**
 
 | Command                  | Sender | Arguments                                              | Response                   | Description                                                                                      |
 | ------------------------ | ------ | ------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
@@ -59,9 +71,130 @@ FerrisShare uses an asynchronous channel (`mpsc::channel`) to transmit accepted
 | **MISSION-ACCOMPLISHED** | Client | —                                                      | `SUCCESS` / `ERROR`        | Marks the end of file transmission. The server verifies that all blocks were received correctly. |
 | **BYE-RIS**              | Either | —                                                      | —                          | Gracefully terminates or cancels the transfer.                                                   |
 
-### **Notes**
+## 2. **High-Level Architecture**
+
+### 2.1 Overview
+
+FerrisShare is organized following a **hexagonal (ports and adapters)** architecture.
+The system is divided into three primary layers:
+
+1. **Core Domain (`src/core/domain`)**
+   Defines the business logic, entities, and service traits (ports).
+   It is _infrastructure-agnostic_ and models how files are transferred, validated, and finalized.
+
+2. **Application Layer (`src/application`)**
+   Orchestrates interactions between domain services and infrastructure.
+   It is responsible for:
+
+   - managing runtime state (via `FerrisShareState`),
+   - loading configuration from the environment (via `main.rs`),
+   - wiring dependencies and initializing services (via `main.rs`).
+
+3. **Infrastructure Layer (`src/infra`)**
+   Provides concrete implementations of domain ports, such as:
+
+   - file-system repositories (`fs_storage_repository.rs`),
+
+This separation ensures that **business logic remains pure** and testable while the infrastructure can evolve independently (e.g., changing from filesystem to S3 storage would only require a new repository implementing the same trait).
+
+---
+
+## 3. **Runtime Model**
+
+FerrisShare uses a bounded Tokio mpsc channel (mpsc::channel::<TcpStream>(1)) to forward accepted TcpStream connections from the listener task to the network handler. This decouples socket acceptance from protocol processing, provides backpressure (buffer size = 1) so the listener will await when the handler is busy, and enforces sequential handling of active connections. Do not change the channel semantics or buffer size without review — consumers and tests rely on the current backpressure behavior.
+
+### 3.1 Execution Flow
+
+![FerrisShare protocol flow](./ferrisshare_logigramme_v2.png)
+
+---
+
+## 4. **Concurrency Model**
+
+FerrisShare uses Tokio’s cooperative multitasking model:
+
+| Component       | Concurrency Mechanism         | Description                                                        |
+| --------------- | ----------------------------- | ------------------------------------------------------------------ |
+| Listener        | `tokio::spawn` task           | Accepts TCP connections asynchronously.                            |
+| Handler         | `mpsc::Receiver<TcpStream>`   | Sequentially handles active connections (bounded by channel size). |
+| File IO         | `tokio::fs`                   | Asynchronous file operations for write and rename.                 |
+| CPU-bound Tasks | `tokio::task::spawn_blocking` | Used for checksum validation or heavy file operations.             |
+
+> The bounded channel (`size = 1`) acts as a **backpressure control**, ensuring the runtime does not accept more concurrent transfers than it can safely process.
+
+---
+
+## 5. **Storage Design**
+
+### 5.1 Storage Repository
+
+The **FSStorageRepository** provides a file-based implementation of the `StorageRepository` trait defined in `core/domain/storage/ports.rs`.
+
+Responsibilities:
+
+- Validate and sanitize filenames to prevent directory traversal.
+- Create a temporary file with suffix `.ferrisshare`.
+- Write incoming blocks asynchronously.
+- Rename the file to its final name once all blocks are received.
+
+Error handling is implemented using a domain-level `StorageError` enum, with variants such as:
+
+- `InvalidPath`
+- `WriteError`
+- `FinalizeError`
+- `ChecksumMismatch`
+
+---
+
+## 6. **Error Management**
+
+The architecture distinguishes between **domain errors** and **infrastructure errors**:
+
+| Layer       | Error Type                           | Description                                            |
+| ----------- | ------------------------------------ | ------------------------------------------------------ |
+| Domain      | `StorageError`, `ProtocolError`      | Typed errors expressing semantic issues.               |
+| Infra       | `std::io::Error`, `tokio::io::Error` | Low-level I/O or network errors.                       |
+| Application | `anyhow::Error`                      | Aggregation or propagation wrapper for untyped errors. |
+
+Each boundary maps its errors upward in a controlled way. For example:
+
+```rust
+fn write_block(&self, block: YeetBlock) -> Result<(), StorageError>
+```
+
+is converted to `anyhow::Error` only at the CLI or handler layer.
+
+---
+
+## 7. Testing Strategy
+
+- Quick protocol smoke-test with netcat:
+  ```bash
+  nc 127.0.0.1 9000
+  HELLO test.txt 1024
+  ```
+- Recommended manual verification steps (use when iterating implementation-by-feature):
+  1. Start with the listener and the bounded `mpsc` channel; confirm accepted `TcpStream`s are queued and backpressure occurs when full.
+  2. Implement protocol command recognition (parser unit tests).
+  3. Implement responder behavior and verify correct textual responses (`OK`, `NOPE`, `OK-HOUSTEN`).
+  4. Enforce protocol rules and sequencing in the handler (reject invalid sequences).
+  5. Execute command handling (dispatch commands to services and capture outcomes).
+  6. Implement the `FSStorageRepository` and validate filename sanitization.
+  7. Test reading binary payloads from the stream and async writing to the temp file.
+  8. Add the CLI path to read a local file and stream its bytes over the connection; verify end-to-end transfer.
+  9. Implement and test the loop over `YEET` blocks to ensure all bytes are written and blocks are acknowledged.
+- For each manual step, codify a corresponding unit or integration test to prevent regressions.
+
+## 8. **Security Considerations**
+
+- All filenames are sanitized — no absolute or relative (`..`) paths allowed.
+- Only local-network communication is assumed; for Internet usage, TLS must be added.
+- The server rejects transfers when disk space is insufficient or when the file already exists.
+- Protocol commands are ASCII-only to prevent injection or encoding ambiguities.
+
+---
+
+## 9. **Conclusion**
 
-- **TCP guarantees delivery**, but `CONFIRM` adds **application-level integrity verification**.
-- **File is transferred in blocks (blobs)** to allow streaming of large files without memory overload.
-- **Bi-directional communication** is handled over the same TCP connection; no additional socket is needed.
-- Protocol is designed to be **minimal, readable, and extensible** for future features (resume, hash verification, multi-file support).
+FerrisShare combines Rust’s async capabilities with a clean domain-driven design to deliver a lightweight, robust P2P file transfer CLI.
+Its modular architecture (domain/application/infra separation), use of Tokio primitives, and simple custom protocol make it easy to extend while ensuring predictable runtime behavior and strong safety guarantees.
diff --git a/docs/ferrisshare_logigramme_v1.png b/docs/ferrisshare_logigramme_v1.png
diff --git a/docs/ferrisshare_logigramme_v2.png b/docs/ferrisshare_logigramme_v2.png
diff --git a/src/core/domain/command/services.rs b/src/core/domain/command/services.rs
@@ -38,7 +38,7 @@ where
                 filesize,
             } => {
                 println!("Execute HELLO command.");
-                let expected_blocks = (*filesize + 1023) / 1024;
+                let expected_blocks = (*filesize + 1023).div_ceil(1024);
                 let mut state_guard = state.lock().await;
                 println!(
                     "Setting state to Receiving with expected_blocks={}",
diff --git a/src/core/domain/network/entities.rs b/src/core/domain/network/entities.rs
@@ -95,7 +95,7 @@ impl TryFrom<&str> for ProtocolMessage {
                 Ok(ProtocolMessage::Error(reason))
             }
             Some("BYE-RIS") => Ok(ProtocolMessage::ByeRis),
-            _ => return Err(ProtocolError::InvalidCommand),
+            _ => Err(ProtocolError::InvalidCommand),
         }
     }
 }
diff --git a/src/core/domain/network/services.rs b/src/core/domain/network/services.rs
@@ -58,7 +58,7 @@ where
     ) -> Result<(), NetworkError> {
         let listener = TcpListener::bind(addr)
             .await
-            .map_err(|e| NetworkError::ListenerBindFailed(e))?;
+            .map_err(NetworkError::ListenerBindFailed)?;
         println!("Listening on {}", addr);
 
         loop {
diff --git a/src/infra/repositories/fs/fs_storage_repository.rs b/src/infra/repositories/fs/fs_storage_repository.rs
@@ -47,22 +47,17 @@ impl StorageRepository for FSStorageRepository {
 
         async move {
             // sanitize
-            if let Err(e) = FSStorageRepository::sanitize_filename(&filename) {
-                return Err(e);
-            }
+            FSStorageRepository::sanitize_filename(&filename)?;
 
             let path = self.file_path_for(&filename);
             // Use a temporary extension during transfer
             let part_path = path.with_extension("ferrisshare");
 
             // create parent dirs if needed
             if let Some(parent) = path.parent() {
-                if let Err(e) = tokio::fs::create_dir_all(parent).await {
-                    return Err(StorageError::Unknown(format!(
-                        "Failed to create dir: {}",
-                        e
-                    )));
-                }
+                tokio::fs::create_dir_all(parent)
+                    .await
+                    .map_err(|e| StorageError::Unknown(format!("Failed to create dir: {}", e)))?;
             }
 
             match tokio::fs::File::create(&part_path).await {
@@ -84,26 +79,22 @@ impl StorageRepository for FSStorageRepository {
 
         async move {
             // sanitize
-            if let Err(e) = FSStorageRepository::sanitize_filename(&filename) {
-                return Err(e);
-            }
+            FSStorageRepository::sanitize_filename(&filename)?;
 
             let path = self.file_path_for(&filename);
             // write into a .ferrisshare temporary file while transferring
             let part_path = path.with_extension("ferrisshare");
 
             // ensure parent dir exists before open
             if let Some(parent) = path.parent() {
-                if let Err(e) = tokio::fs::create_dir_all(parent).await {
-                    return Err(StorageError::Unknown(format!(
-                        "Failed to create dir: {}",
-                        e
-                    )));
-                }
+                tokio::fs::create_dir_all(parent)
+                    .await
+                    .map_err(|e| StorageError::Unknown(format!("Failed to create dir: {}", e)))?;
             }
 
             match tokio::fs::OpenOptions::new()
                 .create(true)
+                .truncate(false)
                 .write(true)
                 .open(&part_path)
                 .await
@@ -133,9 +124,7 @@ impl StorageRepository for FSStorageRepository {
 
         async move {
             // sanitize
-            if let Err(e) = FSStorageRepository::sanitize_filename(&filename) {
-                return Err(e);
-            }
+            FSStorageRepository::sanitize_filename(&filename)?;
 
             let path = PathBuf::from(&base).join(&filename);
             // Rename the .ferrisshare temp file to the final filename

Original file line number	Diff line number	Diff line change
`@@ -95,7 +95,7 @@ impl TryFrom<&str> for ProtocolMessage {`
`95`	`95`	`Ok(ProtocolMessage::Error(reason))`
`96`	`96`	`}`
`97`	`97`	`Some("BYE-RIS") => Ok(ProtocolMessage::ByeRis),`
`98`		`- _ => return Err(ProtocolError::InvalidCommand),`
	`98`	`+ _ => Err(ProtocolError::InvalidCommand),`
`99`	`99`	`}`
`100`	`100`	`}`
`101`	`101`	`}`