Expand description
An allocation-backed, dynamically typed Protocol Buffers implementation.
§no_std contract
This library is unconditionally #![no_std] and only uses core and
alloc. It has no std Cargo feature and no default features. File I/O
is intentionally left to callers; imported schemas are supplied as source
strings through Registry.
Unit tests and the official conformance test adapter may use the standard
library, but proto_rs itself never does.
§Workflow
A caller first creates a Registry when imports are involved.
Every .proto source is registered under its logical import path.
Calling Registry::parse resolves the complete reachable import graph.
A single import-free source can instead be parsed with parse.
The resulting Schema owns runtime message and enum descriptors.
Callers select a MessageDescriptor by its protobuf full name.
A dynamic Message is populated with named Value instances.
encode turns that value into protobuf binary wire bytes.
decode reconstructs a dynamic value using the same descriptor.
No generated Rust source participates in this workflow.
§Registry example
use proto_rs::{Registry, Message, Value, encode};
let mut registry = Registry::new();
registry.register(
"model.proto",
r#"syntax="proto3"; package model; message Id { uint64 value = 1; }"#,
);
registry.register(
"request.proto",
r#"syntax="proto3"; package api; import "model.proto";
message Request { model.Id id = 1; }"#,
);
let schema = registry.parse("request.proto")?;
let id_descriptor = schema.message("model.Id").unwrap();
let request_descriptor = schema.message("api.Request").unwrap();
let mut id = Message::new();
id.insert("value", Value::Uint64(42));
let mut request = Message::new();
request.insert("id", Value::Message(id));
let bytes = encode(&schema, request_descriptor, &request)?;
assert!(!bytes.is_empty());
assert_eq!(id_descriptor.name, "Id");§Audit example
use proto_rs::{AuditTag, EncodeOptions, DuplicatePolicy, FieldOrder, decode,
encode_with_options, parse};
let schema = parse(r#"syntax="proto3"; message A { int32 value = 1; }"#)?;
let descriptor = schema.message("A").unwrap();
let message = decode(&schema, descriptor, &[8, 1, 8, 2, 16, 3])?;
assert!(message.audit.iter().any(|entry| {
entry.tag == AuditTag::DuplicateLastWins
}));
assert!(message.audit.iter().any(|entry| {
entry.tag == AuditTag::UnknownField
}));
let output = encode_with_options(
&schema,
descriptor,
&message,
&EncodeOptions {
forward_unknown_fields: false,
forward_unknown_messages: false,
forward_added_fields: false,
duplicates: DuplicatePolicy::LastOnly,
field_order: FieldOrder::FieldNumber,
..EncodeOptions::default()
},
)?;
assert_eq!(output.bytes, [8, 2]);§Compatibility
The binary codec supports the complete exercised proto3 conformance set.
It also supports the ordinary, non-MessageSet proto2 binary feature set.
Proto2 group and extension declarations are recognized but not decoded.
JSON, text format, JSPB, and Editions are separate unsupported formats.
The repository’s CONFORMANCE.md records the precise boundary.
Unsupported wire types return errors instead of being misinterpreted.
Unknown supported wire fields remain auditable and forwardable.
Serialization policy can prevent forwarding data absent from the schema.
§Stability
Descriptors and values are intentionally generic public data structures.
Audit metadata is excluded from semantic Message equality.
Exact encoded byte order is deterministic for a given dynamic message.
Protobuf semantic equivalence does not require a unique byte ordering.
Errors contain an owned message and the relevant byte offset.
APIs return Result and never require unwinding for malformed input.
Structs§
- Added
Field - A raw field supplied by the application without a schema declaration.
- Audit
Record - Immutable evidence for one decoded or programmatically added occurrence.
- Custom
Option Descriptor - Proto3 extension field that defines a custom descriptor option.
- Decode
Options - Resource and normalization policies applied while decoding wire data.
- Encode
Options - Serialization controls for schema-external, duplicate, and ordered data.
- Encode
Output - Encoded bytes accompanied by the complete audit trail used to produce them.
- Enum
- Runtime descriptor for a protobuf enumeration.
- Enum
Value - One named numeric member of a protobuf enumeration.
- Error
- Error returned when schema or wire data cannot be processed safely.
- Extension
Descriptor - Typed field declared outside its extended message.
- Feature
Set - Inherited protobuf language features resolved for a descriptor.
- Field
- Runtime descriptor for one protobuf message field.
- Import
- Parsed protobuf import declaration.
- Json
Decode Options - Controls acceptance of schema-unknown JSON object members.
- Message
- Allocation-backed dynamic protobuf message and its audit metadata.
- Message
Descriptor - Runtime descriptor for one protobuf message declaration.
- Method
Descriptor - One RPC method retained from a proto3 service declaration.
- Oneof
Descriptor - One oneof declaration and its retained source options.
- Option
Setting - One source-level protobuf option after lexical normalization.
- Registry
- An allocation-backed collection of named
.protosources. - Schema
- Fully parsed and type-resolved collection of protobuf declarations.
- Schema
Parse Options - Resource limits for parsing
.protosources and registry import graphs. - Service
Descriptor - Runtime descriptor for a protobuf service declaration.
- Unknown
Field - Schema-external wire occurrence retained during decoding.
Enums§
- Audit
Mode - Controls retention of original field bytes in decode audit records.
- Audit
Tag - Identifies why an occurrence exists and how decoding treated it.
- Boolean
Value Policy - Controls interpretation of boolean varints other than zero and one.
- Cardinality
- Declared occurrence rule for a protobuf field.
- Duplicate
Input Policy - Controls how duplicate singular fields and duplicate map keys are handled.
- Duplicate
Policy - Controls whether displaced singular occurrences are re-emitted.
- Enum
Type - Resolved handling of numeric values absent from an enum declaration.
- Enum
Value Policy - Controls whether enum numbers absent from the descriptor are accepted.
- Field
Order - Controls the order of serialized protobuf field occurrences.
- Field
Presence - Resolved singular-field presence behavior.
- Field
Type - Resolved protobuf field type used by the dynamic codec.
- Float
Encoding - Controls normalization of floating-point bit patterns during encoding.
- Import
Kind - Import modifier attached to a protobuf import declaration.
- Json
Format - Resolved JSON availability for a declaration.
- MapOrder
- Controls serialization order for entries within each map field.
- Message
Encoding - Resolved wire representation for embedded messages.
- Option
Value Kind - Lexical category of a protobuf option value.
- Repeated
Field Encoding - Resolved wire representation for repeated packable primitives.
- Syntax
- Protobuf source-language edition supported by a parsed schema.
- Unknown
Field Policy - Controls whether unknown wire occurrences are retained after decoding.
- Utf8
Validation - Resolved validation behavior for protobuf string fields.
- Value
- Runtime representation of any supported protobuf field value.
Functions§
- decode
- Decodes protobuf binary bytes into a descriptor-driven dynamic message.
- decode_
json - Decodes protobuf JSON using strict unknown-field handling.
- decode_
json_ with_ options - Decodes protobuf JSON with explicit unknown-field behavior.
- decode_
with_ options - Decodes wire bytes while applying explicit resource and sanitization rules.
- encode
- Serializes a dynamic message using the default forwarding policy.
- encode_
json - Encodes a dynamic message using the canonical protobuf JSON mapping.
- encode_
with_ options - Serializes a message while applying explicit forwarding policies.
- parse
- Parses and resolves one self-contained schema.
- parse_
with_ options - Parses and resolves one source under explicit resource limits.
Type Aliases§
- Result
- Result type returned by schema parsing and protobuf codec operations.