liblwes-node

Node.js port of the LWES (Light Weight Event System) library. Compiled from C to Javascript using Emscripten + asm.js and wrapped in a Javascript API which abstracts the low-level internals.

Installation

$ npm install liblwes

Usage

Emitter

var Emitter = require('liblwes').Emitter;

// Example of emitter with ESF validation and type inference
var emitter = new Emitter({
  'address' : '127.0.0.1',
  'port'    : 1111,
  'esf'     : __dirname +'/data/sample.esf'
});

emitter.emit({
  'type'       : 'FooBar',
  'attributes' : {
    'fooStr'   : 'bar',
    'foo16'    : -32768,
    'fooU16'   : 65535,
    'foo32'    : 2147483647,
    'fooU32'   : 4294967295,
    'foo64'    : '7fffffffffffffff', // 9223372036854775807 decimal
    'fooU64'   : 'ffffffffffffffff', // 18446744073709551615 decimal
    'fooBool'  : true,
    'fooIP'    : '127.0.0.1'
  }
});

// Example of emitter with ESF validation and no type inference
var emitter2 = new Emitter({ 'esf' : __dirname +'/data/sample.esf' });

emitter2.emit({
  'type'       : 'FooBar',
  'attributes' : {
    'fooStr'   : 'Hello',                 // Type spec not needed for String attributes
    'fooBool'  : true,                    // Type spec not needed for Boolean attributes
    'foo32'    : [78427, 'Int32'],        // Other attribute types do need a type spec
    'fooIP'    : ['127.0.0.1', 'IPAddr'],
    'fooU64'   : ['fff87fde', 'UInt64']
  }
});


// Example of emitter with no ESF validation and no type inference
var emitter3 = new Emitter();

emitter3.emit({
  'type'       : 'Whatever',
  'attributes' : {
    'foo'      : 'Hello',                 // Type spec not needed for String attributes
    'bar'      : true,                    // Type spec not needed for Boolean attributes
    'baz'      : [78427, 'Int32'],        // Other attribute types do need a type spec
    'blegga'   : ['127.0.0.1', 'IPAddr'],
    'asdasd'   : ['fff87fde', 'UInt64']
  }
});

The type of each event attribute can be defined in an ESF file, e.g. sample.esf:

FooBar                  # Sample LWES event
{
  string   fooStr;      # Sample string attribute
  int16    foo16;       # Sample 16-bit integer attribute
  uint16   fooU16;      # Sample 16-bit unsigned integer attribute
  int32    foo32;       # Sample 32-bit integer attribute
  uint32   fooU32;      # Sample 32-bit unsigned integer attribute
  int64    foo64;       # Sample 64-bit integer attribute
  uint64   fooU64;      # Sample 64-bit unsigned integer attribute
  boolean  fooBool;     # Sample boolean attribute
  ip_addr  fooIP;       # Sample IP address attribute
}

For more details on the LWES protocol and the ESF specification, please see the LWES documentation at lwes.org or their github page at github.com/lwes.

Listener

var Listener = require('liblwes').Listener;

var listener = new Listener('127.0.0.1', 1111);

// Listen to all events
listener.on('*', function (lwesEvent) {
  console.log(lwesEvent);
});

// Listen to specific events
listener.on('FooBar', function (lwesEvent) {
  console.log('=> Specific event: ' + lwesEvent.type);
});

Note: 64-bit integers are returned as strings.

API documentation

Emitter

The constructor of the Emitter class accepts the following options:

Name	Description
address	The destination IP address ('127.0.0.1' by default).
port	The destination port (1111 by default).
esf	Path to the ESF (Event Specification Format) file (e.g. 'data/sample.esf').
heartbeat	Heartbeat frequency, e.g. 60. Disabled (false) by default.
iface	The network interface (all local interfaces by default).
ttl	The multicast TTL (time to live)

The following attribute types can be used in the event object passed to the emit function:

Type	Description
UInt16	16-bit unsigned integer
Int16	16-bit integer
UInt32	32-bit unsigned integer
Int32	32-bit integer
String	String
IPAddr	IP address
Int64	64-bit integer
UInt64	64-bit unsigned integer
Boolean	Boolean

Emitters can be closed individually with emitter.close() or globally with Emitter.closeAll(). This releases all resources allocated in the emscripten subsystem and fires a System::Shutdown event if the heartbeat is enabled.

Listener

Listeners conform to Node's EventEmitter API, with the addition of wildcard events to support notifications on any LWES event:

listener.on('*', function (lwesEvent) {
  console.log(lwesEvent);
});

Listeners can be closed with the close method:

listener.close();

You can capture liblwes errors by listening on liblwes::error events, e.g.:

listener.on('liblwes::error', function (e) {
  console.log('=> Error: ' + e);
});

Compilation

You can recompile the liblwes.js library with emscripten by running make. The emcc binary must be in your PATH.

License

Created by Luca Bernardo Ciddio for YP Intellectual Property, LLC (YellowPages.com) and licensed under the MIT License.