@kaholo/aws-plugin-library v4.0.2

Overview

This library is an extention of Kaholo Plugin Library. All concepts introduced in there are still valid here, including the bootstrapping. The only difference is that this library includes AWS specific functionality on top of the generic one.

The bootstrapping allows the plugin methods to take the form of:

function pluginMethod(awsClient, params, region)

instead of the typical

function pluginMethod(action, settings)

When using the bootstrapping, the developer can always be sure that:

• awsClient provided in the first argument is already authenticated instance of given AWS service
• the parameters the plugin method receives are parsed and validated based on their config.json definition. Moreover they are already combined with the settings, so no need to handle those separately. The AWS credentials are stripped from the parameters for security reasons.
• the parameters only consists of the values that are defined in config.json for the given method. They are also validated and no empty values are present in the params object.

Core library

bootstrap

function bootstrap (awsService, pluginMethods, autocompleteFuncs)

Allows to use more developer friendly version of plugin methods, removing the necessity of performing such repetitive tasks like manually parsing action arguments and settings or calling the AWS Service constructor.

Parameters

awsService (function) – Native AWS API constructor for the AWS service to be used. This constructor will be called with credentials passed to any of the provided plugin methods and it's result will be passed as a method parameter.

pluginMethods (object) – an object containing all of the plugin methods to be bootstrapped within Kaholo AWS Library. The following parameters will be passed to each and every method provided in this object:

• client (object) – the AWS service instance, the result of calling awsService constructor.
• params (object) – the object containing all of the parameters passed to an action combined with plugin settings. All of the values in this object are already parsed based on either type or parserType provided in config.json.
• region (string) – the region that was provided in action parameters or plugin settings in AWS compatible format.
• originalParameters (object) – the original Kaholo plugin method parameters. The object contains two fields: actions and settings.

autocompleteFuncs (object) – an object containing all of the autocomplete functions to be bootstrapped with Kaholo AWS Library. The following parameters will be passed to each and every function provided in this object:

• query (string) - a query to be used for result filtering
• params (object) - the object containing all of the parameters passed to an action combined with plugin settings. All of the values in this object are already parsed on either type or parserType provided in config.json.
• awsServiceClient (object) – the AWS service instance, the result of calling awsService constructor.
• region (string) – the region that was provided in action parameters or plugin settings in AWS compatible format.
• originalParameters – the original Kaholo plugin method parameters. The object contains two fields: actions and settings.

:information_source: Note: Using originalParameters in either plugin methods or autocomplete function is generally discouraged in favor of already parsed params object. originalParameters should only be used in case when access to the raw object is absolutely necessary – if you wonder if you need to use it, you probably don't.

Returned value

This function returns an objects of bootstrapped functions, ready to be exported form your main plugin script (most likely app.js).

Example usage

• config.json

{
	// ...
	"methods": [
		"name": "describeInstances",
		"params": [
			// ...
			{
				"name": "instanceIds",  
				"type": "text",  
				"parserType": "array",  
				"required": true,  
			}
			// ...
		]
	]
}

• app.js

const aws = require("aws-sdk");
const kaholo = require("kaholo-aws-plugin");

function describeInstances(client, params) {
	// because `instanceIds` is defined in config.json with
	// "parserType": "array", the value of `instanceIds` in `params`
	// will already be parsed as an array - no need to handle this manually!
	const instanceIds = params.instanceIds;
	// Client is aws.EC2 instance, already authenticated with the credentials
	// passed as action params or plugin settings.
	return client.describeInstances({ InstanceIds: instanceIds }).promise(); 
}

module.exports = kaholo.bootstrap(aws.EC2, { describeInstances }, {});

generateAwsMethod

function generateAwsMethod (functionName, payloadFunction = null)

Provides a shorthand way of simply calling AWS SDK functions for given service. This is useful if the whole plugin method should not contain any logic besides calling the SDK with arguments provided in action parameters.

Parameters

functionName (string) – name of AWS service function to be called.

payloadFunction (function) – a function that should be called on already parsed action arguments. This is useful if there is only a simple manipulation or validation on the parameters is required. The function needs to take two arguments – params (an object containing already parsed action parameters and settings) and region (string), and should return object. The return value will be directly passed as parameter to the function specified with functionName .

Returned value

This function returns another function, that should be passed to the bootstrap function, inside pluginMethods argument.

Example usage

const aws = require("aws-sdk");
const kaholo = require("kaholo-aws-library");

const describeInstances = kaholo.generateAwsMethod("describeInstances");

module.exports = kaholo.bootstrap(aws.EC2, { describeInstances }, {});

Please note, that:

const describeInstances = kaholo.generateAwsMethod("describeInstances");

will generate describeInstances as a direct equivalent of the following function:

