fast_websocket_client/
lib.rs

1//! # fast_websocket_client
2//!
3//! [![Crates.io](https://img.shields.io/crates/v/fast_websocket_client)](https://crates.io/crates/fast_websocket_client)
4//! [![docs.rs](https://docs.rs/fast_websocket_client/badge.svg)](https://docs.rs/fast_websocket_client)
5//!
6//! **Tokio-native WebSocket client for Rust** – high-throughput, low-latency, callback-driven, proxy-ready.
7//!
8//! Supports two modes of operation:
9//! - **High-level callback-based client** for ergonomic event-driven use.
10//! - **Low-level direct API** for fine-tuned control with minimal dependencies.
11//!
12//! Quick Example: [examples/async_callback_client.rs](https://github.com/Osteoporosis/fast_websocket_client/blob/main/examples/async_callback_client.rs)
13//!
14//! ## Features
15//!
16//! - JavaScript-like callback API for event handling
17//! - Async/await support via `tokio`
18//! - Powered by [`fastwebsockets`](https://github.com/denoland/fastwebsockets)
19//! - Built-in reconnection and ping loop
20//! - TLS support
21//! - Custom HTTP headers for handshake (e.g., Authorization)
22//! - Proxy support (HTTP CONNECT & SOCKS5)
23//!
24//! ## Installation
25//!
26//! ```bash
27//! cargo add fast_websocket_client
28//! ```
29//!
30//! ## High-Level Callback API
31//!
32//! An ergonomic, JavaScript-like API with built-in reconnect, ping, and lifecycle hooks.
33//!
34//! ```rust
35//! // try this example with
36//! // `cargo run --example wss_client`
37//!
38//! use tokio::time::{Duration, sleep};
39//! use fast_websocket_client::WebSocket;
40//!
41//! #[tokio::main(flavor = "current_thread")]
42//! async fn main() -> Result<(), fast_websocket_client::WebSocketClientError> {
43//!     let ws = WebSocket::new("wss://echo.websocket.org").await?;
44//!
45//!     ws.on_open(|_| async move {
46//!         println!("[OPEN] WebSocket connection opened.");
47//!     })
48//!     .await;
49//!     ws.on_close(|_| async move {
50//!         println!("[CLOSE] WebSocket connection closed.");
51//!     })
52//!     .await;
53//!     ws.on_message(|message| async move {
54//!         println!("[MESSAGE] {}", message);
55//!     })
56//!     .await;
57//!
58//!     sleep(Duration::from_secs(2)).await;
59//!     for i in 1..5 {
60//!         let message = format!("#{}", i);
61//!         if let Err(e) = ws.send(&message).await {
62//!             eprintln!("[ERROR] Send error: {:?}", e);
63//!             break;
64//!         }
65//!         println!("[SEND] {}", message);
66//!         sleep(Duration::from_secs(2)).await;
67//!     }
68//!
69//!     ws.close().await;
70//!     ws.await_shutdown().await;
71//!     Ok(())
72//! }
73//! ```
74//!
75//! ## Low-Level API
76//!
77//! ```rust
78//! use fast_websocket_client::{connect, OpCode};
79//!
80//! #[tokio::main(flavor = "current_thread")]
81//! async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
82//!     let mut client = connect("wss://echo.websocket.org").await?;
83//!
84//!     client.send_string("Hello, WebSocket!").await?;
85//!
86//!     let frame = client.receive_frame().await?;
87//!     if frame.opcode == OpCode::Text {
88//!         println!("Received: {}", String::from_utf8_lossy(&frame.payload));
89//!     }
90//!
91//!     client.send_close("bye").await?;
92//!     Ok(())
93//! }
94//! ```
95//!
96//! ## Running the Example
97//!
98//! Clone the repo and run:
99//!
100//! ```bash
101//! cargo run --example wss_client
102//! ```
103//!
104//! ## Migration Guide (from `0.2.0`)
105//!
106//! | Old                                     | New                    |
107//! |-----------------------------------------|------------------------|
108//! | `client::Offline`                       | `base_client::Offline` |
109//! | `client::Online`                        | `base_client::Online`  |
110//! | Runtime settings via `Online`'s methods | Must now be set before connect via `ConnectionInitOptions`.<br>Changes to the running `WebSocket` take effect on the next (re)connection. |
111//!
112//! **New users:** We recommend starting with the `WebSocket` API for best experience.
113//!
114//! ## Documentation
115//!
116//! - [docs.rs/fast_websocket_client](https://docs.rs/fast_websocket_client)
117//! - [Examples](https://github.com/Osteoporosis/fast_websocket_client/blob/main/examples/)
118//! - [fastwebsockets upstream](https://github.com/denoland/fastwebsockets)
119//!
120//! ---
121//!
122//! 💡 Actively maintained - **contributions are welcome!**
123
124pub mod base_client;
125pub use base_client::connect;
126
127#[cfg(feature = "callback_client")]
128pub mod client;
129#[cfg(feature = "callback_client")]
130pub use client as callback_client;
131#[cfg(feature = "callback_client")]
132pub use client::{
133    ClientConfig, ConnectionInitOptions, WebSocket, WebSocketBuilder, WebSocketClientError,
134};
135
136#[cfg(feature = "proxy")]
137pub mod proxy;
138
139pub use fastwebsockets::OpCode;
140pub use hyper::HeaderMap;
141
142mod tls_connector;
fast_websocket_client/lib.rs

fast_websocket_client/
lib.rs
