o2services-peer-relay v1.0.0

o2services-peer-relay

API

peer = new PeerRelay([opts])

Creates a new peer that becomes apart of the relay network

The following fields can be specified within opts:

• port - The port for the web socket server to listen on. If not defined, then a websocket server is not started
• bootstrap - an array of web socket urls to peers already connected to the network
• wrtc - custom nodejs webrtc implementation. Check out electron-webrtc or wrtc

port can only be specified if the peer is running nodejs since start a WebSocket server is not possible in a browser. Every peer should specify at least on bootstrap peer (unless that peer is the first/only peer in the network)

peer.id

The peer's id. id is 160 bit Buffer. This id is used to identify the peer within the network.

peer.connect(id)

Forms a direct connection with the given peer. id is the id of the peer to connect to and must be a Buffer.

Behind the scenes: a message will be relayed to that peer asking it what transports it supports (WebSocket and/or WebRTC). Then the connection will be formed based on this info; if webrtc is chosen then additional signaling info will be relayed before the connection is formed.

peer.disconnect(id)

Disconnect the a currently connected peer with id.

peer.send(id, data)

Send data to the peer with the id. data can be anything that is JSON serializable. The peer does not have to be directly connected to because it will be relayed through other peers. Message delivery or order is not guaranteed.

peer.destroy([cb])

Destroy the peer and free it's resources. An optional callback can be specified and will be called when all the resources are freed.

Events

peer.on('message', function (data, from) {})

Fired when a message addressed to the peer was received. from is the Buffer id of the peer that sent the message.

peer.on('peer', function (id) {})

Fired when a peer has been directly connected to

PeerRelay.Socket

var socket = new PeerRelay.Socket([opts])

Creates a new dgram like socket that uses peer-relay to send messages between peers instead of UDP. This allows for peer-relay to be used by programs that expect the dgram socket interface. This method accepts the same arguments as the PeerRelay constructor. The returned object tries to match the interface provided by dgram's Socket.

There are a few differences to this socket than dgram's. Mainly, ip addresses are replaced by peer IDs.

socket.send(buffer, offset, length, port, peerRelayID, [cb])

This relays the given buffer to the peer with peerRelayID by calling peer.send(...). The signature for this method is similar to dgram's socket.send except the peer's id is used instead of the ip address. Port is also ignored, but is still required for compatibility reasons.

socket.address()

Returns the peer's id instead of ip address:

{
  address: local peer's id
  port: random number or whatever port socket.bind([port]) was given
  family: a string equal to 'peer-relay'
}

socket.close([cb])

Destroys the underlying PeerRelay instance and emits the socket's close event

socket.bind([port], [cb])

Doesn't do anything since peer-relay doesn't have the conecept of binding and ports, but this method remains for compatibilty with dgram's socket.

socket.peer

references the underlying PeerRelay instance.

socket.on('message', function (buffer, rinfo) {})

buffer is the received message and rinfo is the same structure defined by socket.address() exept the sender's id is in the address field.

socket.on('error', function (err) {})

If peer-relay experiences an error, it is bubbled up through this event.

socket.on('close', function () {})

Emitted when socket.close is called or when PeerRelay closes.

socket.on('listening', function () {})

Doesn't serve any purpose other than dgram socket compatility. This event is emitted after socket.bind() is called.