onwardz
Server-side SDK for managing Onwardz rooms.
Use this in your Rust backend to create rooms, issue join tokens, and manage
room settings. Pairs with @onwardz/js
for browser clients.
Never use this crate in client-side code. It requires your API key, which must stay on the server.
Installation
[]
= "0.1"
Async, runtime-agnostic (built on reqwest). The examples below use tokio.
Quick start
use ;
# async
The token flow
The recommended pattern for production:
Your backend (Rust) Browser (@onwardz/js)
────────────────── ────────────────────
create_room() ──room_id──►
issue_token(room_id) ───token───► new OnwardzRoom({ roomId, token })
room.join()
Tokens expire after 1 hour by default (issue_token(&id, None)). Generate one
per user session.
API reference
OnwardzClient
use OnwardzClient;
// Default endpoint (https://api.onwardz.com/rpc)
let onwardz = new;
// Self-hosted deployment
let onwardz = builder
.server_url
.build;
OnwardzClient is cheap to clone and safe to share across tasks.
create_room(opts) -> CreateRoomResponse
# use ;
# async
list_rooms() -> Vec<Room>
# use OnwardzClient;
# async
delete_room(room_id)
Soft-delete a room. Active participants are not forcibly disconnected, but no new peers can join.
# use OnwardzClient;
# async
configure_room(room_id, opts)
Update room settings. Only the fields you set are changed; use the builder to express set vs clear.
# use ;
# async
| Setter | Clears with | Description |
|---|---|---|
max_participants(n) |
clear_max_participants() |
Participant cap |
expires_at(ts) |
clear_expiry() |
ISO 8601 expiry |
metadata(v) |
— | Arbitrary JSON attached to the room |
allowed_origins(v) |
— | Origin allow-list for browser clients |
theme(t) |
clear_theme() |
Curated look for <onwardz-room> |
issue_token(room_id, ttl_seconds) -> IssueTokenResponse
Issue a signed JWT that lets a browser client join room_id without the API
key. None uses the default 1-hour TTL.
# use OnwardzClient;
# async
Error handling
Calls return OnwardzError. Match rpc_code() against RpcErrorCode to handle
known server conditions by name:
use ;
# async
| Variant | Code | Meaning |
|---|---|---|
RoomNotFound |
-32000 | Room does not exist or was deleted |
PeerNotFound |
-32001 | Peer ID not in signaling state |
Forbidden |
-32003 | Invalid or missing API key |
RoomFull |
-32004 | Room has reached its participant cap |
RoomExpired |
-32005 | Room's expiry timestamp has passed |
CapReached |
-32006 | Account monthly minute quota exhausted |
License
MIT