1use aequora_types::ProtocolVersion;
4use bytes::{Bytes, BytesMut};
5use serde::{Deserialize, Serialize, de::DeserializeOwned};
6use thiserror::Error;
7
8pub const FLAG_ZSTD: u8 = 0b0000_0001;
10const KNOWN_FLAGS: u8 = FLAG_ZSTD;
11
12#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
14pub enum Compression {
15 #[default]
17 None,
18 Zstd { level: i32 },
20}
21
22#[derive(Clone, Copy, Debug, Eq, PartialEq)]
24pub struct EncodeOptions {
25 pub compression: Compression,
27 pub compression_threshold: usize,
29}
30
31impl Default for EncodeOptions {
32 fn default() -> Self {
33 Self {
34 compression: Compression::None,
35 compression_threshold: 4_096,
36 }
37 }
38}
39
40#[derive(Clone, Copy, Debug, Eq, PartialEq)]
42pub struct DecodeLimits {
43 pub max_wire_bytes: usize,
45 pub max_decompressed_bytes: usize,
47}
48
49pub const MAGIC: [u8; 4] = *b"AEQ1";
51pub const HEADER_LEN: usize = 44;
53
54#[derive(Clone, Copy, Debug, Eq, PartialEq)]
56#[repr(u8)]
57pub enum MessageKind {
58 SyncRequest = 1,
60 SyncResponse = 2,
62 BootstrapRequest = 3,
64 BootstrapResponse = 4,
66 SnapshotStreamRequest = 5,
68 SnapshotStreamResponse = 6,
70 PushHint = 7,
72 TransportError = 8,
74}
75
76impl TryFrom<u8> for MessageKind {
77 type Error = CodecError;
78
79 fn try_from(value: u8) -> Result<Self, Self::Error> {
80 match value {
81 1 => Ok(Self::SyncRequest),
82 2 => Ok(Self::SyncResponse),
83 3 => Ok(Self::BootstrapRequest),
84 4 => Ok(Self::BootstrapResponse),
85 5 => Ok(Self::SnapshotStreamRequest),
86 6 => Ok(Self::SnapshotStreamResponse),
87 7 => Ok(Self::PushHint),
88 8 => Ok(Self::TransportError),
89 other => Err(CodecError::MessageKind(other)),
90 }
91 }
92}
93
94#[derive(Clone, Copy, Debug)]
96pub struct DecodedFrame<'a> {
97 pub protocol: ProtocolVersion,
99 pub flags: u8,
101 pub kind: MessageKind,
103 pub payload: &'a [u8],
105}
106
107#[derive(Clone, Copy, Debug, Eq, PartialEq)]
110pub struct FrameHeader {
111 pub protocol: ProtocolVersion,
112 pub flags: u8,
113 pub kind: MessageKind,
114 pub payload_len: usize,
115}
116
117#[derive(Debug, Error)]
119pub enum CodecError {
120 #[error("frame is shorter than the {HEADER_LEN}-byte header")]
122 Truncated,
123 #[error("invalid protocol magic")]
125 Magic,
126 #[error("unsupported message kind {0}")]
128 MessageKind(u8),
129 #[error("declared payload length does not match the frame")]
131 Length,
132 #[error("payload length {actual} exceeds limit {maximum}")]
134 PayloadTooLarge { actual: usize, maximum: usize },
135 #[error("payload integrity check failed")]
137 Integrity,
138 #[error("frame contains unsupported flags {0:#010b}")]
140 Flags(u8),
141 #[error("borrowed decode is unavailable for compressed frames")]
143 BorrowedCompressed,
144 #[error("zstd compression support is not enabled")]
146 CompressionUnavailable,
147 #[error("zstd processing failed: {0}")]
149 Compression(String),
150 #[error("postcard serialization failed: {0}")]
152 Postcard(#[from] postcard::Error),
153 #[cfg(feature = "ron")]
155 #[error("RON serialization failed: {0}")]
156 Ron(String),
157 #[cfg(feature = "json")]
159 #[error("JSON serialization failed: {0}")]
160 Json(String),
161}
162
163pub fn encode<T: Serialize>(
170 protocol: ProtocolVersion,
171 kind: MessageKind,
172 value: &T,
173) -> Result<Vec<u8>, CodecError> {
174 Ok(encode_bytes(protocol, kind, value)?.to_vec())
175}
176
177pub fn encode_bytes<T: Serialize>(
184 protocol: ProtocolVersion,
185 kind: MessageKind,
186 value: &T,
187) -> Result<Bytes, CodecError> {
188 encode_bytes_with_options(protocol, kind, value, EncodeOptions::default())
189}
190
191pub fn encode_with_options<T: Serialize>(
197 protocol: ProtocolVersion,
198 kind: MessageKind,
199 value: &T,
200 options: EncodeOptions,
201) -> Result<Vec<u8>, CodecError> {
202 Ok(encode_bytes_with_options(protocol, kind, value, options)?.to_vec())
203}
204
205pub fn encode_bytes_with_options<T: Serialize>(
212 protocol: ProtocolVersion,
213 kind: MessageKind,
214 value: &T,
215 options: EncodeOptions,
216) -> Result<Bytes, CodecError> {
217 let serialized = postcard::to_stdvec(value)?;
218 let (flags, payload) = compress_payload(serialized, options)?;
219 let length = u32::try_from(payload.len()).map_err(|_| CodecError::PayloadTooLarge {
220 actual: payload.len(),
221 maximum: u32::MAX as usize,
222 })?;
223 let mut frame = BytesMut::with_capacity(HEADER_LEN + payload.len());
224 frame.extend_from_slice(&MAGIC);
225 frame.extend_from_slice(&protocol.0.to_be_bytes());
226 frame.extend_from_slice(&[flags, kind as u8]);
227 frame.extend_from_slice(&length.to_be_bytes());
228 frame.extend_from_slice(blake3::hash(&payload).as_bytes());
229 frame.extend_from_slice(&payload);
230 Ok(frame.freeze())
231}
232
233pub fn inspect_header(header: &[u8], max_payload: usize) -> Result<FrameHeader, CodecError> {
241 if header.len() < HEADER_LEN {
242 return Err(CodecError::Truncated);
243 }
244 if header[..4] != MAGIC {
245 return Err(CodecError::Magic);
246 }
247 let protocol = ProtocolVersion(u16::from_be_bytes([header[4], header[5]]));
248 let flags = header[6];
249 if flags & !KNOWN_FLAGS != 0 {
250 return Err(CodecError::Flags(flags));
251 }
252 let kind = MessageKind::try_from(header[7])?;
253 let payload_len = u32::from_be_bytes([header[8], header[9], header[10], header[11]]) as usize;
254 if payload_len > max_payload {
255 return Err(CodecError::PayloadTooLarge {
256 actual: payload_len,
257 maximum: max_payload,
258 });
259 }
260 Ok(FrameHeader {
261 protocol,
262 flags,
263 kind,
264 payload_len,
265 })
266}
267
268pub fn decode_frame(frame: &[u8], max_payload: usize) -> Result<DecodedFrame<'_>, CodecError> {
275 let header = inspect_header(frame, max_payload)?;
276 if frame.len() != HEADER_LEN + header.payload_len {
277 return Err(CodecError::Length);
278 }
279 let payload = &frame[HEADER_LEN..];
280 let expected = &frame[12..HEADER_LEN];
281 if blake3::hash(payload).as_bytes() != expected {
282 return Err(CodecError::Integrity);
283 }
284 Ok(DecodedFrame {
285 protocol: header.protocol,
286 flags: header.flags,
287 kind: header.kind,
288 payload,
289 })
290}
291
292pub fn decode_borrowed<'a, T>(
300 frame: &'a [u8],
301 expected_kind: MessageKind,
302 max_payload: usize,
303) -> Result<(ProtocolVersion, T), CodecError>
304where
305 T: Deserialize<'a>,
306{
307 let decoded = decode_frame(frame, max_payload)?;
308 if decoded.kind != expected_kind {
309 return Err(CodecError::MessageKind(decoded.kind as u8));
310 }
311 if decoded.flags & FLAG_ZSTD != 0 {
312 return Err(CodecError::BorrowedCompressed);
313 }
314 Ok((decoded.protocol, postcard::from_bytes(decoded.payload)?))
315}
316
317pub fn decode<T: DeserializeOwned>(
323 frame: &[u8],
324 expected_kind: MessageKind,
325 max_payload: usize,
326) -> Result<(ProtocolVersion, T), CodecError> {
327 decode_with_limits(
328 frame,
329 expected_kind,
330 DecodeLimits {
331 max_wire_bytes: max_payload,
332 max_decompressed_bytes: max_payload,
333 },
334 )
335}
336
337pub fn decode_with_limits<T: DeserializeOwned>(
343 frame: &[u8],
344 expected_kind: MessageKind,
345 limits: DecodeLimits,
346) -> Result<(ProtocolVersion, T), CodecError> {
347 let decoded = decode_frame(frame, limits.max_wire_bytes)?;
348 if decoded.kind != expected_kind {
349 return Err(CodecError::MessageKind(decoded.kind as u8));
350 }
351 let decompressed;
352 let payload = if decoded.flags & FLAG_ZSTD != 0 {
353 decompressed = decompress_payload(decoded.payload, limits.max_decompressed_bytes)?;
354 decompressed.as_slice()
355 } else {
356 if decoded.payload.len() > limits.max_decompressed_bytes {
357 return Err(CodecError::PayloadTooLarge {
358 actual: decoded.payload.len(),
359 maximum: limits.max_decompressed_bytes,
360 });
361 }
362 decoded.payload
363 };
364 let value = postcard::from_bytes(payload)?;
365 Ok((decoded.protocol, value))
366}
367
368fn compress_payload(payload: Vec<u8>, options: EncodeOptions) -> Result<(u8, Vec<u8>), CodecError> {
369 match options.compression {
370 Compression::None => Ok((0, payload)),
371 Compression::Zstd { level: _ } if payload.len() < options.compression_threshold => {
372 Ok((0, payload))
373 }
374 #[cfg(feature = "zstd")]
375 Compression::Zstd { level } => {
376 let compressed = zstd::stream::encode_all(payload.as_slice(), level)
377 .map_err(|error| CodecError::Compression(error.to_string()))?;
378 if compressed.len() < payload.len() {
379 Ok((FLAG_ZSTD, compressed))
380 } else {
381 Ok((0, payload))
382 }
383 }
384 #[cfg(not(feature = "zstd"))]
385 Compression::Zstd { .. } => Err(CodecError::CompressionUnavailable),
386 }
387}
388
389#[cfg(feature = "zstd")]
390fn decompress_payload(payload: &[u8], maximum: usize) -> Result<Vec<u8>, CodecError> {
391 use std::io::Read;
392 let decoder = zstd::stream::read::Decoder::new(payload)
393 .map_err(|error| CodecError::Compression(error.to_string()))?;
394 let take_limit = u64::try_from(maximum).unwrap_or(u64::MAX).saturating_add(1);
395 let mut bounded = decoder.take(take_limit);
396 let mut output = Vec::new();
397 bounded
398 .read_to_end(&mut output)
399 .map_err(|error| CodecError::Compression(error.to_string()))?;
400 if output.len() > maximum {
401 return Err(CodecError::PayloadTooLarge {
402 actual: output.len(),
403 maximum,
404 });
405 }
406 Ok(output)
407}
408
409#[cfg(not(feature = "zstd"))]
410fn decompress_payload(_payload: &[u8], _maximum: usize) -> Result<Vec<u8>, CodecError> {
411 Err(CodecError::CompressionUnavailable)
412}
413
414#[cfg(feature = "ron")]
420pub fn to_ron<T: Serialize>(value: &T) -> Result<String, CodecError> {
421 ron::ser::to_string_pretty(value, ron::ser::PrettyConfig::default())
422 .map_err(|error| CodecError::Ron(error.to_string()))
423}
424
425#[cfg(feature = "json")]
432pub fn to_json<T: Serialize>(value: &T) -> Result<String, CodecError> {
433 serde_json::to_string(value).map_err(|error| CodecError::Json(error.to_string()))
434}
435
436#[cfg(feature = "json")]
442pub fn from_json<T: DeserializeOwned>(value: &str) -> Result<T, CodecError> {
443 serde_json::from_str(value).map_err(|error| CodecError::Json(error.to_string()))
444}
445
446#[cfg(test)]
447mod tests {
448 use super::*;
449 use serde::{Deserialize, Serialize};
450
451 #[derive(Debug, Deserialize, Eq, PartialEq, Serialize)]
452 struct Example {
453 value: u32,
454 }
455
456 #[derive(Debug, Deserialize, Eq, PartialEq, Serialize)]
457 struct BorrowedExample<'a> {
458 value: &'a str,
459 }
460
461 #[test]
462 fn framed_values_round_trip() -> Result<(), CodecError> {
463 let frame = encode(
464 ProtocolVersion::V1,
465 MessageKind::SyncRequest,
466 &Example { value: 42 },
467 )?;
468 let (version, decoded) = decode::<Example>(&frame, MessageKind::SyncRequest, 1_024)?;
469 assert_eq!(version, ProtocolVersion::V1);
470 assert_eq!(decoded, Example { value: 42 });
471 Ok(())
472 }
473
474 #[test]
475 fn payload_tampering_is_detected() -> Result<(), CodecError> {
476 let mut frame = encode(
477 ProtocolVersion::V1,
478 MessageKind::SyncRequest,
479 &Example { value: 1 },
480 )?;
481 let last = frame.len().saturating_sub(1);
482 frame[last] ^= 1;
483 assert!(matches!(
484 decode_frame(&frame, 1_024),
485 Err(CodecError::Integrity)
486 ));
487 Ok(())
488 }
489
490 #[test]
491 fn header_limit_rejects_declared_payload_before_body_is_present() -> Result<(), CodecError> {
492 let frame = encode_bytes(
493 ProtocolVersion::V1,
494 MessageKind::SyncRequest,
495 &Example { value: 42 },
496 )?;
497 let header = inspect_header(&frame[..HEADER_LEN], 1_024)?;
498 assert_eq!(header.kind, MessageKind::SyncRequest);
499 assert!(matches!(
500 inspect_header(&frame[..HEADER_LEN], 0),
501 Err(CodecError::PayloadTooLarge { .. })
502 ));
503 Ok(())
504 }
505
506 #[test]
507 fn borrowed_postcard_view_lives_in_the_frame_buffer() -> Result<(), CodecError> {
508 let frame = encode_bytes(
509 ProtocolVersion::V1,
510 MessageKind::SyncRequest,
511 &BorrowedExample { value: "borrowed" },
512 )?;
513 let (_, decoded) =
514 decode_borrowed::<BorrowedExample<'_>>(&frame, MessageKind::SyncRequest, 1_024)?;
515 assert_eq!(decoded.value, "borrowed");
516 Ok(())
517 }
518
519 #[cfg(feature = "zstd")]
520 #[test]
521 fn compressed_payloads_round_trip_with_a_decompressed_limit() -> Result<(), CodecError> {
522 let value = vec![42_u8; 32_768];
523 let frame = encode_with_options(
524 ProtocolVersion::V1,
525 MessageKind::SyncResponse,
526 &value,
527 EncodeOptions {
528 compression: Compression::Zstd { level: 1 },
529 compression_threshold: 1,
530 },
531 )?;
532 assert_ne!(decode_frame(&frame, 1_024)?.flags & FLAG_ZSTD, 0);
533 let (_, decoded) = decode_with_limits::<Vec<u8>>(
534 &frame,
535 MessageKind::SyncResponse,
536 DecodeLimits {
537 max_wire_bytes: 1_024,
538 max_decompressed_bytes: 64 * 1_024,
539 },
540 )?;
541 assert_eq!(decoded, value);
542 assert!(matches!(
543 decode_with_limits::<Vec<u8>>(
544 &frame,
545 MessageKind::SyncResponse,
546 DecodeLimits {
547 max_wire_bytes: 1_024,
548 max_decompressed_bytes: 1_024
549 },
550 ),
551 Err(CodecError::PayloadTooLarge { .. })
552 ));
553 Ok(())
554 }
555
556 #[cfg(feature = "json")]
557 #[test]
558 fn optional_json_round_trips_without_changing_wire_framing() -> Result<(), CodecError> {
559 let encoded = to_json(&Example { value: 42 })?;
560 assert_eq!(from_json::<Example>(&encoded)?, Example { value: 42 });
561 Ok(())
562 }
563}