musli

Excellent performance, no compromises[^1]!

Müsli is a flexible, fast, and generic binary serialization framework for Rust, in the same vein as serde.

It provides a set of formats, each with its own well-documented set of features and tradeoffs. Every byte-oriented serialization method including escaped formats like musli::json has full #[no_std] support with or without alloc. And a particularly neat component providing low-level refreshingly simple zero-copy serialization.

[^1]: As in Müsli should be able to do everything you need and more.

Overview

• See derives to learn how to implement Encode and Decode.
• See data_model to learn about the abstract data model of Müsli.
• See benchmarks and size comparisons to learn about the performance of this framework.
• See tests to learn how this library is tested.
• See musli::serde for seamless compatibility with serde. You might also be interested to learn how Müsli is different.

Usage

Add the following to your Cargo.toml using the format you want to use:

[dependencies]
musli = { version = "0.0.125", features = ["storage"] }

Design

The heavy lifting is done by the Encode and Decode derives which are documented in the derives module.

Müsli operates based on the schema represented by the types which implement these traits.

use musli::{Encode, Decode};

#[derive(Encode, Decode)]
struct Person {
    /* .. fields .. */
}

Note by default a field is identified by its numerical index which would change if they are re-ordered. Renaming fields and setting a default naming policy can be done by configuring the derives.

The binary serialization formats provided aim to efficiently and accurately encode every type and data structure available in Rust. Each format comes with well-documented tradeoffs and aims to be fully memory safe to use.

Internally we use the terms "encoding", "encode", and "decode" because it's distinct from serde's use of "serialization", "serialize", and "deserialize" allowing for the clearer interoperability between the two libraries. Encoding and decoding also has more of a "binary serialization" vibe, which more closely reflects the focus of this framework.

Müsli is designed on similar principles as serde. Relying on Rust's powerful trait system to generate code which can largely be optimized away. The end result should be very similar to handwritten, highly optimized code.

As an example of this, these two functions both produce the same assembly (built with --release):

const OPTIONS: Options = options::new()
    .with_integer(Integer::Fixed)
    .with_byte_order(ByteOrder::NATIVE)
    .build();

const ENCODING: Encoding<OPTIONS> = Encoding::new().with_options();

#[derive(Encode, Decode)]
#[musli(packed)]
pub struct Storage {
    left: u32,
    right: u32,
}

fn with_musli(storage: &Storage) -> Result<[u8; 8]> {
    let mut array = [0; 8];
    ENCODING.encode(&mut array[..], storage)?;
    Ok(array)
}

fn without_musli(storage: &Storage) -> Result<[u8; 8]> {
    let mut array = [0; 8];
    array[..4].copy_from_slice(&storage.left.to_ne_bytes());
    array[4..].copy_from_slice(&storage.right.to_ne_bytes());
    Ok(array)
}

Müsli is different from serde

Müsli's data model does not speak Rust. There are no serialize_struct_variant methods which provides metadata about the type being serialized. The Encoder and Decoder traits are agnostic on this. Compatibility with Rust types is entirely handled using the Encode and Decode derives in combination with modes.

We use GATs to provide easier to use abstractions. GATs were not available when serde was designed.

Everything is a Decoder or Encoder. Field names are therefore not limited to be strings or indexes, but can be named to arbitrary types if needed.

Visitor are only used when needed. serde completely uses visitors when deserializing and the corresponding method is treated as a "hint" to the underlying format. The deserializer is then free to call any method on the visitor depending on what the underlying format actually contains. In Müsli, we swap this around. If the caller wants to decode an arbitrary type it calls decode_any. The format can then either signal the appropriate underlying type or call Visitor::visit_unknown telling the implementer that it does not have access to type information.

We've invented moded encoding allowing the same Rust types to be encoded in many different ways with much greater control over how things encoded. By default we include the Binary and Text modes providing sensible defaults for binary and text-based formats.

Müsli fully supports no-std and no-alloc from the ground up without compromising on features using safe and efficient scoped allocations.

We support detailed tracing when decoding for much improved diagnostics of where something went wrong.

Formats

Formats are currently distinguished by supporting various degrees of upgrade stability. A fully upgrade stable encoding format must tolerate that one model can add fields that an older version of the model should be capable of ignoring.

