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)
Installation
Section titled “Installation”npm install @zero-hub/clientInitialization
Section titled “Initialization”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());Config reference
Section titled “Config reference”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 terminalonZeroHubError. 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 terminalonZeroHubError. Default:2. The round counter resets when a connection is confirmed (the server’s hub info arrives), when a migration redirect lands, or ondisconnect().
Automatic reconnection
Section titled “Automatic reconnection”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 tomaxReconnectAttemptsattempts. 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
maxReconnectRoundssweeps (default2). - Only when every host’s retry budget is spent on every allowed sweep does
the terminal
onZeroHubErrorfire; a manualdisconnect()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.
Topologies: Mesh and SFU
Section titled “Topologies: Mesh and SFU”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.
MeshTopology
Section titled “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
SFUTopology
Section titled “SFUTopology”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 explicitsfuPeerIdis 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.
Hub lifecycle
Section titled “Hub lifecycle”createRandomHub(peerMetadata?, hubMetadata?)/joinRandomHub(hubId, peerMetadata?)- random hub APIsjoinOrCreateIPHub(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.
Peer lifecycle and signaling
Section titled “Peer lifecycle and signaling”The SDK exposes high-level methods for WebRTC signaling:
sendOffer(peerId, rtcOfferOptions?, rtcConfig?)- create and send an offer to a peersendAnswer(peerId, offerSdp, rtcOfferOptions?, rtcConfig?)- generate and send an answeracceptAnswer(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.
Internal / advanced
Section titled “Internal / advanced”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.
| Method | Purpose |
|---|---|
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.
Events
Section titled “Events”onHubInfo(hubInfo)- fired when hub metadata or peer list updatesonPeerStatusChange(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 hereonOffer(peer, offerSdp)- fired whenautoAnswerisfalse; complete the exchange by callingsendAnswer(peer.id, offerSdp)onAnswer(peer, answerSdp)- fired whenautoAcceptAnswerisfalse; complete the exchange by callingacceptAnswer(peer.id, answerSdp)onZeroHubError(error)- when websocket or server errors occur
Example: data channel chat
Section titled “Example: data channel chat”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);Further reading
Section titled “Further reading”- See the guide: TypeScript SDK
- Protocol messages are defined in the
proto/folder of the repository