Crate fast_websocket_client

fast_websocket_client

A blazing-fast, async-native WebSocket client for Rust, built on top of fastwebsockets and tokio.

Supports two modes of operation:

• 🔁 High-level callback-based client for ergonomic event-driven use.
• ⚙️ Low-level direct API for fine-tuned control with minimal dependencies.

Quick Example: examples/async_callback_client.rs

📦 Features

• Async/await support via tokio
• Built-in reconnection and ping loop
• Optional callback-driven lifecycle management
• Custom HTTP headers for handshake (e.g., Authorization)

🛠 Installation

cargo add fast_websocket_client

🔁 High-Level Callback API

An ergonomic, JavaScript-like API with built-in reconnect, ping, and lifecycle hooks.

// try this example with
// `cargo run --example wss_client`

use tokio::time::{Duration, sleep};
use fast_websocket_client::WebSocket;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), fast_websocket_client::WebSocketClientError> {
    let ws = WebSocket::new("wss://echo.websocket.org").await?;

    ws.on_close(|_| async move {
        println!("[CLOSE] WebSocket connection closed.");
    })
    .await;
    ws.on_message(|message| async move {
        println!("[MESSAGE] {}", message);
    })
    .await;

    sleep(Duration::from_secs(1)).await;
    for i in 1..5 {
        let message = format!("#{}", i);
        if let Err(e) = ws.send(&message).await {
            eprintln!("[ERROR] Send error: {:?}", e);
            break;
        }
        println!("[SEND] {}", message);
        sleep(Duration::from_secs(5)).await;
    }

    ws.close().await;
    ws.await_shutdown().await;
    Ok(())
}

🧵 Low-Level API

use fast_websocket_client::{connect, OpCode};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let mut client = connect("wss://echo.websocket.org").await?;

    client.send_string("Hello, WebSocket!").await?;

    let frame = client.receive_frame().await?;
    if frame.opcode == OpCode::Text {
        println!("Received: {}", String::from_utf8_lossy(&frame.payload));
    }

    client.send_close("bye").await?;
    Ok(())
}

🧪 Running the Example

Clone the repo and run:

cargo run --example wss_client

🔄 Migration Guide (from 0.2.0)

Old	New
client::Offline	base_client::Offline
client::Online	base_client::Online
Runtime settings via Online’s methods	Must now be set before connect via ConnectionInitOptions. Changes to the running WebSocket take effect on the next (re)connection.

New users: We recommend starting with the WebSocket API for best experience.

📚 Documentation

• docs.rs/fast_websocket_client
• Examples
• fastwebsockets upstream

---

💡 Actively maintained – contributions are welcome!

Re-exports

pub use base_client::connect;

pub use client as callback_client;

pub use client::ClientConfig;

pub use client::ConnectionInitOptions;

pub use client::WebSocket;

pub use client::WebSocketBuilder;

pub use client::WebSocketClientError;

Modules

base_client

client

Structs

HeaderMap

A set of HTTP headers

Enums

OpCode