Skip to content

Latest commit

 

History

History
187 lines (138 loc) · 6.6 KB

first_addon.md

File metadata and controls

187 lines (138 loc) · 6.6 KB

Create your first SlimIO Addon

For who ?

This guide has been designed for Node.js/Javascript developers.

We assumes that you have already installed and set up a local agent. If not, please refer to this guide

Requirements

⚠️ Node.js must be installed first to get access to npm.

To setup the SlimIO CLI with npm just run in your terminal:

$ npm install @slimio/cli -g

Dont hesitate to check the CLI guide

Getting Started

Go to the root of your Agent folder and run the SlimIO create command:

$ cd yourAgentFolder
$ slimio create addon --name addonName

The generated code will be the following (where addonName is the name of the addon you specified):

import Addon from "@slimio/addon";

const addonName = new Addon("addonName");

/**
 DO THE WORK HERE !
**/

export default addonName;

A complete API Documentation of Addon can be found here. Feel free to inspire yourself and copy existing addons:

By default an Addon already chip with some native Callbacks and Events.

Callbacks

Callbacks are communication functions belonging to addons. They can trigger actions or recover data from an addon. They allow communication between addons in a one-to-one relationship.

Each addon has a set of callbacks (native or declared by the developer itself).

Callbacks name must respect the snake_case typographic convention. (Note: the registerCallback automatically switch camelCase to snake_case).

Register and schedule a callback

It may be useful to schedule a callback that need to be executed at a regular interval but still need sometimes to be triggered manually (that the goal of callback ^^). A common case is to achieve some kind of "cleanup" task on a local database (or searching for external data at a given time).

There is two ways to register a callback:

⚠️ The callback should be an Asynchronous Function (Synchronous function will be rejected with a TypeError).

myAddon.registerCallback("callback_name", async function() {
    console.log("callback_Name has been executed!");
});

OR by declaring the function separately:

async function callbackName() {
    console.log("callback_Name has been executed!");
}
myAddon.registerCallback(callbackName);

if Callback name isn't writted by following the snake_case convention, it will be set automatically !

Schedule a callback execution interval. Use the package Scheduler to achieve a scheduler !

const Scheduler = require("@slimio/scheduler");
const Addon = require("@slimio/addon");

const myAddon = new Addon("myAddon");

async function sayHelloEveryOneSecond() {
   console.log("hello world");
}
myAddon
   .registerCallback(sayHelloEveryOneSecond)
   .schedule(new Scheduler({ interval: 1 }));

Execute a function at a regular interval

Addon bring his custom method to schedule timer interval. What difference with the setInterval of Node.js ?

  • Handle and manage errors for you (avoid falling into the Node.js deprecation 0018).
  • The function is only executed if the addon is awake.
  • They use SlimIO Timer under the hood to avoid drifting.
const myAddon = new Addon("myAddon");

async function regularJob() {
    myAddon.logger.writeLine("regular job has been triggered!");
}
myAddon.registerInterval(regularJob, 30000); // exactly execute regularJob every 30 seconds

It's best practice to use the Addon method instead of setInterval. If you still want to use Node.js setInterval, then be sure to not fall into UnhandledPromiseRejection (the core force best practice so the whole process will be stopped).

Waiting for another addon to be started

It is common for addons to work with each other. But often one or many externals addons can be vital to achieve one or many given tasks. Addon introduce the lockOn method to help developer to avoid unecessary try/catch and break controls.

const myAddon = new Addon("myAddon");

// Ask our addon to wait for events to be ready before being awake ourself.
myAddon.lockOn("events");

// Notice that we catch the 'awake' event instead of 'start'
myAddon.on("awake", async() => {
    // here we are sure that 'events' will be reachable (no need to try/catch that sendOne).
    const info = await myAddon.sendOne("events.get_info");
    console.log(info);
    
    // Now at our turn to declare our addon "ready" to work with others :)
    await myAddon.ready();
});

In a case where events is stopped (for any technical reasons) then our addon will be put in sleep (that the reverse of awake).

myAddon.on("sleep", () => {
   // we may want to close (free) active handlers here
});

More informations on events and states here.

Subscribing to given kinds of events (and receive them in real time).

It may be useful to catch the SlimIO events to achieve given tasks like managing Alarms and Metrics (that the case of Alerting and Aggregator Addons).

Available Subjects are statically available on Addon Class. Example with Alerting:

Alerting.of(Addon.Subjects.alarmUpdate).filter(([CID]) => Storms.has(CID)).subscribe({
    next([CID]) {
        const rule = Storms.get(CID);
        if (!rule.walk()) {
            return;
        }

        new Alarm(`Storm threshold below ${rule.occurence}`, {
            correlateKey: `storm_${CID}`,
            severity: rule.severity
        });
    },
    error(err) {
        Alerting.logger.writeLine(`Alarm.update | Finished with error: ${err}`);
    }
});

Subjects are described with the following TypeScript interface

export interface Subjects {
    ready: string;
    alarmOpen: string;
    alarmUpdate: string;
    alarmClose: string;
    micCreate: string;
    micUpdate: string;
}

After