Skip to content
Get Started Playground

SDK Reference

This page documents the public surface of the ZeroHub Client SDK:

  • initialization and configuration
  • topologies (Mesh, SFU)
  • hub lifecycle (create/join/join-or-create)
  • peer lifecycle (offer/answer/accept)
Terminal window
npm install @zero-hub/client

Import and construct a client instance:

import { MeshTopology, ZeroHubClient, LogLevel } from "@zero-hub/client";
const client = new ZeroHubClient(
["sg1.zerohub.dev"],
{
tls: true,
logLevel: LogLevel.Warning,
},
new MeshTopology()
);
  • tls (boolean) - Use wss (TLS) for the server connection. Default: true.
  • logLevel (enum) - Logging level. Default: LogLevel.Warning.
  • logger (Logger) - Custom logger implementing the minimal logging functions.
  • waitIceCandidatesTimeout (number) - Milliseconds to wait for ICE candidates before sending offer/answer. Default: 2000.
  • autoAnswer / autoAcceptAnswer (boolean) - Automatic handling for incoming offers/answers. Default: true.
  • rtcConfig (RTCConfiguration) - RTCPeerConnection configuration (STUN/TURN servers, etc).
  • rtcOfferOptions (RTCOfferOptions) - Default offer options used when creating offers/answers. Example default: { offerToReceiveAudio: false, offerToReceiveVideo: false }.
  • dataChannelConfig (optional) - Configure data channel creation and handler.
  • mediaChannelConfig (optional) - Configure local media stream and track handling.
  • maxReconnectAttempts (number) - Same-host retries after an abnormal close (1006/1011) on the last configured host before the terminal onZeroHubError. Default: 10. The counter resets to zero when a connection is confirmed (the server’s hub info arrives).
  • reconnectBaseBackoffMs (number) - Base delay (ms) for the exponential backoff between same-host reconnect retries; each retry doubles the previous delay with ±20% jitter, capped at 30 s. Default: 250.
  • maxReconnectRounds (number) - Number of additional full sweeps through the configured host list (wrapping back to the first host after the last host’s retry budget is exhausted) before the terminal onZeroHubError. Default: 2. The round counter resets when a connection is confirmed (the server’s hub info arrives), when a migration redirect lands, or on disconnect().

When a signaling WebSocket closes abnormally (code 1006 abnormal close or 1011 internal error), the client reconnects automatically:

  • An established session (the server’s hub info has confirmed the connection at least once) first retries the same host with exponential backoff (base reconnectBaseBackoffMs, doubling each retry with ±20% jitter, capped at 30 s), up to maxReconnectAttempts attempts. A transient blip (NAT rebind, WiFi reassociation, laptop suspend/resume) is recovered this way without the application intervening.
  • The first connection (before any host has confirmed a session) fails over to the next configured host immediately instead — a single failure advances the host index exactly once, and each host gets a fresh retry budget.
  • When a host’s retry budget is exhausted the client moves on: to the next configured host, or — on the last host — wraps back to the first host for another full sweep, bounded by maxReconnectRounds sweeps (default 2).
  • Only when every host’s retry budget is spent on every allowed sweep does the terminal onZeroHubError fire; a manual disconnect() also leaves no recovery path, since the client never re-dials after an intentional teardown.

The retry budget and the sweep round reset to zero whenever a connection is confirmed (the server’s hub info arrives) or a migration redirect (close code 1001 with a well-formed backup host) lands, so a long-lived healthy session never accumulates backoff.

The library ships with two topology implementations. Select one by passing an instance as the third argument of the ZeroHubClient constructor; the default is MeshTopology.

Connects every peer to every other peer. It handles:

  • creating data channels (if configured)
  • creating offers/answers using a deterministic “higher-id creates offer” rule to avoid collisions
  • wiring media tracks from a local stream to remote peers

A star topology where one peer (the SFU) holds a direct connection to every other peer, and regular clients only ever connect to the SFU — two non-SFU peers never hold a direct connection. This is more scalable for larger groups than a full mesh.

import { SFUTopology, ZeroHubClient, LogLevel } from "@zero-hub/client";
const client = new ZeroHubClient(
["sg1.zerohub.dev"],
{ tls: true, logLevel: LogLevel.Warning },
new SFUTopology()
);
  • Election — By default the SFU is the peer with the numerically lowest peer id (compared with parseInt, not lexicographically, so "2" sorts before "10"). Pin a specific peer instead by passing its id to the constructor: new SFUTopology("42").
  • Offer direction — The SFU is always the offerer toward each client; the client auto-answers through the existing offer/answer path.
  • Re-election — When an implicitly elected SFU leaves the hub (PeerStatus.ZeroHubDisconnected), the remaining peers re-elect the numerically lowest remaining peer id as the new SFU and re-establish the star around it. A duplicate or delayed departure broadcast for the same departed peer does not re-run the election (no second set of connections). When an explicit sfuPeerId is set, no re-election happens — a departure from the designated SFU just logs a warning.
  • P2P drop recovery — When a peer’s WebRTC connection drops while the signaling socket is still alive (PeerStatus.WebRTCDisconnected), only the SFU side re-sends an offer to that client; the established data channels and transceivers are kept.

