liblwes

Node.js port of the LWES C library via Emscripten and asm.js

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.

$ npm install liblwes

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.

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.

The constructor of the Emitter class accepts the following options:

NameDescription
addressThe destination IP address ('127.0.0.1' by default).
portThe destination port (1111 by default).
esfPath to the ESF (Event Specification Format) file (e.g. 'data/sample.esf').
heartbeatHeartbeat frequency, e.g. 60. Disabled (false) by default.
ifaceThe network interface (all local interfaces by default).
ttlThe multicast TTL (time to live)

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

TypeDescription
UInt1616-bit unsigned integer
Int1616-bit integer
UInt3232-bit unsigned integer
Int3232-bit integer
StringString
IPAddrIP address
Int6464-bit integer
UInt6464-bit unsigned integer
BooleanBoolean

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.

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);
});

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

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