Installation

npm install @josefransaenz/hypergate-core

hypergate-core

This library provides a single class called Hypergate which controls the execution of resource-specific applications (plugins) and emits events or messages about their status and data obtained.

Depending of the type of execution and the communication mode needed, a plugin can be defined inside of one of three categories:

• Routines: applications that are executed with the aim of obtaining a result (measurement or data acquisition) and may only need to receive input data at the begining of their execution and may only return output data at the end. The exchange of input and output data with this mode of plugins can be done thorugh a JSON file.
• Tasks: applications that may need to be executed independently of the parent process and may need/produce formatted input/output data to/from the standard I/O.
• Services: applications that may need to be executed all the time or for a exteded period of time and may need to periodically o episodically send or receive information. This type of plugins can provide a ZeroMQ endpoint to which the Hypergate instance can connect a ZMQ_DEALER socket for establishing a bidirectional any-time communication channel.

Example

const Hypergate = require('@josefransaenz/hypergate-core')

const hypergate = new Hypergate({
routines: {
    myRoutine: {
        command: 'myRoutine.exe',
        args: ['myArg1', 'myArg2'],
        path: '/path/to/myRoutine',
        jsonFile: 'temp.json',
        jsonFileSchema: {
            type: 'object',
            properties: { 
                foo: { type: 'string'},
                bar: { type: 'array'}
            }
        }
    }  
}
 });
 
 hypergate.once('routines/myRoutine/completed', (outputData) =>  {
 	console.log('myRoutine was completed with the following result: ' + outputData.bar);
 });
 
 hypergate.once('routines/myRoutine/error', (error) =>  {
 	console.error('Error while executing myRoutine: ' + error);
 });

 var inputData = { foo: 'val1' };

 hypergate.command('routines/myRoutine/start', inputData)
 .then(() => {
 	console.log('myRoutine is executing!');
 }); 
 .catch((error) => {
 	console.error('myRoutine could not be executed ' + error);
 }); 

API Reference

Hypergate ⇐ EventEmitter

Extends: EventEmitter
Emits: _pluginType_/_pluginName_/start, _pluginType_/_pluginName_/error, _pluginType_/_pluginName_/exit, _pluginType_/_pluginName_/stdout, _pluginType_/_pluginName_/stderr, routines/_routineName_/completed, services/_serviceName_/output

• Hypergate ⇐ EventEmitter
  • new Hypergate(plugins)
  • .getStatus() ⇒ status
  • .command(command, payload) ⇒ promise
  • .stop() ⇒ promise
  • "pluginType/pluginName/start"
  • "pluginType/pluginName/error" (error)
  • "pluginType/pluginName/exit" (exitMessage)
  • "pluginType/pluginName/stdout" (data)
  • "pluginType/pluginName/stderr" (data)
  • "routines/routineName/completed" (data)
  • "services/serviceName/output" (data)

new Hypergate(plugins)

An instance of the Hypergate class is a EventEmitters that represents a controller of a set of applications called plugins. A plugin is a script or an executable that can be spawned as a child process of the application that instaciate the Hypergate class.

| Param | Type | Description | | --- | --- | --- | | plugins | object | Definition of the plugins to use. | | plugins.tasks | object | Defines the plugins of type 'tasks'. This type of plugins will be spawned as decoupled child processes which means that they will continue to execute if the main application is closed before the plugins ends their execution. | | plugins.tasks.taskName | object | Parameters for executing taskName plugin. | | plugins.tasks.taskName.command | string | The command for executing the plugin | | plugins.tasks.taskName.args | array | List of string arguments. | | plugins.tasks.taskName.path | string | Current working directory of the plugin. | | plugins.tasks.taskName.detached | boolean | Specify if the plugin should be executed detached from the main application. Default: true | | plugins.tasks.taskName.stdinSchema | string | JSON schema object that specifies the schema for validating the data received with the 'start' command and that will be sent to the standard input of the plugin. | | plugins.tasks.taskName.stdoutSchema | string | JSON schema object that specifies the schema for validating the data received from the plugin standard output and that will be sent in the payload of the 'stdout' event. | | plugins.routines | object | Defines the plugins of type 'routines'. This type of plugins can read input data from a JSON file and can write the output data that results from their execution in the same file. The input data can be provided with the command routines/routineName/start. The output data will be present in the payload of the event routines/routineName/completed. | | plugins.routines.routineName | object | Parameters for executing routineName plugin. | | plugins.routines.routineName.command | string | The command for executing the plugin | | plugins.routines.routineName.args | array | List of string arguments. | | plugins.routines.routineName.path | string | Current working directory of the plugin. | | plugins.routines.routineName.jsonFile | string | Name of the JSON file to use as communication channel with the routine. | | plugins.routines.routineName.jsonFileSchema | object | JSON schema object that specifies the schema for validating the data to be written or read to or from the JSON file | | plugins.services | object | Defines the plugins of type 'services'. This type of plugins can automatically start with the creation of the hypergate instance and can send and receive messages using ZeroMQ. Messages with input data can be sent to the plugins with the command services/serviceName/input. Messages with output data generated by the plugin can be received by listening to an event services/serviceName/output | | plugins.services.serviceName | object | Parameters for executing serviceName plugin | | plugins.services.serviceName.command | string | The command for executing the plugin | | plugins.services.serviceName.args | array | List of string arguments. | | plugins.services.serviceName.path | string | Current working directory of the plugin. | | plugins.services.serviceName.autoStarts | number | Indicates the number of times (n) that the plugin will begin to execute automatically. If n = 1 indicates that it will start inmediately but will remain inactive once the execution ends (either by itself or by command). If n > 1, it will automatically restart n - 1 times during the application lifetime. | | plugins.services.serviceName.zeromqHost | string | ZeroMQ endpoint to establish the communication channel with the plugin. This is done by creating an outgoing conection from a socket of type ZMQ_DEALER. It is a string consisting of a transport :// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to. The plugin application should accept incoming connections. | | plugins.services.serviceName.inputSchema | object | JSON schema object that specifies the schema for validating the input data. | | plugins.services.serviceName.outputSchema | object | JSON schema object that specifies the schema for validating the payload of the messages received from the plugin. |

