Module framed::typed

Sending and receiving serde-serialized structs.

Currently structs are serialized with ssmarshal, but this is an implementation detail that may change without warning. ssmarshal uses a straightforward, compact serialization format that doesn't support compatibility between versions or dynamic length types (arrays, maps). Its lack of versioning fits with the design goals for the frame encoding in this crate: unsuitable for long-term storage or transmission between different versions of an application, but space-efficient.

Example usage from a std crate

The Sender struct writes serialized and encoded values to an inner std::io::Write instance, and the Receiver struct reads and decodes values from an inner std::io::Read instance.

    #[derive(Debug, Deserialize, Eq, PartialEq, Serialize)]
    struct Test {
        a: u8,
        b: u16,
    }

    let payload = Test { a: 1, b: 2 };
    let mut config = framed::bytes::Config::default().typed::<Test>();

    let mut encoded = vec![];
    {
        let mut sender = config.clone().to_sender(&mut encoded);
        sender.send(&payload).expect("send ok");
    }

    // `encoded` now contains the encoded value.

    let mut receiver = config.clone().to_receiver(Cursor::new(encoded));
    let decoded = receiver.recv().expect("recv ok");

    assert_eq!(payload, decoded);

Example usage from a no_std crate

The encode_to_slice and decode_from_slice functions offer an API for no_std crates that do not have a heap allocator and cannot use std::io::Read or std::io::Write.

    let mut codec = config.to_codec();
    let mut ser_buf = [0u8; max_serialize_buf_len::<Test>()];
    let mut encoded_buf = [0u8; max_encoded_len::<Test>()];
    let encoded_len = codec.encode_to_slice(
        &payload,
        &mut ser_buf,
        &mut encoded_buf
    ).expect("encode ok");
    let encoded = &encoded_buf[0..encoded_len];

    // `encoded` now contains the complete encoded frame.

    let mut de_buf = [0u8; max_serialize_buf_len::<Test>()];
    let decoded = codec.decode_from_slice(encoded, &mut de_buf)
                       .expect("decode ok");

    assert_eq!(payload, decoded);

Structs

Codec	Contains methods for encoding and decoding a serializable type T with a specific configuration.
Config	Configurable options for encoding and decoding a serializable type T using a builder pattern.
Receiver	Receives encoded structs of type T from an inner std::io::Read instance.
Sender	Sends encoded structs of type T over an inner std::io::Write instance.

Functions

max_encoded_len	Returns an upper bound for the encoded length of a frame with a serialized T value as its payload.
max_serialize_buf_len	Returns an upper bound for the temporary serialization buffer length needed by encode_to_slice and decode_from_slice when serializing or deserializing a value of type T.