18 releases (10 breaking)

0.13.0 Oct 1, 2024
0.11.0 Jul 6, 2024
0.6.0 Mar 4, 2024
0.2.0 Dec 12, 2023
0.1.7 Nov 11, 2022

#8 in #pack-unpack

21 downloads per month
Used in 2 crates (via psibase)

MIT license

59KB
1.5K SLoC

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.

Dependencies

~3MB
~67K SLoC