DeviceHive plugin core functionality (Node JS implementation)

This module makes it possible to quickly and easily create DeviceHive plugins using NodeJS.

Module structure

PluginCore class (private)

PluginCore class implements basic interaction functionality with DeviceHive service. User is not able to use it.

ProxyClient class (private)

ProxyClient class implements basic transport functionality with DeviceHive WS Proxy service (in plugin mode). User is not able to use it.

DeviceHivePlugin class (public)

DeviceHivePlugin class implements interface for user's plugin service classes. User is able to extends their own plugin services from the DeviceHivePlugin class.

    const { DeviceHivePlugin } = require(`devicehive-plugin-core`);

    class PluginService extends DeviceHivePlugin {
        beforeStart() {}
        afterStart() {}
        handleMessage(message) {}
        beforeStop() {}
        onError(error) {}
    }

Plugin lifecycle hooks

beforeStart() {}
afterStart() {
handleMessage(message) {}
beforeStop() {}
onError(error) {}

1. beforeStart - This hook fires before plugin will do try to connect to DeviceHive WS plugin server
2. afterStart - This hook fires after plugin successfully connects to DeviceHive WS plugin server
3. handleMessage - This hook fires on every incoming Message from DeviceHive
4. beforeStop - This hook fires before plugin will stop it's own process because of some critical reason (For example, WS plugin serer closes the connection)
5. onError - This hook fires on every internal error (critical/non critical)

Plugin API

DeviceHivePlugin class has few methods that are defined internally by core functionality:

sendMessage(message) {}
subscribe(subscriptionGroup) {}
unsubscribe() {}

1. sendMessage - Sends Message object to WS plugin server. Returns Promise with response/error
2. subscribe - Subscribes to plugin topic with optionally mentioned subscription group
3. unsubscribe - Unsubscribes from plugin topic

Plugin entry point

To start plugin you should use next static method of DeviceHivePlugin class:

DeviceHivePlugin.start(<pluginService>, <config>, [<envPrefix>]);

where:

• pluginService - instance of User's own DeviceHivePlugin implementation
• config - configuration object or path to configuration json file. See Configuration section
• envPrefix - prefix to add to environmental variables to override configuration fields

Example:

    const { DeviceHivePlugin } = require(`devicehive-plugin-core`);

    class PluginService extends DeviceHivePlugin {
        beforeStart() {}
        afterStart() {}
        handleMessage(message) {}
        beforeStop() {}
        onError(error) {}
    }
    
    DeviceHivePlugin.start(new PluginService(), {
         DEVICE_HIVE_PLUGIN_WS_ENDPOINT: "ws://localhost:3001",
         DEVICE_HIVE_AUTH_SERVICE_API_URL: "http://localhost:8090/dh/rest",
         PLUGIN_ACCESS_TOKEN: "plugin_access_token",
         AUTO_SUBSCRIPTION_ON_START: true
    }, "MY_PLUGIN_SERVICE");

Configuration

• DEVICE_HIVE_PLUGIN_WS_ENDPOINT - Path to DeviceHive WS server with plugin support
• DEVICE_HIVE_AUTH_SERVICE_API_URL - Path to DeviceHive Auth REST API service
• PLUGIN_TOPIC - Plugin topic
• PLUGIN_TOKEN_LIFE_TIME_MIN - Plugin topic lifetime in minutes. Optional parameter
• USER_LOGIN - User login (plugin owner ar administrator). Optional parameter
• USER_PASSWORD - User password (plugin owner ar administrator). Optional parameter
• USER_ACCESS_TOKEN - User access token (plugin owner ar administrator). Optional parameter
• USER_REFRESH_TOKEN - User refresh token (plugin owner ar administrator). Optional parameter
• PLUGIN_ACCESS_TOKEN - Plugin access token. Optional parameter
• PLUGIN_REFRESH_TOKEN - Plugin refresh token. Optional parameter
• AUTO_SUBSCRIPTION_ON_START - Flag to on/off auto subscription to plugin topic on plugin start

Each configuration field can be overridden with corresponding environmental variable with "PLUGIN" prefix, for example:

PLUGIN.PLUGIN_TOKEN_LIFE_TIME_MIN=60

Prefix separator can be overridden by ENVSEPARATOR environmental variable. Example:

ENVSEPARATOR=_
PLUGIN_PLUGIN_TOKEN_LIFE_TIME_MIN=60

Plugin Authentication

For plugin authentication next configuration combinations can bu used:

1. PLUGIN_ACCESS_TOKEN
2. PLUGIN_REFRESH_TOKEN
3. USER_ACCESS_TOKEN + PLUGIN_TOPIC + DEVICE_HIVE_AUTH_SERVICE_API_URL
4. USER_REFRESH_TOKEN + PLUGIN_TOPIC + DEVICE_HIVE_AUTH_SERVICE_API_URL
5. USER_LOGIN + USER_PASSWORD + PLUGIN_TOPIC + DEVICE_HIVE_AUTH_SERVICE_API_URL

For 3-5 combination the PLUGIN_TOKEN_LIFE_TIME_MIN configuration field can be mentioned.