oxiproto-core — Pure-Rust Protocol Buffers runtime and wire-format primitives

oxiproto-core is the runtime layer of the OxiProto stack — COOLJAPAN's Pure-Rust Protocol Buffers implementation. It defines the encoding/decoding types that generated message code depends on at runtime: a standalone implementation of the protobuf binary wire format (varint, ZigZag, tags, fixed-width, length-delimited), the native message/name/oneof traits, proto2 extension storage, and unknown-field preservation.

It contains no code generation (that lives in oxiproto-codegen), no build.rs glue (oxiproto-build), and no CLI (oxiproto-cli). The crate is #![forbid(unsafe_code)] and supports no_std (with alloc) by disabling the std feature. For convenience it also re-exports the fundamental prost traits (Message, Name) and prost_types so downstream crates have a single dependency for both the native and prost-compatible code paths.

Installation

[dependencies]
oxiproto-core = "0.1.2"

no_std (relying on alloc):

[dependencies]
oxiproto-core = { version = "0.1.2", default-features = false, features = ["alloc"] }

With Serde derives on the wire helper types:

[dependencies]
oxiproto-core = { version = "0.1.2", features = ["serde"] }

Quick Start

Encode and decode protobuf wire-format fields directly with the streaming buffers:

use oxiproto_core::wire::{DecodeBuffer, EncodeBuffer, WireType};

// Encode: field 1 = varint 42, field 2 = string "hello"
let mut enc = EncodeBuffer::new();
enc.write_tag(1, WireType::Varint)?;
enc.write_varint(42);
enc.write_tag(2, WireType::Len)?;
enc.write_string("hello");
let bytes = enc.into_vec();

// Decode the same buffer back
let mut dec = DecodeBuffer::new(&bytes);
let tag = dec.read_tag()?;
assert_eq!(tag.field_number, 1);
assert_eq!(dec.read_varint()?, 42);

let tag = dec.read_tag()?;
assert_eq!(tag.field_number, 2);
assert_eq!(dec.read_string()?, "hello");
assert!(dec.is_empty());
# Ok::<(), oxiproto_core::wire::WireError>(())

Implementing the native message trait

use oxiproto_core::{OxiMessage, OxiProtoResult};
use oxiproto_core::wire::{DecodeBuffer, EncodeBuffer, WireType};

#[derive(Debug, Default)]
struct Point { x: i32, y: i32 }

impl OxiMessage for Point {
    fn encoded_len(&self) -> usize { /* tag + varint sizes */ 4 }

    fn encode_raw(&self, buf: &mut EncodeBuffer) {
        // proto3: omit default (zero) values
        if self.x != 0 { let _ = buf.write_tag(1, WireType::Varint); buf.write_varint_i32(self.x); }
        if self.y != 0 { let _ = buf.write_tag(2, WireType::Varint); buf.write_varint_i32(self.y); }
    }

    fn merge(&mut self, buf: &mut DecodeBuffer) -> OxiProtoResult<()> {
        while !buf.is_empty() {
            let tag = buf.read_tag()?;
            match tag.field_number {
                1 => self.x = buf.read_varint_i32()?,
                2 => self.y = buf.read_varint_i32()?,
                _ => buf.skip_field(tag.wire_type)?,
            }
        }
        Ok(())
    }

    fn clear(&mut self) { *self = Self::default(); }
}

// `encode_to_vec` / `decode` come for free as provided methods.
let bytes = Point { x: 3, y: 4 }.encode_to_vec();
let p = Point::decode(&bytes)?;
assert_eq!((p.x, p.y), (3, 4));
# Ok::<(), oxiproto_core::OxiProtoError>(())

API Overview

Crate root re-exports

OxiMessage trait

The native message trait. Every generated message type implements it; it works directly with wire::EncodeBuffer / wire::DecodeBuffer rather than the bytes crate.

Supertraits: Sized + Debug + Default + Send + Sync.

OxiName trait

OxiOneof trait

Implemented by generated oneof-group enums so the containing message can dispatch through them.

Extensions — proto2 extension storage

Stores extension values as raw wire bytes keyed by field number (BTreeMap for stable order). Lazily encoded on write, decoded on read.

wire module

A complete, standalone protobuf wire-format implementation. Submodules are public so lower-level helpers (e.g. wire::varint::encoded_len_varint) are reachable.

WireType enum

Methods: WireType::from_u32(u32) -> Result<Self, WireError>, value(self) -> u32; implements Display. With the serde feature it derives Serialize/Deserialize.

DecodeBuffer<'a> — cursor-based reader (zero-copy)

EncodeBuffer — append-only writer

Tag and free functions

Tag { field_number: u32, wire_type: WireType }. Constants: MAX_FIELD_NUMBER (2²⁹−1), RESERVED_RANGE_START (19000), RESERVED_RANGE_END (19999).

Unknown-field preservation (unknown)

Feature Flags

Error Variants — OxiProtoError

Stack-wide error enum (#[non_exhaustive]); implements Display + core::error::Error.

From<std::io::Error> (with std) and From<wire::WireError> conversions are provided.

WireError (in wire)

Related crates

• oxiproto — top-level façade that re-exports the OxiProto stack
• oxiproto-codegen — FileDescriptorSet → Rust source generation
• oxiproto-build — build.rs integration (.proto → Rust, no protoc)
• oxiproto-cli — command-line compiler
• oxiproto-json — canonical Protobuf-JSON encode/decode
• oxiproto-reflect — runtime reflection over descriptors
• oxiproto-wkt — Google well-known types

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)