rivven_protocol/
lib.rs

1//! Rivven Wire Protocol
2//!
3//! This crate defines the wire protocol types shared between rivven-client and rivvend.
4//! It provides serialization/deserialization for all protocol messages.
5//!
6//! # Wire Format
7//!
8//! All messages use a unified wire format with format auto-detection:
9//!
10//! ```text
11//! ┌─────────────────┬─────────────────┬──────────────────────────────┐
12//! │ Length (4 bytes)│ Format (1 byte) │ Payload (N bytes)            │
13//! │ Big-endian u32  │ 0x00 = postcard │ Serialized message           │
14//! │                 │ 0x01 = protobuf │                              │
15//! └─────────────────┴─────────────────┴──────────────────────────────┘
16//! ```
17//!
18//! - **postcard** (0x00): High-performance Rust-native binary format
19//! - **protobuf** (0x01): Cross-language format for Go, Java, Python clients
20//!
21//! # Protocol Stability
22//!
23//! The enum variant order is significant for postcard serialization. Changes to variant
24//! order will break wire compatibility with existing clients/servers.
25//!
26//! # Example
27//!
28//! ```rust,ignore
29//! use rivven_protocol::{Request, Response, WireFormat};
30//!
31//! // Serialize with format prefix
32//! let request = Request::Ping;
33//! let bytes = request.to_wire(WireFormat::Postcard)?;
34//!
35//! // Deserialize with auto-detection
36//! let (response, format) = Response::from_wire(&bytes)?;
37//! ```
38
39mod error;
40mod messages;
41mod metadata;
42pub mod serde_utils;
43mod types;
44
45// Protobuf types (optional, for cross-language clients)
46#[cfg(feature = "protobuf")]
47pub mod proto {
48    //! Protobuf-generated types for cross-language client support.
49    //!
50    //! Enable with `--features protobuf`. Used by Go, Java, and other language clients.
51    include!(concat!(env!("OUT_DIR"), "/rivven.protocol.v1.rs"));
52}
53
54// Protobuf conversion utilities
55#[cfg(feature = "protobuf")]
56mod proto_convert;
57
58pub use error::{ProtocolError, Result};
59pub use messages::{
60    DeleteRecordsResult, QuotaAlteration, QuotaEntry, Request, Response, TopicConfigDescription,
61    TopicConfigEntry, TopicConfigValue,
62};
63pub use metadata::{BrokerInfo, PartitionMetadata, TopicMetadata};
64pub use types::{MessageData, SchemaType};
65
66/// Protocol version for compatibility checking
67pub const PROTOCOL_VERSION: u32 = 1;
68
69/// Maximum message size (64 MiB)
70pub const MAX_MESSAGE_SIZE: usize = 64 * 1024 * 1024;
71
72/// Wire format identifier
73#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
74#[repr(u8)]
75pub enum WireFormat {
76    /// Postcard format (Rust-native, fastest)
77    #[default]
78    Postcard = 0x00,
79    /// Protobuf format (cross-language)
80    Protobuf = 0x01,
81}
82
83impl WireFormat {
84    /// Parse format from byte
85    #[inline]
86    pub fn from_byte(b: u8) -> Option<Self> {
87        match b {
88            0x00 => Some(Self::Postcard),
89            0x01 => Some(Self::Protobuf),
90            _ => None,
91        }
92    }
93
94    /// Convert to byte
95    #[inline]
96    pub const fn as_byte(self) -> u8 {
97        self as u8
98    }
99}
rivven_protocol/lib.rs

rivven_protocol/
lib.rs
