Crate rivven_protocol 

Rivven Wire Protocol

This crate defines the wire protocol types shared between rivven-client and rivvend. It provides serialization/deserialization for all protocol messages.

Wire Format

All messages use a unified wire format with format auto-detection and correlation ID:

┌─────────────────┬─────────────────┬──────────────────────────┬──────────────────────┐
│ Length (4 bytes)│ Format (1 byte) │ Correlation ID (4 bytes) │ Payload (N bytes)    │
│ Big-endian u32  │ 0x00 = postcard │ Big-endian u32           │ Serialized message   │
│                 │ 0x01 = protobuf │                          │                      │
└─────────────────┴─────────────────┴──────────────────────────┴──────────────────────┘

• postcard (0x00): High-performance Rust-native binary format
• protobuf (0x01): Cross-language format for Go, Java, Python clients
• correlation_id: Matches responses to their originating requests

Protocol Stability

The enum variant order is significant for postcard serialization. Changes to variant order will break wire compatibility with existing clients/servers.

Example

use rivven_protocol::{Request, Response, WireFormat};

// Serialize with format prefix
let request = Request::Ping;
let bytes = request.to_wire(WireFormat::Postcard, 1)?;

// Deserialize with auto-detection
let (response, format, correlation_id) = Response::from_wire(&bytes)?;

Modules

serde_utils

Serde utilities for bytes serialization

Structs

BatchRecord

A single record within a Request::PublishBatch.

BrokerInfo

Broker/node information for metadata discovery

DeleteRecordsResult

Delete records result for a partition

MessageData

Serialized message data for transport

PartitionMetadata

Partition metadata for cluster discovery

QuotaAlteration

Quota alteration request

QuotaEntry

Quota entry in describe response

TopicConfigDescription

Topic configuration in describe response

TopicConfigEntry

Topic configuration entry for AlterTopicConfig

TopicConfigValue

Topic configuration value with metadata

TopicMetadata

Topic metadata for cluster discovery

Enums

ProtocolError

Protocol error types

Request

Protocol request messages

Response

Protocol response messages

SchemaType

Schema type (format) for schema registry

WireFormat

Wire format identifier

Constants

MAX_AUTH_PAYLOAD

Maximum authentication / SASL payload (64 KiB).

MAX_LIST_LEN

Maximum number of items in a list field (topics, partitions, configs, etc.).

MAX_MESSAGES_PER_RESPONSE

Maximum number of messages in a single Response::Messages batch.

MAX_MESSAGE_SIZE

Maximum message size (10 MiB)

MAX_NAME_LEN

Maximum topic/group/entity name length (256 bytes).

PROTOCOL_VERSION

Protocol version for compatibility checking

WIRE_HEADER_SIZE

Wire header size: format byte (1) + correlation_id (4)

Functions

is_internal_topic

Check whether a topic name designates an internal system topic.

Type Aliases

Result

Result type for protocol operations

SyncGroupAssignments

Partition assignments for SyncGroup: Vec<(member_id, Vec<(topic, Vec<partition>)>)>