Crate protobuf_core

Crate protobuf_core 

Source
Expand description

A primitive utility library for Protocol Buffers in Rust.

This library provides common definitions, constants, enums, and basic logic for implementing Protocol Buffers. It is designed to minimize entry barriers for developers who want to implement Protocol Buffers functionality.

§Overview

This library provides building blocks for implementing Protocol Buffers, not a complete message parser or serializer. It focuses on:

  • Low-level primitives: Raw field I/O without semantic interpretation
  • Flexibility: Support for both owned and borrowed data
  • Minimal dependencies: Only depends on thiserror for error handling
  • Clear API: Trait-based extension methods following Rust conventions

§Quick Start

§Reading Fields

This library provides multiple ways to read protobuf fields from different sources:

use protobuf_core::{Field, IteratorExtProtobuf, AsRefExtProtobuf};

// From a byte iterator - returns Field<Vec<u8>> (Len values are Vec<u8>)
let bytes = vec![0x08, 0x96, 0x01]; // field 1: 150
let fields: Vec<Field<Vec<u8>>> = bytes
    .into_iter()
    .protobuf_fields()
    .collect::<Result<Vec<Field<Vec<u8>>>, _>>()
    .unwrap();

// From a slice - returns Field<&[u8]> (Len values are &[u8], zero-copy)
let slice: &[u8] = &[0x08, 0x96, 0x01];
let fields: Vec<Field<&[u8]>> = AsRefExtProtobuf::read_protobuf_fields(&slice)
    .collect::<Result<Vec<Field<&[u8]>>, _>>()
    .unwrap();

§Writing Fields

use protobuf_core::{WriteExtProtobuf, Field, FieldValue, FieldNumber};

let mut buffer = Vec::new();
let field: Field<Vec<u8>> = Field::new(
    FieldNumber::try_from(1)?,
    FieldValue::from_uint64(150)
);
buffer.write_protobuf_field(&field)?;

§Core Types

§Fields

  • Field<L>: Represents a raw protobuf field with a field number and value. The L type parameter represents the type used for length-delimited values (e.g., Vec<u8> for owned data, &'a [u8] for borrowed data).
  • FieldValue<L>: Represents the raw value of a field. It can be:
    • Varint(Varint): Variable-width integers (Int32, Int64, UInt32, UInt64, SInt32, SInt64, Bool, Enum)
    • I32([u8; 4]): 32-bit fixed-width values (Fixed32, SFixed32, Float)
    • I64([u8; 8]): 64-bit fixed-width values (Fixed64, SFixed64, Double)
    • Len(L): Length-delimited values (String, Bytes, embedded messages, packed repeated fields)

§Basic Types

  • Tag: Represents a protobuf tag (field number + wire type)
  • Varint: Represents a deserialized varint value (8-byte internal representation)
  • FieldNumber: A validated field number (range: 1 to 2^29 - 1)
  • WireType: Represents the protobuf wire type (Varint, Int32, Int64, Len, StartGroup, EndGroup)

§Error Handling

  • ProtobufError: Unified error type for all protobuf operations
  • Result<T>: Type alias for Result<T, ProtobufError>

§Reading Traits

The library provides several traits for reading protobuf fields from different sources:

§Writing Traits

§Tag/Varint Traits

For lower-level operations, the library provides traits for reading and writing tags and varints:

§Feature Flags

  • read (enabled by default): Enables field reading utilities
  • write (enabled by default): Enables field writing utilities

You can use features independently:

[dependencies]
protobuf-core = { version = "0.1.0", default-features = false, features = ["read"] }

§Constants

The library also provides various constants related to the protobuf wire format:

Structs§

Field
A raw field read from the wire
FieldNumber
A validated Protocol Buffers field number.
ProtobufFieldIterator
Iterator for reading raw protobuf fields sequentially from a reader
ProtobufFieldIteratorFromBytes
Iterator for reading raw protobuf fields sequentially from a byte iterator
ProtobufFieldSliceIterator
Iterator for reading raw protobuf fields sequentially from a slice
Tag
A protobuf tag containing field number and wire type
Varint
A deserialized varint value.

Enums§

FieldValue
A raw field value read from the wire
ProtobufError
Unified error type for all protobuf operations
WireType
Wire types used in Protocol Buffers encoding.

Constants§

FIELD_NUMBER_SHIFT
Bit shift for extracting the field number from a tag.
FIXED32_BYTES
Size of a 32-bit fixed-width value in bytes.
FIXED64_BYTES
Size of a 64-bit fixed-width value in bytes.
MAX_1_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 1 byte.
MAX_2_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 2 bytes.
MAX_3_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 3 bytes.
MAX_4_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 4 bytes.
MAX_5_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 5 bytes.
MAX_6_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 6 bytes.
MAX_7_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 7 bytes.
MAX_8_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 8 bytes.
MAX_9_BYTE_VARINT
Maximum variable-length integer value that can be encoded in 9 bytes.
MAX_FIELD_NUMBER
Maximum field number allowed in Protocol Buffers.
MAX_MESSAGE_SIZE
Maximum message size when serialized (2 GiB).
MAX_STRING_SIZE
Maximum string/bytes field size (2 GiB).
MAX_VARINT_BYTES
Maximum varint size in bytes.
MIN_FIELD_NUMBER
Minimum field number allowed in Protocol Buffers.
VARINT_CONTINUATION_BIT
Continuation bit mask for varint encoding.
VARINT_PAYLOAD_MASK
Payload bit mask for varint encoding.
WIRE_TYPE_MASK
Bit mask for extracting the wire type from a tag.

Traits§

AsRefExtProtobuf
Extension trait for reading raw Protocol Buffer fields from slice types
IteratorExtProtobuf
Extension trait for reading raw Protocol Buffer fields from byte iterators.
IteratorExtTag
Extension trait for reading tag from byte iterators.
IteratorExtVarint
Extension trait for collecting varints from byte iterators.
ReadExtProtobuf
Extension trait for reading raw Protocol Buffer fields from Read types
ReadExtTag
Extension trait for reading tags from Read instances.
ReadExtVarint
Extension trait for reading varints from Read instances.
TryIteratorExtProtobuf
Extension trait for reading raw Protocol Buffer fields from byte iterators that yield Result<u8, E>.
TryIteratorExtTag
Extension trait for reading tag from byte iterators that yield Result<u8, E>.
TryIteratorExtVarint
Extension trait for reading varints from byte iterators that yield Result<u8, E>.
WriteExtProtobuf
Extension trait for writing raw Protocol Buffer fields to Write types
WriteExtVarint
Extension trait for writing varints to Write instances.

Type Aliases§

Result
Custom Result type for protobuf operations