Enum Format 

#[non_exhaustive]
pub enum Format {
    Packed,
    Storage,
    Wire,
    Descriptive,
    Json,
}

Available on crate feature api only.

The serialization format used for message bodies.

The format is negotiated per connection, see the [negotiation protocol] for the details of how. Message headers are never affected by this and always use a fixed envelope, which is what makes negotiation possible in the first place.

The variants are ordered from least to most capable. Each capability that is dropped makes the encoding more compact:

	reorder	missing	unknown	self
Packed	✗	✗	✗	✗
Storage	✔	✔	✗	✗
Wire	✔	✔	✔	✗
Descriptive	✔	✔	✔	✔
Json	✔	✔	✔	✔

• reorder determines whether fields may be reordered in the model.
• missing determines whether decoding tolerates missing fields, which is what allows new optional fields to be added.
• unknown determines whether decoding can skip fields it does not know about. A format which can do this is fully upgrade safe, since an old peer can talk to a new one.
• self determines whether the format is self-descriptive, so that the data can be decoded without the model.

Examples

use musli_web::api::Format;

assert_eq!(Format::default(), Format::Wire);
assert!(Format::Wire.is_upgrade_safe());
assert!(!Format::Storage.is_upgrade_safe());
assert!(Format::Json.is_human_readable());

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Packed

The musli::packed format.

The most compact format, but it requires that both peers use exactly the same model. Suitable when client and server are deployed together.

Storage

The musli::storage format.

Tolerates missing fields, but cannot skip fields it does not know about.

Wire

The musli::wire format.

Fully upgrade safe, so peers built against different versions of the model can talk to each other. This is the default.

Descriptive

The musli::descriptive format.

Fully upgrade safe and self-descriptive, at the cost of a larger payload.

Json

The musli::json format.

Human readable, which is useful when the traffic has to be inspected by hand. Encoded using the Text mode so that fields are keyed by name.

Implementations

impl Format

pub const DEFAULT: Self = Self::Wire

The default format, which is Format::Wire.

This is used by a client which has not picked a format, and by a server for a connection which has not negotiated one.

Examples

use musli_web::api::Format;

assert_eq!(Format::DEFAULT, Format::Wire);

pub const ALL: &'static [Format]

Every format in order of increasing capability.

Note that this includes formats which the crate might not have been built with support for, see Format::is_supported.

Examples

use musli_web::api::Format;

assert!(Format::ALL.contains(&Format::Json));

pub const fn to_u8(self) -> u8

Get the stable identifier used for this format on the wire.

Zero is never used, so it is available to indicate an absent format.

Examples

use musli_web::api::Format;

assert_eq!(Format::Wire.to_u8(), 3);
assert_eq!(Format::from_u8(3), Some(Format::Wire));

pub const fn from_u8(id: u8) -> Option<Self>

Construct a format from the stable identifier used on the wire.

Returns None if the identifier is not known, which is how a peer built against an older version of this crate reports a format it has never heard of.

Examples

use musli_web::api::Format;

assert_eq!(Format::from_u8(1), Some(Format::Packed));
assert_eq!(Format::from_u8(0), None);
assert_eq!(Format::from_u8(200), None);

pub const fn name(self) -> &'static str

The name of the format.

Examples

use musli_web::api::Format;

assert_eq!(Format::Wire.name(), "wire");

pub const fn is_upgrade_safe(self) -> bool

Test if the format can skip over unknown fields, making it fully upgrade safe.

Examples

use musli_web::api::Format;

assert!(Format::Wire.is_upgrade_safe());
assert!(!Format::Packed.is_upgrade_safe());

pub const fn is_self_descriptive(self) -> bool

Test if the format is self-descriptive, so that data can be decoded without access to the model.

Examples

use musli_web::api::Format;

assert!(Format::Descriptive.is_self_descriptive());
assert!(!Format::Wire.is_self_descriptive());

pub const fn is_human_readable(self) -> bool

Test if the format produces output which is meant to be read by humans.

Examples

use musli_web::api::Format;

assert!(Format::Json.is_human_readable());
assert!(!Format::Wire.is_human_readable());

impl Format

pub const fn is_supported(self) -> bool

Test if this build of the crate has support for the format.

Formats are gated behind features, so a peer might genuinely be unable to speak a format which the other side asks for. This is what the negotiation protocol uses to decide whether a request can be honored.

Examples

use musli_web::api::Format;

// The default format is always available.
assert!(Format::DEFAULT.is_supported());

pub fn supported() -> impl Iterator<Item = Format>

Iterate over every format this build of the crate supports.

Examples

use musli_web::api::Format;

assert!(Format::supported().any(|f| f == Format::DEFAULT));

Trait Implementations

impl Clone for Format

fn clone(&self) -> Format

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Format

impl Debug for Format

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Format

fn default() -> Self

Construct the default format, which is Format::DEFAULT.

Examples

use musli_web::api::Format;

assert_eq!(Format::default(), Format::Wire);

impl Display for Format

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Format

impl Hash for Format

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Format

fn cmp(&self, other: &Format) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Format

fn eq(&self, other: &Format) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Format

fn partial_cmp(&self, other: &Format) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for Format