Skip to main content

Crate proto_rs

Crate proto_rs 

Source
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§

AddedField
A raw field supplied by the application without a schema declaration.
AuditRecord
Immutable evidence for one decoded or programmatically added occurrence.
CustomOptionDescriptor
Proto3 extension field that defines a custom descriptor option.
DecodeOptions
Resource and normalization policies applied while decoding wire data.
EncodeOptions
Serialization controls for schema-external, duplicate, and ordered data.
EncodeOutput
Encoded bytes accompanied by the complete audit trail used to produce them.
Enum
Runtime descriptor for a protobuf enumeration.
EnumValue
One named numeric member of a protobuf enumeration.
Error
Error returned when schema or wire data cannot be processed safely.
ExtensionDescriptor
Typed field declared outside its extended message.
FeatureSet
Inherited protobuf language features resolved for a descriptor.
Field
Runtime descriptor for one protobuf message field.
Import
Parsed protobuf import declaration.
JsonDecodeOptions
Controls acceptance of schema-unknown JSON object members.
Message
Allocation-backed dynamic protobuf message and its audit metadata.
MessageDescriptor
Runtime descriptor for one protobuf message declaration.
MethodDescriptor
One RPC method retained from a proto3 service declaration.
OneofDescriptor
One oneof declaration and its retained source options.
OptionSetting
One source-level protobuf option after lexical normalization.
Registry
An allocation-backed collection of named .proto sources.
Schema
Fully parsed and type-resolved collection of protobuf declarations.
SchemaParseOptions
Resource limits for parsing .proto sources and registry import graphs.
ServiceDescriptor
Runtime descriptor for a protobuf service declaration.
UnknownField
Schema-external wire occurrence retained during decoding.

Enums§

AuditMode
Controls retention of original field bytes in decode audit records.
AuditTag
Identifies why an occurrence exists and how decoding treated it.
BooleanValuePolicy
Controls interpretation of boolean varints other than zero and one.
Cardinality
Declared occurrence rule for a protobuf field.
DuplicateInputPolicy
Controls how duplicate singular fields and duplicate map keys are handled.
DuplicatePolicy
Controls whether displaced singular occurrences are re-emitted.
EnumType
Resolved handling of numeric values absent from an enum declaration.
EnumValuePolicy
Controls whether enum numbers absent from the descriptor are accepted.
FieldOrder
Controls the order of serialized protobuf field occurrences.
FieldPresence
Resolved singular-field presence behavior.
FieldType
Resolved protobuf field type used by the dynamic codec.
FloatEncoding
Controls normalization of floating-point bit patterns during encoding.
ImportKind
Import modifier attached to a protobuf import declaration.
JsonFormat
Resolved JSON availability for a declaration.
MapOrder
Controls serialization order for entries within each map field.
MessageEncoding
Resolved wire representation for embedded messages.
OptionValueKind
Lexical category of a protobuf option value.
RepeatedFieldEncoding
Resolved wire representation for repeated packable primitives.
Syntax
Protobuf source-language edition supported by a parsed schema.
UnknownFieldPolicy
Controls whether unknown wire occurrences are retained after decoding.
Utf8Validation
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.