websockets_monoio/
lib.rs

1//! # websockets-monoio
2//!
3//! A high-performance WebSocket client library built for the [`monoio`] async runtime
4//! using `io_uring` on Linux. This library provides both `ws://` and `wss://` (TLS)
5//! support with optimized low-allocation operations and efficient memory usage.
6//!
7//! ## Features
8//!
9//! - **🚀 High Performance**: Built on `monoio` runtime with `io_uring` for maximum efficiency on Linux
10//! - **🔒 TLS Support**: Full `wss://` support via `monoio-rustls`
11//! - **📦 Built for monoio**: Optimized for monoio async runtime
12//! - **🛡️ Secure**: Uses `rustls` with `webpki-roots` for certificate validation
13//! - **⚡ Low-Allocation**: Zero-copy message sending and optimized connection setup
14//! - **🔧 Simple API**: Easy-to-use client interface
15//!
16//! ## Quick Start
17//!
18//! Add to your `Cargo.toml`:
19//!
20//! ```toml
21//! [dependencies]
22//! websockets-monoio = "0.1"
23//! monoio = "0.2"
24//! fastwebsockets-monoio = "0.10"
25//! anyhow = "1.0"
26//! ```
27//!
28//! ## Basic Example
29//!
30//! ```no_run
31//! use fastwebsockets_monoio::{Frame, OpCode};
32//! use websockets_monoio::WsClient;
33//!
34//! #[monoio::main]
35//! async fn main() -> anyhow::Result<()> {
36//!     // Connect to a WebSocket server
37//!     let mut client = WsClient::connect(
38//!         "wss://echo.websocket.org/",
39//!         &[],
40//!     ).await?;
41//!
42//!     // Send a text message
43//!     client
44//!         .ws
45//!         .write_frame(Frame::text("Hello, WebSocket!".as_bytes().into()))
46//!         .await?;
47//!
48//!     // Read the response
49//!     let frame = client.ws.read_frame().await?;
50//!     match frame.opcode {
51//!         OpCode::Text => {
52//!             let text = std::str::from_utf8(&frame.payload)?;
53//!             println!("Received: {}", text);
54//!         }
55//!         OpCode::Close => {
56//!             println!("Connection closed by server");
57//!         }
58//!         _ => {}
59//!     }
60//!
61//!     Ok(())
62//! }
63//! ```
64//!
65//! ## Cryptocurrency Exchange Example
66//!
67//! ```no_run
68//! use fastwebsockets_monoio::{Frame, OpCode};
69//! use websockets_monoio::WsClient;
70//!
71//! #[monoio::main]
72//! async fn main() -> anyhow::Result<()> {
73//!     // Connect to Binance ticker stream
74//!     let mut client = WsClient::connect(
75//!         "wss://stream.binance.com:9443/ws/btcusdt@trade",
76//!         &[],
77//!     ).await?;
78//!
79//!     // Subscribe to trades
80//!     let subscribe = r#"{"method":"SUBSCRIBE","params":["btcusdt@trade"],"id":1}"#;
81//!     client
82//!         .ws
83//!         .write_frame(Frame::text(subscribe.as_bytes().into()))
84//!         .await?;
85//!
86//!     // Stream trade data
87//!     loop {
88//!         let frame = client.ws.read_frame().await?;
89//!         match frame.opcode {
90//!             OpCode::Text => {
91//!                 let text = std::str::from_utf8(&frame.payload)?;
92//!                 println!("Trade: {}", text);
93//!             }
94//!             OpCode::Binary => {
95//!                 println!("Binary frame ({} bytes)", frame.payload.len());
96//!             }
97//!             OpCode::Close => {
98//!                 println!("Stream closed");
99//!                 break;
100//!             }
101//!             OpCode::Ping | OpCode::Pong => {
102//!                 // Auto-handled by fastwebsockets
103//!             }
104//!             _ => {}
105//!         }
106//!     }
107//!
108//!     Ok(())
109//! }
110//! ```
111//!
112//! ## Platform Support
113//!
114//! - **Linux**: Full support with `io_uring` (recommended)
115//! - **macOS/Windows**: Limited support (falls back to standard async I/O)
116//!
117//! For maximum performance, deploy on Linux with kernel version 5.1+ for full `io_uring` support.
118//!
119//! [`monoio`]: https://docs.rs/monoio
120
121pub mod client;
122pub mod http_upgrade;
123pub mod tls;
124pub mod url;
125
126pub use client::{WsClient, WsStream};
websockets_monoio/lib.rs

websockets_monoio/
lib.rs
