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

Download history 131/week @ 2024-07-03 8/week @ 2024-07-10 2/week @ 2024-07-24 109/week @ 2024-08-07 11/week @ 2024-08-14 1/week @ 2024-08-21 3/week @ 2024-08-28 18/week @ 2024-09-11 12/week @ 2024-09-18 117/week @ 2024-09-25 114/week @ 2024-10-02 14/week @ 2024-10-09 4/week @ 2024-10-16

252 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