Skip to main content

rodecaster_protocol/
frame.rs

1//! TCP stream packet framing codec.
2//!
3//! Frames protocol messages using a 4-byte magic header (`0xF2B49E2C`)
4//! and a 4-byte little-endian length prefix:
5//! `[magic (4B)][length (4B)][payload]`.
6
7/// Magic header for RODECaster protocol packets (little-endian on the wire).
8pub const MAGIC_HEADER: u32 = 0xF2B49E2C;
9
10/// A length-prefixed protocol packet.
11#[derive(Debug, Clone)]
12pub struct Packet {
13    pub header: u32,
14    pub length: u32,
15    pub payload: Vec<u8>,
16}
17
18impl Packet {
19    pub fn new(payload: Vec<u8>) -> Self {
20        Packet {
21            header: MAGIC_HEADER,
22            length: payload.len() as u32,
23            payload,
24        }
25    }
26
27    pub fn to_bytes(&self) -> Vec<u8> {
28        let mut out = Vec::with_capacity(8 + self.payload.len());
29        out.extend_from_slice(&self.header.to_le_bytes());
30        out.extend_from_slice(&self.length.to_le_bytes());
31        out.extend_from_slice(&self.payload);
32        out
33    }
34
35    /// Parse a packet from bytes, returning it and the total bytes consumed.
36    pub fn from_bytes(data: &[u8]) -> Option<(Self, usize)> {
37        if data.len() < 8 {
38            return None;
39        }
40
41        let header = u32::from_le_bytes([data[0], data[1], data[2], data[3]]);
42        if header != MAGIC_HEADER {
43            return None;
44        }
45
46        let length = u32::from_le_bytes([data[4], data[5], data[6], data[7]]) as usize;
47        let total_len = 8 + length;
48
49        if data.len() < total_len {
50            return None;
51        }
52
53        Some((
54            Packet {
55                header,
56                length: length as u32,
57                payload: data[8..total_len].to_vec(),
58            },
59            total_len,
60        ))
61    }
62}
63
64/// Result of scanning a byte buffer for a leading frame without allocating.
65#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub enum FrameScan {
67    /// Exactly one complete frame of `len` bytes starts at offset 0.
68    Complete { len: usize },
69    /// Valid magic header, but the full frame has not arrived yet.
70    Incomplete,
71    /// Offset 0 does not match the magic header.
72    Desync,
73}
74
75/// Scan `buf` for a complete frame at offset 0 without allocating.
76pub fn scan_frame(buf: &[u8]) -> FrameScan {
77    if buf.len() < 8 {
78        return FrameScan::Incomplete;
79    }
80    let header = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]);
81    if header != MAGIC_HEADER {
82        return FrameScan::Desync;
83    }
84    let length = u32::from_le_bytes([buf[4], buf[5], buf[6], buf[7]]) as usize;
85    let total = 8 + length;
86    if buf.len() < total {
87        return FrameScan::Incomplete;
88    }
89    FrameScan::Complete { len: total }
90}
91
92/// Borrow the payload of one complete frame at offset 0 without copying.
93pub fn frame_payload(buf: &[u8]) -> Option<&[u8]> {
94    match scan_frame(buf) {
95        FrameScan::Complete { len } => Some(&buf[8..len]),
96        FrameScan::Incomplete | FrameScan::Desync => None,
97    }
98}
99
100#[cfg(test)]
101mod tests {
102    use super::*;
103
104    #[test]
105    fn test_packet_roundtrip() {
106        let payload = vec![0x01, 0x02, 0x03, 0x04];
107        let packet = Packet::new(payload.clone());
108        let bytes = packet.to_bytes();
109
110        let (parsed, len) = Packet::from_bytes(&bytes).unwrap();
111        assert_eq!(len, bytes.len());
112        assert_eq!(parsed.payload, payload);
113    }
114
115    #[test]
116    fn to_bytes_layout_is_magic_len_payload() {
117        let packet = Packet::new(vec![0xAA, 0xBB]);
118        let bytes = packet.to_bytes();
119        assert_eq!(&bytes[0..4], &0xF2B4_9E2Cu32.to_le_bytes()); // magic, LE
120        assert_eq!(&bytes[4..8], &2u32.to_le_bytes()); // length, LE
121        assert_eq!(&bytes[8..], &[0xAA, 0xBB]);
122    }
123
124    #[test]
125    fn scan_frame_complete_returns_total_len() {
126        let bytes = Packet::new(vec![0xAA, 0xBB, 0xCC]).to_bytes();
127        assert_eq!(scan_frame(&bytes), FrameScan::Complete { len: bytes.len() });
128    }
129
130    #[test]
131    fn scan_frame_incomplete_when_shorter_than_header_or_frame() {
132        assert_eq!(scan_frame(&[]), FrameScan::Incomplete);
133        assert_eq!(scan_frame(&[0x2c, 0x9e, 0xb4]), FrameScan::Incomplete); // <8 bytes
134        let full = Packet::new(vec![1, 2, 3, 4, 5]).to_bytes();
135        // Valid magic + length, but one payload byte short.
136        assert_eq!(scan_frame(&full[..full.len() - 1]), FrameScan::Incomplete);
137    }
138
139    #[test]
140    fn scan_frame_desync_on_bad_magic() {
141        assert_eq!(scan_frame(&[0, 0, 0, 0, 0, 0, 0, 0]), FrameScan::Desync);
142    }
143
144    #[test]
145    fn scan_frame_stops_at_first_frame_boundary() {
146        let first = Packet::new(vec![0x09]).to_bytes();
147        let first_len = first.len();
148        let mut two = first;
149        two.extend_from_slice(&Packet::new(vec![0x08]).to_bytes());
150        assert_eq!(scan_frame(&two), FrameScan::Complete { len: first_len });
151    }
152
153    #[test]
154    fn frame_payload_borrows_inner_bytes() {
155        let payload = vec![0x02, 0xDE, 0xAD];
156        let bytes = Packet::new(payload.clone()).to_bytes();
157        assert_eq!(frame_payload(&bytes), Some(&payload[..]));
158        // First frame's payload only, ignoring a trailing second frame.
159        let mut two = bytes;
160        two.extend_from_slice(&Packet::new(vec![0xFF]).to_bytes());
161        assert_eq!(frame_payload(&two), Some(&payload[..]));
162        // Incomplete / desync borrow nothing.
163        assert_eq!(frame_payload(&[0x2c, 0x9e]), None);
164        assert_eq!(frame_payload(&[0, 0, 0, 0, 0, 0, 0, 0]), None);
165    }
166}