RustySocks

Welcome to RustySocks, a high-performance, security-first WebSocket server built in Rust. Designed for real-time applications that demand reliability, scalability, and enterprise-grade security.

Why RustySocks?

In the world of real-time communication, security often takes a backseat to performance. RustySocks changes that paradigm by providing:

Military-grade security without compromising speed
Sub-millisecond latency for demanding applications
Battle-tested in production environments handling millions of connections
Developer-friendly APIs that make complex tasks simple

Key Features

🛡️ Security First

Advanced rate limiting with multi-tier protection
Built-in XSS and CSRF protection
Comprehensive security event logging
TLS certificate validation and monitoring
Production environment warnings

⚡ Performance

Zero-copy message handling
Optimized broadcast algorithms
Connection pooling and reuse
Minimal memory footprint
Benchmarked at 1M+ concurrent connections

🔧 Developer Experience

Simple, intuitive API
Extensive documentation and examples
Plugin architecture for extensibility
Comprehensive error handling
Full TypeScript client support

Use Cases

RustySocks excels in scenarios requiring:

Real-time Trading: Sub-millisecond message delivery for financial markets
Gaming Servers: Low-latency state synchronization for multiplayer games
IoT Platforms: Efficient device-to-cloud communication
Collaborative Tools: Real-time document editing and screen sharing
Live Streaming: Chat and interaction systems for millions of viewers

Quick Example

use rusty_socks::{Server, ServerConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ServerConfig::from_env()?;
    let server = Server::new(config).await?;
    
    println!("RustySocks server running on {}", server.address());
    server.run().await?;
    
    Ok(())
}

Ready to Start?

Head over to the Installation Guide to get RustySocks up and running in minutes.

For a quick hands-on experience, check out our Quick Start Tutorial.

Community

Join our growing community:

GitHub Discussions - Ask questions and share ideas

License

RustySocks is open source under the MIT license. See LICENSE for details.

Installation

RustySocks can be installed and deployed in multiple ways depending on your needs.

Prerequisites

Rust 1.75 or higher (for building from source)
OpenSSL or LibreSSL (for TLS support)
Docker (optional, for containerized deployment)

Installation Methods

Using Cargo (Recommended)

The simplest way to install RustySocks is through Cargo:

cargo install rusty-socks

Building from Source

For the latest features or custom modifications:

git clone https://github.com/egdavid/rusty-socks.git
cd rusty-socks
cargo build --release

The binary will be available at target/release/rusty-socks.

Using Docker

Pull the official Docker image:

docker pull rustysocks/server:latest

Or use Docker Compose:

version: '3.8'
services:
  rustysocks:
    image: rustysocks/server:latest
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      - RUST_LOG=info
      - JWT_SECRET=${JWT_SECRET}
    volumes:
      - ./config:/etc/rustysocks
      - ./certs:/certs

Package Managers

Homebrew (macOS/Linux)

brew tap rustysocks/tap
brew install rustysocks

APT (Debian/Ubuntu)

curl -fsSL https://rustysocks.io/install/apt-key.gpg | sudo apt-key add -
echo "deb https://rustysocks.io/apt stable main" | sudo tee /etc/apt/sources.list.d/rustysocks.list
sudo apt update
sudo apt install rustysocks

Verifying Installation

After installation, verify RustySocks is working:

rustysocks --version

You should see output like:

rustysocks 0.1.0

System Requirements

Minimum Requirements

CPU: 1 core
RAM: 512MB
Disk: 50MB
Network: 1Gbps recommended

Production Requirements

For production deployments handling 10k+ concurrent connections:

CPU: 4+ cores
RAM: 8GB+
Disk: SSD with 100GB+
Network: 10Gbps+

Operating System Support

RustySocks is tested on:

Linux: Ubuntu 20.04+, Debian 11+, RHEL 8+, Alpine 3.15+
macOS: 11.0+ (Big Sur and later)
Windows: Windows Server 2019+, Windows 10+
BSD: FreeBSD 13+, OpenBSD 7.0+

TLS Certificate Setup

