Skip to content

PeerPigeon ​

The mesh: browsers and servers linked over WebRTC, with signed storage that replicates between them.

bash
npm install peerpigeon

GitHub · npm · Quick start

What it gives an app ​

  • A partial mesh. Each peer keeps between minPeers and maxPeers links, chosen and repaired as peers come and go, through FreeRTC relays.
  • Gossip and direct messages. broadcast reaches the whole room; sendDirect reaches one peer, routed hop by hop across the mesh by CECR.
  • Encryption. A room cipher and per-peer keys: broadcastEncrypted and sendEncryptedDirect.
  • Signed, synced storage. Records in five spaces, signed by their writers, synced to the room and kept on storage servers. See Storage.
  • Relay choice. It joins the room's closest healthy relays, local ones first (how).

The node ​

js
import { PeerPigeonNode } from 'peerpigeon'

const node = new PeerPigeonNode({ networkId: 'my-app', sessionId: 'lobby', signalingServer: 'wss://peer.ooo/ws', automaticSignalingServer: true, storage: {} })
await node.start()

Options ​

OptionDefaultWhat it does
networkIdYour app's namespace. Peers meet only with the same network and room
sessionIdThe room
signalingServerThe relay to start from
signalingServersMore relays, used if the registry is empty or unreachable
automaticSignalingServerChoose the room's relays from the registry
relayDirectory_relays.peer.oooDNS directory of direct relays (false to use only the registry)
minPeers, maxPeersHow many links to keep
rolenoneWhat this peer is, announced to relays ('storage')
dialRolesanyDial only peers with these roles ([]: dial nobody, still answer)
iceServersFreeRTC'sICE servers for WebRTC (FreeRTC's defaults are public STUN servers)
cryptoonfalse to leave encryption out; { keyPair } to be the same identity as on another device; { persistKeyPair: 'session' } to keep it for this tab only
storageoffOptions to attach storage (replicate, servers, …)
debugoffPeerPigeon's own console messages

Methods ​

Method
start()Join the room (opens storage when asked for)
broadcast(data), broadcastReliable(data)To everyone in the room; the reliable one tracks delivery
sendDirect(peerId, data)To one peer, across the mesh
broadcastEncrypted(text), sendEncryptedDirect(peerId, text)The same, encrypted
getConnectedPeers()The peers linked to this one
getGlobalPeers(), getDiscoveredPeers()Peers known in the room
getPeerRole(peerId)The role a relay listed a peer with
connectToPeer(peerId)Dial a peer now, whatever its role
getKeyPair()This node's identity, secret keys included
currentRelay(), currentRelayName()The relay in use, as a URL and as a name to show
openStorage(sessionId, { owner })Another storage room, for example one owned by a single key
storageThis node's storage (see Storage)
storageServersIts link to the storage servers
destroy()Leave and close everything

Events ​

node.on(event, handler): ready, peerConnected, peerDisconnected, message, keyDiscovered, graphChanged, capacityChanged, deliveryProgress, deliveryComplete, deliveryTimeout, cecrStateChanged, error.

A message carries kind ('broadcast' or 'direct'), data, fromPeerId, encrypted, local (sent by this node) and hops.

In Node ​

The same package runs in Node, which is how storage servers and test peers run. WebRTC there comes from werift.

peer.ooo · peer to peer on PeerPigeon