Müsli is a flexible and generic binary serialization framework.
The central components of the framework are the [Encode] and [Decode] derives. They are thoroughly documented in the [derives] module.
I've chosen to internally use the term "encoding", "encode", and "decode" because it's common terminology when talking about binary formats. It's also distinct from [serde]'s use of "serialization" allowing for the ease of using both libraries side by side if desired.
Müsli is designed with 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 a handwritten encoding. The binary serialization formats provided aim to efficiently and natively support and accurately encode every type and data structure available in Rust.
As an example of this, these two functions both produce the same assembly on
my machine (built with --release):
```rust
const ENCODING: Encoding
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 withoutmusli(storage: &Storage) -> Result<[u8; 8]> { let mut array = [0; 8]; array[..4].copyfromslice(&storage.left.tonebytes()); array[4..].copyfromslice(&storage.right.tone_bytes()); Ok(array) } ```
The heavy lifting in user code is done through the [Encode] and [Decode] derives. They are both documented in the [derives] module. Müsli operates solely based on the schema derived from the types it uses.
```rust use musli::{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].
Where Müsli differs in design is that we make sparser use of the visitor pattern. Instead the encoding interacts with the framework through encoding interfaces that describe "what it wants" and leverages GATs to make the API ergonomic and efficient.
Note how decoding a sequence [does not require the use of a visitor]:
```rust use musli::de::{Decode, Decoder, SequenceDecoder}; use musli::mode::Mode;
struct MyType {
data: Vec
impl<'de, M> Decode<'de, M> for MyType where M: Mode {
fn decode
while let Some(decoder) = seq.next()? {
data.push(Decode::<M>::decode(decoder)?);
}
seq.end()?;
Ok(Self {
data
})
}
} ```
Another major aspect where Müsli differs is in the concept of
modes (note the M parameter above). Since this is a parameter of
the Encode and Decode traits it allows for the same data model to be
serialized in many different ways. This is a larger topic and is covered
further down.
Add the following to your Cargo.toml:
toml
musli = "0.0.46"
musli-wire = "0.0.46"
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 | missing | unknown | self |
|-|-|-|-|-|
| [musli-storage] #[musli(packed)] | ✗ | ✗ | ✗ | ✗ |
| [musli-storage] | ✔ | ✔ | ✗ | ✗ |
| [musli-wire] | ✔ | ✔ | ✔ | ✗ |
| [musli-descriptive] | ✔ | ✔ | ✔ | ✔ |
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
byte-oriented IPC where the data models of each client are 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.
For every feature you drop, the format becomes more compact and efficient.
musli-storage #[musli(packed)] for example is roughly as compact as
[bincode] while [musli-wire] is comparable to something like [protobuf].
The following is an example of full upgrade stability using [musli-wire]:
```rust use musli::{Encode, Decode};
struct Version1 { name: String, }
struct Version2 {
name: String,
#[musli(default)]
age: Option
let version2 = musliwire::tobuffer(&Version2 { name: String::from("Aristotle"), age: Some(62), })?;
let version1: Version1 = musliwire::decode(version2.asslice())?;
assert_eq!(version1, Version1 { name: String::from("Aristotle"), }); ```
The following is an example of partial upgrade stability using [musli-storage]:
```rust use musli::{Encode, Decode};
let version2 = muslistorage::tobuffer(&Version2 { name: String::from("Aristotle"), age: Some(62), })?;
assert!(muslistorage::decode::<_, Version1>(version2.asslice()).is_err());
let version1 = muslistorage::tobuffer(&Version1 { name: String::from("Aristotle"), })?;
let version2: Version2 = muslistorage::decode(version1.asslice())?;
assert_eq!(version2, Version2 { name: String::from("Aristotle"), age: None, }); ```
In Müsli the same model can be serialized in different ways. Instead of requiring the use of multiple models, we instead support each model implementing different modes.
A mode allows for different encoding attributes to apply depending on which mode something is performed in. A mode can apply to any musli parameter giving you a lot of flexibility.
If a mode is not specified, an implementation will apply to all modes (M:
Mode), if at least one mode is specified it will be implemented for all
modes which are present in a model and [DefaultMode]. This way, an
encoding which uses DefaultMode (which it does by default) should always
work.
```rust use musli::mode::{DefaultMode, Mode}; use musli::{Decode, Encode}; use musli_json::Encoding;
enum Alt {} impl Mode for Alt {}
struct Word<'a> { text: &'a str, teineigo: bool, }
let CONFIG: Encoding
let word = Word { text: "あります", teineigo: true, };
let out = CONFIG.tostring(&word)?; asserteq!(out, r#"{"text":"あります","teineigo":true}"#); let word2 = CONFIG.fromstr(&out[..])?; asserteq!(word, word2);
let out = ALTCONFIG.tostring(&word)?; asserteq!(out, r#"["あります",true]"#); let word2 = ALTCONFIG.fromstr(&out[..])?; asserteq!(word, word2);
```
This library currently has two instances of unsafe:
A mem::transcode in Tag::kind. Which guarantees that converting into
the Kind enum which is #[repr(u8)] is as efficient as possible. (Soon
to be replaced with an equivalent safe variant).
A largely unsafe SliceReader which provides more efficient reading than
the default Reader impl for &[u8] does (which uses split_at). Since it
can perform most of the necessary comparisons directly on the pointers.
The following are the results of preliminary benchmarking and should be taken with a big grain of 🧂.
The two benchmark suites portrayed are:
* rt-prim - which is a small object containing one of each primitive type
and a string and a byte array.
* rt-lg - which is roundtrip encoding of a large object, containing
vectors and maps of other objects.
