use aequora_types::ProtocolVersion;
use bytes::{Bytes, BytesMut};
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use thiserror::Error;
pub const FLAG_ZSTD: u8 = 0b0000_0001;
const KNOWN_FLAGS: u8 = FLAG_ZSTD;
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum Compression {
#[default]
None,
Zstd { level: i32 },
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct EncodeOptions {
pub compression: Compression,
pub compression_threshold: usize,
}
impl Default for EncodeOptions {
fn default() -> Self {
Self {
compression: Compression::None,
compression_threshold: 4_096,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct DecodeLimits {
pub max_wire_bytes: usize,
pub max_decompressed_bytes: usize,
}
pub const MAGIC: [u8; 4] = *b"AEQ1";
pub const HEADER_LEN: usize = 44;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[repr(u8)]
pub enum MessageKind {
SyncRequest = 1,
SyncResponse = 2,
BootstrapRequest = 3,
BootstrapResponse = 4,
SnapshotStreamRequest = 5,
SnapshotStreamResponse = 6,
PushHint = 7,
TransportError = 8,
}
impl TryFrom<u8> for MessageKind {
type Error = CodecError;
fn try_from(value: u8) -> Result<Self, Self::Error> {
match value {
1 => Ok(Self::SyncRequest),
2 => Ok(Self::SyncResponse),
3 => Ok(Self::BootstrapRequest),
4 => Ok(Self::BootstrapResponse),
5 => Ok(Self::SnapshotStreamRequest),
6 => Ok(Self::SnapshotStreamResponse),
7 => Ok(Self::PushHint),
8 => Ok(Self::TransportError),
other => Err(CodecError::MessageKind(other)),
}
}
}
#[derive(Clone, Copy, Debug)]
pub struct DecodedFrame<'a> {
pub protocol: ProtocolVersion,
pub flags: u8,
pub kind: MessageKind,
pub payload: &'a [u8],
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct FrameHeader {
pub protocol: ProtocolVersion,
pub flags: u8,
pub kind: MessageKind,
pub payload_len: usize,
}
#[derive(Debug, Error)]
pub enum CodecError {
#[error("frame is shorter than the {HEADER_LEN}-byte header")]
Truncated,
#[error("invalid protocol magic")]
Magic,
#[error("unsupported message kind {0}")]
MessageKind(u8),
#[error("declared payload length does not match the frame")]
Length,
#[error("payload length {actual} exceeds limit {maximum}")]
PayloadTooLarge { actual: usize, maximum: usize },
#[error("payload integrity check failed")]
Integrity,
#[error("frame contains unsupported flags {0:#010b}")]
Flags(u8),
#[error("borrowed decode is unavailable for compressed frames")]
BorrowedCompressed,
#[error("zstd compression support is not enabled")]
CompressionUnavailable,
#[error("zstd processing failed: {0}")]
Compression(String),
#[error("postcard serialization failed: {0}")]
Postcard(#[from] postcard::Error),
#[cfg(feature = "ron")]
#[error("RON serialization failed: {0}")]
Ron(String),
#[cfg(feature = "json")]
#[error("JSON serialization failed: {0}")]
Json(String),
}
pub fn encode<T: Serialize>(
protocol: ProtocolVersion,
kind: MessageKind,
value: &T,
) -> Result<Vec<u8>, CodecError> {
Ok(encode_bytes(protocol, kind, value)?.to_vec())
}
pub fn encode_bytes<T: Serialize>(
protocol: ProtocolVersion,
kind: MessageKind,
value: &T,
) -> Result<Bytes, CodecError> {
encode_bytes_with_options(protocol, kind, value, EncodeOptions::default())
}
pub fn encode_with_options<T: Serialize>(
protocol: ProtocolVersion,
kind: MessageKind,
value: &T,
options: EncodeOptions,
) -> Result<Vec<u8>, CodecError> {
Ok(encode_bytes_with_options(protocol, kind, value, options)?.to_vec())
}
pub fn encode_bytes_with_options<T: Serialize>(
protocol: ProtocolVersion,
kind: MessageKind,
value: &T,
options: EncodeOptions,
) -> Result<Bytes, CodecError> {
let serialized = postcard::to_stdvec(value)?;
let (flags, payload) = compress_payload(serialized, options)?;
let length = u32::try_from(payload.len()).map_err(|_| CodecError::PayloadTooLarge {
actual: payload.len(),
maximum: u32::MAX as usize,
})?;
let mut frame = BytesMut::with_capacity(HEADER_LEN + payload.len());
frame.extend_from_slice(&MAGIC);
frame.extend_from_slice(&protocol.0.to_be_bytes());
frame.extend_from_slice(&[flags, kind as u8]);
frame.extend_from_slice(&length.to_be_bytes());
frame.extend_from_slice(blake3::hash(&payload).as_bytes());
frame.extend_from_slice(&payload);
Ok(frame.freeze())
}
pub fn inspect_header(header: &[u8], max_payload: usize) -> Result<FrameHeader, CodecError> {
if header.len() < HEADER_LEN {
return Err(CodecError::Truncated);
}
if header[..4] != MAGIC {
return Err(CodecError::Magic);
}
let protocol = ProtocolVersion(u16::from_be_bytes([header[4], header[5]]));
let flags = header[6];
if flags & !KNOWN_FLAGS != 0 {
return Err(CodecError::Flags(flags));
}
let kind = MessageKind::try_from(header[7])?;
let payload_len = u32::from_be_bytes([header[8], header[9], header[10], header[11]]) as usize;
if payload_len > max_payload {
return Err(CodecError::PayloadTooLarge {
actual: payload_len,
maximum: max_payload,
});
}
Ok(FrameHeader {
protocol,
flags,
kind,
payload_len,
})
}
pub fn decode_frame(frame: &[u8], max_payload: usize) -> Result<DecodedFrame<'_>, CodecError> {
let header = inspect_header(frame, max_payload)?;
if frame.len() != HEADER_LEN + header.payload_len {
return Err(CodecError::Length);
}
let payload = &frame[HEADER_LEN..];
let expected = &frame[12..HEADER_LEN];
if blake3::hash(payload).as_bytes() != expected {
return Err(CodecError::Integrity);
}
Ok(DecodedFrame {
protocol: header.protocol,
flags: header.flags,
kind: header.kind,
payload,
})
}
pub fn decode_borrowed<'a, T>(
frame: &'a [u8],
expected_kind: MessageKind,
max_payload: usize,
) -> Result<(ProtocolVersion, T), CodecError>
where
T: Deserialize<'a>,
{
let decoded = decode_frame(frame, max_payload)?;
if decoded.kind != expected_kind {
return Err(CodecError::MessageKind(decoded.kind as u8));
}
if decoded.flags & FLAG_ZSTD != 0 {
return Err(CodecError::BorrowedCompressed);
}
Ok((decoded.protocol, postcard::from_bytes(decoded.payload)?))
}
pub fn decode<T: DeserializeOwned>(
frame: &[u8],
expected_kind: MessageKind,
max_payload: usize,
) -> Result<(ProtocolVersion, T), CodecError> {
decode_with_limits(
frame,
expected_kind,
DecodeLimits {
max_wire_bytes: max_payload,
max_decompressed_bytes: max_payload,
},
)
}
pub fn decode_with_limits<T: DeserializeOwned>(
frame: &[u8],
expected_kind: MessageKind,
limits: DecodeLimits,
) -> Result<(ProtocolVersion, T), CodecError> {
let decoded = decode_frame(frame, limits.max_wire_bytes)?;
if decoded.kind != expected_kind {
return Err(CodecError::MessageKind(decoded.kind as u8));
}
let decompressed;
let payload = if decoded.flags & FLAG_ZSTD != 0 {
decompressed = decompress_payload(decoded.payload, limits.max_decompressed_bytes)?;
decompressed.as_slice()
} else {
if decoded.payload.len() > limits.max_decompressed_bytes {
return Err(CodecError::PayloadTooLarge {
actual: decoded.payload.len(),
maximum: limits.max_decompressed_bytes,
});
}
decoded.payload
};
let value = postcard::from_bytes(payload)?;
Ok((decoded.protocol, value))
}
fn compress_payload(payload: Vec<u8>, options: EncodeOptions) -> Result<(u8, Vec<u8>), CodecError> {
match options.compression {
Compression::None => Ok((0, payload)),
Compression::Zstd { level: _ } if payload.len() < options.compression_threshold => {
Ok((0, payload))
}
#[cfg(feature = "zstd")]
Compression::Zstd { level } => {
let compressed = zstd::stream::encode_all(payload.as_slice(), level)
.map_err(|error| CodecError::Compression(error.to_string()))?;
if compressed.len() < payload.len() {
Ok((FLAG_ZSTD, compressed))
} else {
Ok((0, payload))
}
}
#[cfg(not(feature = "zstd"))]
Compression::Zstd { .. } => Err(CodecError::CompressionUnavailable),
}
}
#[cfg(feature = "zstd")]
fn decompress_payload(payload: &[u8], maximum: usize) -> Result<Vec<u8>, CodecError> {
use std::io::Read;
let decoder = zstd::stream::read::Decoder::new(payload)
.map_err(|error| CodecError::Compression(error.to_string()))?;
let take_limit = u64::try_from(maximum).unwrap_or(u64::MAX).saturating_add(1);
let mut bounded = decoder.take(take_limit);
let mut output = Vec::new();
bounded
.read_to_end(&mut output)
.map_err(|error| CodecError::Compression(error.to_string()))?;
if output.len() > maximum {
return Err(CodecError::PayloadTooLarge {
actual: output.len(),
maximum,
});
}
Ok(output)
}
#[cfg(not(feature = "zstd"))]
fn decompress_payload(_payload: &[u8], _maximum: usize) -> Result<Vec<u8>, CodecError> {
Err(CodecError::CompressionUnavailable)
}
#[cfg(feature = "ron")]
pub fn to_ron<T: Serialize>(value: &T) -> Result<String, CodecError> {
ron::ser::to_string_pretty(value, ron::ser::PrettyConfig::default())
.map_err(|error| CodecError::Ron(error.to_string()))
}
#[cfg(feature = "json")]
pub fn to_json<T: Serialize>(value: &T) -> Result<String, CodecError> {
serde_json::to_string(value).map_err(|error| CodecError::Json(error.to_string()))
}
#[cfg(feature = "json")]
pub fn from_json<T: DeserializeOwned>(value: &str) -> Result<T, CodecError> {
serde_json::from_str(value).map_err(|error| CodecError::Json(error.to_string()))
}
#[cfg(test)]
mod tests {
use super::*;
use serde::{Deserialize, Serialize};
#[derive(Debug, Deserialize, Eq, PartialEq, Serialize)]
struct Example {
value: u32,
}
#[derive(Debug, Deserialize, Eq, PartialEq, Serialize)]
struct BorrowedExample<'a> {
value: &'a str,
}
#[test]
fn framed_values_round_trip() -> Result<(), CodecError> {
let frame = encode(
ProtocolVersion::V1,
MessageKind::SyncRequest,
&Example { value: 42 },
)?;
let (version, decoded) = decode::<Example>(&frame, MessageKind::SyncRequest, 1_024)?;
assert_eq!(version, ProtocolVersion::V1);
assert_eq!(decoded, Example { value: 42 });
Ok(())
}
#[test]
fn payload_tampering_is_detected() -> Result<(), CodecError> {
let mut frame = encode(
ProtocolVersion::V1,
MessageKind::SyncRequest,
&Example { value: 1 },
)?;
let last = frame.len().saturating_sub(1);
frame[last] ^= 1;
assert!(matches!(
decode_frame(&frame, 1_024),
Err(CodecError::Integrity)
));
Ok(())
}
#[test]
fn header_limit_rejects_declared_payload_before_body_is_present() -> Result<(), CodecError> {
let frame = encode_bytes(
ProtocolVersion::V1,
MessageKind::SyncRequest,
&Example { value: 42 },
)?;
let header = inspect_header(&frame[..HEADER_LEN], 1_024)?;
assert_eq!(header.kind, MessageKind::SyncRequest);
assert!(matches!(
inspect_header(&frame[..HEADER_LEN], 0),
Err(CodecError::PayloadTooLarge { .. })
));
Ok(())
}
#[test]
fn borrowed_postcard_view_lives_in_the_frame_buffer() -> Result<(), CodecError> {
let frame = encode_bytes(
ProtocolVersion::V1,
MessageKind::SyncRequest,
&BorrowedExample { value: "borrowed" },
)?;
let (_, decoded) =
decode_borrowed::<BorrowedExample<'_>>(&frame, MessageKind::SyncRequest, 1_024)?;
assert_eq!(decoded.value, "borrowed");
Ok(())
}
#[cfg(feature = "zstd")]
#[test]
fn compressed_payloads_round_trip_with_a_decompressed_limit() -> Result<(), CodecError> {
let value = vec![42_u8; 32_768];
let frame = encode_with_options(
ProtocolVersion::V1,
MessageKind::SyncResponse,
&value,
EncodeOptions {
compression: Compression::Zstd { level: 1 },
compression_threshold: 1,
},
)?;
assert_ne!(decode_frame(&frame, 1_024)?.flags & FLAG_ZSTD, 0);
let (_, decoded) = decode_with_limits::<Vec<u8>>(
&frame,
MessageKind::SyncResponse,
DecodeLimits {
max_wire_bytes: 1_024,
max_decompressed_bytes: 64 * 1_024,
},
)?;
assert_eq!(decoded, value);
assert!(matches!(
decode_with_limits::<Vec<u8>>(
&frame,
MessageKind::SyncResponse,
DecodeLimits {
max_wire_bytes: 1_024,
max_decompressed_bytes: 1_024
},
),
Err(CodecError::PayloadTooLarge { .. })
));
Ok(())
}
#[cfg(feature = "json")]
#[test]
fn optional_json_round_trips_without_changing_wire_framing() -> Result<(), CodecError> {
let encoded = to_json(&Example { value: 42 })?;
assert_eq!(from_json::<Example>(&encoded)?, Example { value: 42 });
Ok(())
}
}