a40d16dae0
Add documentation for the new logging config options (output and level), including usage examples, field reference table, and updated project structure listing the internal/logging package.
156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
# WebSocket Relay Server
|
|
|
|
A minimal Go WebSocket relay server that broadcasts every incoming message to all connected clients. Supports TLS, Prometheus metrics, configurable logging, and graceful shutdown.
|
|
|
|
## Features
|
|
|
|
- **Fan-out broadcasting** — every message is relayed to all connected clients
|
|
- **TLS support** — optional `wss://` via cert/key PEM files
|
|
- **Prometheus metrics** — connection counts, message totals, disconnections
|
|
- **Configurable logging** — output to stdout, stderr, or file with level filtering
|
|
- **Graceful shutdown** — clean exit on SIGINT/SIGTERM with client notification
|
|
- **Zero dependencies at runtime** — single static binary
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install dependencies
|
|
go mod tidy
|
|
|
|
# Run the server (defaults to ws://localhost:8443)
|
|
make run
|
|
|
|
# Or with a custom config
|
|
go run . --config-file=./config.yaml
|
|
```
|
|
|
|
Open `example/index.html` in multiple browser tabs to test the P2P chat demo.
|
|
|
|
## Configuration
|
|
|
|
Edit `config.yaml`:
|
|
|
|
```yaml
|
|
server:
|
|
port: 8443
|
|
tls:
|
|
enabled: false # Set true for wss://
|
|
cert_file: cert.pem
|
|
key_file: key.pem
|
|
|
|
metrics:
|
|
enabled: true
|
|
port: 9090 # Prometheus metrics at :9090/metrics
|
|
|
|
logging:
|
|
output: stderr # stdout, stderr, or a file path
|
|
level: info # debug, info, warn, error
|
|
```
|
|
|
|
Override the config file path with `--config-file`:
|
|
|
|
```bash
|
|
./websocket-relay --config-file=/etc/relay/config.yaml
|
|
```
|
|
|
|
## Logging
|
|
|
|
The `logging` section controls where and what the server logs:
|
|
|
|
| Field | Values | Default | Description |
|
|
|-------|--------|---------|-------------|
|
|
| `output` | `stdout`, `stderr`, or a file path | `stderr` | Log output destination |
|
|
| `level` | `debug`, `info`, `warn`, `error` | `info` | Minimum log level to output |
|
|
|
|
**Examples:**
|
|
|
|
```yaml
|
|
# Log everything to a file
|
|
logging:
|
|
output: /var/log/websocket-relay.log
|
|
level: debug
|
|
|
|
# Quiet mode — only warnings and errors to stderr
|
|
logging:
|
|
output: stderr
|
|
level: warn
|
|
```
|
|
|
|
Log messages are prefixed with the level: `[DEBUG]`, `[INFO]`, `[WARN]`, `[ERROR]`.
|
|
|
|
File output uses append mode (`O_APPEND`) so logs are preserved across restarts and safe for external log rotation tools.
|
|
|
|
## Usage
|
|
|
|
Connect any WebSocket client to the server:
|
|
|
|
```javascript
|
|
const ws = new WebSocket('ws://localhost:8443/');
|
|
|
|
ws.onmessage = (event) => console.log('Received:', event.data);
|
|
ws.onopen = () => ws.send('Hello from client!');
|
|
```
|
|
|
|
With TLS enabled:
|
|
|
|
```javascript
|
|
const ws = new WebSocket('wss://localhost:8443/');
|
|
```
|
|
|
|
All messages sent by any client are broadcast to every connected client (including the sender).
|
|
|
|
## Build
|
|
|
|
```bash
|
|
make build # Build binary → build/websocket-relay
|
|
make release # Cross-compile linux/amd64 + darwin/arm64
|
|
make clean # Remove build artifacts
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
make test # Run all tests (unit + integration)
|
|
```
|
|
|
|
## Metrics
|
|
|
|
When `metrics.enabled` is `true`, Prometheus metrics are exposed at `http://localhost:9090/metrics`:
|
|
|
|
| Metric | Type | Description |
|
|
|--------|------|-------------|
|
|
| `websocket_connected_clients` | Gauge | Currently connected clients |
|
|
| `websocket_messages_total` | Counter | Total messages relayed |
|
|
| `websocket_connections_total` | Counter | Total connections established |
|
|
| `websocket_disconnections_total` | Counter | Total disconnections |
|
|
|
|
## Graceful Shutdown
|
|
|
|
The server handles `SIGINT` and `SIGTERM` signals:
|
|
|
|
1. Stops accepting new connections
|
|
2. Sends WebSocket `CloseGoingAway` frame to all connected clients
|
|
3. Closes all connections and exits cleanly
|
|
|
|
Shutdown timeout is 10 seconds.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
websocket-relay/
|
|
├── main.go # Entry point, signal handling, graceful shutdown
|
|
├── internal/
|
|
│ ├── config/config.go # YAML config loader
|
|
│ ├── hub/hub.go # WebSocket hub, connection management, broadcast
|
|
│ ├── logging/logging.go # Log output setup and leveled logger
|
|
│ └── metrics/metrics.go # Prometheus metric definitions
|
|
├── example/index.html # Browser P2P chat demo
|
|
├── config.yaml # Runtime configuration
|
|
├── config.example.yaml # Example config with TLS and logging
|
|
└── Makefile # Build, test, release commands
|
|
```
|
|
|
|
## License
|
|
|
|
See repository for license details.
|