mplane

mPlane nodeJS implementation

#mPlane nodeJS reference library

This is the mPlane nodejs library. The architecture and software structure is freely inspired by mPlane reference implementation written in python by Brian Trammell brian@trammell.ch.

#Installation

npm install mplane

#Usage example In this example we set a simple capability for a pinger probe. First of all import the main mPlane library

var mplane = require('mplane');
 
// The IP address of the pinger 
var __MY_IP__ = "192.168.0.123";
 
// Initialize available primitives from the registry 
// It can be a local file or a remote __URL__ 
mplane.Element.initialize_registry("https://raw.githubusercontent.com/fp7mplane/protocol-ri/master/mplane/registry.json");
 
// Create a new mPlane Capability 
var pingerCapability = new mplane.Capability();
 
// Set the accepted time and periodicity 
pingerCapability.set_when("now ... future / 1s");
 
// Add parameters with associated constraints 
pingerCapability.add_parameter({
    type:"destination.ip4",
    constraints:"192.168.0.1 ... 192.168.0.254"
});
pingerCapability.add_parameter({
    type:"number",
    constraints:"1 ... 10"
});
pingerCapability.add_parameter({
        type:"source.ip4",
        constraints:__MY_IP__
});
 
// Add result columns 
pingerCapability.add_result_column("delay.twoway")
    .set_metadata_value("System_type","Pinger")
    .set_metadata_value("System_version","0.1a")
    .set_metadata_value("System_ID","Lab test machine").update_token();
    
// Define a label 
pingerCapability.set_label("DEMO pinger");

Please refer to the Examples directory for a working mPlane probe. For a complete set of mPlane components (probe, supervisor and client) build by means of this repository, please refer to mPlane components.

#Chainability Each mPlane function supports chainability For example you can define all the parameters in a single chain:

// Add parameters with associated constraints 
pingerCapability.add_parameter({
    type:"destination.ip4",
    constraints:"192.168.0.1 ... 192.168.0.254"
}).add_parameter({
    type:"number",
    constraints:"1 ... 10"
}).add_parameter({
        type:"source.ip4",
        constraints:__MY_IP__
});

#Interaction with the RI The mPlane Reference Implementation, written in python, can be find here. In order to correctly interact with any component using the RI messages formats, two method have been exposed in the library, to decode messages generated by the RI and to send messages to a RI component.

##from_dict This is a global method exposed in the mplane library. It sould be used to import any raw message received from an mPlane RI component. It will generate an mplane object of the type contained in the message. In the following example the data received as a body of an HTTP communication is imported in an mPlane object.

var result = mplane.from_dict(body);

This method, defined for any mPlane information element, should be used before sending data to a RI component. The following example, shows how the pinger capability defined in the above probe example be transformed in a standard mPlane message.

/* serialize the capability in an mPlane RI message*/
var RICapabilitySstatement = pingerCapability.to_dict();
 
/* Shows the serialized capability*/
console.log(RICapabilitySstatement);

This is the output of the above example

{
    "capability":"measure",
    "label":"pinger_TI_test",
    "metadata":{
        "System_type":"Pinger",
        "System_version":"0.1a",
        "System_ID":"Lab test machine"
    },
    "link":"",
    "token":"c61ad8db5f9a4cc38e7ae8d8b5deae85ea93187b",
    "when":"now ... future / 1s",
    "resultvalues":[],
    "results":["delay.twoway"],
    "parameters":{
        "destination.ip4":"192.168.0.1 ... 192.168.255.255",
        "number":"1 ... 10",
        "source.ip4":"192.168.0.1"
    }
}

#Transport

The base mPlane library implements the mPlane Information Model elements that can be used to build messages to be carried on top of any protocol of choice (SSH, HTTP,...). A nodejs HTTPS API has been implemented for basic usage (create and read elements) and can be find here.

#EXAMPLES A complete set of basic mPlane components is ready to use here.

#Documentation

Please refer to the API reference mPlane nodejs API

#Release Notes

You can find release notes here