For production use, you'll need TLS certificates:

Using Let's Encrypt

certbot certonly --standalone -d yourdomain.com

Self-signed (Development Only)

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Next Steps

Configure your server: Configuration Guide
Run your first server: Quick Start Tutorial
Deploy to production: Production Checklist

Quick Start

Get a RustySocks server running in under 5 minutes!

Step 1: Install RustySocks

cargo install rusty-socks

Step 2: Create Configuration

Create a .env file with minimal configuration:

# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# Security (Generate secure values for production!)
JWT_SECRET=your-secret-key-change-this
ENCRYPTION_KEY=your-32-byte-encryption-key-here

# Optional: Enable TLS
# TLS_CERT_PATH=/path/to/cert.pem
# TLS_KEY_PATH=/path/to/key.pem

Step 3: Run the Server

rustysocks serve

You should see:

[INFO] RustySocks v0.1.0 starting...
[INFO] Server listening on ws://0.0.0.0:8080
[INFO] Security checks passed
[INFO] Ready to accept connections

Step 4: Connect a Client

Using JavaScript/TypeScript

const ws = new WebSocket('ws://localhost:8080/ws');

ws.onopen = () => {
    console.log('Connected to RustySocks!');
    
    // Send authentication
    ws.send(JSON.stringify({
        type: 'AUTH',
        payload: {
            token: 'your-jwt-token'
        }
    }));
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('Received:', message);
};

// Join a room
ws.send(JSON.stringify({
    type: 'JOIN_ROOM',
    payload: {
        room_id: 'general'
    }
}));

// Broadcast a message
ws.send(JSON.stringify({
    type: 'BROADCAST',
    payload: {
        room_id: 'general',
        message: 'Hello, RustySocks!'
    }
}));

Using the RustySocks Client Library

import { RustySocksClient } from 'rustysocks-client';

const client = new RustySocksClient('ws://localhost:8080');

await client.connect();
await client.authenticate('your-jwt-token');
await client.joinRoom('general');

client.on('message', (msg) => {
    console.log('Received:', msg);
});

await client.broadcast('general', 'Hello, RustySocks!');

Step 5: Monitor Your Server

Check server health:

curl http://localhost:8080/health

View metrics:

curl http://localhost:8080/metrics

Example: Simple Chat Server

Here's a complete example of a chat server:

Server Configuration

use rusty_socks::{Server, ServerConfig, MessageHandler, Message};
use std::sync::Arc;

#[derive(Clone)]
struct ChatHandler;

#[async_trait::async_trait]
impl MessageHandler for ChatHandler {
    async fn handle_message(
        &self,
        message: Message,
        context: Arc<rusty_socks::Context>
    ) -> rusty_socks::Result<()> {
        match message.message_type.as_str() {
            "CHAT" => {
                // Broadcast to all users in the room
                context.broadcast_to_room(
                    &message.room_id.unwrap_or_default(),
                    message
                ).await?;
            }
            _ => {}
        }
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ServerConfig::from_env()?;
    let server = Server::builder()
        .config(config)
        .handler(ChatHandler)
        .build()
        .await?;
    
    server.run().await?;
    Ok(())
}

HTML Client

<!DOCTYPE html>
<html>
<head>
    <title>RustySocks Chat</title>
</head>
<body>
    <div id="messages"></div>
    <input type="text" id="input" placeholder="Type a message...">
    <button onclick="sendMessage()">Send</button>

    <script>
        const ws = new WebSocket('ws://localhost:8080/ws');
        const messages = document.getElementById('messages');
        
        ws.onmessage = (event) => {
            const msg = JSON.parse(event.data);
            if (msg.type === 'CHAT') {
                const div = document.createElement('div');
                div.textContent = msg.payload.message;
                messages.appendChild(div);
            }
        };
        
        function sendMessage() {
            const input = document.getElementById('input');
            ws.send(JSON.stringify({
                type: 'CHAT',
                room_id: 'general',
                payload: {
                    message: input.value
                }
            }));
            input.value = '';
        }
    </script>
</body>
</html>