import Foglet from 'foglet-core/src/foglet.js'

public class | source

Foglet

Extends:

events~EventEmitter → Foglet

Foglet is the main class used to build fog computing applications.

It serves as a High level API over a Random Peer Sampling (RPS) network, typically Spray (https://github.com/RAN3D/spray-wrtc). It provides utilities to send to other peers in the network, and to receives messages send to him by these same peers. Messages can be send to a single neighbour, in a unicast way, or to all peers in the network, in a broadcast way.

Example:

'use strict';
const Foglet = require('foglet');

// let's create a simple application that send message in broadcast
const foglet = new Foglet({
  rps: {
    type: 'spray-wrtc', // we choose Spray as a our RPS
    options: {
      protocol: 'my-awesome-broadcast-application', // the name of the protocol run by our app
      webrtc: { // some WebRTC options
        trickle: true, // enable trickle
        config: {iceServers : []} // define iceServers here if you want to run this code outside localhost
      },
      signaling: { // configure the signaling server
        address: 'http://signaling.herokuapp.com', // put the URL of the signaling server here
        room: 'my-awesome-broadcast-application' // the name of the room for the peers of our application
      }
    }
  }
});

// connect the foglet to the signaling server
foglet.share();

// Connect the foglet to our network
foglet.connection().then(() => {
  // listen for broadcast messages
  foglet.onBroadcast((id, message) => {
    console.log('The peer', id, 'just sent me by broadcast:', message);
  });

  // send a message in broadcast
  foglet.sendBroadcast('Hello World !');
});

Constructor Summary

Public Constructor
public	constructor(options: Object): void Constructor of Foglet

Member Summary

Public Members
public get	id: string: * Get the foglet ID.
public get	inViewID: string: * Get the in-view ID of this foglet
public get	outViewID: string: * Get the out-view ID of this foglet

Private Members
private	_id: *
private	_networkManager: *
private	_options: *
private	_ssh: *

Method Summary

Public Methods
public	connection(foglet: Foglet, name: string, timeout: number): Promise Connect the Foglet to the network.
public	createMedia(overlayname: [type], options: Object): MediaStream Create an object media stream with sendUnicast and sendBroadcast methods
public	getArcs(overlayName: [type]): String[] Return an array with all arcs Ids (i.e.: all connection availables)
public	getNeighbours(limit: Integer, overlayName: String): String[] Get the IDs of all available neighbours with or without their suffix -I or -O
public	getRandomNeighbourId(): string \| null Get the ID of a random neighbour
public	getReachableNeighbours(transform: Boolean, overlayName: String): String[] Get the IDs of all available neighbours with or without their suffix -I or -O
public	onBroadcast(callback: MessageCallback): void Listen for incoming broadcast messages, and invoke a callback on each of them.
public	onStreamBroadcast(callback: MessageCallback): void Listen on incoming unicasted streams
public	onStreamUnicast(callback: MessageCallback): void Listen on incoming unicasted streams
public	onUnicast(callback: MessageCallback): void Listen for incoming unicast messages, and invoke a callback on each of them.
public	overlay(name: string): Network Select and get an overlay to use for communication using its index.
public	sendBroadcast(message: object): boolean Send a broadcast message to all connected peers in the network.
public	sendMulticast(ids: string[], message: object): boolean Send a message to a set of neighbours (in a multicast way).
public	sendUnicast(id: string, message: object): boolean Send a message to a specific neighbour (in a unicast way).
public	share(name: string): void Connect the foglet to the signaling server.
public	streamBroadcast(isReady: VersionVector): StreamRequest Begin the streaming of a message to all peers (using broadcast)
public	streamUnicast(id: string): StreamRequest Begin the streaming of a message to another peer (using unicast)
public	unshare(name: integer): void Revoke the connection with the signaling server.
public	use(middleware: Object, priority: Number): void Register a middleware, with an optional priority

Public Constructors

public constructor(options: Object): void source

Constructor of Foglet

Params:

Name	Type	Attribute	Description
options	Object		Options used to build the Foglet
options.verbose	boolean		If True, activate logging
options.id	boolean		Id of the foglet, will identify the peer as ID-I and ID-O in a neighbor view, respectively for Outgoing and ingoing arcs
options.rps	Object		Options used to configure the Random Peer Sampling (RPS) network
options.rps.type	string		The type of RPS (`spray-wrtc` for Spray, `cyclon` for Cyclon or `custom` for a custom network
options.rps.options	Object		Options by the type of RPS choosed
options.rps.options.protocol	string		Name of the protocol run by the application
options.rps.options.maxPeers	string		Using Cyclon, fix the max number of peers in the partial view
options.rps.options.webrtc	Object		WebRTC dedicated options (see SimplePeer @see(https://github.com/feross/simple-peer) WebRTC docs for more details)
options.rps.options.timeout	number		RPS timeout before definitively close a WebRTC connection
options.rps.options.delta	number		RPS shuffle interval
options.rps.options.signaling	Object		Options used to configure the interactions with the signaling server
options.rps.options.signaling.address	string		URL of the signaling server
options.rps.options.signaling.room	string		Name of the room in which the application run
options.overlay	Object		Options used to configure custom overlay in addition of the RPS
options.overlay.options	Object		Options propagated to all overlays, same as the options field used to configure the RPS.
options.overlay.overlays	OverlayConfig[]		Set of config objects used to build the overlays

Return:

void

Throw:

InitConstructException	thrown when options are not provided
ConstructException	thrown when key options are missing

Public Members

public get id: string: * source

Get the foglet ID.

WARNING: this id is not the same as used by the RPS.

Return:

string

The foglet ID

public get inViewID: string: * source

Get the in-view ID of this foglet

Return:

string

The in-view ID of the foglet

public get outViewID: string: * source

Get the out-view ID of this foglet

Return:

string

The out-view ID of the foglet

Private Members

private _id: * source

private _networkManager: * source

private _options: * source

private _ssh: * source

Public Methods

public connection(foglet: Foglet, name: string, timeout: number): Promise source

Connect the Foglet to the network. If a parameter is supplied, the foglet try to connect with another foglet.

Otherwise, it uses the signaling server to perform the connection. In this case, one must call Foglet#share before, to connect the foglet to the signaling server first.

By default, connect the foglet to the base RPS. Use the name parameter to select which overlay to connect with.

Params:

Name	Type	Attribute	Description
foglet	Foglet	optional default: null	(optional) Foglet to connect with. Leav to `null` rely on the signaling server.
name	string	optional default: null	(optional) Name of the overlay to connect. Default to the RPS.
timeout	number	optional default: 60000	(optional) Connection timeout. Default to 6.0s

Return:

Promise

A Promise fullfilled when the foglet is connected

Example:

const foglet = new Foglet({
  // some options...
});
foglet.share();
foglet.connection().then(console.log).catch(console.err);

public createMedia(overlayname: [type], options: Object): MediaStream source

Create an object media stream with sendUnicast and sendBroadcast methods

Params:

Name	Type	Attribute	Description
overlayname	[type]	optional default: null	The name of the overlay to use for send messages
options	Object	optional default: {}	the options to use for creating the media manager (default chunkSize=128k)

Return:

MediaStream

public getArcs(overlayName: [type]): String[] source

Return an array with all arcs Ids (i.e.: all connection availables)

Params:

Name	Type	Attribute	Description
overlayName	[type]	optional default: undefined	Define the overlay to use

Return:

String[]

Array of ids

Example:

const foglet = new Foglet();

// print the IDs of up to five neighbours
console.log(foglet.getArcs());
// will return ['peer1-O', 'peer2-I', 'peer2-O', 'peer3-I'...]

public getNeighbours(limit: Integer, overlayName: String): String[] source

Get the IDs of all available neighbours with or without their suffix -I or -O

Params:

Name	Type	Attribute	Description
limit	Integer	optional default: true	Max number of neighbours to look for
overlayName	String	optional default: undefined	Define the overlay to use

Return:

String[]

Set of IDs for all available neighbours

Example:

const foglet = new Foglet({
  // some options...
});

// print the IDs of up to five neighbours
console.log(foglet.getNeighbours());
// will return ['peer1-I', 'peer2-I', 'peer3-I', ...]
// print the IDs of all neighbours
console.log(foglet.getNeighbours(Infinity));
// will return ['peer1-I', 'peer1-O', 'peer3-I', ...]

public getRandomNeighbourId(): string | null source

Get the ID of a random neighbour

Return:

string | null

The ID of a random neighbour, or null if not found

public getReachableNeighbours(transform: Boolean, overlayName: String): String[] source

Get the IDs of all available neighbours with or without their suffix -I or -O

Params:

Name	Type	Attribute	Description
transform	Boolean	optional default: true	enable the transformation of ids eg: 'peer' or 'peer-O'
overlayName	String	optional default: undefined	Define the overlay to use

Return:

String[]

Set of IDs for all available neighbours

Example:

const foglet = new Foglet({
  // some options...
});

// print the IDs of up to five neighbours
console.log(foglet.getReachableNeighbours());
// will return ['peer1-O', 'peer2-O', 'peer3-O', ...]
// print the IDs of all neighbours
console.log(foglet.getReachableNeighbours(false));
// will return ['peer1', 'peer2', 'peer3', ...]

public onBroadcast(callback: MessageCallback): void source

Listen for incoming broadcast messages, and invoke a callback on each of them.

Params:

Name	Type	Attribute	Description
callback	MessageCallback		Callback function inovked with the message

Return:

void

Example:

const foglet = new Foglet({
  // some options...
});

foglet.onBroadcast((id, msg) => {
  console.log('The peer', id, 'just sent by broadcast:', msg);
});

public onStreamBroadcast(callback: MessageCallback): void source

Listen on incoming unicasted streams

Params:

Name	Type	Attribute	Description
callback	MessageCallback		Callback invoked with a StreamMessage as message

Return:

void

Example:

const foglet = getSomeFoglet();

foglet.onStreamBroadcast((id, stream) => {
 console.log('a peer with id = ', id, ' is streaming data to me');
 stream.on('data', data => console.log(data));
 stream.on('end', () => console.log('no more data available from the stream'));
});

public onStreamUnicast(callback: MessageCallback): void source

Listen on incoming unicasted streams

Params:

Name	Type	Attribute	Description
callback	MessageCallback		Callback invoked with a StreamMessage as message

Return:

void

Example:

const foglet = getSomeFoglet();

foglet.onStreamUnicast((id, stream) => {
 console.log('a peer with id = ', id, ' is streaming data to me');
 stream.on('data', data => console.log(data));
 stream.on('end', () => console.log('no more data available from the stream'));
});

public onUnicast(callback: MessageCallback): void source

Listen for incoming unicast messages, and invoke a callback on each of them.

Params:

Name	Type	Attribute	Description
callback	MessageCallback		Callback function inovked with the message

Return:

void

Example:

const foglet = new Foglet({
  // some options...
});

foglet.onUnicast((id, msg) => {
  console.log('My neighbour', id, 'just sent me by unicast:', msg);
});

public overlay(name: string): Network source

Select and get an overlay to use for communication using its index. The RPS is always provided when no parameter are provided. Then, overlays are indexed by their name.

Params:

Name	Type	Attribute	Description
name	string	optional default: null	(optional) Name of the overlay to get. Default to the RPS.

Return:

Network

Return the network for the given ID.

Example:

const foglet = new Foglet({
 // some options...
});

// Get the 'latencies' overlay
const overlay = foglet.overlay('latencies');

public sendBroadcast(message: object): boolean source

Send a broadcast message to all connected peers in the network.

Params:

Name	Type	Attribute	Description
message	object		The message to send

Return:

boolean

True if the messahe has been sent, False otherwise

Example:

const foglet = new Foglet({
  // some options...
});

foglet.sendBroadcast('Hello everyone!');

public sendMulticast(ids: string[], message: object): boolean source

Send a message to a set of neighbours (in a multicast way). These messages will be received by neighbours on the unicast channel.

Params:

Name	Type	Attribute	Description
ids	string[]		The IDs of the targeted neighbours
message	object		The message to send

Return:

boolean

True if the messahe has been sent, False otherwise

Example:

const foglet = new Foglet({
  // some options...
});

// get IDs of some neighbours
const ids = foglet.getNeighbours(5);

foglet.sendMulticast(ids, 'Everyone, get in here!');

public sendUnicast(id: string, message: object): boolean source

Send a message to a specific neighbour (in a unicast way).

Params:

Name	Type	Attribute	Description
id	string		The ID of the targeted neighbour
message	object		The message to send

Return:

boolean

True if the messahe has been sent, False otherwise

Example:

const foglet = new Foglet({
  // some options...
});

// get the ID of one neighbour
const id = foglet.getRandomNeighbourId();

foglet.sendUnicast(id, 'Hi diddly ho neighborino!');

Connect the foglet to the signaling server.

By default, connect the RPS to the signaling server. Use the name parameter to select which overlay to connect.

Params:

Name	Type	Attribute	Description
name	string	optional default: null	(optional) Name of the overlay to connect to the signaling server. Default to the RPS.

Return:

void

public streamBroadcast(isReady: VersionVector): StreamRequest source

Begin the streaming of a message to all peers (using broadcast)

Params:

Name	Type	Attribute	Description
isReady	VersionVector	optional default: undefined	Id of the message to wait before this message is received

Return:

StreamRequest

Stream used to transmit data to all peers

Example:

const foglet = getSomeFoglet();

const stream = foglet.sendBroadcast();
stream.write('Hello');
stream.write(' world!');
stream.end();

public streamUnicast(id: string): StreamRequest source

Begin the streaming of a message to another peer (using unicast)

Params:

Name	Type	Attribute	Description
id	string		Id of the peer

Return:

StreamRequest

Stream used to transmit data to another peer

Example:

const foglet = getSomeFoglet();
const peerID = getSomePeerID();

const stream = foglet.streamUnicast(peerID);
stream.write('Hello');
stream.write(' world!');
stream.end();

public unshare(name: integer): void source

Revoke the connection with the signaling server.

By default, disconnect the RPS from the signaling server. Use the name parameter to select which overlay to connect.

Params:

Name	Type	Attribute	Description
name	integer	optional default: null	(optional) Name of the overlay to disconnect from the signaling server. Default to the RPS.

Return:

void

public use(middleware: Object, priority: Number): void source

Params:

Name	Type	Attribute	Description
middleware	Object		The middleware to register
middleware.in	function		Function applied on middleware input
middleware.out	function		Function applied on middleware output
priority	Number	optional default: 0	(optional) The middleware priority

Return:

void

Example:

const foglet = new Foglet({
 // some options...
});

const middleware = {
 in: msg => {
   return msg + ' and Thanks';
 },
 out: msg => {
   return msg + ' for all the Fish';
 }
};

foglet.use(middleware);

Foglet

Extends:

Example:

Constructor Summary

Member Summary

Method Summary

Public Constructors

public constructor(options: Object): void source

Params:

Return:

Throw:

Public Members

public get id: string: * source

Return:

public get inViewID: string: * source

Return:

public get outViewID: string: * source

Return:

Private Members

private _id: * source

private _networkManager: * source

private _options: * source

private _ssh: * source

Public Methods

public connection(foglet: Foglet, name: string, timeout: number): Promise source

Params:

Return:

Example:

public createMedia(overlayname: [type], options: Object): MediaStream source

Params:

Return:

public getArcs(overlayName: [type]): String[] source

Params:

Return:

Example:

public getNeighbours(limit: Integer, overlayName: String): String[] source

Params:

Return:

Example:

public getRandomNeighbourId(): string | null source

Return:

public getReachableNeighbours(transform: Boolean, overlayName: String): String[] source

Params:

Return:

Example:

public onBroadcast(callback: MessageCallback): void source

Params:

Return:

Example:

public onStreamBroadcast(callback: MessageCallback): void source

Params:

Return:

Example:

public onStreamUnicast(callback: MessageCallback): void source

Params:

Return:

Example:

public onUnicast(callback: MessageCallback): void source

Params:

Return:

Example:

public overlay(name: string): Network source

Params:

Return:

Example:

public sendBroadcast(message: object): boolean source

Params:

Return:

Example:

public sendMulticast(ids: string[], message: object): boolean source

Params:

Return:

Example:

public sendUnicast(id: string, message: object): boolean source

Params:

Return:

Example:

public share(name: string): void source

Params:

Return: