Enable CLI modules to act as both client and server

Author: cdcseacave

.gitattributes

@@ -0,0 +1,15 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Rust source files should always use LF
+*.rs text eol=lf
+*.toml text eol=lf
+*.md text eol=lf
+
+# Scripts should use LF
+*.sh text eol=lf
+*.py text eol=lf
+
+# Windows scripts should use CRLF
+*.bat text eol=crlf
+*.ps1 text eol=crlf

.github/copilot-instructions.md

@@ -300,7 +300,7 @@ P2PFileTransfer/
 #### Python Integration Tests
 - Script: `test_transfer.py`
 - Tests real file transfers end-to-end
-- Verifies statistics, compression, data integrity
+- Verifies statistics, compression, windowed mode, data integrity
 - Remove `test_file` before running, when changing test size or compressibility
 
 ---
@@ -411,3 +411,20 @@ python3 benchmark.py
 2. **Fix the bug** and verify test passes
 3. **Run full test suite** to ensure no regressions
 4. **Update CHANGELOG.md** with the fix
+
+### Documentation Policy
+**CRITICAL**: Never create new markdown documentation files for feature summaries or implementation notes.
+
+✅ **DO**:
+- Update `README.md` with usage examples and user-facing documentation
+- Update `DESIGN.md` with architecture and implementation details
+- Update `TODO.md` to remove completed features or add notes for partial implementations
+- Update `CHANGELOG.md` with dated entries for all changes
+- Add inline code comments and module documentation
+
+❌ **DON'T**:
+- Create files like `FEATURE_NAME.md`, `IMPLEMENTATION_SUMMARY.md`, `QUICK_REFERENCE.md`, etc.
+- Create separate documentation files for individual features
+- Create temporary documentation files that duplicate existing docs
+
+**Rationale**: Keep documentation centralized in the four main files (README, DESIGN, TODO, CHANGELOG) to avoid fragmentation and maintenance burden.

.rustfmt.toml

@@ -2,10 +2,8 @@ edition = "2021"
 max_width = 100
 hard_tabs = false
 tab_spaces = 4
-newline_style = "Unix"
+newline_style = "Auto"
 use_small_heuristics = "Default"
 reorder_imports = true
 reorder_modules = true
 remove_nested_parens = true
-format_strings = true
-format_macro_bodies = true

CHANGELOG.md

@@ -7,8 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Bidirectional session support** (2025-10-06): CLI can now act as both client and server
+  - Added `SessionParams` struct with `--role`, `--peer`, `--port`, and `--discover` parameters
+  - Added `TransferParams` struct for common transfer configuration
+  - Send command can operate as client (default) or server (`--role server`)
+  - Receive command can operate as server (default) or client (`--role client`)
+  - Both peers can send or receive after session establishment
+  - Session documentation updated to clarify bidirectional capabilities
+  - Added `P2PSession::establish()` convenience method for role-based connection (eliminates code duplication)
+
 ### Changed
 - **CLI parameter rename** (2025-10-06): `--log-level` renamed to `--verbosity` for better clarity
+- **CLI parameter rename** (2025-10-06): `--to` renamed to `--peer` for consistency with session role model
 - **Protocol optimization** (2025-10-06): Removed redundant `uncompressed_size` field from `ChunkMessage`, saving 4 bytes per chunk
 - **InFlightChunk refactoring** (2025-10-06): Now stores complete `ChunkMessage` for efficient retransmission without data duplication
 

Cargo.toml

@@ -2,7 +2,7 @@
 name = "p2p-transfer"
 version = "0.1.0"
 edition = "2021"
-authors = ["Your Name <your.email@example.com>"]
+authors = ["cDc <cdc.seacave@gmail.com>"]
 description = "A lightweight P2P file transfer tool with compression"
 license = "MIT"
 repository = "https://github.com/yourusername/p2p-transfer"

DESIGN.md

@@ -454,28 +454,55 @@ session.run_event_loop(&output_dir, auto_accept).await?;
 - ✅ Supports session multiplexing (future)
 - ✅ Foundation for file browsing protocol (future)
 
-#### CLI Integration
+#### CLI Integration with Role Selection
 
-**External interface unchanged:**
+**CLI interface (flexible role selection)**:
 ```bash
-# Send (establishes session, sends, closes)
-p2p-transfer send file.zip --to host:port
+# Send as client (default) - connect to peer and send
+p2p-transfer send file.zip --peer host:port
+
+# Send as server - listen for peer to connect, then send
+p2p-transfer send file.zip --role server --port 7778
 
-# Receive (establishes session, auto-receives until closed)
+# Receive as server (default) - listen for peer and receive
 p2p-transfer receive --output ./downloads --port 7778
+
+# Receive as client - connect to peer and receive
+p2p-transfer receive --output ./downloads --role client --peer host:port
 ```
 
