Skip to content

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 fieldPeerPigeon optionWhat it is
Networknetwork (and the announce's instance_id)networkIdYour app's namespace, for example pigeonfeed
Roomsession_idsessionIdA 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:

  1. 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.
  2. Tiers: a healthy local relay comes before every cloud relay. Healthy means under 5% failed joins and under 90% of capacity.
  3. 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).
  4. 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.

peer.ooo · peer to peer on PeerPigeon