openws-server 0.1.2

WebSocket server with room-based messaging, private messages, HTTP broadcast, and configurable limits
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# openws-server

WebSocket server in Rust with room-based messaging, private messages, HTTP broadcast, and optional configuration. Designed as a standalone service that any frontend can consume.

## Quick start

```bash
# Run directly
cargo run

# Or with Docker
docker compose up
```

Server starts on `http://0.0.0.0:3000`.

## Protocol

Connect via WebSocket to `ws://localhost:3000/ws`. All messages are JSON with a `type` field.

### Client → Server

| type | fields |
|------|--------|
| `join` | `room`, `username` |
| `send` | `room`, `text` |
| `private` | `to`, `text` |
| `ping` | _(none)_ |

### Server → Client

| type | fields |
|------|--------|
| `joined` | `room`, `username` |
| `message` | `room`, `from`, `text`, `at` |
| `private` | `from`, `text` |
| `user_joined` | `room`, `username` |
| `user_left` | `room`, `username` |
| `error` | `code`, `message` |
| `pong` | _(none)_ |

## HTTP endpoints

| method | path | description |
|--------|------|-------------|
| GET | `/health` | server health with room/client counts |
| GET | `/stats` | per-room breakdown |
| POST | `/api/broadcast` | send a message to a room via HTTP |

### Broadcast from your backend

```bash
curl -X POST http://localhost:3000/api/broadcast \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{"room":"general","text":"hello from backend","from":"system"}'
```

The broadcast endpoint requires an API key set in `openws.toml` (or via `OPENWS_API_KEY` env var). The endpoint is disabled by default.

## Client library

Connect from any JavaScript/TypeScript frontend using the official client:

```bash
npm install openws-client
```

Or clone the repo directly:

```bash
git clone https://github.com/benjamin0mar/openws-client-js.git
```

```js
import { OpenWS } from "openws-client";

const ws = new OpenWS("ws://localhost:3000/ws");
await ws.join("general", "alice");
ws.on("message", (msg) => console.log(msg.from, msg.text));
```

## Configuration

Create a `openws.toml` file or use environment variables. Priority: env var > `openws.toml` > default.

```toml
[server]
host = "0.0.0.0"
port = 3000

[limits]
max_clients      = 1000
max_rooms        = 100
max_message_size = 8192
max_username_len = 32

[heartbeat]
ping_interval_secs = 30
pong_timeout_secs  = 10

[broadcast]
api_key = ""
```

Environment variables: `OPENWS_PORT`, `OPENWS_MAX_CLIENTS`, `OPENWS_PING_INTERVAL`, `OPENWS_API_KEY`.

## Stack

Rust 2021 · Tokio · Axum · serde_json · tracing · config-rs · Docker