rustwave 0.1.0

A lightweight async event-driven WebSocket framework for Rust
Documentation

RustWave is a lightweight asynchronous WebSocket framework for Rust that provides a clean, event-driven API for building real-time applications. Built on Tokio, RustWave offers namespaces, rooms, broadcasting, and typed payloads while keeping the API simple and ergonomic.

Features

  • Async WebSocket server & client
  • Event-driven API
  • Namespaces
  • Rooms
  • Broadcasting
  • Typed payload parsing
  • Built on Tokio
  • Simple and ergonomic API

Why RustWave?

  • Simple event-driven API
  • Built on Tokio
  • Typed payload parsing
  • Namespaces and rooms
  • Minimal dependencies
  • Easy to integrate into existing projects

Installation

Add RustWave to your Cargo.toml:

[dependencies]
rustwave = "0.1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

Server

use rustwave::{Result, Server};

#[tokio::main]
async fn main() -> Result<()> {
    let server = Server::bind("127.0.0.1:8080");

    server.on("message", |data, ctx| async move {
        println!("Client {} says: {}", ctx.get_socket_id(), data);
    });

    server.run().await?;
    Ok(())
}

Client

use rustwave::{Client, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = Client::connect("ws://127.0.0.1:8080").await?;

    client.on("message", |data| async move {
        println!("Client got message: {}", data);
    });

    client.emit("message", "Hello Server!".to_string()).await?;

    client.wait().await;

    Ok(())
}

Examples

For a complete example, see the examples directory.

API Overview

Type Responsibility
Server Binds to an address, manages namespaces, accepts incoming connections
Namespace Isolated event/room registry for a specific path (e.g. /chat)
Client Connects to a RustWave server and exchanges events
PeerContext Handle for a connected socket — emit, broadcast, join/leave rooms
Payload Wraps incoming event data, parseable into any Deserialize type

Benchmark

Test Environment

  • CPU: Intel(R) Core(TM) i3-3220 CPU @ 3.30GHz
  • RAM: 4 GB
  • OS: Fedora Linux
  • Rust: 1.94.0
  • Build: cargo run --release

Echo Benchmark

Metric Value
Concurrent clients 10,000
Messages per client 100
Total messages 1,000,000
Message loss 0
Total time 8.88 s
Throughput 112,587 msgs/sec

Roadmap

  • Event-driven API
  • Async WebSocket server
  • Async WebSocket client
  • Rooms
  • Namespaces
  • Broadcasting
  • Broadcast except sender
  • Typed payload parsing
  • Client disconnection
  • Multiple event handlers
  • Middleware support
  • Authentication hooks
  • Automatic reconnection for clients
  • Binary message support
  • Configurable heartbeat (Ping/Pong)
  • Request/response acknowledgements (ACKs)
  • Custom serializer support
  • Connection metadata

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.