hypergate.getStatus() ⇒ status

Returns the status of the hypergate instance

hypergate.command(command, payload) ⇒ promise

Execute a command for communicating or controlling a plugin or requesting the status of the hypergate instance

| Param | Type | Description | | --- | --- | --- | | command | string | A string that specifices the command for a plugin as 'pluginType/pluginName/action' or request the status of the hypergate instance if equal to 'hypergate/status/request'. pluginType should be equal to 'tasks', 'routines' or 'services'. Any other value will return a rejected promise. pluginName should be equal to one of the plugin names specified during the creation of the hypergate instance. Any other value will return a rejected promise. action should be equal to 'start' or 'kill'. For plugins of type 'services' it could also be equal to 'input' or 'restart'. Any other value will return a rejected promise. If action = 'start' it spawns the a child process with the parameters defined for the plugin during the creation of the hypergate instance. If the plugin is of type 'routines', the payload with the data to be written in the JSON file (if specified) will be validated against the JSON schema provided during the plugin definition. If action = 'kill' and the plugin is runnig it sends the signal 'SIGTERM' to the related child process If action = 'input' it sends a ZeroMQ message to the plugin with the provided payload which will be validated against the input JSON schema provided during the plugin definition. If action = 'restart' and the plugins if of type 'services' it will have the same effect as a 'kill' command followed by a 'start' command. | | payload | object | Payload data |

hypergate.stop() ⇒ promise

Stop all running plugins. Returns a promise that is full filled when all process are stopped

"pluginType/pluginName/start"

Emmitted when the process of the plugin is launched. This event do not guarantee that the plugin sucesfully started to execute.

"pluginType/pluginName/error" (error)

Emmitted when an error occurred during the execution of the plugin is launched. This event do not guarantee that the plugin sucesfully started to execute.

| Param | Type | Description | | --- | --- | --- | | error | any | Error message or error object. |

"pluginType/pluginName/exit" (exitMessage)

Emmitted when the process of the plugin ends.

| Param | Type | Description | | --- | --- | --- | | exitMessage | string | Exit message. |

"pluginType/pluginName/stdout" (data)

Emmitted when a chunk of data is received from the stdout of the process of the plugin.

| Param | Type | Description | | --- | --- | --- | | data | string | The chunk of data. |

"pluginType/pluginName/stderr" (data)

Emmitted when a chunk of data is received from the stderr of the process of the plugin.

| Param | Type | Description | | --- | --- | --- | | data | string | The chunk of data. |

"routines/routineName/completed" (data)

Emmitted when a plugin of type 'routines' completes its execution and its output data is successfully retrieved.

| Param | Type | Description | | --- | --- | --- | | data | object | The output data resulting from the plugin execution. |

"services/serviceName/output" (data)

Emmitted when a message is received from a plugin of type 'services'.

| Param | Type | Description | | --- | --- | --- | | data | object | The payload of the message received. |

status : object

The status of an hypergate instance.

Properties

| Name | Type | Description | | --- | --- | --- | | version | string | Semantic version of the hypergate library used (see https://semver.org/). | | tasks | object | Specifies the status of the plugins of type 'tasks'. | | tasks.taskName | boolean | Status of the taskName plugin | | tasks.taskName.running | boolean | Indicate if the task is running. | | tasks.taskName.lastStart | boolean | Date of the last start event specified as the the number of milliseconds from 01 January, 1970 in UTC. | | routines | object | Specifies the status of the plugins of type 'routines'. | | routines.routineName | boolean | Status of the routineName plugin | | routines.routineName.running | boolean | Indicate if the routine is running. | | routines.routineName.lastStart | boolean | Date of the last start event specified as the the number of milliseconds from 01 January, 1970 in UTC. | | services | object | Specifies the status of the plugins of type 'services'. | | services.serviceName | boolean | Status of the serviceName plugin | | services.serviceName.running | boolean | Indicate if the service is running. | | services.serviceName.lastStart | boolean | Date of the last start event specified as the the number of milliseconds from 01 January, 1970 in UTC. |