openws-server 0.1.2

WebSocket server with room-based messaging, private messages, HTTP broadcast, and configurable limits
openws-server-0.1.2 is not a library.

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

# 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

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:

npm install openws-client

Or clone the repo directly:

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

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.

[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