hero/interfaces/websocket/server/cmd/README.md

Circles WebSocket Server Binary

A command-line WebSocket server for hosting Circles with authentication and TLS support.

Binary: Server

Installation

Build the binary:

cargo build --release

Usage

# Basic usage - starts server on localhost:8443
cargo run

# Custom host and port
cargo run -- --host 0.0.0.0 --port 9000

# Enable authentication
cargo run -- --auth

# Enable TLS/WSS with certificates
cargo run -- --tls --cert /path/to/cert.pem --key /path/to/key.pem

# Use separate TLS port
cargo run -- --tls --cert cert.pem --key key.pem --tls-port 8444

# Custom Redis URL
cargo run -- --redis-url redis://localhost:6379/1

# Increase verbosity
cargo run -- -v          # Debug logging
cargo run -- -vv         # Full debug logging
cargo run -- -vvv        # Trace logging

Command-Line Options

Option	Short	Default	Description
--host	-H	127.0.0.1	Server bind address
--port	-p	8443	Server port
--redis-url		redis://127.0.0.1/	Redis connection URL
--auth		false	Enable secp256k1 authentication
--tls		false	Enable TLS/WSS support
--cert			Path to TLS certificate file (required with --tls)
--key			Path to TLS private key file (required with --tls)
--tls-port			Separate port for TLS connections
--verbose	-v		Increase verbosity (stackable)

Configuration Examples

Development Server

# Simple development server
cargo run

# Development with authentication
cargo run -- --auth

Production Server

# Production with TLS and authentication
cargo run -- \
  --host 0.0.0.0 \
  --port 8080 \
  --tls \
  --tls-port 8443 \
  --cert /etc/ssl/certs/circles.pem \
  --key /etc/ssl/private/circles.key \
  --auth \
  --redis-url redis://redis-server:6379/0

Custom Redis Configuration

# Connect to remote Redis with authentication
cargo run -- --redis-url redis://username:password@redis.example.com:6379/2

Logging Levels

The server supports multiple verbosity levels:

• Default (cargo run): Shows only warnings and circle_ws_lib info
• Debug (-v): Shows debug info for circle_ws_lib, info for actix
• Full Debug (-vv): Shows debug for all components
• Trace (-vvv+): Shows trace-level logging for everything

TLS/SSL Configuration

When using --tls, you must provide both certificate and key files:

# Generate self-signed certificate for testing
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Run server with TLS
cargo run -- --tls --cert cert.pem --key key.pem

Authentication

When --auth is enabled, clients must complete secp256k1 authentication:

1. Client connects to WebSocket
2. Server sends authentication challenge
3. Client signs challenge with private key
4. Server verifies signature and grants access

Redis Integration

The server uses Redis for:

• Session management
• Message persistence
• Cross-instance communication (in clustered deployments)

Supported Redis URL formats:

• redis://localhost/ - Local Redis, default database
• redis://localhost:6379/1 - Local Redis, database 1
• redis://user:pass@host:port/db - Authenticated Redis
• rediss://host:port/ - Redis with TLS

Error Handling

The server provides clear error messages for common configuration issues:

• Missing TLS certificate or key files
• Invalid Redis connection URLs
• Port binding failures
• Authentication setup problems

Dependencies

• actix-web: Web server framework
• tokio-tungstenite: WebSocket implementation
• redis: Redis client
• rustls: TLS implementation
• clap: Command-line argument parsing