initial commit

interfaces/websocket/server/cmd/README.md

@@ -0,0 +1,142 @@
+# Circles WebSocket Server Binary
+
+A command-line WebSocket server for hosting Circles with authentication and TLS support.
+
+## Binary: Server
+
+### Installation
+
+Build the binary:
+```bash
+cargo build --release
+```
+
+### Usage
+
+```bash
+# 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
+```bash
+# Simple development server
+cargo run
+
+# Development with authentication
+cargo run -- --auth
+```
+
+#### Production Server
+```bash
+# 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
+```bash
+# 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:
+
+```bash
+# 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