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:
awsClientprovided 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.jsondefinition. 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.jsonfor the given method. They are also validated and no empty values are present in theparamsobject.
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.
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 callingawsServiceconstructor.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 eithertypeorparserTypeprovided inconfig.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:actionsandsettings.
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 filteringparams(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 eithertypeorparserTypeprovided inconfig.json.awsServiceClient(object) – the AWS service instance, the result of callingawsServiceconstructor.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:actionsandsettings.
ℹ️ Note:
UsingoriginalParametersin either plugin methods or autocomplete function is generally discouraged in favor of already parsedparamsobject.originalParametersshould 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.
This function returns an objects of bootstrapped functions, ready to be exported form your main plugin script (most likely app.js).
- 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 }, {});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.
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 .
This function returns another function, that should be passed to the bootstrap function, inside pluginMethods argument.
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();
}function removeUndefinedAndEmpty(object)Removes all of the object's fields which has value of empty string (""), empty object ({}), empty array([]), null, undefined
object (object) – object to be cleaned
A copy of provided object with all of it's "undefined and empty" fields removed.
function buildTagSpecification(resourceType, tags)Returns an AWS compatible tag specification object. More information: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_TagSpecification.html
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.
An AWS compatible tag specification object structured as follows:
{
"ResourceType": <resourceType>,
"Tags": [
"Tag1": "Tag-value1",
// ...
]
}bootstrap function and benefit from automatically parsed parameters, then you shouldn't use those
function removeCredentials(params, labels = consts.DEFAULT_CREDENTIAL_LABELS)Removes the credentials from the params based on provided labels.
ℹ️ Note:
This function is automatically called by corebootstrapfunction on every plugin method and autocomplete function for security reasons!
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"
},params object without the specified credentials keys.
function readRegion(params, settings, label = consts.DEFAULT_CREDENTIAL_LABELS.REGION)Retrieves parsed region from parameters or settings.
ℹ️ Note:
Value fromparametersalways take priority over the value insettings.
params (object) – raw action parameters
settings (object) – raw plugin settings
label (string) – label under which the region is stored. Default value: REGION.
String cotaining selected region.
function listRegions(query = "")An autocomplete function providing a list of AWS EC2 supported regions, filtered by query.
query (string) – query to filter the list by
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)regionId (string) – AWS region id
User-friendly region name
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.
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.
An autocomplete list with desired values
/*
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");function filterItemsByQuery(autocompleteItems, query)Filters the provided list of autocomplete items by given query
autocompleteItems (array of objects) – autocomplete items list to filter
query (string) – query to filter the list by
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
value (string) – value to create autocomplete item from
label (string) – label to be used to describe the value
A proper autocomplete item from the value in the form of:
{
"id": "value",
"value": "label"
}