Home Manual Reference Source Repository

Installation

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:

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

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

NodeJS

const netflux = require('netflux')

Configuration

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

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

References

Class Summary

Static Public Class Summary
public

BotServer can listen on web socket.

public

Wrapper class for RTCDataChannel and WebSocket.

public

It is responsible to build a channel between two peers with a help of WebSocketService and WebRTCService.

public

Fully connected web channel manager.

public

Message builder service is responsible to build messages to send them over the WebChannel and treat messages received by the WebChannel.

public

Abstract class which each service should inherit.

public

It is a factory helper class which is responsible to instantiate any service class.

public

This class represents a door of the WebChannel for the current peer.

public

Utility class contains some helper static methods.

public

This class is an API starting point.

public

Service class responsible to establish connections between peers via RTCDataChannel.

public

Service class responsible to establish connections between peers via WebSocket.

Interface Summary

Static Public Interface Summary
public

It is responsible to preserve Web Channel structure intact (i.e.

Function Summary

Static Public Function Summary
public

Create WebChannel.

Variable Summary

Static Public Variable Summary
public

WebRTCService identifier.

public

WebSocketService identifier.

Typedef Summary

Static Public Typedef Summary
public

Header of the metadata of the messages sent/received over the WebChannel.

public

Necessary data to join the WebChannel.

public
public

WebChannel settings

External Summary

Static Public External Summary
public
public
public
public
public
public
public
public
public
public