websockets-monoio

Note: Documentation is AI generated.

A high-performance WebSocket client library built for the monoio async runtime using io_uring on Linux. This library provides both ws:// and wss:// (TLS) support with zero-copy operations and efficient memory usage.

Features

• 🚀 High Performance: Built on monoio runtime with io_uring for maximum efficiency on Linux
• 🔒 TLS Support: Full wss:// support via monoio-rustls
• 📦 Zero Dependencies on tokio: Pure monoio implementation
• 🛡️ Secure: Uses rustls with webpki-roots for certificate validation
• ⚡ Zero-Copy: Efficient frame handling with minimal allocations
• 🔧 Simple API: Easy-to-use client interface

Quick Start

Add to your Cargo.toml:

[dependencies]
websockets-monoio = "0.1.0"
monoio = "0.2"
fastwebsockets-monoio = "0.10"
anyhow = "1.0"

Examples

Basic WebSocket Connection

use fastwebsockets_monoio::{Frame, OpCode};
use websockets_monoio::WsClient;

#[monoio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to a WebSocket server
    let mut client = WsClient::connect(
        "wss://echo.websocket.org/",
        &[],
    ).await?;

    // Send a text message
    client
        .ws
        .write_frame(Frame::text("Hello, WebSocket!".as_bytes().to_vec().into()))
        .await?;

    // Read the response
    let frame = client.ws.read_frame().await?;
    match frame.opcode {
        OpCode::Text => {
            let text = std::str::from_utf8(&frame.payload)?;
            println!("Received: {}", text);
        }
        OpCode::Close => {
            println!("Connection closed by server");
        }
        _ => {}
    }

    Ok(())
}

Cryptocurrency Exchange Streaming

use fastwebsockets_monoio::{Frame, OpCode};
use websockets_monoio::WsClient;

#[monoio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to Binance ticker stream
    let mut client = WsClient::connect(
        "wss://stream.binance.com:9443/ws/btcusdt@trade",
        &[],
    ).await?;

    // Subscribe to trades
    let subscribe = r#"{"method":"SUBSCRIBE","params":["btcusdt@trade"],"id":1}"#;
    client
        .ws
        .write_frame(Frame::text(subscribe.as_bytes().to_vec().into()))
        .await?;

    // Stream trade data
    loop {
        let frame = client.ws.read_frame().await?;
        match frame.opcode {
            OpCode::Text => {
                let text = std::str::from_utf8(&frame.payload)?;
                println!("Trade: {}", text);
            }
            OpCode::Binary => {
                println!("Binary frame ({} bytes)", frame.payload.len());
            }
            OpCode::Close => {
                println!("Stream closed");
                break;
            }
            OpCode::Ping | OpCode::Pong => {
                // Auto-handled by fastwebsockets
            }
            _ => {}
        }
    }

    Ok(())
}

Custom Headers

use websockets_monoio::WsClient;

#[monoio::main]
async fn main() -> anyhow::Result<()> {
    // Connect with custom headers
    let client = WsClient::connect(
        "wss://api.example.com/ws",
        &[
            ("Authorization", "Bearer your-token"),
            ("User-Agent", "YourApp/1.0"),
        ],
    ).await?;

    // Use the client...
    Ok(())
}

API Reference

WsClient

The main client struct for WebSocket connections.

Methods

• connect(url: &str, extra_headers: &[(&str, &str)]) -> Result<Self> - Connect to a WebSocket URL
• into_inner(self) -> WebSocket<WsStream> - Get the underlying WebSocket stream

Supported URL Schemes

• ws:// - Plain WebSocket connections
• wss:// - TLS-encrypted WebSocket connections

Performance Characteristics

This library is optimized for high-frequency trading and real-time applications:

• Zero-copy frame handling where possible
• Efficient TLS via rustls with ring cryptography
• io_uring integration for minimal syscall overhead on Linux
• Auto-pong/auto-close handling to reduce application overhead

Platform Support

• Linux: Full support with io_uring
• macOS/Windows: Limited support (falls back to standard async I/O)

For maximum performance, deploy on Linux with kernel version 5.1+ for full io_uring support.