-**Internal flow (new)**:
+**Internal flow**:
 ```rust
-// Send command
-let mut session = P2PSession::connect(...).await?;
-session.send_path(&path, progress_callback).await?;
+// Unified session establishment using P2PSession::establish()
+let mut session = P2PSession::establish(
+    &role,              // "client" or "server"
+    peer_addr,          // Some(addr) for client, None for server
+    bind_addr,          // Bind address (used by server)
+    device_id,
+    capabilities,
+    Some(config),       // Config for client, can be None for server
+).await?;
 
-// Receive command
-let mut session = P2PSession::accept(...).await?;
-session.run_event_loop(&output, auto_accept).await?;  // Auto-receive loop
+// Then perform operation (send or receive)
+session.send_path(&path, progress_callback).await?;
+// or
+session.run_event_loop(&output, auto_accept).await?;
 ```
 
+**Common CLI Parameters**:
+- `SessionParams`: `--role`, `--peer`, `--port`, `--discover`
+- `TransferParams`: `--compress`, `--compress-level`, `--adaptive`, `--chunk-size`, `--window-size`, `--max-speed`, `--auto-reconnect`, `--max-retries`
+
+**Role Defaults**:
+- `send` command: defaults to `client` (connects to peer)
+- `receive` command: defaults to `server` (listens for peer)
+- Can be overridden with `--role` parameter
+
+**Code Reuse**:
+- `P2PSession::establish()` eliminates duplicate connection logic
+- Both `send.rs` and `receive.rs` use the same session establishment code
+- Cleaner, more maintainable CLI implementation
+
 #### Future Enhancements
 
 With session foundation in place:

README.md

@@ -89,43 +89,54 @@ cargo build --release
 
 ### Basic Usage
 
+#### Bidirectional Sessions
+After a session is established, **both peers are equal** and can send or receive files. The `--role` parameter only determines who initiates the connection:
+- **Client role** (default for send): Connects to a peer
+- **Server role** (default for receive): Listens for incoming connections
+
 #### Send a File
 ```bash
-# Direct connection (windowed mode is default)
-p2p-transfer send myfile.zip --to 192.168.1.100:8080
+# Send as client (default) - connect to peer and send
+p2p-transfer send myfile.zip --peer 192.168.1.100:8080
+
+# Send as server - listen for peer to connect, then send
+p2p-transfer send myfile.zip --role server --port 8080
 
-# With auto-discovery
+# With auto-discovery (client mode)
 p2p-transfer send myfile.zip --discover
 
 # Sequential mode (one chunk at a time)
-p2p-transfer send myfile.zip --to 192.168.1.100:8080 --window-size 1
+p2p-transfer send myfile.zip --peer 192.168.1.100:8080 --window-size 1
 ```
 
 #### Send a Folder
 ```bash
 # Transfer entire directory with structure
-p2p-transfer send ./my_project --to 192.168.1.100:8080
+p2p-transfer send ./my_project --peer 192.168.1.100:8080
 
 # With compression (adaptive by default)
-p2p-transfer send ./documents --to 192.168.1.100:8080 --compress --compress-level 5
+p2p-transfer send ./documents --peer 192.168.1.100:8080 --compress --compress-level 5
 
 # Adaptive compression auto-disables for incompressible data (default: enabled)
-p2p-transfer send ./mixed_content --to 192.168.1.100:8080 --adaptive true
+p2p-transfer send ./mixed_content --peer 192.168.1.100:8080 --adaptive true
 
 # Force compression even for incompressible data
-p2p-transfer send ./photos --to 192.168.1.100:8080 --adaptive false
+p2p-transfer send ./photos --peer 192.168.1.100:8080 --adaptive false
 ```
 
 #### Receive Files/Folders
 ```bash
-# Start receiver on port 8080 (automatically receives when peer sends)
-p2p-transfer receive ./downloads --port 8080
+# Receive as server (default) - listen for peer to connect and receive
+p2p-transfer receive --output ./downloads --port 8080
+
+# Receive as client - connect to peer and receive files
+p2p-transfer receive --output ./downloads --role client --peer 192.168.1.100:8080
 
 # Auto-accept incoming transfers (no prompts)
-p2p-transfer receive ./received --port 7778 --auto-accept
+p2p-transfer receive --output ./received --port 7778 --auto-accept
 
 # Short form
-p2p-transfer receive ./received -p 7778 -a
+p2p-transfer receive -o ./received -p 7778 -a
 ```
 
 **Note**: The receiver now runs in an event loop that automatically handles incoming transfers. When a peer initiates a send, the receiver will automatically start receiving - no manual action needed. The session stays alive for multiple transfers until the connection is closed.
