stream_tungstenite/
lib.rs

1// Suppress missing_errors_doc for the entire crate - error documentation is centralized in the error module
2#![allow(clippy::missing_errors_doc)]
3
4//! stream-tungstenite: WebSocket client with automatic reconnection.
5//!
6//! This library provides a robust WebSocket client that handles:
7//! - Automatic reconnection with configurable retry strategies
8//! - Application-level handshakes (authentication, subscriptions)
9//! - Extension system for lifecycle and message handling
10//! - Connection state management and monitoring
11//!
12//! # Quick Start
13//!
14//! ```rust,ignore
15//! use stream_tungstenite::{WebSocketClient, ClientConfig};
16//! use std::sync::Arc;
17//!
18//! #[tokio::main]
19//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
20//!     // Create client with builder pattern
21//!     let client = WebSocketClient::builder("wss://example.com/ws")
22//!         .receive_timeout(std::time::Duration::from_secs(30))
23//!         .build();
24//!
25//!     // Subscribe to messages before running
26//!     let mut messages = client.subscribe();
27//!
28//!     // Run client in background
29//!     let client = Arc::new(client);
30//!     tokio::spawn({
31//!         let client = client.clone();
32//!         async move { client.run().await }
33//!     });
34//!
35//!     // Receive messages
36//!     while let Ok(msg) = messages.recv().await {
37//!         println!("Received: {:?}", msg);
38//!     }
39//!
40//!     Ok(())
41//! }
42//! ```
43//!
44//! # Architecture
45//!
46//! ```text
47//! ┌─────────────────────────────────────────────────────────────────┐
48//! │                      WebSocketClient                            │
49//! │  - High-level API for WebSocket connections                     │
50//! │  - Automatic reconnection with retry strategies                 │
51//! │  - Message broadcasting via channels                            │
52//! └─────────────────────────────────────────────────────────────────┘
53//!                              │
54//!          ┌───────────────────┼───────────────────┐
55//!          ▼                   ▼                   ▼
56//! ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
57//! │   Handshake     │ │   Extension     │ │   Connection    │
58//! │   - Auth        │ │   - Lifecycle   │ │   - State       │
59//! │   - Subscribe   │ │   - Messages    │ │   - Retry       │
60//! │   - Chained     │ │   - Logging     │ │   - Supervisor  │
61//! └─────────────────┘ └─────────────────┘ └─────────────────┘
62//! ```
63
64// Core modules
65pub mod client;
66pub mod error;
67
68// Layer modules
69pub mod connection;
70pub mod context;
71pub mod extension;
72pub mod handshake;
73pub mod message;
74pub mod transport;
75
76/// Re-export tokio-tungstenite types
77pub mod tokio_tungstenite {
78    pub use tokio_tungstenite::*;
79}
80
81/// Prelude for convenient imports
82pub mod prelude {
83    pub use crate::client::*;
84    pub use crate::connection::{
85        ConnectionEvent, ConnectionSnapshot, ConnectionStatus, ExponentialBackoff, FixedDelay,
86        NoRetry, RetryStrategy,
87    };
88    pub use crate::context::ConnectionContext;
89    pub use crate::error::*;
90    pub use crate::extension::{Extension, ExtensionHost};
91    pub use crate::extension::{LoggingExtension, StatusViewer};
92    pub use crate::handshake::{
93        AuthHandshaker, ChainedHandshaker, NoOpHandshaker, SubscribeHandshaker,
94    };
95    pub use crate::handshake::{BoxHandshaker, Handshaker};
96    pub use crate::message::SharedMessage;
97}
98
99// Re-export main types at crate root
100pub use client::{ClientConfig, Sender, WebSocketClient, WebSocketClientBuilder};
101pub use connection::ConnectionEvent;
102pub use error::{
103    ClientError, ConnectError, DisconnectReason, HandshakeError, ReceiveError, SendError,
104};
105pub use message::SharedMessage;
stream_tungstenite/lib.rs

stream_tungstenite/
lib.rs
