Milestone 1

core_protocol/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "core_protocol"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+bincode = "1.3.3"
+chrono = { version = "0.4.44", features = ["serde"] }
+secrecy = { version = "0.10.3", features = ["serde"] }
+serde = { version = "1.0.228", features = ["derive"] }
+thiserror = "2.0.18"
+uuid = { version = "1.23.1", features = ["v4", "serde"] }

core_protocol/src/constants.rs

@@ -0,0 +1,15 @@
+//! Fixed system-wide specifications.
+//!
+//! Contains constants required for hardware configuration, network binding, 
+//! and math routines such as audio framing lengths.
+
+/// The uniform audio sampling rate (48 kHz).
+/// We lock the entire system to 48kHz because Opus performs optimally at this rate.
+pub const SAMPLE_RATE: u32 = 48000;
+
+/// The exact number of audio samples per 20ms frame at 48kHz.
+/// Opus strictly requires a specific frame size (like 20ms) to function correctly.
+pub const FRAME_SIZE: usize = 960;
+
+/// The default TCP port used for reliable control lane communication.
+pub const TCP_PORT: u16 = 8080;

core_protocol/src/lib.rs

@@ -0,0 +1,13 @@
+//! Core Protocol definitions for the Voice App.
+//!
+//! This module defines the foundational types and constants shared between the 
+//! client and server nodes. It ensures that both ends of the connection speak the 
+//! exact same structural language for serialization/deserialization.
+
+#![forbid(unsafe_code)]
+#![deny(clippy::all, clippy::pedantic)]
+#![deny(clippy::unwrap_used, clippy::expect_used)]
+
+pub mod constants;
+pub mod tcp_events;
+pub mod udp_packets;

core_protocol/src/tcp_events.rs

@@ -0,0 +1,31 @@
+//! TCP Control Lane events.
+//!
+//! Defines the reliable commands sent over the TCP connection for state 
+//! synchronization, such as authentication and text chat.
+
+use serde::{Deserialize, Serialize};
+
+/// Represents all possible events sent over the reliable TCP control lane.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum TcpEvent {
+    /// Initial request from the client containing their chosen username.
+    AuthRequest {
+        /// The username requested by the client.
+        username: String,
+    },
+    /// The server's response confirming authentication and granting a session token.
+    AuthResponse {
+        /// A unique, ephemeral ID assigned to the client for the duration of the session.
+        session_token: u32,
+    },
+    /// A request to join a specific voice channel.
+    ChannelJoin {
+        /// The unique ID of the target channel.
+        channel_id: u32,
+    },
+    /// A text message intended for the current channel's chat.
+    ChatMessage {
+        /// The raw text message.
+        message: String,
+    },
+}

core_protocol/src/udp_packets.rs

@@ -0,0 +1,20 @@
+//! UDP High-speed Voice Packet structures.
+//!
+//! Defines the headers and payload structures for the low-latency voice data
+//! sent over UDP.
+
+use serde::{Deserialize, Serialize};
+
+/// The header attached to every UDP voice frame.
+/// 
+/// We separate this from the payload to allow the server to rapidly route packets 
+/// using just the `session_token` without fully deserializing the heavy audio data.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoicePacketHeader {
+    /// The unique session ID matching the client's TCP authentication token.
+    pub session_token: u32,
+    /// A strictly increasing sequence number to detect dropped or out-of-order packets.
+    pub sequence_num: u64,
+    /// The timestamp of the packet generation, used to align jitter buffers.
+    pub timestamp: u64,
+}