@@ -185,18 +196,18 @@ Currently, when both machines are behind NAT, you need to manually use the disco
 2. **On Machine B (sender)** - Connect using Machine A's public IP:
    ```bash
    # Send to Machine A's public IP and forwarded port
-   p2p-transfer send myfile.zip --to 203.0.113.5:7778
+   p2p-transfer send myfile.zip --peer 203.0.113.5:7778
    ```
 
 #### Resume Interrupted Transfer
 ```bash
 # Transfer gets interrupted (Ctrl+C)
-p2p-transfer send ./large_folder --to 192.168.1.100:8080
+p2p-transfer send ./large_folder --peer 192.168.1.100:8080
 # State saved to: transfer_12345678-1234-5678-1234-567812345678.json
 
 # Resume later (supports chunk-level resume)
 p2p-transfer resume 12345678-1234-5678-1234-567812345678 \
-    --to 192.168.1.100:8080 \
+    --peer 192.168.1.100:8080 \
     --path ./large_folder
 ```
 
@@ -222,16 +233,16 @@ p2p-transfer history --failed
 
 ```bash
 # LAN (low latency, < 5ms)
-p2p-transfer send file.zip --to 192.168.1.100:8080 --window-size 8
+p2p-transfer send file.zip --peer 192.168.1.100:8080 --window-size 8
 
 # WiFi (medium latency, 10-20ms) - DEFAULT
-p2p-transfer send file.zip --to 192.168.1.100:8080 --window-size 16
+p2p-transfer send file.zip --peer 192.168.1.100:8080 --window-size 16
 
 # Internet (high latency, 50-100ms)
-p2p-transfer send file.zip --to 192.168.1.100:8080 --window-size 32
+p2p-transfer send file.zip --peer 192.168.1.100:8080 --window-size 32
 
 # Satellite/VPN (very high latency, 500ms+)
-p2p-transfer send file.zip --to 192.168.1.100:8080 --window-size 64
+p2p-transfer send file.zip --peer 192.168.1.100:8080 --window-size 64
 ```
 
 **Memory Usage**: Window size × 1MB chunk size
@@ -243,16 +254,16 @@ p2p-transfer send file.zip --to 192.168.1.100:8080 --window-size 64
 
 ```bash
 # Limit to 10 MB/s (useful for shared networks)
-p2p-transfer send largefile.zip --to 192.168.1.100:8080 --max-speed 10M
+p2p-transfer send largefile.zip --peer 192.168.1.100:8080 --max-speed 10M
 
 # Limit to 1 GB/s (for very fast networks)
-p2p-transfer send largefile.zip --to 192.168.1.100:8080 --max-speed 1G
+p2p-transfer send largefile.zip --peer 192.168.1.100:8080 --max-speed 1G
 
 # Limit to 512 KB/s (for slow connections)
-p2p-transfer send largefile.zip --to 192.168.1.100:8080 --max-speed 512K
+p2p-transfer send largefile.zip --peer 192.168.1.100:8080 --max-speed 512K
 
 # Unlimited bandwidth (default)
-p2p-transfer send largefile.zip --to 192.168.1.100:8080
+p2p-transfer send largefile.zip --peer 192.168.1.100:8080
 ```
 
 **How it works**:
@@ -267,16 +278,16 @@ Transfers automatically recover from network failures with exponential backoff:
 
 ```bash
 # Auto-reconnect is enabled by default
-p2p-transfer send large_folder/ --to 192.168.1.100:8080
+p2p-transfer send large_folder/ --peer 192.168.1.100:8080
 
 # Disable auto-reconnect (manual resume only)
-p2p-transfer send large_folder/ --to 192.168.1.100:8080 --auto-reconnect false
+p2p-transfer send large_folder/ --peer 192.168.1.100:8080 --auto-reconnect false
 
 # Unlimited retries (keeps trying until success or permanent error)
-p2p-transfer send large_folder/ --to 192.168.1.100:8080 --max-retries 0
+p2p-transfer send large_folder/ --peer 192.168.1.100:8080 --max-retries 0
 
 # Custom retry limit
-p2p-transfer send large_folder/ --to 192.168.1.100:8080 --max-retries 10
+p2p-transfer send large_folder/ --peer 192.168.1.100:8080 --max-retries 10
 ```
 
 **How it works**:
@@ -347,7 +358,7 @@ Progress: 100/100 chunks (100.0%, complete)
 
 # Later...
 $ p2p-transfer resume abc12345-def6-7890-ghij-klmnopqrstuv \
-    --to 192.168.1.100:8080 --path my_project
+    --peer 192.168.1.100:8080 --path my_project
 
 🔄 Resuming transfer
   Progress: 8/10 files (80.0%)

benchmark.py

@@ -99,7 +99,7 @@ def run_sender_test(self, test_name: str, file_path: Path, mode: str, window_siz
         # Build command
         cmd = [
             self.binary_path, "send", str(file_path),
-            "--to", f"{self.receiver_ip}:{self.port}"
+            "--peer", f"{self.receiver_ip}:{self.port}"
         ]
 
         # Set window size: 1 for sequential, or specified value for windowed