rustwave 0.1.0

<p align="center">
  <img src="assets/logo.png" alt="RustWave Logo" width="180">
</p>
<h1 align="center">RustWave</h1>

<p align="center">
  Lightweight asynchronous event-driven WebSocket framework for Rust.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Rust-1.94%2B-orange?logo=rust" alt="Rust">
  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT">
  <img src="https://img.shields.io/badge/Async-Tokio-success?logo=tokio" alt="Tokio">
  <img src="https://img.shields.io/badge/WebSocket-Event--Driven-green" alt="WebSocket">
</p>

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`:

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

## Quick Start

### Server

```rust
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

```rust
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.

- 📖 [Examples Guide](examples/README.md)


## 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

- [x] Event-driven API
- [x] Async WebSocket server
- [x] Async WebSocket client
- [x] Rooms
- [x] Namespaces
- [x] Broadcasting
- [x] Broadcast except sender
- [x] Typed payload parsing
- [x] Client disconnection
- [x] 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.