oxiproto 0.1.2

Pure Rust protobuf toolkit (no protoc)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

#![forbid(unsafe_code)]

//! `oxiproto` — Pure Rust protobuf toolkit, no `protoc` required.
//!
//! This crate is the top-level facade for the OxiProto stack.  It re-exports
//! the core types from [`oxiproto_core`] and conditionally exposes helpers
//! from the sub-crates depending on which features are enabled.
//!
//! ## Quick start
//!
//! ```rust
//! # use oxiproto::prelude::*;
//! // Use OxiMessage for native wire-format encode/decode (no prost macros needed).
//! // Use Message (prost) for prost-derive generated types.
//! ```
//!
//! ## Trait overview
//!
//! | Trait          | Source               | Description |
//! |----------------|----------------------|-------------|
//! | [`OxiMessage`] | `oxiproto-core`      | Native wire-format encode/decode trait. Generated by codegen when `emit_oxi_message_impl=true`. |
//! | [`OxiName`]    | `oxiproto-core`      | Provides `NAME`, `PACKAGE`, `full_name()`, `type_url()` for a message type. |
//! | [`OxiOneof`]   | `oxiproto-core`      | Marker trait for native oneof enum types. |
//! | [`Extensions`] | `oxiproto-core`      | Trait for proto extension fields. |
//! | `Message`      | `prost`              | The prost derive-based message trait (re-exported for compat). |
//! | `Name`         | `prost`              | The prost name trait (re-exported for compat). |
//!
//! ## Features
//!
//! | Feature      | Default | Description |
//! |--------------|---------|-------------|
//! | `build`      | off     | Enables `oxiproto::build` with `compile_protos` and `Builder`. |
//! | `reflect`    | off     | Enables `oxiproto::reflect` with runtime `DescriptorPool` and `DynamicMessage`. |
//! | `wkt`        | off     | Enables `oxiproto::wkt` with Well-Known Type extension traits. |
//! | `wkt-chrono` | off     | Enables `wkt` + the `chrono` interop methods on `TimestampExt` / `DurationExt`. |
//! | `codegen`    | off     | Enables `oxiproto::codegen` for generating plain Rust from a `FileDescriptorSet`. |

pub use oxiproto_core::prost_types;
pub use oxiproto_core::{
    Extensions, Message, Name, OxiMessage, OxiName, OxiOneof, OxiProtoError, OxiProtoResult,
};

/// Native wire format primitives (varint, zigzag, tags, fixed, buffers).
///
/// Re-exported from [`oxiproto_core::wire`] and always available regardless
/// of which features are enabled.
pub use oxiproto_core::wire;

/// Returns the version string of the `oxiproto` crate.
///
/// # Example
///
/// ```
/// let v = oxiproto::version();
/// assert!(!v.is_empty());
/// ```
pub fn version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

/// Encode a message implementing [`OxiMessage`] to a `Vec<u8>`.
///
/// This is a convenience wrapper around [`OxiMessage::encode_to_vec`].
///
/// # Example
///
/// ```ignore
/// let bytes = oxiproto::encode(&my_message);
/// ```
pub fn encode<T: OxiMessage>(msg: &T) -> Vec<u8> {
    msg.encode_to_vec()
}

/// Decode a message from a byte slice.
///
/// This is a convenience wrapper around [`OxiMessage::decode`].
///
/// # Errors
///
/// Returns [`OxiProtoError`] if the bytes cannot be decoded into `T`.
///
/// # Example
///
/// ```ignore
/// let msg = oxiproto::decode::<MyMessage>(&bytes)?;
/// ```
pub fn decode<T: OxiMessage>(bytes: &[u8]) -> OxiProtoResult<T> {
    T::decode(bytes)
}

/// Top-level re-export of [`oxiproto_build::compile_protos`] for ergonomic use
/// in downstream `build.rs` files.
///
/// Enabled with the `build` feature.
#[cfg(feature = "build")]
pub use oxiproto_build::compile_protos;

/// Glob-importable prelude of the most commonly used OxiProto types.
///
/// ```
/// use oxiproto::prelude::*;
/// ```
pub mod prelude {
    pub use oxiproto_core::wire::{DecodeBuffer, EncodeBuffer, WireType};
    pub use oxiproto_core::{
        Extensions, Message, Name, OxiMessage, OxiName, OxiOneof, OxiProtoError, OxiProtoResult,
    };
}

/// Build-time helpers for compiling `.proto` files to Rust.
///
/// Enabled with the `build` feature.
#[cfg(feature = "build")]
pub mod build {
    pub use oxiproto_build::*;
}

/// Runtime protobuf reflection via `prost-reflect`.
///
/// Enabled with the `reflect` feature.
#[cfg(feature = "reflect")]
pub mod reflect {
    pub use oxiproto_reflect::*;
}

/// Well-Known Types interop (Timestamp, Duration, Any, etc.).
///
/// Enabled with the `wkt` feature. Use the `wkt-chrono` feature to also
/// enable `chrono` conversion methods.
#[cfg(feature = "wkt")]
pub mod wkt {
    pub use oxiproto_wkt::*;
}

/// Code generation from `FileDescriptorSet` to plain Rust structs/enums.
///
/// Enabled with the `codegen` feature.
#[cfg(feature = "codegen")]
pub mod codegen {
    pub use oxiproto_codegen::*;
}

/// Canonical Protobuf-JSON mapping.
///
/// Enabled with the `json` feature. Provides [`json::to_json`],
/// [`json::from_json`], and [`json::JsonCodec`].
#[cfg(feature = "json")]
pub mod json {
    pub use oxiproto_json::*;
}

/// Migration guide: prost → OxiProto.
///
/// This module contains only documentation explaining how to migrate from the
/// `prost` ecosystem to the OxiProto stack.  See the module-level rustdoc for
/// the full guide (Cargo.toml changes, build.rs, trait equivalence, WKT, JSON,
/// reflection, no_std, and interoperability during incremental migration).
pub mod migration;