Skip to main content

Crate rapidproto

Crate rapidproto 

Source
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 an Arena grow on the heap and adds Owned. Without it, give the arena a buffer with Arena::with_buffer.
  • serde adds serde::Serialize impls. 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§

example
The code rapidproto-build generates for an example schema.
stream
Types for stream decoders.

Structs§

Arena
The memory that arena decoders store messages in.
DecodeError
The error a decoder returns.
MapIter
An iterator over a MapView’s (key, value) pairs in wire order, from MapView::iter.
MapView
The entries of a Protobuf map field.
Ownedalloc
A decoded message together with its input and its Arena.
ProtoBytes
A Protobuf bytes value.
ProtoStr
A Protobuf string value, which may hold invalid UTF-8.

Enums§

ErrorKind
Why a decode failed.

Constants§

MAX_DECODE_DEPTH
How deep sub-messages and groups can nest in an arena decoder.

Traits§

ArenaDecodealloc
A message type that Owned can hold.