For genuinely custom strategies, implement the Topology interface (see client/src/topology in the repository) and pass an instance as the third argument of ZeroHubClient.

  • createRandomHub(peerMetadata?, hubMetadata?) / joinRandomHub(hubId, peerMetadata?) - random hub APIs
  • joinOrCreateIPHub(peerMetadata?, hubMetadata?) - IP hub API (hub id is derived from the caller’s IP)
  • joinStaticHub(hubId, peerMetadata?) - join an existing static (never-expires) hub

These entry points all return Promise<void>: the Promise resolves when the signaling WebSocket opens and rejects when the connection attempt fails (a failed dial — DNS failure / connection refused — or an abnormal close with a code other than 1000/1001/1006/1011). Note that “socket open” is not “hub joined”: the server’s hub info arrives after the socket opens, so hub join completion is still delivered via the onHubInfo callback (and subsequent peer activity via onPeerStatusChange). await the call to know the socket is open, but do not read myPeerId/peers immediately after the await — they are populated when onHubInfo fires. Since the Promise rejects on connection failure, handle the rejection (try/catch or .catch) instead of dropping the returned Promise.

Static hubs are created out-of-band via the admin HTTP endpoint GET /v1/static-hubs/create (requires the Authorization header), since the browser WebSocket API cannot send custom headers. Use an HTTP client (curl, fetch from a Node.js process) to create a static hub, then connect to it with joinStaticHub.

The SDK exposes high-level methods for WebRTC signaling:

  • sendOffer(peerId, rtcOfferOptions?, rtcConfig?) - create and send an offer to a peer
  • sendAnswer(peerId, offerSdp, rtcOfferOptions?, rtcConfig?) - generate and send an answer
  • acceptAnswer(peerId, answerSdp) - set remote answer SDP

The SDK will by default wait for ICE candidates for waitIceCandidatesTimeout ms before forcing the offer/answer to be sent.

The following methods are public on ZeroHubClient only so that tests and topology implementations can reach them. They are implementation details, not part of the stable public API, and may change or be removed without a major version bump.

MethodPurpose
reconnect(currentURL: URL, newHost?: string)Re-establishes the signaling WebSocket after an abnormal close. Called internally from the socket’s onclose handler.
connectToZeroHub(url: URL): Promise<void>Opens (or re-opens) a WebSocket to the given URL. Called internally by openHubConnection and the reconnection logic.
handleZeroHubMessage(serverMessage: ServerMessage)Dispatches a decoded ServerMessage to the appropriate handler (hub info, offer, answer, ICE candidate, peer join/disconnect). Called internally from the socket’s onmessage handler.
updatePeerStatus(peerId: string, status: PeerStatus)Updates a peer’s status in the internal peer map and fires onPeerStatusChange. Called internally by message dispatch and the ICE-ready callbacks.
sendOfferToWebsocket(peerId: string, offerSession: RTCSessionDescription)Sends an offer SDP to the server for the target peer and sets the peer status to Offering. Called internally by armSendOnIceReady.
sendAnswerToWebsocket(peerId: string, answerSession: RTCSessionDescription)Sends an answer SDP to the server for the target peer and sets the peer status to Answering. Called internally by armSendOnIceReady.
sendIceCandidateToWebsocket(peerId: string, candidate: RTCIceCandidate)Trickles an ICE candidate to the server for the target peer. Called internally by armSendOnIceReady.

Do not call these from application code; use the high-level entry points (createRandomHub, joinRandomHub, joinStaticHub, sendOffer, sendAnswer, acceptAnswer) instead.

  • onHubInfo(hubInfo) - fired when hub metadata or peer list updates
  • onPeerStatusChange(peer) - fired when a peer status changes (Pending, Connected, etc.)
  • onPeerError(peer, error) - fired when a per-peer WebRTC signaling exchange fails (creating/applying SDP or a media-track error); transient signaling-socket delivery failures are retried automatically and are not reported here
  • onOffer(peer, offerSdp) - fired when autoAnswer is false; complete the exchange by calling sendAnswer(peer.id, offerSdp)
  • onAnswer(peer, answerSdp) - fired when autoAcceptAnswer is false; complete the exchange by calling acceptAnswer(peer.id, answerSdp)
  • onZeroHubError(error) - when websocket or server errors occur
const topology = new MeshTopology();
const client = new ZeroHubClient(["sg1.zerohub.dev"], { logLevel: LogLevel.Debug }, topology);
client.config.dataChannelConfig = {
rtcDataChannelInit: { ordered: true },
onDataChannel: (peer, dc, isOwner) => {
dc.onmessage = (ev) => console.log(`from ${peer.id}:`, ev.data);
},
};
// `joinRandomHub` returns a Promise that resolves when the signaling socket
// opens and rejects on connection failure, so `await` it (or `.catch`) —
// never drop the returned Promise. The join itself completes later, when the
// `onHubInfo` callback fires, so don't read `myPeerId` or `peers` right
// after the `await`.
await client.joinRandomHub(
"my-random-hub-id", // random hub id returned to the creator via onHubInfo
{ displayName: "alice" } // peer metadata shared with other peers
);
  • See the guide: TypeScript SDK
  • Protocol messages are defined in the proto/ folder of the repository