rivven_client/
lib.rs

1//! # rivven-client
2//!
3//! Native async Rust client library for [Rivven](https://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//! ## Feature Flags
86//!
87//! - `tls` - Enable TLS support via rustls
88
89pub mod client;
90pub mod error;
91pub mod resilient;
92
93pub use client::{AuthSession, Client};
94pub use error::{Error, Result};
95pub use resilient::{ResilientClient, ResilientClientConfig, ResilientClientConfigBuilder};
96
97// Re-export TLS configuration when available
98#[cfg(feature = "tls")]
99pub use rivven_core::tls::TlsConfig;
100
101// Re-export protocol types from rivven-protocol
102pub use rivven_protocol::{
103    BrokerInfo, MessageData, PartitionMetadata, Request, Response, TopicMetadata, MAX_MESSAGE_SIZE,
104    PROTOCOL_VERSION,
105};
rivven_client/lib.rs

rivven_client/
lib.rs
