Crate prost_reflect
source ·Expand description
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:
DescriptorPool
wraps aFileDescriptorSet
output by the protobuf compiler to provide an API for inspecting type definitions.DynamicMessage
provides encoding, decoding and reflection of an arbitrary protobuf message definition described by aMessageDescriptor
.
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));
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();
Re-exports
Modules
text-format
Structs
DescriptorPool
.DescriptorPool
is a collection of related descriptors. Typically it will be created from
a FileDescriptorSet
output by the protobuf compiler
(see DescriptorPool::from_file_descriptor_set
) but it may also be built up by adding files individually.serde
DynamicMessage
provides encoding, decoding and reflection of a protobuf message.ServiceDescriptor
.serde
Enums
DynamicMessage::try_set_field()
.Traits
Derive Macros
derive
ReflectMessage
trait.