Documentation

API Documentation

Complete API reference for WS-RS WebSocket server implementation in Rust.

Core Modules

WebSocketServer

Main server implementation for handling WebSocket connections.

use ws_rs::WebSocketServer;

let server = WebSocketServer::new("127.0.0.1:8080");
server.start().await?;

Connection Management

Handle client connections and disconnections.

server.on_connect(|client_id| {
    println!("Client {} connected", client_id);
});

server.on_disconnect(|client_id| {
    println!("Client {} disconnected", client_id);
});

Message Handling

Process incoming messages from clients.

server.on_message(|client_id, message| {
    println!("Received from {}: {}", client_id, message);
    
    // Echo back to sender
    server.send(client_id, message).await?;
    
    // Broadcast to all clients
    server.broadcast(message).await?;
});

Broadcasting

Send messages to multiple clients.

// Broadcast to all clients
server.broadcast("Hello everyone!").await?;

// Broadcast to specific room
server.broadcast_to_room("room1", "Room message").await?;

// Broadcast except sender
server.broadcast_except(sender_id, "Message").await?;

Configuration

use ws_rs::{WebSocketServer, Config};

let config = Config {
    max_connections: 10000,
    max_message_size: 10 * 1024 * 1024, // 10MB
    compression: true,
    compression_level: 6,
    ping_interval: 30, // seconds
    pong_timeout: 10,  // seconds
    ..Default::default()
};

let server = WebSocketServer::with_config("127.0.0.1:8080", config);

Error Handling

use ws_rs::{WebSocketServer, Error};

match server.send(client_id, message).await {
    Ok(_) => println!("Message sent successfully"),
    Err(Error::ClientNotFound) => println!("Client not connected"),
    Err(Error::MessageTooLarge) => println!("Message exceeds size limit"),
    Err(e) => println!("Error: {}", e),
}

Advanced Features

Rooms & Channels

// Join a room
server.join_room(client_id, "lobby").await?;

// Leave a room
server.leave_room(client_id, "lobby").await?;

// Get room members
let members = server.get_room_members("lobby").await?;

Custom Protocols

let server = WebSocketServer::builder()
    .bind("127.0.0.1:8080")
    .protocols(vec!["chat", "binary"])
    .build();

TLS/SSL Support

use ws_rs::tls::TlsConfig;

let tls_config = TlsConfig {
    cert_path: "cert.pem",
    key_path: "key.pem",
};

let server = WebSocketServer::builder()
    .bind("0.0.0.0:443")
    .tls(tls_config)
    .build();

Message Types

use ws_rs::Message;

// Text message
let msg = Message::Text("Hello".to_string());

// Binary message
let msg = Message::Binary(vec![1, 2, 3]);

// Ping/Pong
let msg = Message::Ping(vec![]);
let msg = Message::Pong(vec![]);

// Close
let msg = Message::Close(Some((1000, "Normal closure".to_string())));

Performance Tips

Connection Pooling - Reuse connections when possible
Message Batching - Send multiple small messages as one
Compression - Enable for text-heavy applications
Backpressure - Handle slow clients gracefully
Load Balancing - Distribute connections across multiple servers

Examples

Check out the examples directory for complete working examples:

echo-server - Simple echo server
chat-server - Multi-room chat application
broadcast - Broadcasting messages to all clients
secure - TLS/SSL secured WebSocket server

📚 WS-RS Documentation