Partial upgrade stability can still be useful as is the case of the musli::storage format below, because reading from storage only requires decoding to be upgrade stable. So if correctly managed with #[musli(default)] this will never result in any readers seeing unknown fields.

The available formats and their capabilities are:

reorder determines whether fields must occur in exactly the order in which they are specified in their type. Reordering fields in such a type would cause unknown but safe behavior of some kind. This is only suitable for communication where the data models of each client are strictly synchronized.

missing determines if reading can handle missing fields through something like Option<T>. This is suitable for on-disk storage, because it means that new optional fields can be added as the schema evolves.

unknown determines if the format can skip over unknown fields. This is suitable for network communication. At this point you've reached upgrade stability. Some level of introspection is possible here, because the serialized format must contain enough information about fields to know what to skip which usually allows for reasoning about basic types.

self determines if the format is self-descriptive. Allowing the structure of the data to be fully reconstructed from its serialized state. These formats do not require models to decode and can be converted to and from dynamic containers such as musli::value for introspection. Such formats also allows for type-coercions to be performed, so that a signed number can be correctly read as an unsigned number if it fits in the destination type.

For every feature you drop, the format becomes more compact and efficient. musli::storage using #[musli(packed)] for example is roughly as compact as bincode while musli::wire is comparable in size to something like protobuf. All formats are primarily byte-oriented, but some might perform bit packing if the benefits are obvious.

[^json]: This is strictly not a binary serialization, but it was implemented as a litmus test to ensure that Müsli has the necessary framework features to support it. Luckily, the implementation is also quite good!

Upgrade stability

The following is an example of full upgrade stability using musli::wire. Version1 can be decoded from an instance of Version2 because it understands how to skip fields which are part of Version2. We're also explicitly adding #[musli(name = ..)] to the fields to ensure that they don't change in case they are re-ordered.

use musli::{Encode, Decode};

#[derive(Debug, PartialEq, Encode, Decode)]
struct Version1 {
    #[musli(mode = Binary, name = 0)]
    name: String,
}

#[derive(Debug, PartialEq, Encode, Decode)]
struct Version2 {
    #[musli(mode = Binary, name = 0)]
    name: String,
    #[musli(mode = Binary, name = 1)]
    #[musli(default)]
    age: Option<u32>,
}

let version2 = musli::wire::to_vec(&Version2 {
    name: String::from("Aristotle"),
    age: Some(61),
})?;

let version1: Version1 = musli::wire::decode(version2.as_slice())?;

The following is an example of partial upgrade stability using musli::storage on the same data models. Note how Version2 can be decoded from Version1 but not the other way around making it suitable for on-disk storage where the schema can evolve from older to newer versions.

let version2 = musli::storage::to_vec(&Version2 {
    name: String::from("Aristotle"),
    age: Some(61),
})?;

assert!(musli::storage::decode::<_, Version1>(version2.as_slice()).is_err());

let version1 = musli::storage::to_vec(&Version1 {
    name: String::from("Aristotle"),
})?;

let version2: Version2 = musli::storage::decode(version1.as_slice())?;

Modes

In Müsli in contrast to serde the same model can be serialized in different ways. Instead of requiring the use of distinct models we support implementing different modes for a single model.

A mode is a type parameter, which allows for different attributes to apply depending on which mode an encoder is configured to use. A mode can apply to any musli attributes giving you a lot of flexibility.

If a mode is not specified, an implementation will apply to all modes (M), if at least one mode is specified it will be implemented for all modes which are present in a model and Binary. This way, an encoding which uses Binary which is the default mode should always work.

For more information on how to configure modes, see derives.

Below is a simple example of how we can use two modes to provide two completely different formats using a single struct:

use musli::{Decode, Encode};
use musli::json::Encoding;

enum Alt {}

#[derive(Decode, Encode)]
#[musli(mode = Alt, packed)]
#[musli(name_all = "name")]
struct Word<'a> {
    text: &'a str,
    teineigo: bool,
}

const CONFIG: Encoding = Encoding::new();
const ALT_CONFIG: Encoding<Alt> = Encoding::new().with_mode();

let word = Word {
    text: "あります",
    teineigo: true,
};

