Skip to content

FreeRTC ​

Relays that introduce peers and federate with each other. Run one on Cloudflare Workers or Node.

bash
npm install freertc

GitHub · 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 relayLocal relay
Runs onCloudflare Workers, with D1Node, on your own machine (node scripts/node-relay.mjs)
Addresswss://<worker>.<account>.workers.dev/ws or your domainws://<host>:8788/ws; behind NAT, a tunnel through a public relay
Reached by browsersDirectlyOver a punched WebRTC connection, or wss://<name>:8443/ws with its own name and certificate
Preferred by PeerPigeonAfter healthy local relaysFirst, when healthy

The browser client ​

js
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 ​

KindTypes
Discoveryannounce, withdraw, discover, peer_list, redirect
Negotiationconnect_request, connect_accept, connect_reject, offer, answer, ice_candidate, ice_end, renegotiate
Controlping, pong, bye, error, ack
Extensionext

peer.ooo · peer to peer on PeerPigeon