#protobuf #serialization #json

prost-reflect

A protobuf library extending prost with reflection support and dynamic messages

28 releases (9 breaking)

0.10.1 Jan 7, 2023
0.9.2 Aug 14, 2022
0.9.0 Jul 30, 2022
0.6.1 Feb 27, 2022
0.3.3 Dec 30, 2021

#60 in Encoding

Download history 9827/week @ 2022-10-18 8132/week @ 2022-10-25 11735/week @ 2022-11-01 12507/week @ 2022-11-08 14756/week @ 2022-11-15 12914/week @ 2022-11-22 11118/week @ 2022-11-29 10787/week @ 2022-12-06 11881/week @ 2022-12-13 9862/week @ 2022-12-20 6071/week @ 2022-12-27 10546/week @ 2023-01-03 12738/week @ 2023-01-10 11826/week @ 2023-01-17 14353/week @ 2023-01-24 16015/week @ 2023-01-31

57,068 downloads per month
Used in 2 crates

MIT/Apache

490KB
11K SLoC

crates.io docs.rs deps.rs MSRV Continuous integration codecov.io Apache 2.0 OR MIT licensed

prost-reflect

A protobuf library extending prost with reflection support and dynamic messages.

Usage

This crate provides support for dynamic protobuf messages. These are useful when the protobuf type definition is not known ahead of time.

The main entry points into the API of this crate are:

Example - decoding

DynamicMessage does not implement Default since it needs a message descriptor to function. To decode a protobuf byte stream into an instance of this type, use DynamicMessage::decode to create a default value for the MessageDescriptor instance and merge into it:

use prost::Message;
use prost_types::FileDescriptorSet;
use prost_reflect::{DynamicMessage, DescriptorPool, Value};

let pool = DescriptorPool::decode(include_bytes!("file_descriptor_set.bin").as_ref()).unwrap();
let message_descriptor = pool.get_message_by_name("package.MyMessage").unwrap();

let dynamic_message = DynamicMessage::decode(message_descriptor, b"\x08\x96\x01".as_ref()).unwrap();

assert_eq!(dynamic_message.get_field_by_name("foo").unwrap().as_ref(), &Value::I32(150));

Example - JSON mapping

When the serde feature is enabled, DynamicMessage can be deserialized to and from the canonical JSON mapping defined for protobuf messages.

use prost::Message;
use prost_reflect::{DynamicMessage, DescriptorPool, Value};
use serde_json::de::Deserializer;

let pool = DescriptorPool::decode(include_bytes!("file_descriptor_set.bin").as_ref()).unwrap();
let message_descriptor = pool.get_message_by_name("package.MyMessage").unwrap();

let json = r#"{ "foo": 150 }"#;
let mut deserializer = Deserializer::from_str(json);
let dynamic_message = DynamicMessage::deserialize(message_descriptor, &mut deserializer).unwrap();
deserializer.end().unwrap();

assert_eq!(dynamic_message.get_field_by_name("foo").unwrap().as_ref(), &Value::I32(150));

Example - implementing ReflectMessage

The ReflectMessage trait provides a .descriptor() method to get type information for a message. By default it is just implemented for DynamicMessage.

The ReflectMessage trait provides a .descriptor() method to get type information for a message. It is implemented for DynamicMessage and the well-known-types provided by prost-types.

When the derive feature is enabled, it can be derived for Message implementations. The derive macro takes the following parameters:

Name Value
descriptor_pool An expression that resolves to a DescriptorPool containing the message type. The descriptor should be cached to avoid re-building it.
message_name The full name of the message, used to look it up within DescriptorPool.
use prost::Message;
use prost_reflect::{DescriptorPool, ReflectMessage};
use once_cell::sync::Lazy;

static DESCRIPTOR_POOL: Lazy<DescriptorPool>
    = Lazy::new(|| DescriptorPool::decode(include_bytes!("file_descriptor_set.bin").as_ref()).unwrap());

#[derive(Message, ReflectMessage)]
#[prost_reflect(descriptor_pool = "DESCRIPTOR_POOL", message_name = "package.MyMessage")]
pub struct MyMessage {}

let message = MyMessage {};
assert_eq!(message.descriptor().full_name(), "package.MyMessage");

If you are using prost-build, the prost-reflect-build crate provides helpers to generate ReflectMessage implementations:

prost_reflect_build::Builder::new()
    .compile_protos(&["src/package.proto"], &["src"])
    .unwrap();

Minimum Supported Rust Version

Rust 1.60 or higher.

The minimum supported Rust version may be changed in the future, but it will be done with a minor version bump.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~1–1.8MB
~35K SLoC