diff --git a/Documentation/Mile_Stones/Milestone_1.md b/Documentation/Mile_Stones/Milestone_1.md index ef7f2a7..ff533a9 100644 --- a/Documentation/Mile_Stones/Milestone_1.md +++ b/Documentation/Mile_Stones/Milestone_1.md @@ -3,6 +3,7 @@ ### 1. Workspace Setup - [ ] Initialize the root Cargo workspace: `cargo init --vcs none` (delete `src/`). Create a root `Cargo.toml` with `[workspace] members = ["core_protocol", "server_node", "client_node"]`. +- [ ] **AI Context Trap (File Structure):** Strictly adhere to the directory layout and module hierarchy defined in `File_Structure.md`. Do not invent new file paths or module names; map every new crate and file exactly to the blueprint. - [ ] Create crates: `cargo new --lib core_protocol`, `cargo new --bin server_node`, `cargo new --bin client_node`. - [ ] Add strict lints (`#![forbid(unsafe_code)]`, etc.) to the root workspace or individual `lib.rs`/`main.rs` files. - [ ] **Dependencies (`core_protocol`):** Add `serde`, `bincode`, `uuid`, `chrono`, `thiserror`, `secrecy` (for zeroing sensitive keys). @@ -18,7 +19,7 @@ - [ ] **Server:** In `server_node/src/main.rs`, initialize `tokio::net::TcpListener::bind("0.0.0.0:8080")`. - [ ] **Server:** Spawn a new `tokio::spawn(async move { ... })` for each incoming `TcpStream`. - [ ] **Client:** In `client_node/src/network/control.rs`, implement `TcpStream::connect("127.0.0.1:8080")`. -- [ ] **Shared:** Implement a framing mechanism (e.g., sending a `u32` length prefix before the `bincode` serialized `TcpEvent`) to prevent TCP stream fragmentation. +- [ ] **AI Context Trap (TCP Framing):** Raw TCP streams suffer from fragmentation. Do NOT attempt to manually buffer bytes. You must use `tokio_util::codec::LengthDelimitedCodec` (with `tokio_serde` and `bincode`) to abstract the frame boundaries cleanly. ### 4. Login Logic & State - [ ] **Server State:** Create `server_node/src/state.rs`. Define a `DashMap` to store active session tokens. diff --git a/Documentation/Mile_Stones/Milestone_2.md b/Documentation/Mile_Stones/Milestone_2.md index 6e8db0e..73ad5fd 100644 --- a/Documentation/Mile_Stones/Milestone_2.md +++ b/Documentation/Mile_Stones/Milestone_2.md @@ -3,7 +3,7 @@ ### 1. UI Layout (`client_node/ui`) - [ ] **Dependencies:** Add `egui`, `eframe`. -- [ ] **Initialization:** In `main.rs`, launch `eframe::run_native`. +- [ ] **AI Context Trap (Eframe + Tokio):** Do NOT use `#[tokio::main]` on the client. `eframe` demands the main thread. Manually build a `tokio::runtime::Runtime`, spawn the background network actors, and pass MPSC channels into the `AppState` before calling `eframe::run_native()`. - [ ] **Architecture:** Create `struct AppState`. Implement `eframe::App` trait for it. - [ ] **Layout:** Build the basic classic TeamSpeak UI. Left panel (tree view of hardcoded channels), right panel (text chat log). diff --git a/Documentation/Mile_Stones/Milestone_5.md b/Documentation/Mile_Stones/Milestone_5.md index 5443ebc..279e322 100644 --- a/Documentation/Mile_Stones/Milestone_5.md +++ b/Documentation/Mile_Stones/Milestone_5.md @@ -3,6 +3,7 @@ ### 1. Database Setup (`server_node/database.rs`) - [ ] **Dependencies:** Add `sqlx` with the `sqlite` and `runtime-tokio` features. +- [ ] **AI Context Trap (SQLite Locking):** SQLite will throw `database is locked` errors under heavy async load. Ensure the `sqlx::sqlite::SqliteConnectOptions` explicitly sets `PRAGMA journal_mode=WAL` to allow concurrent UDP/TCP access. - [ ] **Schema Migrations:** Create `users` (ID, Name, Hash, Role) and `channels` (ID, Name, ParentID, RequiredRole, Bitrate). Run migrations on startup via `sqlx::migrate!()`. - [ ] **Permissions Check:** During the TCP `ChannelJoin` event, query the DB to ensure the user's Role $\ge$ the `RequiredRole` of the channel. diff --git a/Documentation/Mile_Stones/Milestone_6.md b/Documentation/Mile_Stones/Milestone_6.md index a597471..421284c 100644 --- a/Documentation/Mile_Stones/Milestone_6.md +++ b/Documentation/Mile_Stones/Milestone_6.md @@ -3,6 +3,7 @@ ### 1. Network Encryption - [ ] **TCP TLS:** Wrap the server's `TcpListener` and client's `TcpStream` using `rustls`. Generate or require self-signed certificates for the server. +- [ ] **AI Context Trap (Crypto Nonce):** `chacha20poly1305` is completely compromised if a Nonce is reused. To avoid tracking state or sending large random bytes over UDP, strictly cast the `SequenceNumber` (u64) padded with zeros into a 12-byte array to act as a guaranteed-unique Nonce. - [ ] **UDP Encryption:** Add `chacha20poly1305`. After Opus encoding, encrypt the payload byte array using a symmetric key negotiated during the TLS TCP handshake, before sending over UDP. ### 2. Dockerization diff --git a/File_Structure.md b/File_Structure.md index 9ad6956..bcae3ca 100644 --- a/File_Structure.md +++ b/File_Structure.md @@ -1,6 +1,14 @@ voice_app/ ├── Cargo.toml # Workspace manifest; links all crates +├── README.md # Project entry point and documentation index ├── .gitignore # Exclude /target, .env, and binary/database files +├── LICENSE # Project licensing (e.g., AGPLv3 or MIT) +├── Documentation/ # Comprehensive technical specifications and plans +│ ├── High_level_plan/ # Technical specs and architecture overview +│ ├── Low_level_plan/ # Implementation details and data flow +│ ├── Mile_Stones/ # Code-level step-by-step checklists +│ ├── Standards/ # Strict rules for code quality and testing +│ └── Concept/ # UI mockups and aesthetic references ├── core_protocol/ # Shared binary logic and network Enums │ ├── Cargo.toml # deps: serde, bincode, uuid, chrono │ └── src/ @@ -19,6 +27,7 @@ voice_app/ │ ├── tcp_router.rs # Logic for reliable control lanes │ ├── udp_relay.rs # High-speed voice packet forwarding │ ├── web_api.rs # Axum REST API and embedded file serving +│ ├── telemetry.rs # Prometheus /metrics endpoint for server health │ └── auth_service.rs # Argon2 hashing and JWT token generation ├── client_node/ # Desktop application, audio engine, and plugin host │ ├── Cargo.toml # deps: eframe, cpal, audiopus, webrtc-dsp, extism @@ -31,7 +40,8 @@ voice_app/ │ │ └── chat_area.rs # Text messages and system logs │ ├── network/ # Internet connectivity modules │ │ ├── control.rs # TCP: TLS, Heartbeats, Auto-reconnect -│ │ └── voice.rs # UDP: Jitter buffer (40ms), Seq ordering, Decryption +│ │ ├── voice.rs # UDP: Jitter buffer (40ms), Seq ordering, Decryption +│ │ └── chaos.rs # UDP Middleware: Artificial packet loss/latency injection │ ├── audio/ # Real-time pipeline with 20ms frames │ │ ├── capture.rs # Microphone -> Lock-free Ringbuffer │ │ ├── dsp.rs # Noise suppression & Echo cancellation (WebRTC) @@ -40,6 +50,8 @@ voice_app/ │ └── plugins/ # Wasm Extension Sandbox │ ├── runtime.rs # Extism Wasm runtime initialization │ └── hooks.rs # Event triggers: OnVoice, OnMessage, OnJoin +├── tests/ # Integration and Load Testing +│ └── load_tester.rs # Standalone binary simulating 100+ concurrent clients ├── deploy/ # Automation and containerization assets │ ├── Dockerfile # Multi-stage build for tiny server images │ ├── docker-compose.yml # One-click deployment for Docker/NAS users