let out = CONFIG.to_string(&word)?;
assert_eq!(out, r#"{"text":"あります","teineigo":true}"#);

let out = ALT_CONFIG.to_string(&word)?;
assert_eq!(out, r#"["あります",true]"#);

Going very fast

With the previous sections it should be apparent that speed is primarily a game of tradeoffs. If we make every tradeoff in favor of speed Müsli is designed to be the fastest framework out there.

The tradeoffs we will be showcasing to achieve speed here are:

• Pre-allocate serialization space. This avoids all allocations during serialization. The tradeoff is that if the data we are serializing contains dynamically sized information which goes beyond the pre-allocated space, we will error.
• Use fixed-sized integers and floats. We use more space, but the cost of serializing numerical fields essentially boils down to copying them.
• Use a native byte order. With this we avoid any byte-swapping operations. But our data becomes less portable.
• Use a packed format. This doesn't allow for any upgrades, but we avoid paying the overhead of serializing field identifiers.
• Use the Slice allocator. This avoids all heap allocations using the system allocator. While the system allocator is quite efficient and normally shouldn't be avoided, the slice allocator is a fixed-slab allocator. The tradeoff here is that we will error in case we run out of memory, but we only need to use the allocator if the types being serialized (or the format) demands it.
• Disable error handling. Code generation will be able to remove everything related to error handling, like allocations. To do this we can make use of the Ignore context. If an error happens, we are only informed of that fact through a zero-sized marker type.

We achieve this through the following methods:

use musli::context::{ErrorMarker as Error, Ignore};
use musli::options::{self, Float, Integer, Options};
use musli::storage::Encoding;
use musli::{Decode, Encode};
use musli::alloc::Slice;

enum Packed {}

const OPTIONS: Options = options::new()
    .with_length(Integer::Fixed)
    .with_integer(Integer::Fixed)
    .with_float(Float::Fixed)
    .build();

const ENCODING: Encoding<OPTIONS, Packed> = Encoding::new().with_options().with_mode();

#[inline]
pub fn encode<'buf, T>(buf: &'buf mut [u8], value: &T, alloc: &Slice<'_>) -> Result<&'buf [u8], Error>
where
    T: Encode<Packed>,
{
    let cx = Ignore::with_alloc(alloc);
    let w = ENCODING.to_slice_with(&cx, &mut buf[..], value)?;
    Ok(&buf[..w])
}

#[inline]
pub fn decode<'buf, T>(buf: &'buf [u8], alloc: &Slice<'_>) -> Result<T, Error>
where
    T: Decode<'buf, Packed>,
{
    let cx = Ignore::with_alloc(alloc);
    ENCODING.from_slice_with(&cx, buf)
}

We also need some cooperation from the types being serialized since they need to use the Packed mode we defined just above:

use musli::{Encode, Decode};

#[derive(Encode, Decode)]
#[musli(mode = Packed, packed)]
struct Person {
    name: String,
    age: u32,
}

Using the framework above also needs a bit of prep, namely the slice allocator need to be initialized:

use musli::alloc::{ArrayBuffer, Slice};

let mut buf = ArrayBuffer::new();
let alloc = Slice::new(&mut buf);

That's it! You are now using Müsli in the fastest possible mode. Feel free to use it to "beat" any benchmarks. In fact, the musli_storage_packed mode in our internal benchmarks beat pretty much every framework with these methods.

My hope is that this should illustrate why you shouldn't blindly trust benchmarks. Sometimes code is not fully optimized, but most of the time there is a tradeoff. If a benchmark doesn't tell you what tradeoffs are being made, don't just naively trust a number.

Unsafety

This is a non-exhaustive list of unsafe use in this crate, and why they are used:

• A mem::transmute in Tag::kind. Which guarantees that converting into the Kind enum which is #[repr(u8)] is as efficient as possible.

• A largely unsafe SliceReader which provides more efficient reading than the default Reader impl for &[u8] does. Since it can perform most of the necessary comparisons directly on the pointers.

• Some unsafety related to UTF-8 handling in musli::json, because we check UTF-8 validity internally ourselves (like serde_json).

• FixedBytes<N>, which is a stack-based container that can operate over uninitialized data. Its implementation is largely unsafe. With it stack-based serialization can be performed which is useful in no-std environments.

• Some unsafe is used for owned String decoding in all binary formats to support faster string processing through simdutf8. Disabling the simdutf8 feature (enabled by default) removes the use of this unsafe.

To ensure this library is correctly implemented with regards to memory safety, extensive testing and fuzzing is performed using miri. See tests for more information.