rivven_client/
lib.rs

1//! # rivven-client
2//!
3//! Native async Rust client library for [Rivven](https://rivven.hupe1980.github.io/rivven/),
4//! the high-performance, single-binary event streaming platform.
5//!
6//! ## Features
7//!
8//! - **Async/Await**: Built on Tokio for high-performance async I/O
9//! - **Connection Pooling**: Efficient connection management with [`ResilientClient`]
10//! - **Circuit Breaker**: Automatic failure detection and recovery
11//! - **Automatic Retries**: Exponential backoff with configurable limits
12//! - **Multi-Server Failover**: Bootstrap server list with automatic failover
13//! - **SCRAM-SHA-256 Authentication**: Secure password-based authentication
14//! - **TLS Support**: Optional TLS encryption (requires `tls` feature)
15//!
16//! ## Quick Start
17//!
18//! ```rust,ignore
19//! use rivven_client::{ResilientClient, ResilientClientConfig};
20//!
21//! # async fn example() -> rivven_client::Result<()> {
22//! // Create a client with connection pooling and circuit breaker
23//! let config = ResilientClientConfig::builder()
24//!     .servers(vec!["127.0.0.1:9092".to_string()])
25//!     .max_connections(10)
26//!     .build()?;
27//!
28//! let client = ResilientClient::new(config).await?;
29//!
30//! // Publish a message
31//! client.publish("my-topic", b"Hello, Rivven!").await?;
32//!
33//! // Consume messages
34//! let messages = client.consume("my-topic", 0, 0, 100).await?;
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! ## Authentication
40//!
41//! The client supports SCRAM-SHA-256 authentication:
42//!
43//! ```rust,no_run
44//! use rivven_client::{Client, AuthSession};
45//!
46//! # async fn example() -> rivven_client::Result<()> {
47//! let mut client = Client::connect("127.0.0.1:9092").await?;
48//!
49//! // Authenticate with SCRAM-SHA-256
50//! client.authenticate_scram("username", "password").await?;
51//! # Ok(())
52//! # }
53//! ```
54//!
55//! ## Resilient Client
56//!
57//! For production use, [`ResilientClient`] provides:
58//!
59//! - **Connection Pooling**: Reuses connections across requests
60//! - **Circuit Breaker**: Stops sending requests to failing servers
61//! - **Retries**: Automatic retries with exponential backoff
62//! - **Failover**: Tries multiple bootstrap servers
63//!
64//! ```rust,ignore
65//! use rivven_client::{ResilientClient, ResilientClientConfig};
66//!
67//! # async fn example() -> rivven_client::Result<()> {
68//! let config = ResilientClientConfig::builder()
69//!     .servers(vec![
70//!         "broker1:9092".to_string(),
71//!         "broker2:9092".to_string(),
72//!         "broker3:9092".to_string(),
73//!     ])
74//!     .max_connections(20)
75//!     .max_retries(5)
76//!     .circuit_breaker_threshold(3)
77//!     .circuit_breaker_timeout(std::time::Duration::from_secs(30))
78//!     .build()?;
79//!
80//! let client = ResilientClient::new(config).await?;
81//! # Ok(())
82//! # }
83//! ```
84//!
85//! ## Request Pipelining
86//!
87//! For maximum throughput, use [`PipelinedClient`] which allows multiple
88//! in-flight requests over a single connection:
89//!
90//! ```rust,ignore
91//! use rivven_client::{PipelinedClient, PipelineConfig};
92//!
93//! # async fn example() -> rivven_client::Result<()> {
94//! // High-throughput configuration
95//! let config = PipelineConfig::high_throughput();
96//! let client = PipelinedClient::connect("127.0.0.1:9092", config).await?;
97//!
98//! // Send 1000 requests concurrently
99//! let handles: Vec<_> = (0..1000)
100//!     .map(|i| {
101//!         let client = client.clone();
102//!         tokio::spawn(async move {
103//!             client.publish("topic", format!("msg-{}", i)).await
104//!         })
105//!     })
106//!     .collect();
107//!
108//! for handle in handles {
109//!     handle.await??;
110//! }
111//! # Ok(())
112//! # }
113//! ```
114//!
115//! ## Feature Flags
116//!
117//! - `tls` - Enable TLS support via rustls
118//!
119//! ## High-Performance Producer
120//!
121//! For maximum throughput with all best practices, use [`Producer`]:
122//!
123//! ```rust,ignore
124//! use rivven_client::{Producer, ProducerConfig};
125//! use std::sync::Arc;
126//!
127//! let config = ProducerConfig::builder()
128//!     .bootstrap_servers(vec!["localhost:9092".to_string()])
129//!     .batch_size(16384)
130//!     .linger_ms(5)
131//!     .enable_idempotence(true)
132//!     .build();
133//!
134//! let producer = Arc::new(Producer::new(config).await?);
135//!
136//! // Thread-safe sharing
137//! for i in 0..1000 {
138//!     let producer = Arc::clone(&producer);
139//!     tokio::spawn(async move {
140//!         producer.send("topic", format!("msg-{}", i)).await
141//!     });
142//! }
143//! ```
144
145pub mod client;
146pub mod error;
147pub mod pipeline;
148pub mod producer;
149pub mod resilient;
150
151pub use client::{AlterTopicConfigResult, AuthSession, Client, DeleteRecordsResult, ProducerState};
152pub use error::{Error, Result};
153pub use pipeline::{PipelineConfig, PipelineConfigBuilder, PipelineStatsSnapshot, PipelinedClient};
154pub use producer::{
155    CompressionType, Producer, ProducerConfig, ProducerConfigBuilder, ProducerStatsSnapshot,
156    RecordMetadata,
157};
158pub use resilient::{ResilientClient, ResilientClientConfig, ResilientClientConfigBuilder};
159
160// Re-export TLS configuration when available
161#[cfg(feature = "tls")]
162pub use rivven_core::tls::TlsConfig;
163
164// Re-export protocol types from rivven-protocol
165pub use rivven_protocol::{
166    BrokerInfo, MessageData, PartitionMetadata, Request, Response, SchemaType, TopicConfigEntry,
167    TopicMetadata, WireFormat, MAX_MESSAGE_SIZE, PROTOCOL_VERSION,
168};
rivven_client/lib.rs

rivven_client/
lib.rs
