Skip to content

Latest commit

 

History

History
64 lines (46 loc) · 2.41 KB

README.md

File metadata and controls

64 lines (46 loc) · 2.41 KB

High-level Protobuf conversion library for Exonum

Travis Build Status License: Apache-2.0 rust 1.45.0+ required

exonum-proto provides a high-level interface for interacting with code generated by protoc-rust crate.

The central part of this crate is ProtobufConvert trait.

The main purpose of this trait is to allow users to create a map between their types and the types generated from .proto descriptions, while providing a mechanism for additional validation of Protobuf data.

Most of the time you do not have to implement this trait because most of the use cases are covered by #[derive(ProtobufConvert)] from the exonum-derive crate.

A typical example of such mapping with validation is manual implementation of this trait for exonum_crypto::Hash. exonum_crypto::Hash is a fixed sized array of bytes but Protobuf does not allow us to express this constraint since only dynamically sized arrays are supported.

If you would like to use Hash as a part of your Protobuf struct, you would have to write a conversion function from Protobuf proto::Hash(which is dynamically sized array of bytes) toexonum_crypto::Hash and call it every time when you want to use exonum_crypto::Hash in your application.

The provided ProtobufConvert implementation for Hash allows you to embed this field into your struct and generate ProtobufConvert for it using #[derive(ProtobufConvert)], which will validate your structure based on the validation function for Hash.

Consult the crate docs for more details.

Examples

Sample Protobuf roundtrip:

use exonum_proto::ProtobufConvert;
use bit_vec::BitVec;

let bit_vector = BitVec::from_bytes(&[0b_1010_0000, 0b_0001_0010]);
let bit_vector_pb = bit_vector.to_pb();
let deserialized_bit_vector: BitVec = ProtobufConvert::from_pb(pb_bv).unwrap();
assert_eq!(bit_vector, deserialized_bit_vector);

Usage

Include exonum-proto as a dependency in your Cargo.toml:

[dependencies]
exonum-proto = "1.0.0"

License

exonum-proto is licensed under the Apache License (Version 2.0). See LICENSE for details.