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 theparams
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 callingawsService
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 eithertype
orparserType
provided 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:actions
andsettings
.
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 eithertype
orparserType
provided inconfig.json
. -
awsServiceClient
(object) – the AWS service instance, the result of callingawsService
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
andsettings
.
ℹ️ Note:
UsingoriginalParameters
in either plugin methods or autocomplete function is generally discouraged in favor of already parsedparams
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",
// ...
]
}
bootstrap
function and benefit from automatically parsed parameters, then you shouldn't use those
removeCredentials
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 corebootstrap
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.
ℹ️ Note:
Value fromparameters
always take priority over the value insettings
.
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"
}