❤
npm
Sign UpSign In

@josefransaenz/hypergate-core

1.0.4 • Public • Published

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

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.

Readme

Keywords

none

Package Sidebar

Install

npm i @josefransaenz/hypergate-core

Weekly Downloads

0

Version

1.0.4

License

GPL-3.0

Unpacked Size

88.4 kB

Total Files

15

Last publish

Collaborators

  • josefransaenz
Try on RunKit
Report malware