Skip to content
Get Started Playground

Server Reference

This page documents the server-facing HTTP/WebSocket endpoints and the protobuf messages used for signaling.

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.

  • 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 the Authorization header (base64 of the server’s APP_CLIENT_SECRET)

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 optional peerMetadata.
  • GET /v1/static-hubs/create?id={hubId} - create a static (never-expires) hub. Admin-gated: requires the Authorization header (base64 of the server’s APP_CLIENT_SECRET). Plain HTTP (no WebSocket upgrade). Accepts optional hubMetadata. 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, fetch from a Node.js process), then connect with /v1/static-hubs/join.
  • GET /v1/random-hubs/create - create a random hub (server assigns the hub ID, delivered to the client via hubInfoMessage). Accepts optional peerMetadata and hubMetadata.
  • GET /v1/random-hubs/join?id={hubId} - join a random hub. Accepts optional peerMetadata.
  • GET /v1/random-hubs/get?id={hubId} - get an existing random hub’s metadata as plain HTTP JSON (no WebSocket upgrade, no peer roster)
  • GET /v1/ip-hubs/join-or-create - join or create an IP hub (server derives hubId from the request IP). Accepts optional peerMetadata and hubMetadata (used only on create)

Note: The docs repository contains proto/ definitions describing the WebSocket messages used by the server and client for signaling.

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.
  1. Client connects to the WS endpoint with the hub join/create path and query params
  2. Server responds with ServerMessage.hubInfoMessage containing peer list and assigned myPeerId
  3. Clients exchange offers and answers via ClientMessage.sendOfferMessage / ClientMessage.sendAnswerMessage which the server forwards to the target peer
  • Messages use string-encoded JSON for metadata fields; keep metadata small 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.

The client will send a sendOfferMessage containing answerPeerId and offerSdp. The server will forward this to the target peer as a ServerMessage.offerMessage.

  • See proto/client_message.proto and proto/server_message.proto in the repository
  • SDK: SDK Reference
  • Guides: Hub types