README.md

zyre.js

Node.js port of Zyre - an open-source framework for proximity-based peer-to-peer applications

Description

Zyre.js provides peer discovery and reliable (group) messaging over local area networks. Some of the key features:

• Zyre.js works without administration or configuration
• Peers can join or leave the network at any time
• Peers can communicate directly with each other; no central server or message broker needed
• Peers can join groups
• Zyre.js loses no message, even when the network is under heavy load
• Zyre.js is designed to be used in WiFi networks (but can also be used in Ethernet networks)
• Peer discovery usually takes less than a second

Zyre.js implements the ZRE protocol.

Zyre.js 2.x is currently available as beta, which uses the rewritten zeromq.js 6.x

Installation

npm install zyre.js

Beta:

npm install zyre.js@beta

Documentation

A full jsdoc documentation can be found here.

Usage

const Zyre = require('zyre.js');

Creates a new zyre.js instance (arguments are optional).

const zyre = new Zyre({
  name: 'foo',      // Name of the zyre node
  iface: 'eth0',    // Network interface or IPv4 address
  headers: {        // Headers will be sent on every new connection
    foo: 'bar',
  },
  evasive: 5000,    // Timeout after which the local node will try to ping a not responding peer
  expired: 30000,   // Timeout after which a not responding peer gets disconnected
  port: 49152,      // Port for incoming messages, will be incremented if already in use
  bport: 5670,      // Discovery beacon broadcast port
  binterval: 1000,  // Discovery beacon broadcast interval
});

Starts up the zyre.js instance. Must be called before any other function.

// Async function, so you can register...
zyre.start(() => {
  // ...a callback or
}).then(() => {
  // ...a Promise
});

Stops the zyre.js instance. Deletes all peers data.

// Async function, so you can register...
zyre.stop(() => {
  // ...a callback or
}).then(() => {
  // ...a Promise
});

Sends a private message to the peer with the given identity. The message can be a string or a raw buffer.

zyre.whisper(identity, message);

Sends a message to the group with the given name. The message can be a string or a raw buffer.

zyre.shout(group, message);

Joins the group with the given name.

zyre.join(group);

Leaves the group with the given name.

zyre.leave(group);

Returns the identity of the local node. The identity is a 16 byte UUID as hex string.

zyre.getIdentity();

Returns information of the connected peer with the given identity.

zyre.getPeer(identity);

Returns information of all connected peers.

zyre.getPeers();

Returns information of the group with the given name.

zyre.getGroup(name);

Returns information of all known groups.

zyre.getGroups();

Sets the encoding of received messages. Defaults to utf8. Available are: ascii, utf8, utf16le/ucs2, base64, binary, hex, raw/null

zyre.setEncoding('utf8');   // Default encoding
zyre.setEncoding(null);     // Raw buffers

Connect is fired when a new peer joins the network.

zyre.on('connect', (id, name, headers) => {
  // ...
});

Disconnect is fired when a peer disconnects from the network.

zyre.on('disconnect', (id, name) => {
  // ...
});

Expired is fired when a peer timed out. (uses expired timeout value)

zyre.on('expired', (id, name) => {
  // ...
});

Whisper is fired when a peer sends a private message.

zyre.on('whisper', (id, name, message) => {
  // ...
});

Shout is fired when a peer sends a group message.

zyre.on('shout', (id, name, message, group) => {
  // ...
});

Join is fired when a peer joins a group.

zyre.on('join', (id, name, group) => {
  // ...
});

Leave is fired when a peer leaves a group.

zyre.on('leave', (id, name, group) => {
  // ...
});

Examples

There is a sample chat package that can be found here.

Inline example of two nodes talking to each other:

const Zyre = require('zyre.js');

const chris = new Zyre({ name: 'Chris' });
const john = new Zyre({ name: 'John' });

chris.on('connect', () => {
  chris.shout('CHAT', 'Hello World');
});

chris.on('whisper', (id, name, message) => {
  console.log(`${name}: ${message}`);
});

chris.start(() => {
  chris.join('CHAT');
});

john.on('shout', (id, name, message, group) => {
  console.log(`(${group}) ${name}: ${message}`);
  john.whisper(id, `Hello ${name}`);
});

john.start(() => {
  john.join('CHAT');
});

Prints:

(CHAT) Chris: Hello World
John: Hello Chris