Skip to main content

aequora_codec/
lib.rs

1//! Checksummed framing and serialization codecs.
2
3use aequora_types::ProtocolVersion;
4use bytes::{Bytes, BytesMut};
5use serde::{Deserialize, Serialize, de::DeserializeOwned};
6use thiserror::Error;
7
8/// Frame flag indicating a zstd-compressed Postcard payload.
9pub const FLAG_ZSTD: u8 = 0b0000_0001;
10const KNOWN_FLAGS: u8 = FLAG_ZSTD;
11
12/// Optional payload compression selected after capability negotiation.
13#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
14pub enum Compression {
15    /// Send the serialized payload directly.
16    #[default]
17    None,
18    /// Use zstd when the payload reaches the configured threshold and compression is smaller.
19    Zstd { level: i32 },
20}
21
22/// Encoding controls for one frame.
23#[derive(Clone, Copy, Debug, Eq, PartialEq)]
24pub struct EncodeOptions {
25    /// Negotiated compression algorithm.
26    pub compression: Compression,
27    /// Do not spend CPU compressing payloads smaller than this value.
28    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/// Independent wire and decompressed limits used to prevent compression bombs.
41#[derive(Clone, Copy, Debug, Eq, PartialEq)]
42pub struct DecodeLimits {
43    /// Maximum bytes carried by the frame.
44    pub max_wire_bytes: usize,
45    /// Maximum bytes permitted after decompression.
46    pub max_decompressed_bytes: usize,
47}
48
49/// Aequora protocol magic.
50pub const MAGIC: [u8; 4] = *b"AEQ1";
51/// Fixed header size: magic, version, flags, kind, length, and BLAKE3 digest.
52pub const HEADER_LEN: usize = 44;
53
54/// Frame message discriminator.
55#[derive(Clone, Copy, Debug, Eq, PartialEq)]
56#[repr(u8)]
57pub enum MessageKind {
58    /// A synchronization request.
59    SyncRequest = 1,
60    /// A synchronization response.
61    SyncResponse = 2,
62    /// A bootstrap request.
63    BootstrapRequest = 3,
64    /// A bootstrap response.
65    BootstrapResponse = 4,
66    /// A request for a sequence of bounded bootstrap pages.
67    SnapshotStreamRequest = 5,
68    /// One page in a bounded bootstrap stream.
69    SnapshotStreamResponse = 6,
70    /// An advisory journal-advance notification.
71    PushHint = 7,
72    /// A transport-level error encoded without domain payloads.
73    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/// Decoded, integrity-checked protocol frame.
95#[derive(Clone, Copy, Debug)]
96pub struct DecodedFrame<'a> {
97    /// Protocol version from the frame header.
98    pub protocol: ProtocolVersion,
99    /// Reserved feature flags.
100    pub flags: u8,
101    /// Payload message kind.
102    pub kind: MessageKind,
103    /// Verified serialized payload.
104    pub payload: &'a [u8],
105}
106
107/// Validated fixed header. Reading this before the payload permits an oversized frame to be
108/// rejected without allocating its declared body.
109#[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/// Wire decoding or encoding failure.
118#[derive(Debug, Error)]
119pub enum CodecError {
120    /// Frame is shorter than the fixed header.
121    #[error("frame is shorter than the {HEADER_LEN}-byte header")]
122    Truncated,
123    /// Magic bytes do not identify Aequora.
124    #[error("invalid protocol magic")]
125    Magic,
126    /// Message kind is not supported.
127    #[error("unsupported message kind {0}")]
128    MessageKind(u8),
129    /// Declared payload length does not match the frame.
130    #[error("declared payload length does not match the frame")]
131    Length,
132    /// Payload exceeded the configured limit.
133    #[error("payload length {actual} exceeds limit {maximum}")]
134    PayloadTooLarge { actual: usize, maximum: usize },
135    /// Payload digest did not match.
136    #[error("payload integrity check failed")]
137    Integrity,
138    /// Frame uses flag bits unknown to this implementation.
139    #[error("frame contains unsupported flags {0:#010b}")]
140    Flags(u8),
141    /// Borrowed decoding requires the serialized bytes to remain in the caller's stable buffer.
142    #[error("borrowed decode is unavailable for compressed frames")]
143    BorrowedCompressed,
144    /// Peer requested compression that was not compiled into this crate.
145    #[error("zstd compression support is not enabled")]
146    CompressionUnavailable,
147    /// Compression or decompression failed.
148    #[error("zstd processing failed: {0}")]
149    Compression(String),
150    /// Postcard serialization failed.
151    #[error("postcard serialization failed: {0}")]
152    Postcard(#[from] postcard::Error),
153    /// RON diagnostic serialization failed.
154    #[cfg(feature = "ron")]
155    #[error("RON serialization failed: {0}")]
156    Ron(String),
157    /// Optional JSON diagnostic serialization or deserialization failed.
158    #[cfg(feature = "json")]
159    #[error("JSON serialization failed: {0}")]
160    Json(String),
161}
162
163/// Encodes a serializable value as a checksummed Postcard Aequora frame.
164///
165/// # Errors
166///
167/// Returns [`CodecError`] when Postcard serialization fails or the payload cannot fit in
168/// the frame's 32-bit length field.
169pub 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
177/// Encodes directly into immutable reference-counted bytes for transport handoff without a
178/// payload clone.
179///
180/// # Errors
181///
182/// Returns [`CodecError`] when serialization or framing fails.
183pub 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
191/// Encodes a checksummed frame with thresholded negotiated compression.
192///
193/// # Errors
194///
195/// Returns [`CodecError`] for serialization, compression, or length failures.
196pub 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
205/// Encodes a checksummed frame into a controlled [`BytesMut`] construction buffer and freezes it
206/// for immutable sharing at the transport boundary.
207///
208/// # Errors
209///
210/// Returns [`CodecError`] for serialization, compression, or length failures.
211pub 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
233/// Validates the fixed frame preamble and declared length before callers allocate or read the
234/// payload body.
235///
236/// # Errors
237///
238/// Returns [`CodecError`] for a short or malformed header, unsupported kind/flags, or a declared
239/// payload beyond `max_payload`.
240pub 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
268/// Validates and splits a frame without deserializing its payload.
269///
270/// # Errors
271///
272/// Returns [`CodecError`] for malformed headers, invalid magic or kinds, excessive sizes,
273/// inconsistent lengths, or a payload digest mismatch.
274pub 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
292/// Deserializes a borrowed typed view directly from an uncompressed stable frame buffer. The
293/// returned value cannot outlive `frame`, keeping borrowed lifetimes away from durable state.
294///
295/// # Errors
296///
297/// Returns [`CodecError`] for invalid framing, a kind mismatch, compression, size, or Postcard
298/// decoding failure.
299pub 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
317/// Decodes and deserializes a framed Postcard value of the expected kind.
318///
319/// # Errors
320///
321/// Returns [`CodecError`] when frame validation or Postcard deserialization fails.
322pub 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
337/// Decodes a frame with separate compressed-wire and decompressed payload limits.
338///
339/// # Errors
340///
341/// Returns [`CodecError`] for framing, integrity, decompression, size, or Postcard failures.
342pub 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/// Serializes a value for human-readable diagnostics and fixtures.
415///
416/// # Errors
417///
418/// Returns [`CodecError`] when the value cannot be represented as RON.
419#[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/// Serializes a value as optional human-readable JSON for debugging, administration, or web
426/// interoperability. JSON is never used by the primary synchronization transport.
427///
428/// # Errors
429///
430/// Returns [`CodecError`] when the value cannot be represented as JSON.
431#[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/// Deserializes optional diagnostic JSON into a caller-selected DTO.
437///
438/// # Errors
439///
440/// Returns [`CodecError`] when the JSON is malformed or does not match the DTO.
441#[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}