@liongard/roar-sdk v0.4.0

Roar SDK

Roar SDK is designed to make development for Roar Inspectors easy and consistent. It provides all the needed functionality common to inspectors and Roar specific resources an inspector might need. When env is development, the SDK looks for a credentials.json document in your working directory and expects it to contain the roar platform url and credentials. In production, the credentials are to be passed as command line params.

Installation

yarn install @liongard/roar-sdk

Configurable Environment Vars:

• NODE_ENV
  • default: (no value or 'production') sends to AWS.
  • 'development' --> Dumps payloads and logs locally rather than to AWS.
• ROAR_SDK
  • default: AWS is configured remotely as normal..
  • 'localstack' --> Dumps payloads to localstack AWS mock.

Expected Environment Vars for production:

• AGENT_ID
• AGENT_NAME
• AGENT_UID
• AWS_ACCESS_KEY_ID
• AWS_REGION
• AWS_SECRET_ACCESS_KEY
• RESPONSE_QUEUE

API

Example usage:

const { platform } = require('@liongard/roar-sdk');
platform.log.info('hello world');
platform.sendPayload({name:"hello world"});

Functions

getBase64Credentials - Returns the credentials for the job encoded in base64 and ready for usage in the typical http request scenario as the value for the X-ROAR-API-KEY. Example usage:

request({
      method: 'GET',
      url,
      json: true,
      headers: {
        Accept: 'application/json',
        'X-ROAR-API-KEY': `${roarSDK.getBase64Credentials()}`,
      },
    },...

getURL() - Returns the url that was defined in the credentials for the roar platform.

getJob() - Returns the entire job object (aka credentials).

log.info(string message) - Sends an informational message to the roar platform.

log.preflight(string message) - Sends a message to the roar platform indicating that there was a problem in preflight validation. Tells the local process to exit with exit code 2 because validation has failed.

log.fatal(string message) - Sends a message to the roar platform indicating that a fatal error has occured and processing cannot continue. Tells the local process to exit with exit code 1.

log.verbose(string message) - sends a message to the Roar platform that shows up in the UI only when the inspector is run in debug mode. Useful for very verbose logging.

sendPayload(object payload) - Sends the provided json to the roar platform s3 bucket using the credentials provided in credentials.json or on the command line. When NODE_ENV is development, writes payload to a local file called payload rather than calling s3.

Note: The dependency 'ssh2shell' needs to stay at version 1.9.1 and should not be upgraded to anything newer as of now. An issue was introduced in later versions where a ECONNABORT error is no longer caught by the ssh session's error handler. This was due to a change where the callbacks for the dependency were moved to be associated with a different object (from stream.finish to connection.close).

Authentication

Example usage:

const { authentication } = require('@liongard/roar-sdk');

Functions

AuthKeyController() - Authentication via bearer token. Instantiate this class to create auth key controller.

const keyController = new authentication.AuthKeyController();
keyController
    .getAccessToken(
      tokenKey,
      authTokenUrl,
      authData,
      authConfig,
      expiryTimeSeconds
    )