Module cbor

concordium_rust_sdk::common

Module cbor 

Source
Expand description

§CBOR serialization

This module implementations generic CBOR serialization based on data models defined via Rust types. Types should implement CborSerialize and CborDeserialize to define the serialization structure. The interface to implement the serialization goes through CborEncoder and CborDecoder that implements the CBOR encoding format. The module implements serialization of primitive Rust types like integers, strings and byte arrays.

§Deriving CborSerialize and CborDeserialize

§Structs

CborSerialize and CborDeserialize can be derived on structs with named fields and struct tuples:

ⓘ
#[derive(CborSerialize, CborDeserialize)]
struct TestStruct {
    field1: u64,
    field2: String,
}

#[derive(Debug, Eq, PartialEq, CborSerialize, CborDeserialize)]
struct TestTuple(u64, String);

Structs with named fields are serialized as CBOR maps using camel cased field names as keys (of data item type text) and tuples are serialized as CBOR arrays.

§Enums

CborSerialize and CborDeserialize can be derived on enums using map or tagged representation.

Using #[cbor(map)] represents the enum as a map with a single key that is the variant name camel cased (the key is a text data item).

ⓘ
#[derive(CborSerialize, CborDeserialize)]
#[cbor(map)]
enum TestEnum {
    Var1(u64),
    Var2(String),
}

Using #[cbor(tagged)] represents the enum as a tagged data item. At most one of the variants can be untagged:

ⓘ
#[derive(CborSerialize, CborDeserialize)]
#[cbor(tagged)]
enum TestEnum {
    #[cbor(tag = 39991)]
    Var1(u64),
    #[cbor(tag = 39992)]
    Var2(bool),
    Var3(String),
}

Each variant is serialized prefixed with the declared tag (except for the untagged variant).

All enum variants must be single element tuples.

§CborMaybeKnown type

In the enum examples above, the type CborMaybeKnown<TestEnum> will implement CborSerialize and CborDeserialize. Wrapping enums in the CborMaybeKnown types will deserialize known variants to CborMaybeKnown::Known and unknown variants to CborMaybeKnown::Unknown. In the case of deserializing an unknown variant in the map representation, the value in CborMaybeKnown::Unknown will be a Value::Map with a single entry. In the case of the tagged representation, the value in CborMaybeKnown::Unknown will be a Value::Tag including the tagged value. In any case, deserializing to CborMaybeKnown<TestEnum> and serializing again, will be the identity operation, no matter if the variant is known or not.

§Supported attributes

§cbor(key)

For structs with named fields, set map key explicit to positive (integer) data item:

ⓘ
#[derive(CborSerialize, CborDeserialize)]
struct TestStruct {
    #[cbor(key = 1)]
    field1: u64,
}

In this example, the field is encoded with a key that is the positive (integer) data item 1, instead of using the field name.

§cbor(tag)

Adds tag https://www.rfc-editor.org/rfc/rfc8949.html#name-tagging-of-items to encoded data item:

ⓘ
#[derive(CborSerialize, CborDeserialize)]
#[cbor(tag = 39999)]
struct TestStruct {
    field1: u64,
}

In this example the tag 39999 is prefixed the encoding of TestStruct in the CBOR.

The attribute is also needed on enum variants when using tagged representations, see example above.

§cbor(peek_tag)

For enums using tagged representation, marks the enum variant as being prefixed with this tag, without serializing/deserializing the tag:

ⓘ
#[derive(CborSerialize, CborDeserialize)]
enum TestEnum {
    #[cbor(tag = 39991)]
    Var1(u64),
    #[cbor(peek_tag = 39992)]
    Var2(TaggedStruct),
}

#[derive(CborSerialize, CborDeserialize)]
#[cbor(tag = 39992)]
struct TaggedStruct(String);

In this example, the tag 39992 is serialized as part of TaggedStruct, not as part of serializing the enum TestEnum.

§cbor(transparent)

Serializes the type as the (single) field in the struct.

ⓘ
#[derive(CborSerialize, CborDeserialize)]
struct TestStruct {
    field1: u64,
}

