Crate fracpack

Rust support for the fracpack format.

Psibase uses a new binary format, fracpack, which has the following goals:

• Quickly pack and unpack data, making it suitable for service-to-service communication, node-to-node communication, blockchain-to-outside communication, and database storage.
• Forwards and backwards compatibility; it supports adding new optional fields to the end of structs and tuples, even when they are embedded in variable-length vectors, fixed-length arrays, optional, and other structs and tuples.
• Option to read without unpacking (almost zero-copy); helps to efficiently handle large data. TODO: this library doesn’t implement this feature yet.
• Doesn’t require a code generator to support either C++ or Rust; macros and metaprogramming handle it.
• Efficient compression when combined with the compression algorithm from Cap ‘n’ Proto.

Example use

use fracpack::{Pack, Unpack, Result};

#[derive(Pack, Unpack, PartialEq, Debug)]
#[fracpack(fracpack_mod = "fracpack")]
struct Example {
    a_string: String,
    a_tuple: (u32, String),
}

let orig = Example {
    a_string: "content".into(),
    a_tuple: (1234, "5678".into()),
};

// Convert to fracpack format
let packed: Vec<u8> = orig.packed();

// Convert from fracpack format
let unpacked = Example::unpacked(&packed)?;

assert_eq!(orig, unpacked);

Note: #[fracpack(fracpack_mod = "fracpack")] is only needed when using the fracpack library directly instead of through the psibase crate.

Caution

It’s easy to accidentally convert from a fixed-size array reference (&[T;7]) to a slice (&[T]). This matters to fracpack, which has different, and incompatible, encodings for the two types.

Enums

• Error

Traits

• Pack
  Convert to fracpack format
• Unpack
  Unpack fracpack data
• UnpackOwned
  Use this trait on generic functions instead of Unpack when the deserialized data may only be owned instead of borrowed from the source.

Type Aliases

• Result

Derive Macros

• Pack
• Unpack