Crate protobuf

Library to read and write protocol buffers data

Version 2 is stable

Currently developed branch of rust-protobuf is 3. It has the same spirit as version 2, but contains numerous improvements like:

• runtime reflection for mutability, not just for access
• protobuf text format and JSON parsing (which rely on reflection)
• dynamic message support: work with protobuf data without generating code from schema

Stable version of rust-protobuf will be supported until version 3 released.

Tracking issue for version 3.

How to generate rust code

There are several ways to generate rust code from .proto files

Invoke protoc programmatically with protoc-rust crate (recommended)

Have a look at readme in protoc-rust crate.

Use pure rust protobuf parser and code generator

Readme should be in protobuf-codegen-pure crate.

Use protoc-gen-rust plugin

Readme is here.

Generated code

Have a look at generated files (for current development version), used internally in rust-protobuf:

• descriptor.rs for descriptor.proto (that is part of Google protobuf)

Copy on write

Rust-protobuf can be used with bytes crate.

To enable Bytes you need to:

1. Enable with-bytes feature in rust-protobuf:

[dependencies]
protobuf = { version = "~2.0", features = ["with-bytes"] }

2. Enable bytes option

with Customize when codegen is invoked programmatically:

protoc_rust::run(protoc_rust::Args {
    ...
    customize: Customize {
        carllerche_bytes_for_bytes: Some(true),
        carllerche_bytes_for_string: Some(true),
        ..Default::default()
    },
});

or in .proto file:

import "rustproto.proto";

option (rustproto.carllerche_bytes_for_bytes_all) = true;
option (rustproto.carllerche_bytes_for_string_all) = true;

With these options enabled, fields of type bytes or string are generated as Bytes or Chars respectively. When CodedInputStream is constructed from Bytes object, fields of these types get subslices of original Bytes object, instead of being allocated on heap.

Accompanying crates

• protoc-rust and protobuf-codegen-pure can be used to rust code from .proto crates.
• protobuf-codegen for protoc-gen-rust protoc plugin.
• protoc crate can be used to invoke protoc programmatically.
• protoc-bin-vendored contains protoc command packed into the crate.

Re-exports

• pub use crate::error::ProtobufError;
• pub use crate::error::ProtobufResult;

Modules

• descriptor
  Generated file from google/protobuf/descriptor.proto
• error
  Protobuf error type
• ext
  Utilities to support “extension” fields.
• json
  JSON serialization and deserialization.
• lazy
  Lazily initialized data. Used in generated code.
• plugin
  Generated file from google/protobuf/compiler/plugin.proto
• reflect
  Reflection implementation for protobuf types.
• rt
  Functions used by generated protobuf code. Should not be used by programs written by hands.
• rustproto
  Generated file from rustproto.proto
• text_format
  Protobuf “text format” implementation.
• types
  Implementations of ProtobufType for all types.
• well_known_types
  Generated code for “well known types”
• wire_format
  Serialization constants.

Structs

• CachedSize
  Cached size field used in generated code. It is always equal to itself to simplify generated code. (Generated code can use #[derive(Eq)]).
• CodedInputStream
  Buffered read with handy utilities.
• CodedOutputStream
  Buffered write with handy utilities
• RepeatedField
  Wrapper around vector to avoid deallocations on clear.
• SingularField
  Like Option<T>, but keeps the actual element on clear.
• SingularPtrField
  Like Option<Box<T>>, but keeps the actual element on clear.
• UnknownFields
  Hold “unknown” fields in parsed message.
• UnknownFieldsIter
  Iterator over UnknownFields
• UnknownValues
  Field unknown values.
• UnknownValuesIter
  Iterator over unknown values

Enums

• UnknownValue
  Unknown value.
• UnknownValueRef
  Reference to unknown value.

Constants

• VERSION
  protobuf crate version
• VERSION_2_27_1
  This symbol can be referenced to assert that proper version of crate is used

Traits

• Clear
  anything that can be cleared
• Message
  Trait implemented for all generated structs for protobuf messages.
• ProtobufEnum
  Trait implemented by all protobuf enum types.

Functions

• parse_from_bytesDeprecated
  Parse message from byte array.
• parse_from_readerDeprecated
  Parse message from reader. Parse stops on EOF or when error encountered.
• parse_length_delimited_fromDeprecated
  Parse length-delimited message from stream.
• parse_length_delimited_from_bytesDeprecated
  Parse length-delimited message from bytes.
• parse_length_delimited_from_readerDeprecated
  Parse length-delimited message from Read.