#[derive(CborSerialize, CborDeserialize)]
#[cbor(transparent)]
struct TestStructWrapper(TestStruct);

In this example TestStructWrapper is serialized as TestStruct.

§cbor(other)

This attribute can be applied to a variant in an enum for a field in a struct. When applied to a variant in an enum represented as a CBOR map, “unknown” map entries are deserialized to this variant.

ⓘ
#[derive(CborSerialize, CborDeserialize)]
#[cbor(map)]
enum TestEnum {
    Var1(u64),
    Var2(String),
    #[cbor(other)]
    Unknown(String, value::Value),
}

In this example, entries in the CBOR map that is not present in the enum are deserialized as Unknown. The #[cbor(other)] variant is a tuple of the map key and the map value.

When applied to a variant in an enum represented with tags, tags not declared in the enum are deserialized to this variant.

ⓘ
#[derive(CborSerialize, CborDeserialize)]
#[cbor(tagged)]
enum TestEnum {
    #[cbor(tag = 39991)]
    Var1(u64),
    #[cbor(tag = 39991)]
    Var2(String),
    #[cbor(other)]
    Unknown(u64, value::Value),
}

In this example, entries in the CBOR map that is not present in the enum are deserialized as Unknown. The #[cbor(other)] variant is a tuple of the tag and tagged data item.

When applied to a field in a struct with named fields, “unknown” map entries are deserialized into this field.

ⓘ
#[derive(CborSerialize, CborDeserialize)]
struct TestStruct {
    field1:  u64,
    #[cbor(other)]
    unknown: HashMap<MapKey, value::Value>,
}

In this example, entries in the CBOR map that are not present in the struct are each deserialized into an entry in the map in the field unknown.

Modules§

value
Dynamic data model for generic CBOR

Structs§

ArrayDecoder
Decoder of CBOR array
ArrayEncoder
CBOR array encoder
Bytes
CBOR bytes data item.
CborSerializationError
Error for serializing or deserializing CBOR
DecimalFraction
Decimal fraction consisting of exponent e and mantissa m, see https://www.rfc-editor.org/rfc/rfc8949.html#name-decimal-fractions-and-bigfl. It represents the numerical value m * 10^e.
Decoder
CBOR decoder implementation
Encoder
CBOR encoder implementation
MapDecoder
Decoder of CBOR map
MapEncoder
CBOR map encoder
SerializationOptions
Options applied when serializing and deserializing
UnsignedDecimalFraction
Unsigned decimal fraction consisting of exponent e and non-negative mantissa m, see https://www.rfc-editor.org/rfc/rfc8949.html#name-decimal-fractions-and-bigfl. It represents the numerical value m * 10^e.

Enums§

CborMaybeKnown
Represents a value deserialized from CBOR to a type that may not be able to represent all variants of data.
DataItemHeader
CBOR data item header.
DataItemType
CBOR data item type. Corresponds roughly to CBOR major types.
MapKey
Key in a CBOR map
MapKeyRef
Key in a CBOR map
UnknownMapKeys
How to handle unknown keys in decoded CBOR maps.

Traits§

CborArrayDecoder
Decoder of CBOR array
CborArrayEncoder
Encoder of CBOR array
CborDecoder
Decoder of CBOR. See https://www.rfc-editor.org/rfc/rfc8949.html#section-3
CborDeserialize
Type that can be deserialized from CBOR
CborEncoder
Encoder of CBOR. See https://www.rfc-editor.org/rfc/rfc8949.html#section-3
CborMapDecoder
Decoder of CBOR map
CborMapEncoder
Encoder of CBOR map
CborSerialize
Type that can be CBOR serialized

Functions§

cbor_decode
Decodes value from the given CBOR. If all input is not parsed, an error is returned.
cbor_decode_with_options
Decodes value from the given CBOR. If all input is not parsed, an error is returned.
cbor_encode
Encodes the given value as CBOR

Type Aliases§

CborSerializationResult
Result of serialization or deserialization