wirepact 0.1.0

A teaching protocol crate: protocols are contracts, not HTTP.
Documentation
use crate::error::{Result, WirePactError};
use crate::message::Message;
use bytes::{Buf, BufMut, BytesMut};

pub const DEFAULT_MAX_FRAME_SIZE: u32 = 64 * 1024;

const TYPE_HELLO: u8 = 1;
const TYPE_WELCOME: u8 = 2;
const TYPE_PING: u8 = 3;
const TYPE_PONG: u8 = 4;
const TYPE_ECHO: u8 = 5;
const TYPE_ECHO_REPLY: u8 = 6;
const TYPE_GOODBYE: u8 = 7;
const TYPE_BYE: u8 = 8;
const TYPE_ERROR: u8 = 255;

const PADDING_BYTE: u8 = 4;
/// Length-prefixed binary codec used by production-style clients.
#[derive(Debug, Clone)]
pub struct FrameCodec {
    buffer: BytesMut,
    max_frame_size: u32,
}

impl FrameCodec {
    pub fn new() -> Self {
        Self::with_max_frame_size(DEFAULT_MAX_FRAME_SIZE)
    }

    pub fn with_max_frame_size(max_frame_size: u32) -> Self {
        Self {
            buffer: BytesMut::new(),
            max_frame_size,
        }
    }

    pub fn feed(&mut self, chunk: &[u8]) {
        self.buffer.extend_from_slice(chunk);
    }

    pub fn buffered_len(&self) -> usize {
        self.buffer.len()
    }

    pub fn decode_messages(&mut self) -> Result<Vec<Message>> {
        let mut messages = Vec::new();

        loop {
            if self.buffer.len() < 4 {
                break;
            }

            let frame_len = u32::from_be_bytes([
                self.buffer[0],
                self.buffer[1],
                self.buffer[2],
                self.buffer[3],
            ]) as usize;

            if frame_len as u32 > self.max_frame_size {
                return Err(WirePactError::FrameTooLarge {
                    size: frame_len as u32,
                    max: self.max_frame_size,
                });
            }

            let total = PADDING_BYTE as usize + frame_len;
            if self.buffer.len() < total {
                break;
            }

            let mut frame = self.buffer.split_to(total);
            frame.advance(PADDING_BYTE as usize);
            messages.push(parse_frame(&frame)?);
        }

        Ok(messages)
    }

    pub fn encode(&self, message: &Message) -> Vec<u8> {
        let mut payload = BytesMut::new();
        let frame_type = write_payload(&mut payload, message);

        let mut out = BytesMut::with_capacity(4 + 1 + payload.len());
        out.put_u32((1 + payload.len()) as u32);
        out.put_u8(frame_type);
        out.extend_from_slice(&payload);
        out.to_vec()
    }
}

impl Default for FrameCodec {
    fn default() -> Self {
        Self::new()
    }
}

fn parse_frame(mut payload: &[u8]) -> Result<Message> {
    if payload.is_empty() {
        return Err(WirePactError::InvalidPayload {
            message: "frame",
            reason: "missing type byte".into(),
        });
    }

    let frame_type = payload.get_u8();
    match frame_type {
        TYPE_HELLO | TYPE_WELCOME => decode_name_message(frame_type, &mut payload),
        TYPE_PING => Ok(Message::Ping),
        TYPE_PONG => Ok(Message::Pong),
        TYPE_ECHO => Ok(Message::Echo {
            payload: payload.to_vec(),
        }),
        TYPE_ECHO_REPLY => Ok(Message::EchoReply {
            payload: payload.to_vec(),
        }),
        TYPE_GOODBYE => Ok(Message::Goodbye),
        TYPE_BYE => Ok(Message::Bye),
        TYPE_ERROR => decode_error(&mut payload),
        other => Err(WirePactError::InvalidFrameType(other)),
    }
}

fn decode_name_message(frame_type: u8, payload: &mut &[u8]) -> Result<Message> {
    if payload.len() < 2 {
        return Err(WirePactError::InvalidPayload {
            message: "hello/welcome",
            reason: "missing name length".into(),
        });
    }

    let name_len = payload.get_u16() as usize;
    if payload.len() < name_len {
        return Err(WirePactError::Incomplete {
            needed: 2 + name_len,
            available: 2 + payload.len(),
        });
    }

    let name_bytes = &payload[..name_len];
    *payload = &payload[name_len..];
    let name =
        String::from_utf8(name_bytes.to_vec()).map_err(|_| WirePactError::InvalidPayload {
            message: "hello/welcome",
            reason: "name must be valid UTF-8".into(),
        })?;

    match frame_type {
        TYPE_HELLO => Ok(Message::Hello { name }),
        TYPE_WELCOME => Ok(Message::Welcome { name }),
        _ => unreachable!(),
    }
}

fn decode_error(payload: &mut &[u8]) -> Result<Message> {
    if payload.is_empty() {
        return Err(WirePactError::InvalidPayload {
            message: "error",
            reason: "missing code".into(),
        });
    }

    let code = payload.get_u8();
    if payload.len() < 2 {
        return Err(WirePactError::InvalidPayload {
            message: "error",
            reason: "missing message length".into(),
        });
    }

    let msg_len = payload.get_u16() as usize;
    if payload.len() < msg_len {
        return Err(WirePactError::Incomplete {
            needed: 3 + msg_len,
            available: 3 + payload.len(),
        });
    }

    let msg_bytes = &payload[..msg_len];
    let message =
        String::from_utf8(msg_bytes.to_vec()).map_err(|_| WirePactError::InvalidPayload {
            message: "error",
            reason: "message must be valid UTF-8".into(),
        })?;

    Ok(Message::Error { code, message })
}

fn write_payload(out: &mut BytesMut, message: &Message) -> u8 {
    match message {
        Message::Hello { name } | Message::Welcome { name } => {
            let frame_type = if matches!(message, Message::Hello { .. }) {
                TYPE_HELLO
            } else {
                TYPE_WELCOME
            };
            out.put_u16(name.len() as u16);
            out.extend_from_slice(name.as_bytes());
            frame_type
        }
        Message::Ping => TYPE_PING,
        Message::Pong => TYPE_PONG,
        Message::Echo { payload } | Message::EchoReply { payload } => {
            out.extend_from_slice(payload);
            if matches!(message, Message::Echo { .. }) {
                TYPE_ECHO
            } else {
                TYPE_ECHO_REPLY
            }
        }
        Message::Goodbye => TYPE_GOODBYE,
        Message::Bye => TYPE_BYE,
        Message::Error { code, message } => {
            out.put_u8(*code);
            out.put_u16(message.len() as u16);
            out.extend_from_slice(message.as_bytes());
            TYPE_ERROR
        }
    }
}

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

    #[test]
    fn round_trip_frame_messages() {
        let codec = FrameCodec::new();
        let ping = codec.encode(&Message::Ping);
        let echo = codec.encode(&Message::echo(b"game move"));

        let mut decoder = FrameCodec::new();
        decoder.feed(&ping);
        decoder.feed(&echo);

        let messages = decoder.decode_messages().unwrap();
        assert_eq!(messages, vec![Message::Ping, Message::echo(b"game move")]);
    }
}