st_protocol/

frame.rs

//! Frame encoding/decoding
//!
//! ## Frame Format
//!
//! ```text
//! ┌──────┬─────────────────┬──────┐
//! │ verb │     payload     │ 0x00 │
//! │ 1B   │   N bytes       │ END  │
//! └──────┴─────────────────┴──────┘
//! ```

#[cfg(feature = "alloc")]
use alloc::vec::Vec;

use crate::{Verb, Payload, END, ESC, ProtocolError, ProtocolResult, MAX_FRAME_SIZE};

/// A complete protocol frame
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Frame {
    verb: Verb,
    payload: Payload,
}

impl Frame {
    /// Create a new frame
    pub fn new(verb: Verb, payload: Payload) -> Self {
        Frame { verb, payload }
    }

    /// Create a simple frame with no payload
    pub fn simple(verb: Verb) -> Self {
        Frame {
            verb,
            payload: Payload::empty(),
        }
    }

    /// Get the verb
    pub fn verb(&self) -> Verb {
        self.verb
    }

    /// Get the payload
    pub fn payload(&self) -> &Payload {
        &self.payload
    }

    /// Consume and return the payload
    pub fn into_payload(self) -> Payload {
        self.payload
    }

    /// Encode frame for wire transmission
    #[cfg(any(feature = "std", feature = "alloc"))]
    pub fn encode(&self) -> Vec<u8> {
        let encoded_payload = self.payload.encode();
        let mut out = Vec::with_capacity(encoded_payload.len() + 2);

        out.push(self.verb.as_byte());
        out.extend_from_slice(&encoded_payload);
        out.push(END);

        out
    }

    /// Decode frame from wire format
    pub fn decode(data: &[u8]) -> ProtocolResult<Self> {
        // Minimum frame: verb + END = 2 bytes
        if data.len() < 2 {
            return Err(ProtocolError::FrameTooShort);
        }

        if data.len() > MAX_FRAME_SIZE {
            return Err(ProtocolError::FrameTooLarge);
        }

        // Last byte must be END
        if data[data.len() - 1] != END {
            return Err(ProtocolError::MissingEndMarker);
        }

        // First byte is verb
        let verb = Verb::from_byte(data[0]).ok_or(ProtocolError::InvalidVerb(data[0]))?;

        // Payload is everything between verb and END
        let payload_data = &data[1..data.len() - 1];
        let payload = Payload::decode(payload_data)?;

        Ok(Frame { verb, payload })
    }

    /// Check if frame is valid (verb + END marker present)
    pub fn is_valid(data: &[u8]) -> bool {
        if data.len() < 2 {
            return false;
        }
        if data[data.len() - 1] != END {
            return false;
        }
        Verb::from_byte(data[0]).is_some()
    }

    /// Find the end of a frame in a buffer (returns length including END)
    pub fn find_end(data: &[u8]) -> Option<usize> {
        let mut i = 1; // Skip verb byte

        while i < data.len() {
            match data[i] {
                END => return Some(i + 1),
                ESC if i + 1 < data.len() => i += 2, // Skip escape sequence
                ESC => return None, // Incomplete escape
                _ => i += 1,
            }
        }

        None // No END found
    }
}

/// Builder for constructing frames
pub struct FrameBuilder {
    verb: Verb,
    payload: Payload,
}

impl FrameBuilder {
    pub fn new(verb: Verb) -> Self {
        FrameBuilder {
            verb,
            payload: Payload::new(),
        }
    }

    /// Add a byte to payload
    pub fn byte(mut self, b: u8) -> Self {
        self.payload.push_byte(b);
        self
    }

    /// Add a string to payload
    pub fn string(mut self, s: &str) -> Self {
        self.payload.push_str(s);
        self
    }

    /// Add bytes to payload
    pub fn bytes(mut self, data: &[u8]) -> Self {
        for &b in data {
            self.payload.push_byte(b);
        }
        self
    }

    /// Add u16 LE to payload
    pub fn u16_le(mut self, v: u16) -> Self {
        self.payload.push_u16_le(v);
        self
    }

    /// Add u32 LE to payload
    pub fn u32_le(mut self, v: u32) -> Self {
        self.payload.push_u32_le(v);
        self
    }

    /// Build the frame
    pub fn build(self) -> Frame {
        Frame {
            verb: self.verb,
            payload: self.payload,
        }
    }
}

// Convenience constructors for common frames
impl Frame {
    /// Create a PING frame
    pub fn ping() -> Self {
        Frame::simple(Verb::Ping)
    }

    /// Create a STATS frame
    pub fn stats() -> Self {
        Frame::simple(Verb::Stats)
    }

    /// Create an OK/ACK frame
    pub fn ok() -> Self {
        Frame::simple(Verb::Ok)
    }

    /// Create an ERROR frame with message
    pub fn error(message: &str) -> Self {
        Frame::new(Verb::Error, Payload::from_string(message))
    }

