FreeRTC
Relays that introduce peers and federate with each other. Run one on Cloudflare Workers or Node.
npm install freertcGitHub · npm · Run a relay
What a relay does
A FreeRTC relay accepts WebSocket connections at /ws and speaks PSP:
- peers announce themselves in a network and room, and discover the others there;
- it carries the offer, answer and ICE messages that let two peers open a WebRTC connection;
- it queues directed messages for a peer that is reconnecting.
That is all: signaling only. Once peers are connected, nothing else goes through it.
Federation
Relays find each other through a Kademlia overlay: a relay's id is the SHA-256 of its signing key, and a room's providers are kept on the five relays closest to the room's key. Discovery asks at most eight providers; a message for one peer goes to at most two. There is no hub: a new relay joins through any of its seed relays and carries on from the relays they name.
So two peers on different relays meet when they use the same network and room.
Cloud and local relays
| Cloud relay | Local relay | |
|---|---|---|
| Runs on | Cloudflare Workers, with D1 | Node, on your own machine (node scripts/node-relay.mjs) |
| Address | wss://<worker>.<account>.workers.dev/ws or your domain | ws://<host>:8788/ws; behind NAT, a tunnel through a public relay |
| Reached by browsers | Directly | Over a punched WebRTC connection, or wss://<name>:8443/ws with its own name and certificate |
| Preferred by PeerPigeon | After healthy local relays | First, when healthy |
The browser client
import { createSignalingClient } from 'freertc/client'
const client = createSignalingClient({
peerId: crypto.randomUUID(),
networkId: 'my-app',
roomId: 'pairing-room',
signalUrl: 'wss://peer.ooo/ws',
onDataMessage: ({ peerId, data }) => console.log(peerId, data),
})
client.connect()client.initiateConnection(peerId) opens a data channel and client.sendData(data, peerId) sends on it. PeerPigeon uses this client under its mesh; most apps use PeerPigeon instead of calling it directly.
Relay on demand. With a way to carry negotiation over the mesh (signalTransport) and relay: { mode: 'on-demand' }, a peer with a healthy mesh lets its relay socket go, and wakes it when it needs it. A few anchors, the peers closest to the room, stay registered so newcomers still find a way in.
Messages
| Kind | Types |
|---|---|
| Discovery | announce, withdraw, discover, peer_list, redirect |
| Negotiation | connect_request, connect_accept, connect_reject, offer, answer, ice_candidate, ice_end, renegotiate |
| Control | ping, pong, bye, error, ack |
| Extension | ext |