Expand description
Runtime for the Protobuf decoders that rapidproto-build generates.
RapidProto only decodes. rapidproto-build generates decoders from your schema at build time, and
the generated code uses this crate. Add rapidproto to your dependencies and rapidproto-build to
your build dependencies, both pinned to the same version with =. The example module shows a
schema, the build script and the generated code.
§Arena and stream decoders
An arena decoder decodes the whole message. Msg::decode(input, &arena) returns a &Msg with an
accessor for each field. string and bytes values borrow from input, and everything else is
stored in the Arena.
use example::arena::weather::Report;
use rapidproto::Arena;
let arena = Arena::new();
let report = Report::decode(input, &arena)?;
assert_eq!(report.stations()[0].name(), "Zurich");Msg::decode_owned(input) returns an Owned, which holds the input and the arena, so you do not
have to keep them alive yourself.
A stream decoder builds no message. It passes the fields you select to your handlers and skips the
rest, so it suits reading a few fields of a large message. rapidproto-build generates arena
decoders by default, and stream decoders when you turn on Config::stream. See stream.
§Decoding rules
A decoder skips unknown fields, which the schema does not declare, and declared fields that arrive
with the wrong wire type. It does not check that strings are valid UTF-8. ProtoStr::to_str does
that when you read one.
An arena decoder fails if a required field is missing, or if a singular message or group field
appears twice, where Protobuf would merge the two. A stream decoder checks neither.
§Untrusted input
An arena decoder fails if sub-messages or groups nest deeper than MAX_DECODE_DEPTH. Its arena
can grow to many times the size of the input, so decode into your own arena and limit it with
Arena::set_capacity_limit. A stream decoder does not allocate, and it decodes a sub-message
only when your handler calls decode on it.
§Features
alloc, on by default, lets anArenagrow on the heap and addsOwned. Without it, give the arena a buffer withArena::with_buffer.serdeaddsserde::Serializeimpls. See Serde.
The crate is no_std, and without serde it has no dependencies.
§Debug output
Decoded messages implement Debug, which prints the fields that are set under their names in the
schema, such as Station { name: "Zurich", unit: Celsius, temperatures: [12.5, 13.0] }. A field
with presence appears when it is set, even at its default value. That covers optional fields,
message fields and groups, and editions fields with explicit presence. A field without presence,
such as a proto3 scalar with no optional, appears when its value is not the default. required
fields always appear. repeated and map fields appear when they are not empty, and a oneof
appears as its set member. A field a decode profile drops does not appear, and a raw field shows
its bytes.
An enum prints its classify() variant, such as Celsius, or Unknown(7) for a number the schema
does not name. bytes print as a byte string, such as b"\xff", and a string with invalid UTF-8
as ProtoStr(b"\xff"). A stream struct prints the length of its encoded message, such as
Station { len: 20 }.
§Serde
With rapidproto-build’s Config::serde and this crate’s serde feature, decoded messages
implement serde::Serialize. There is no Deserialize.
A message serializes as a map from field name to value, with the fields Debug prints. An enum
serializes as its i32, and a raw field as bytes.
bytes goes through serialize_bytes, so the format decides how it looks. serde_json writes an
array of numbers. A string with invalid UTF-8 serializes as bytes too. A map key repeated on the
wire appears more than once. A message gives the serializer no length up front, so a format that
needs one cannot serialize it.
With serde_json, a non-finite float or double becomes null, and a map fails if a string
key has invalid UTF-8.
Modules§
Structs§
- Arena
- The memory that arena decoders store messages in.
- Decode
Error - The error a decoder returns.
- MapIter
- An iterator over a
MapView’s(key, value)pairs in wire order, fromMapView::iter. - MapView
- The entries of a Protobuf
mapfield. - Owned
alloc - A decoded message together with its input and its
Arena. - Proto
Bytes - A Protobuf
bytesvalue. - Proto
Str - A Protobuf
stringvalue, which may hold invalid UTF-8.
Enums§
- Error
Kind - Why a decode failed.
Constants§
- MAX_
DECODE_ DEPTH - How deep sub-messages and groups can nest in an arena decoder.
Traits§
- Arena
Decode alloc - A message type that
Ownedcan hold.