# 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