function describeInstances(client, params) {
	if (!_.hasIn(client, "describeInstances")) {  
	 throw new Error(`No method "describeInstances" found on client!`);  
	}
	const payload = helpers.removeUndefinedAndEmpty(params);  
  
return client.describeInstances(payload).promise();
}

Helpers

removeUndefinedAndEmpty

function removeUndefinedAndEmpty(object)

Removes all of the object's fields which has value of empty string (""), empty object ({}), empty array([]), null, undefined

Parameters

object (object) – object to be cleaned

Returned value

A copy of provided object with all of it's "undefined and empty" fields removed.

buildTagSpecification

function buildTagSpecification(resourceType, tags)

Returns an AWS compatible tag specification object. More information: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_TagSpecification.html

Parameters

resourceType (string) – Resource type to be used for tag specification tags (string, array of strings, object or array of objects) – Tags to be used in tags specification. Both parsed and unparsed. Please refer to tags parser documentation below to see the acceptable tags format.

Returned value

An AWS compatible tag specification object structured as follows:

{
	"ResourceType": <resourceType>,
	"Tags": [
		"Tag1": "Tag-value1",
		// ...
	]
}

:warning: The functions below are meant to be used with raw action parameters and settings provided from Kaholo platform. If you intend to use bootstrap function and benefit from automatically parsed parameters, then you shouldn't use those :warning:

removeCredentials

function removeCredentials(params, labels = consts.DEFAULT_CREDENTIAL_LABELS)

Removes the credentials from the params based on provided labels.

:information_source: Note: This function is automatically called by core bootstrap function on every plugin method and autocomplete function for security reasons!

Parameters

params (object) – Object to remove credentials from. labels (object) – Object that specifies what labels to search for. The default value is defined as follows:

  "DEFAULT_CREDENTIAL_LABELS": {
    "ACCESS_KEY": "AWS_ACCESS_KEY_ID",
    "SECRET_KEY": "AWS_SECRET_ACCESS_KEY",
    "REGION": "REGION"
  },

Returned value

params object without the specified credentials keys.

readRegion

function readRegion(params, settings, label = consts.DEFAULT_CREDENTIAL_LABELS.REGION)

Retrieves parsed region from parameters or settings.

:information_source: Note: Value from parameters always take priority over the value in settings.

Parameters

params (object) – raw action parameters settings (object) – raw plugin settings label (string) – label under which the region is stored. Default value: REGION.

Returned value

String cotaining selected region.

Autocomplete

listRegions

function listRegions(query = "")

An autocomplete function providing a list of AWS EC2 supported regions, filtered by query.

Parameters

query (string) – query to filter the list by

Returned value

A list of autocomplete objects containing all of the AWS EC2 supported regions, filtered by query.

function getRegionLabel(regionId)

Provides a user-friendly name of the region based on the region id, for example:

console.log(getRegionLabel("eu-west-2"));

// output:
// Europe (London)

Parameters

regionId (string) – AWS region id

Returned value

User-friendly region name

autocompleteListFromAwsCall

function autocompleteListFromAwsCall(listFuncName, pathToArray = "", pathToValue = "")

Creates a autocomplete list based on the result of AWS Service method call. This function returns another function that when executed, will call the AWS service method and extract the list of elements based on provided parameters to create a autocomplete list.

Parameters

listFuncName (string) – a name of the function to be called on AWS service client pathToArray (string) – a path to array on the returned object pathToValue (string) – a path to the value. This is to be used in case that pathToArray leads to array of objects – in this case this path determines where in such object is the value that we want to use in the autocomplete list.

Returned value

An autocomplete list with desired values

Example usage

/* 
The value returned from AWS S3 "listBuckets" function is structured as follows:

{ 
	Buckets: [ 
		{ CreationDate: <Date Representation>, Name: "examplebucket" }, 
		{ CreationDate: <Date Representation>, Name: "examplebucket2" }, 
		{ CreationDate: <Date Representation>, Name: "examplebucket3" } 
	], 
	Owner: { 
		DisplayName: "own-display-name", 
		ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31" 
	} 
}

So in order to get a function that will retrieve the list of autocomplete items with only the bucket names, we can call `listBucketsAutocomplete` in the following way:
*/

autocomplete.autocompleteListFromAwsCall("listBuckets", "Buckets", "Name");

filterItemsByQuery

function filterItemsByQuery(autocompleteItems, query)

Filters the provided list of autocomplete items by given query

Parameters

autocompleteItems (array of objects) – autocomplete items list to filter query (string) – query to filter the list by

Returned value

An alphabetically sorted list of all autocomplete items that contains all of the words in query

function toAutocompleteItemFromPrimitive(value, label = value)

Creates an autocomplete item from value

Parameters

value (string) – value to create autocomplete item from label (string) – label to be used to describe the value

Returned value

A proper autocomplete item from the value in the form of:

{
	"id": "value",
	"value": "label"
}