Networks, rooms and relays
Two names decide who a peer can meet: its network and its room. Peers find each other only when both match, whichever relay each of them is on.
Network and room
| PSP field | PeerPigeon option | What it is | |
|---|---|---|---|
| Network | network (and the announce's instance_id) | networkId | Your app's namespace, for example pigeonfeed |
| Room | session_id | sessionId | A group inside it, for example global or a game's id |
The relay's domain is not a boundary: peer.ooo and decentralize.ooo federate, so peers that use the same network and room meet even on different relays.
Roles
A peer can say what it is with a role, a short lowercase word in its announce (storage for a storage server). Relays list peers with a role before the rest, so in a room with many people and a few servers the servers are never cut from a list. In PeerPigeon:
role: 'storage'makes a node announce itself as one;dialRoles: ['storage']makes a node dial only peers with that role (it still answers dials from anyone);node.getPeerRole(peerId)reads the role a relay listed a peer with.
How a peer chooses its relay
With automaticSignalingServer: true, a peer reads the relay registry (/api/v1/relays) from the relay it was given, then:
- Candidates: the room's five relays closest to the key FreeRTC publishes the room under, so a room's peers gather on a few relays.
- Tiers: a healthy local relay comes before every cloud relay. Healthy means under 5% failed joins and under 90% of capacity.
- Score, lower wins: the measured join time, plus 2,000 for each unit of failure rate and 1,000 for each unit of load (and 300 for a relay reached only through its tunnel).
- Hysteresis: a peer keeps the relay it used last unless another is in a better tier or at least 30% better.
Peers measure each join and share their measurements with new neighbours, so a page benefits from what others have seen. The details are in PeerPigeon's RELAYS.md.
Local and cloud relays
A cloud relay is a Cloudflare Worker. A local relay runs the same code under Node, on someone's own machine; behind NAT it reaches the network through a tunnel to a public relay, and browsers reach it over a punched WebRTC connection. Local relays can have their own name and certificate (for example ef0d4c0a988ec0d2.decentralize.ooo), so browsers anywhere reach them over wss://. See Run a relay.
Relays are signaling only
A relay passes announcements, discovery answers and the offer, answer and ICE messages of a connection. Once two browsers are connected, nothing they say to each other goes through it. Relays keep no data for apps: that is what storage servers are for.