Server Reference
This page documents the server-facing HTTP/WebSocket endpoints and the protobuf messages used for signaling.
HTTP endpoints (management)
Section titled “HTTP endpoints (management)”The server routes these endpoints by path only and does not check the HTTP
method, so any method reaches the handler; clients conventionally use GET,
which is what the AsyncAPI spec (server/api.yml) models.
Every path in the router switch of server/pkg/handler/handler.go is listed below, grouped by hub type. The query parameters match server/api.yml.
General
Section titled “General”GET /v1/status- health / version endpoint (public, read-only)GET /v1/admin/migrate?host={newHost}- start a zero-downtime migration: new connections are routed to the backup host while existing ones drain. Admin-gated: requires theAuthorizationheader (base64 of the server’sAPP_CLIENT_SECRET)
Static hubs (/v1/static-hubs/*)
Section titled “Static hubs (/v1/static-hubs/*)”Static hubs use client-supplied IDs and never expire: they are created out-of-band by an admin and joined via WebSocket.
GET /v1/static-hubs/join?id={hubId}- join an existing static hub. Accepts optionalpeerMetadata.GET /v1/static-hubs/create?id={hubId}- create a static (never-expires) hub. Admin-gated: requires theAuthorizationheader (base64 of the server’sAPP_CLIENT_SECRET). Plain HTTP (no WebSocket upgrade). Accepts optionalhubMetadata. Creation is out-of-band from the browser WebSocket API — browsers cannot set custom headers on a WebSocket handshake, so issue this request with a plain HTTP client (curl,fetchfrom a Node.js process), then connect with/v1/static-hubs/join.
Random hubs (/v1/random-hubs/*)
Section titled “Random hubs (/v1/random-hubs/*)”GET /v1/random-hubs/create- create a random hub (server assigns the hub ID, delivered to the client viahubInfoMessage). Accepts optionalpeerMetadataandhubMetadata.GET /v1/random-hubs/join?id={hubId}- join a random hub. Accepts optionalpeerMetadata.GET /v1/random-hubs/get?id={hubId}- get an existing random hub’s metadata as plain HTTP JSON (no WebSocket upgrade, no peer roster)
IP hubs (/v1/ip-hubs/*)
Section titled “IP hubs (/v1/ip-hubs/*)”GET /v1/ip-hubs/join-or-create- join or create an IP hub (server derives hubId from the request IP). Accepts optionalpeerMetadataandhubMetadata(used only on create)
Note: The docs repository contains
proto/definitions describing the WebSocket messages used by the server and client for signaling.
WebSocket protocol
Section titled “WebSocket protocol”The server speaks a binary protobuf-based protocol for efficiency. The primary messages are:
ClientMessage- messages sent from client to server (create/join, sendOffer, sendAnswer, etc.)ServerMessage- messages sent from server to client with hub info, offers, answers, peer join/leave notifications.
Typical flow
Section titled “Typical flow”- Client connects to the WS endpoint with the hub join/create path and query params
- Server responds with
ServerMessage.hubInfoMessagecontaining peer list and assignedmyPeerId - Clients exchange offers and answers via
ClientMessage.sendOfferMessage/ClientMessage.sendAnswerMessagewhich the server forwards to the target peer
Protobuf notes and best practices
Section titled “Protobuf notes and best practices”- Messages use string-encoded JSON for
metadatafields; keepmetadatasmall to avoid large messages. - Consider adding validation for maximum string lengths in server-side logic.
- For very high-performance scenarios, evaluate FlatBuffers but for developer ergonomics protobuf is a good default.
Example: offer exchange
Section titled “Example: offer exchange”The client will send a sendOfferMessage containing answerPeerId and offerSdp.
The server will forward this to the target peer as a ServerMessage.offerMessage.
Further reading
Section titled “Further reading”- See
proto/client_message.protoandproto/server_message.protoin the repository - SDK: SDK Reference
- Guides: Hub types