pamoja-codec

Serialization and framing for pamoja: pluggable wire formats behind a common Codec trait.

The same capability in every language

Pluggable serialization for pamoja payloads.

Concrete wire formats - CBOR for constrained devices, Protocol Buffers, JSON, or raw framing - implement the Codec trait. This crate defines the trait and provides serde-based implementations behind feature flags:

• CborCodec (feature cbor, on by default) - compact binary framing for constrained devices and metered links.
• JsonCodec (feature json, on by default) - human-readable framing for interop and debugging.
• BytesCodec (always available) - a no-op codec that carries raw bytes.

For metered links it also packs batches of samples into far fewer bytes: encode_deltas delta-encodes a series of integers, and Quantizer rounds f32 readings to a fixed precision and delta-encodes them.

json_to_cbor and cbor_to_json convert a whole document between the two formats without a Rust type for it, which is what a caller holding an untyped payload needs in order to reach the compact form.

Examples

A little-endian codec for u32 values:

use pamoja_codec::Codec;
use pamoja_core::{Error, Result};

struct LeU32;

impl Codec<u32> for LeU32 {
    fn encode(&self, value: &u32) -> Result<Vec<u8>> {
        Ok(value.to_le_bytes().to_vec())
    }

    fn decode(&self, bytes: &[u8]) -> Result<u32> {
        let array = bytes
            .try_into()
            .map_err(|_| Error::Codec("expected 4 bytes".into()))?;
        Ok(u32::from_le_bytes(array))
    }
}

let codec = LeU32;
let encoded = codec.encode(&42).unwrap();
assert_eq!(codec.decode(&encoded).unwrap(), 42);

trait Codec

Encodes and decodes values of type T to and from byte buffers.

A codec is the bridge between in-memory values and the bytes carried by a Transport or persisted by a Store.

fn encode(&self, value: &T) -> Result <Vec <u8>>

Encodes a value into a byte buffer.

Arguments

• value - the value to serialize.

Returns

A byte buffer containing the encoded representation of value.

Errors

Returns Error::Codec if the value cannot be encoded.

fn decode(&self, bytes: &[u8]) -> Result <T>

Decodes a value from a byte buffer.

Arguments

• bytes - the encoded representation to deserialize.

Returns

The value decoded from bytes.

Errors

Returns Error::Codec if bytes is not a valid encoding of T.

License

MIT - part of the pamoja workspace: one memory-safe Rust core with bindings for every language.