Installation

NPM

npm install -S netflux

Netflux has an optional peer dependency: wrtc. This package provides WebRTC API in NodeJS. It is optional because Netflux can use WebSocket instead. For some use cases maybe you still want to connect your server to the peer to peer network via RTCDataChannel, then you have to successfully install this dependency.

If you have problems with wrtc installation then:

• For Ubuntu 16.04 execute: sudo apt-get install libncurses5-dev libssl-dev libnss3-dev libexpat1-dev
• For another system, consult wrtc home page: https://github.com/js-platform/node-webrtc

What you need

For fully functional peer to peer network, Netflux needs:

• Signaling server (default: wss://sigver-coastteam.rhcloud.com:8443)
• STUN server (default: stun:turn01.uswest.xirsys.com)
• TURN server (no default)

Netflux comes with Signaling and STUN servers by default for easier quickstart. You may specify each of those servers (how to do it).

Signaling server

We developed a signaling server called Sigver. It is the only signaling server (signaling mechanism) which is supported by Netflux for now. It is available online:

ws://sigver-coastteam.rhcloud.com:8000

or

wss://sigver-coastteam.rhcloud.com:8443

Remark: Due to the rhcloud application hosting specification, following a period of inactivity, the server will be available after a while. Try again a few seconds later.

We recommend to deploy your own instance of Sigver for production.

STUN/TURN servers

STUN and TURN servers are used by WebRTC.

A few free STUN servers are available online, provided by Xirsys or Google for example. Unfortunately free TURN server is no longer available on the Internet. Thus there is no one by default in Netflux. Some companies like Xirsys may help.

Usage

There are two builds in dist folder:

dist/netflux.es2015.es.js     // ES2015 code & ES bundle (export/import)
dist/netflux.es5.umd.min.js   // ES5 code minified & UMD bundle

ES2015 module

dist/netflux.es2015.es.js

Recommended for using along with RollupJS, SystemJS or any other ES2015 module loader. If you consider to use Rollup, check jsnext:main. Netflux supports it.

import {create, BotServer, WEB_RTC, WEB_SOCKET} from 'netflux'

If you do not use jsnext:main then:

import {create, BotServer, WEB_RTC, WEB_SOCKET} from './node_modules/netflux/dist/netflux.es2015.es.js'

UMD module

dist/netflux.es5.umd.min.js

Universal Module Definition module is compatible with AMD, CommonJS and "global" modules. It works in browser and NodeJS.

Browser

<script src="netflux.es5.umd.min.js">
  window.netflux !== undefined // true
</script>

CDN

• Release: https://cdn.rawgit.com/coast-team/netflux/v1.0.0-rc.4/dist/netflux.es5.umd.min.js
• Nightly: https://github.com/coast-team/netflux/blob/master/dist/netflux.es2015.es.js

NodeJS

const netflux = require('netflux')

Configuration

You can rewrite each of the following settings.

When using netflux.create(settings) function, the default settings are:

{
  connector: WEB_RTC,
  topology: FULLY_CONNECTED,
  signalingURL: 'wss://sigver-coastteam.rhcloud.com:8443'
  iceServers: [
    {urls:'stun:turn01.uswest.xirsys.com'}
  ]
}

For new BotServer(settings) the default settings are:

{
  connector: WEB_SOCKET,
  topology: FULLY_CONNECTED,
  signalingURL: 'wss://sigver-coastteam.rhcloud.com:8443'
  iceServers: [
    {urls:'stun:turn01.uswest.xirsys.com'}
  ],
  host: 'localhost',
  port: 9000
}

Documentation for the settings may be found here.

Examples

Each of the clients in the following examples included dist/netflux.es5.umd.min.js script in his browser. Thus Netflux is available under global netflux variable.

3 browsers/clients

Peers A, B and C will constitute a peer to peer network. We suppose that all of them using the default Signaling server provided by Netflux.

A creates the network:

// Creates network with default settings
let network = netflux.create();

// When a message  has arrived from the network
network.onMessage = (peerId, msg, isBroadcast) => {
  // do something...
};

// When a new peer has joined the network
network.onPeerJoin = (peerId) => {
  // do something...
};

// When one of the network members has left
network.onPeerLeave = (peerId) => {
  // do something...
};

// Allows other peers to join this network
network.open()
  .then(({key}) => {
    // Other peers can now join this network
  })

A gives B the key. B joins the network:

// Creates network with default settings
let network = netflux.create();

network.onMessage = (peerId, msg, isBroadcast) => { /* do something... */};

network.onPeerJoin = (peerId) => { /* do something... */};

network.onPeerLeave = (peerId) => { /* do something... */};

// Joins the network with the key provided by A
network.join(key)
  .then(() => {
    /*
      B has joined successfully.
      From now onPeerJoin handler will be called in A's browser and
      onPeerJoin handler will be called in B's browser too
      (because of A who is already the network member).
    */
  })

A or B gives C the key. C joins the network, then he sends one message to all member and one private message to B:

// Creates network with default settings
let network = netflux.create();

network.onMessage = (peerId, msg, isBroadcast) => { /* do something... */};

network.onPeerJoin = (peerId) => { /* do something... */};

network.onPeerLeave = (peerId) => { /* do something... */};

// Joins the network with the key provided by A
network.join(key)
  .then(() => {
    /*
      C has joined successfully.
      From now onPeerJoin handler will be called in A's browser once, in B's
      browser once and in C's browser twice (because of A and B).
    */

    // C sends a message to all network members
    network.send('Hello everyone! It is C.')

    // C sends a private message to B
    network.sendTo(idOfB, 'Pss, B, you know, A cannot hear us!')
  })

References