    /// Create a SCAN frame
    pub fn scan(path: &str, depth: u8) -> Self {
        let mut payload = Payload::new();
        // Length-prefixed path
        let len = path.len();
        if len <= 126 {
            payload.push_byte((len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(len as u16);
        }
        payload.push_str(path);
        payload.push_byte(depth);

        Frame::new(Verb::Scan, payload)
    }

    /// Create a SEARCH frame (simple - pattern only)
    pub fn search(pattern: &str) -> Self {
        Frame::new(Verb::Search, Payload::from_string(pattern))
    }

    /// Create a SEARCH frame with path, pattern, and max results
    pub fn search_path(path: &str, pattern: &str, max_results: u8) -> Self {
        let mut payload = Payload::new();

        // Length-prefixed path
        let path_len = path.len();
        if path_len <= 126 {
            payload.push_byte((path_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(path_len as u16);
        }
        payload.push_str(path);

        // Length-prefixed pattern
        let pattern_len = pattern.len();
        if pattern_len <= 126 {
            payload.push_byte((pattern_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(pattern_len as u16);
        }
        payload.push_str(pattern);

        // Max results
        payload.push_byte(max_results);

        Frame::new(Verb::Search, payload)
    }

    /// Create a FORMAT frame with just mode (lists formats)
    pub fn format(mode: &str) -> Self {
        Frame::new(Verb::Format, Payload::from_string(mode))
    }

    /// Create a FORMAT frame with mode, path, and depth (scans and formats)
    pub fn format_path(mode: &str, path: &str, depth: u8) -> Self {
        let mut payload = Payload::new();

        // Length-prefixed mode
        let mode_len = mode.len();
        if mode_len <= 126 {
            payload.push_byte((mode_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(mode_len as u16);
        }
        payload.push_str(mode);

        // Length-prefixed path
        let path_len = path.len();
        if path_len <= 126 {
            payload.push_byte((path_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(path_len as u16);
        }
        payload.push_str(path);

        // Depth
        payload.push_byte(depth);

        Frame::new(Verb::Format, payload)
    }

    /// Create a REMEMBER frame
    pub fn remember(content: &str, keywords: &str, memory_type: &str) -> Self {
        let mut payload = Payload::new();

        // Length-prefixed content
        let content_len = content.len();
        if content_len <= 126 {
            payload.push_byte((content_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(content_len as u16);
        }
        payload.push_str(content);

        // Length-prefixed keywords
        let keywords_len = keywords.len();
        if keywords_len <= 126 {
            payload.push_byte((keywords_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(keywords_len as u16);
        }
        payload.push_str(keywords);

        // Length-prefixed type
        let type_len = memory_type.len();
        if type_len <= 126 {
            payload.push_byte((type_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(type_len as u16);
        }
        payload.push_str(memory_type);

        // Default emotional state (neutral)
        payload.push_byte(128); // valence = 0.0
        payload.push_byte(128); // arousal = 0.5

        Frame::new(Verb::Remember, payload)
    }

    /// Create a RECALL frame
    pub fn recall(keywords: &str, max_results: u8) -> Self {
        let mut payload = Payload::new();

        // Length-prefixed keywords
        let keywords_len = keywords.len();
        if keywords_len <= 126 {
            payload.push_byte((keywords_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(keywords_len as u16);
        }
        payload.push_str(keywords);

        payload.push_byte(max_results);

        Frame::new(Verb::Recall, payload)
    }

    /// Create a FORGET frame
    pub fn forget(memory_id: &str) -> Self {
        Frame::new(Verb::Forget, Payload::from_string(memory_id))
    }

    /// Create an M8_WAVE frame (get memory stats)
    pub fn m8_wave() -> Self {
        Frame::simple(Verb::M8Wave)
    }

    /// Create an AUDIO frame with AcousticMemory data
    ///
    /// Payload format: [AYE8 magic + serialized AcousticMemory bytes]
    /// The bytes should be from liquid-rust's AcousticMemory::to_bytes()
    pub fn audio(acoustic_bytes: &[u8]) -> Self {
        let mut payload = Payload::new();
        for &b in acoustic_bytes {
            payload.push_byte(b);
        }
        Frame::new(Verb::Audio, payload)
    }

    /// Create an AUDIO frame with text and emotion (simplified)
    ///
    /// For when you don't have full AcousticMemory, just text + emotion
    pub fn audio_simple(text: &str, valence: f32, arousal: f32) -> Self {
        let mut payload = Payload::new();

        // Length-prefixed text
        let text_len = text.len();
        if text_len <= 126 {
            payload.push_byte((text_len as u8) + 0x80);
        } else {
            payload.push_byte(0xFF);
            payload.push_u16_le(text_len as u16);
        }
        payload.push_str(text);

        // Emotion as two bytes (0-255 range)
        // valence: -1.0 to 1.0 → 0 to 255
        // arousal: 0.0 to 1.0 → 0 to 255
        payload.push_byte(((valence + 1.0) * 127.5) as u8);
        payload.push_byte((arousal * 255.0) as u8);

        Frame::new(Verb::Audio, payload)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_ping_frame() {
        let frame = Frame::ping();
        let encoded = frame.encode();
        assert_eq!(encoded, vec![0x05, 0x00]); // ENQ + END
    }

    #[test]
    fn test_error_frame() {
        let frame = Frame::error("not found");
        let encoded = frame.encode();
        assert_eq!(encoded[0], 0x15); // NAK
        assert_eq!(encoded[encoded.len() - 1], 0x00); // END
    }

    #[test]
    fn test_frame_roundtrip() {
        let original = Frame::scan("/home/hue", 3);
        let encoded = original.encode();
        let decoded = Frame::decode(&encoded).unwrap();

        assert_eq!(decoded.verb(), Verb::Scan);
    }

    #[test]
    fn test_find_end() {
        let data = vec![0x01, 0x41, 0x42, 0x00]; // SCAN "AB" END
        assert_eq!(Frame::find_end(&data), Some(4));
    }

    #[test]
    fn test_find_end_with_escape() {
        let data = vec![0x01, 0x1B, 0x00, 0x00]; // SCAN ESC-NULL END
        assert_eq!(Frame::find_end(&data), Some(4));
    }

    #[test]
    fn test_builder() {
        let frame = FrameBuilder::new(Verb::Search)
            .string("*.rs")
            .build();

        assert_eq!(frame.verb(), Verb::Search);
        assert_eq!(frame.payload().as_str(), Some("*.rs"));
    }
}