README.md

Installer

SlimIO Agent and Addons installer. We use this package in:

• the CLI to install and clone the agent and all addons.
• Tcp-SDK for testing the communication with the Socket addon.

This package has been designed to be used by Addons to achieve clean unit-testing (by re-cloning a complete agent).

Requirements

• Node.js v12 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/installer
# or
$ yarn add @slimio/installer

Usage example

Clone a SlimIO agent (what we do for example in the Tcp-Sdk test suite).

const installer = require("@slimio/installer");
const treekill = require("tree-kill");

async function main() {
    const agentDir = process.cwd();
    await installer.initAgent(agentDir, { name: "agent" });

    // Start the SlimIO Agent his child process
    const cp = await installer.runAgent(agentDir, true);

    try {
        // Do your work here...
    }
    finally {
        treekill(cp.pid);
    }
}
main().catch(console.error);

Or install SlimIO Addons in a valid SlimIO Agent directory.

const installer = require("@slimio/installer");

// CONSTANTS
const kAddonsToInstall = ["cpu", "MySQL"];

async function main() {
    const agentDir = process.cwd();

    await Promise.allSettled(
        kAddonsToInstall.map((addonName) => installer.installAddon(addonName, agentDir))
    );
}
main().catch(console.error);

API

initAgent(location: string, options?: InitOptions): Promise< string >

This method will extract and install all required (built-in) addons for a SlimIO Agent.

interface InitOptions {
    token?: string;
    name?: string;
    forceClean?: boolean;
}

By default forceClean is equal to true (this mean that the code will try to remove any agent on the system!).

runAgent(location: string, silent?: boolean, options?: object): Promise< NodeJS.ReadStream >

Run a given SlimIO Agent in a dedicated Node.js child process. Return the process Read Stream.

installDependencies(cwd?: string, lock?: boolean): Promise< void >

Install the dependencies of a given Node.js project directory (it spawn a Node.js process to run the npm install / npm ci command). This command only install production dependencies (devDependencies are ignored).

The current working dir value is process.cwd().

renameDirFromManifest(dir?: string, fileName?: string): Promise< string >

Found the real addon name in the SlimIO manifest file and rename the directory name (because by default the directory name is the one from github which is a bad thing). This method is automatically used in installAddon.

By default value of the fileName argument is slimio.toml. The current working dir value is process.cwd().

extractAgent(dest: string, options?: ExtractOptions): Promise< string >

Download the Agent archive on github (or extract a recent version stored in cache for performance). This method is used by initAgent.

interface ExtractOptions {
    downloadFromRemote?: boolean;
    token?: string;
    name?: string;
}

By default downloadFromRemote is equal to true.

installAddon(addonExpr: string, dest: string, options?: InstallOptions): Promise< string >

Install one Addon at the given destination (which must be a valid SlimIO Agent path).

interface InstallOptions {
    installDependencies?: boolean;
    searchInRegistry?: boolean;
    token?: string;
}

By default the dependencies of the addon will be installed. The searchInRegistry default value is false.

await installAddon("SlimIO.Socket", "./myAgent");
await installAddon("YourGithubOrg.AddonName", "./myAgent");
await installAddon("Alerting", "./myAgent"); // Same as SlimIO.Alerting
await installAddon("https://github.com/SlimIO/Aggregator", "./myAgent");

parseAddonExpr(addonExpr: URL | string): ExprResult

Parse an Addon installation expression. The function try to guess the Organization and the Repository name by itself, if there is no org then it will return SlimIO as the default org. The returned payload is described by the following TypeScript interface:

interface ExprResult {
    repoUserOrg: string;
    repoName: string;
    host: null | string;
}

Current supported host are github.com and gitlab.com.

parseAddonExpr("https://github.com/SlimIO/Socket"); // { repoUserOrg: "SlimIO", repoName: "Socket", host: "github.com" }
parseAddonExpr("Socket"); // { repoUserOrg: "SlimIO", repoName: "Socket", host: null }
parseAddonExpr("Foo/Socket"); // { repoUserOrg: "Foo", repoName: "Socket", host: null }

setRegistryURL(url: URL): void

Configure the default registry URL used under the hood by the Registry SDK package.

CONSTANTS

The list of builtin addons can be retrieved with the CONSTANTS object.

const { CONSTANTS } = require("@slimio/installer");

console.log(CONSTANTS.BUILT_IN_ADDONS);

Dependencies

Name	Refactoring	Security Risk	Usage
@slimio/github	Minor	Medium	Download and extract github repositories
@slimio/gitlab	Minor	Medium	Download and extract gitlab repositories
@slimio/manifest	Minor	Low	Read, Write and manage SlimIO manifest
@slimio/registry-sdk	Minor	Low	SlimIO Registry SDK
tar-fs	Minor	High	fs bindings for tar-stream

License

MIT