TS3-vibed/Documentation/Mile_Stones/Milestone_1.md

Milestone 1: The Foundation (The Skeleton)

Goal: Initialize the project and establish the shared language between client and server.

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"].
• 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).
• Dependencies (server_node): Add tokio (full), tracing, tracing-subscriber, anyhow, dashmap.
• Dependencies (client_node): Add tokio (rt-multi-thread), tracing, tracing-subscriber, anyhow.

2. Protocol Definitions (core_protocol)

• Create src/tcp_events.rs. Define enum TcpEvent { AuthRequest { username: String, ... }, AuthResponse { session_token: u32, ... }, ChannelJoin { ... }, ChatMessage { ... } } with #[derive(Serialize, Deserialize)].
• Create src/udp_packets.rs. Define struct VoicePacketHeader { pub session_token: u32, pub sequence_num: u64, pub timestamp: u64 } with #[derive(Serialize, Deserialize)].
• Create src/constants.rs. Define pub const SAMPLE_RATE: u32 = 48000;, pub const FRAME_SIZE: usize = 960;, pub const TCP_PORT: u16 = 8080;.

3. TCP Handshake (server_node & client_node)

• 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.

4. Login Logic & State

• Server State: Create server_node/src/state.rs. Define a DashMap<u32, UserState> to store active session tokens.
• Authentication Flow: Client sends TcpEvent::AuthRequest. Server generates a random u32 session token, stores it in DashMap, and returns TcpEvent::AuthResponse.
• Validation: Ensure the server actively drops the connection if the client sends invalid or excessively large payloads.

5. Observability (Logging)

• Initialization: In both binaries' main.rs, call tracing_subscriber::fmt::init().
• Implementation: Replace all println! calls with tracing::info!, tracing::warn!, or tracing::error!.
• Tracing Context: Use #[tracing::instrument] on core TCP handler functions to automatically log client IPs and session IDs.