oxiproto 0.1.3

# oxiproto — The COOLJAPAN Pure-Rust protobuf facade

[![Crates.io](https://img.shields.io/crates/v/oxiproto.svg)](https://crates.io/crates/oxiproto)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

`oxiproto` is the top-level facade crate for the OxiProto stack — a Pure-Rust protobuf toolkit that needs **no `protoc`** and no C/C++ libraries. It re-exports the core wire-format types from `oxiproto-core` (always available) and conditionally surfaces each higher layer — build-time codegen, runtime reflection, Well-Known Types, and canonical JSON — behind cargo features, so you depend on a single crate and turn on only what you use.

OxiProto ships its own native wire codec via the `OxiMessage` trait (no prost derive macros required) while remaining interoperable with `prost`'s `Message` / `Name` traits, which are re-exported for compatibility. Code generation from `.proto` files happens at build time through `oxiproto-build` / `oxiproto-codegen`; the generated types can implement `OxiMessage` directly.

## Installation

```toml
[dependencies]
# Core only (wire format + traits), always Pure Rust.
oxiproto = "0.1.3"

# Build-time .proto compilation (for build.rs).
oxiproto = { version = "0.1.3", features = ["build"] }

# Runtime reflection + canonical JSON.
oxiproto = { version = "0.1.3", features = ["reflect", "json"] }

# Well-Known Types with chrono interop.
oxiproto = { version = "0.1.3", features = ["wkt-chrono"] }

# Everything.
oxiproto = { version = "0.1.3", features = ["build", "reflect", "wkt-chrono", "codegen", "json"] }
```

## Quick Start

```rust
use oxiproto::prelude::*;

// `OxiMessage` is the native wire-format encode/decode trait.
// Generated types implement it when codegen emits `emit_oxi_message_impl=true`,
// after which the crate-level helpers work directly:
fn roundtrip<T: OxiMessage + PartialEq + std::fmt::Debug>(msg: &T) {
    let bytes = oxiproto::encode(msg);
    let decoded = oxiproto::decode::<T>(&bytes).expect("decode");
    assert_eq!(&decoded, msg);
}
```

The native wire primitives are always available, regardless of features:

```rust
use oxiproto::wire::{DecodeBuffer, EncodeBuffer, WireType};
```

## API Overview

### Crate-root functions

| Function | Returns | Description |
|----------|---------|-------------|
| `version()` | `&'static str` | The `oxiproto` crate version (`env!("CARGO_PKG_VERSION")`) |
| `encode<T: OxiMessage>(msg)` | `Vec<u8>` | Encode an `OxiMessage` to bytes (wraps `OxiMessage::encode_to_vec`) |
| `decode<T: OxiMessage>(bytes)` | `OxiProtoResult<T>` | Decode an `OxiMessage` from bytes (wraps `OxiMessage::decode`) |
| `compile_protos(...)` | — | Re-export of `oxiproto_build::compile_protos` for `build.rs` (**`build` feature**) |

### Traits re-exported at the crate root

| 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) |

### Other crate-root re-exports

| Item | Source | Description |
|------|--------|-------------|
| `OxiProtoError` | `oxiproto-core` | The stack-wide error enum |
| `OxiProtoResult<T>` | `oxiproto-core` | `Result<T, OxiProtoError>` alias |
| `wire` | `oxiproto-core::wire` | Native wire primitives (varint, zigzag, tags, fixed, buffers); always available |
| `prost_types` | `oxiproto-core` | Re-export of `prost-types` for the standard descriptor/WKT structs |

### `prelude` module

`use oxiproto::prelude::*;` glob-imports the most common types: `OxiMessage`, `OxiName`, `OxiOneof`, `Extensions`, `Message`, `Name`, `OxiProtoError`, `OxiProtoResult`, and the wire types `DecodeBuffer`, `EncodeBuffer`, `WireType`.

### Feature-gated sub-modules

Each enabled feature surfaces the corresponding sub-crate under a module of the same name (a `pub use <crate>::*;` re-export):

| Module | Feature | Re-exports | Highlights |
|--------|---------|-----------|------------|
| `oxiproto::build` | `build` | `oxiproto-build` | `compile_protos`, `Builder` for `build.rs` |
| `oxiproto::reflect` | `reflect` | `oxiproto-reflect` | `DescriptorPool`, `DynamicMessage`, `pool_from_fds*`, native reflection stack |
| `oxiproto::wkt` | `wkt` | `oxiproto-wkt` | `TimestampExt`, `DurationExt`, `AnyExt`, `FieldMaskExt`, scalar wrappers, … |
| `oxiproto::codegen` | `codegen` | `oxiproto-codegen` | Generate plain Rust structs/enums from a `FileDescriptorSet` |
| `oxiproto::json` | `json` | `oxiproto-json` | `to_json`, `from_json`, `JsonCodec` (canonical Protobuf-JSON) |

## Feature Flags

| Feature | Default | Enables | Description |
|---------|---------|---------|-------------|
| `build` | off | `oxiproto-build` | `oxiproto::build` + crate-root `compile_protos` for `build.rs` |
| `reflect` | off | `oxiproto-reflect` | `oxiproto::reflect` — runtime `DescriptorPool` and `DynamicMessage` |
| `wkt` | off | `oxiproto-wkt` | `oxiproto::wkt` — Well-Known Type extension traits |
| `wkt-chrono` | off | `wkt` + `oxiproto-wkt/chrono` | `wkt` plus the `chrono` interop methods on `TimestampExt` / `DurationExt` |
| `codegen` | off | `oxiproto-codegen` | `oxiproto::codegen` — generate plain Rust from a `FileDescriptorSet` |
| `json` | off | `oxiproto-json` | `oxiproto::json` — canonical Protobuf-JSON mapping |
| `json-runtime-harness` | off | — | Internal harness toggle for JSON runtime tests |

The default feature set is empty: a bare `oxiproto` dependency gives you the always-available core (wire format + traits) and nothing else.

## `OxiProtoError` variants

The stack-wide error enum (`#[non_exhaustive]`). Implements `Display` and `std::error::Error`, with `From` conversions from `std::io::Error` and `wire::WireError`.

| Variant | Description |
|---------|-------------|
| `ParseError(String)` | A `.proto` source file could not be parsed or resolved |
| `CodegenError(String)` | Rust code could not be generated from the parsed descriptors |
| `IoError(std::io::Error)` | An underlying I/O operation failed (**`std` feature**) |
| `WireFormatError(wire::WireError)` | A wire-format encode or decode error |

## OxiProto crates

| Crate | Role |
|-------|------|
| [`oxiproto-core`](../oxiproto-core) | Native wire format, `OxiMessage` / `OxiName` / `OxiOneof` / `Extensions` traits, shared `OxiProtoError` |
| [`oxiproto-codegen`](../oxiproto-codegen) | Generates plain Rust structs/enums from a `FileDescriptorSet` |
| [`oxiproto-build`](../oxiproto-build) | Build-time `.proto` compilation helpers (`compile_protos`, `Builder`) |
| [`oxiproto-cli`](../oxiproto-cli) | Command-line tooling for the stack |
| [`oxiproto-reflect`](../oxiproto-reflect) | Runtime reflection (`DescriptorPool`, `DynamicMessage`) |
| [`oxiproto-wkt`](../oxiproto-wkt) | Well-Known Types interop (Timestamp, Duration, Any, …) |
| [`oxiproto-json`](../oxiproto-json) | Canonical Protobuf-JSON mapping |

## License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)