diff --git a/README b/README deleted file mode 100644 index 75ddbcd..0000000 --- a/README +++ /dev/null @@ -1 +0,0 @@ -Instructions can be found under manual/index.html \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..46803ad --- /dev/null +++ b/README.md @@ -0,0 +1,173 @@ +
+ +
+ +# AWS Greengrass Core SDK for JavaScript + +The **AWS Greengrass Core SDK for JavaScript** allows developers to write JavaScript Lambda functions which will run within Greengrass. + +## Overview + +This document provides instructions for preparing your Greengrass Core environment to run Lambda functions written in JavaScript. It also includes examples on how to develop a Lambda function in JavaScript as well as packaging and running an example Hello World file in JavaScript for your Greengrass core. + +## Preparing your Greengrass to run NodeJS Lambda functions + +The environment where Greengrass is running on needs to be able to run NodeJS 8.10 applications. + +* Install NodeJS 8.10 for your platform. You can download the newest NodeJS from [https://nodejs.org/en/download/](https://nodejs.org/en/download/). +* When you untar the package downloaded from NodeJS website, you will find `node` file under `bin` directory. +* Copy the file to _**/usr/bin**_ or _**/usr/local/bin**_ folder. +* Rename the file to _**nodejs8.10**_ +* Make sure the file is not a symlink. + +## Getting Started - Hello World + +* Copy `samples/HelloWorld` folder to your workspace. +* Create a folder `node_modules` under `HelloWorld` folder. +* Unzip aws-greengrass-core-sdk-js.zip into the folder. It should create a folder HelloWorld/node_modules/aws-greengrass-core-sdk +* Zip up the content of HelloWorld folder so that the index.js is on the top of the zip file structure. +* Go to AWS Lambda Console. +* Create a new function. +* Choose the Runtime as `Node.js 8.10` +* Upload the zip file in _Lambda function code_ section. +* Handler is _index.handler_ +* Choose any role as the role is not used within Greengrass. +* After creating the function, publish the Lambda. +* Create an Alias and point to the Published version (not $LATEST). +* Go to your Greengrass Group and add the Lambda under Lambdas section. +* Click on the Lambda and change the _Lambda lifecycle_ to _Make this function long-lived and keep it running indefinitely._ +* Add a Subscription with the following configuration: + * Source: Lambda which you just created and added to the group + * Target: IoT Cloud + * Topic: hello/world +* Deploy. A message from your Lambda should be published to the topic _hello/world_ in the cloud every 5 seconds. You can check this by going to AWS IoT's _Test_ page and subscribing to topic _hello/world_. + +## Including aws-greengrass-core-sdk with your function + +Unzip the SDK into your node_modules folder of your function. This should create a aws-greengrass-core-sdk folder which includes the SDK. + +## Logging in NodeJS Lambdas + +Your _console.log_ operation will be logged as INFO. A _console.error_ operation will be logged as ERROR. Currently, our NodeJS SDK only allows you to log at INFO or ERROR level only. + +## Supported Datatypes + +From GGC version 1.5, you can send both JSON and binary data as a payload when you invoking other Lambdas or publishing a message using IotData service. In order to make your lambda be able to handle binary payload, you need to configure the lambda in Greengrass console to mark it using binary input payload so that GGC can know how to deal with the data. + +## Supported Context + +In Greengrass, you can send a context object in a JSON format to be passed to another Lambda that is being invoked. The context format looks like this: `{ custom: { customData: 'customData', }, }` + +## Compatibility + +
+ +
+ +## Compatibility[¶](#compatibility "Permalink to this headline") + +As new features are added to AWS Greengrass, previous versions of the Greengrass SDK will be incompatible with newer versions of the AWS Greengrass core. The following table lists the compatible SDKs for all GGC releases. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GGC VersionCompatible SDK Versions
1.0.x-1.6.x1.0.x-1.2.x
1.7.x-1.8.x1.0.x-1.3.x
1.9.x1.0.x-1.4.x
+ +
+ +
+ +## 1.4.0 Updates[¶](#1.4.0updates "Permalink to this headline") + +Added support for Node.js 8.10 Lambda runtime. Lambda functions that use Node.js 8.10 runtime can now run on an AWS IoT Greengrass core. (Existing Lambda functions that use Node.js 6.10 runtime can still run on Greengrass core, but they can’t be updated after 5/30/2019\. Please refer to [AWS Lambda Runtimes Support Policy](https://docs.aws.amazon.com/lambda/latest/dg/runtime-support-policy.html).) + +
+ +
+ +## 1.3.1 Updates[¶](#1.3.1updates "Permalink to this headline") + +Improved log level granularity. + +
+ +
+ +## 1.3.0 Updates[¶](#1.3.0updates "Permalink to this headline") + +SDK supports SecretsManager client. + +
+ +
+ +## 1.2.0 Updates[¶](#1.2.0updates "Permalink to this headline") + +SDK and GGC compatibility check takes place in the background. + +
+ +
+ +## 1.1.0 Updates[¶](#1.1.0updates "Permalink to this headline") + +Lambda only accepted payload in JSON format. With this update, Invoking or publishing binary payload to a lambda is supported. + +
+ +
+ +## 1.0.1 Updates[¶](#1.0.1updates "Permalink to this headline") + +SShadow operations were not receiving responses from the local shadow properly. This has been fixed. + +Lambda Invoke function's InvocationType's default value was Event. This has been changed to RequestResponse. + +
+ +## Getting Help + +* [Ask on a Greengrass forum](https://forums.aws.amazon.com/forum.jspa?forumID=254) + +## License + +Apache 2.0
+ + + diff --git a/aws-greengrass-core-sdk/index.js b/aws-greengrass-core-sdk/index.js new file mode 100644 index 0000000..dd11906 --- /dev/null +++ b/aws-greengrass-core-sdk/index.js @@ -0,0 +1,7 @@ +/* + * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + */ +exports.GreengrassInterfaceVersion = '1.3'; +exports.Lambda = require('./lambda'); +exports.IotData = require('./iotdata'); +exports.SecretsManager = require('./secretsmanager'); diff --git a/aws-greengrass-core-sdk/iotdata.js b/aws-greengrass-core-sdk/iotdata.js new file mode 100644 index 0000000..c40c80e --- /dev/null +++ b/aws-greengrass-core-sdk/iotdata.js @@ -0,0 +1,148 @@ +/* + * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + */ + +const Buffer = require('buffer').Buffer; + +const Lambda = require('./lambda'); +const Util = require('./util'); +const GreengrassCommon = require('aws-greengrass-common-js'); + +const envVars = GreengrassCommon.envVars; +const MY_FUNCTION_ARN = envVars.MY_FUNCTION_ARN; +const SHADOW_FUNCTION_ARN = envVars.SHADOW_FUNCTION_ARN; +const ROUTER_FUNCTION_ARN = envVars.ROUTER_FUNCTION_ARN; + +class IotData { + constructor() { + this.lambda = new Lambda(); + } + + getThingShadow(params, callback) { + /* + * Call shadow lambda to obtain current shadow state. + * @param {object} params object contains parameters for the call + * REQUIRED: 'thingName' the name of the thing + */ + const thingName = Util.getRequiredParameter(params, 'thingName'); + if (thingName === undefined) { + callback(new Error('"thingName" is a required parameter.'), null); + return; + } + + const payload = ''; + this._shadowOperation('get', thingName, payload, callback); + } + + updateThingShadow(params, callback) { + /* + * Call shadow lambda to update current shadow state. + * @param {object} params object contains parameters for the call + * REQUIRED: 'thingName' the name of the thing + * 'payload' the state information in JSON format + */ + const thingName = Util.getRequiredParameter(params, 'thingName'); + if (thingName === undefined) { + callback(new Error('"thingName" is a required parameter.'), null); + return; + } + + const payload = Util.getRequiredParameter(params, 'payload'); + if (payload === undefined) { + callback(new Error('"payload" is a required parameter.'), null); + return; + } + + this._shadowOperation('update', thingName, payload, callback); + } + + deleteThingShadow(params, callback) { + /* + * Call shadow lambda to delete the shadow state. + * @param {object} params object contains parameters for the call + * REQUIRED: 'thingName' the name of the thing + */ + const thingName = Util.getRequiredParameter(params, 'thingName'); + if (thingName === undefined) { + callback(new Error('"thingName" is a required parameter.'), null); + return; + } + + const payload = ''; + this._shadowOperation('delete', thingName, payload, callback); + } + + publish(params, callback) { + /* + * Publishes state information. + * @param {object} params object contains parameters for the call + * REQUIRED: 'topic' the topic name to be published + * 'payload' the state information in JSON format + */ + const topic = Util.getRequiredParameter(params, 'topic'); + if (topic === undefined) { + callback(new Error('"topic" is a required parameter'), null); + return; + } + + const payload = Util.getRequiredParameter(params, 'payload'); + if (payload === undefined) { + callback(new Error('"payload" is a required parameter'), null); + return; + } + + const context = { + custom: { + source: MY_FUNCTION_ARN, + subject: topic, + }, + }; + + const buff = Buffer.from(JSON.stringify(context)); + const clientContext = buff.toString('base64'); + + const invokeParams = { + FunctionName: ROUTER_FUNCTION_ARN, + InvocationType: 'Event', + ClientContext: clientContext, + Payload: payload, + }; + + console.log(`Publishing message on topic "${topic}" with Payload "${payload}"`); + + this.lambda.invoke(invokeParams, (err, data) => { + if (err) { + callback(err, null); // an error occurred + } else { + callback(null, data); // successful response + } + }); + } + + _shadowOperation(operation, thingName, payload, callback) { + const topic = `$aws/things/${thingName}/shadow/${operation}`; + const context = { + custom: { + subject: topic, + }, + }; + + const clientContext = Buffer.from(JSON.stringify(context)).toString('base64'); + const invokeParams = { + FunctionName: SHADOW_FUNCTION_ARN, + ClientContext: clientContext, + Payload: payload, + }; + + console.log(`Calling shadow service on topic "${topic}" with payload "${payload}"`); + this.lambda.invoke(invokeParams, (err, data) => { + if (err) { + callback(err, null); + } else { + callback(null, data); + } + }); + } +} + +module.exports = IotData; diff --git a/aws-greengrass-core-sdk/lambda.js b/aws-greengrass-core-sdk/lambda.js new file mode 100644 index 0000000..1380b93 --- /dev/null +++ b/aws-greengrass-core-sdk/lambda.js @@ -0,0 +1,116 @@ +/* + * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + */ + +const Util = require('./util'); +const IPCClient = require('aws-greengrass-ipc-sdk-js'); +const GreengrassCommon = require('aws-greengrass-common-js'); +const logging = require('aws-greengrass-common-js').logging; + +const AUTH_TOKEN = GreengrassCommon.envVars.AUTH_TOKEN; + +const logger = new logging.LocalWatchLogger(); + +class Lambda { + constructor() { + this.ipc = new IPCClient(AUTH_TOKEN); + } + + invoke(params, callback) { + const functionName = Util.getRequiredParameter(params, 'FunctionName'); + if (functionName === undefined) { + callback(new Error('"FunctionName" is a required parameter'), null); + return; + } + + let arnFields; + try { + arnFields = new GreengrassCommon.FunctionArnFields(functionName); + } catch (e) { + callback(new Error(`FunctionName is malformed: ${e}`), null); + return; + } + + let invocationType; + if (params.InvocationType === undefined || params.InvocationType === null) { + invocationType = 'RequestResponse'; + } else { + invocationType = params.InvocationType; + } + + if (invocationType !== 'Event' && invocationType !== 'RequestResponse') { + callback(new Error(`InvocationType '${invocationType}' is incorrect, should be 'Event' or 'RequestResponse'`), null); + return; + } + + const clientContext = params.ClientContext ? params.ClientContext : ''; + const payload = params.Payload; + const qualifier = params.Qualifier; + + if (!Util.isValidQualifier(qualifier)) { + callback(new Error(`Qualifier '${qualifier}' is incorrect`), null); + return; + } + + const qualifierInternal = arnFields.qualifier; + + // generate the right full function arn with qualifier + if (qualifierInternal && qualifier && qualifierInternal !== qualifier) { + callback(new Error(`Qualifier '${qualifier}' does not match the version in FunctionName`), null); + return; + } + + const finalQualifier = qualifierInternal === undefined || qualifierInternal == null ? qualifier : qualifierInternal; + + let functionArn; + if (typeof GreengrassCommon.buildFunctionArn === 'function') { + // GGC v1.9.0 or newer + functionArn = GreengrassCommon.buildFunctionArn( + arnFields.unqualifiedArn, + finalQualifier); + } else { + // older version of GGC + throw new Error('Function buildFunctionArn not found. buildFunctionArn is introduced in GGC v1.9.0. ' + + 'Please check your GGC version.'); + } + + // verify client context is base64 encoded + if (Object.prototype.hasOwnProperty.call(params, 'ClientContext')) { + const cxt = params.ClientContext; + if (!Util.isValidContext(cxt)) { + callback(new Error('Client Context is invalid'), null); + return; + } + } + + logger.debug(`Invoking local lambda ${functionArn} with payload ${payload} and client context ${clientContext}`); + + this.ipc.postWork(functionArn, payload, clientContext, invocationType, (postWorkErr, invocationId) => { + if (postWorkErr) { + logger.error(`Failed to invoke function due to ${postWorkErr}`); + callback(postWorkErr, null); + return; + } + + if (invocationType === 'RequestResponse') { + this.ipc.getWorkResult(functionArn, invocationId, (getWorkResultErr, body, functionErr, statusCode) => { + if (getWorkResultErr) { + logger.error(`Failed to get work result due to ${getWorkResultErr}`); + callback(getWorkResultErr, null); + return; + } + const data = { + FunctionError: functionErr, + StatusCode: statusCode, + Payload: body, + }; + callback(null, data); + }); + } else { + callback(null, invocationId); + } + }); + } +} + +module.exports = Lambda; diff --git a/aws-greengrass-core-sdk/secretsmanager.js b/aws-greengrass-core-sdk/secretsmanager.js new file mode 100644 index 0000000..80a7c15 --- /dev/null +++ b/aws-greengrass-core-sdk/secretsmanager.js @@ -0,0 +1,95 @@ +/* + * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + */ +const Buffer = require('buffer').Buffer; + +const Lambda = require('./lambda'); +const Util = require('./util'); +const GreengrassCommon = require('aws-greengrass-common-js'); + +const KEY_SECRET_ID = 'SecretId'; +const KEY_VERSION_ID = 'VersionId'; +const KEY_VERSION_STAGE = 'VersionStage'; +const KEY_SECRET_ARN = 'ARN'; +const KEY_SECRET_NAME = 'Name'; +const KEY_CREATED_DATE = 'CreatedDate'; + +const envVars = GreengrassCommon.envVars; +const SECRETS_MANAGER_FUNCTION_ARN = envVars.SECRETS_MANAGER_FUNCTION_ARN; + +class SecretsManager { + constructor() { + this.lambda = new Lambda(); + } + + getSecretValue(params, callback) { + const secretId = Util.getRequiredParameter(params, KEY_SECRET_ID); + const versionId = Util.getRequiredParameter(params, KEY_VERSION_ID); + const versionStage = Util.getRequiredParameter(params, KEY_VERSION_STAGE); + + if (secretId === undefined) { + callback(new Error(`"${KEY_SECRET_ID}" is a required parameter`), null); + return; + } + // TODO: Remove this once we support query by VersionId + if (versionId !== undefined) { + callback(new Error('Query by VersionId is not yet supported'), null); + return; + } + if (versionId !== undefined && versionStage !== undefined) { + callback(new Error('VersionId and VersionStage cannot both be specified at the same time'), null); + return; + } + + const getSecretValueRequestBytes = + SecretsManager._generateGetSecretValueRequestBytes(secretId, versionId, versionStage); + + const invokeParams = { + FunctionName: SECRETS_MANAGER_FUNCTION_ARN, + Payload: getSecretValueRequestBytes, + }; + + console.log(`Getting secret value from secrets manager: ${getSecretValueRequestBytes}`); + + this.lambda.invoke(invokeParams, (err, data) => { + if (err) { + callback(err, null); // an error occurred + } else if (SecretsManager._is200Response(data.Payload)) { + callback(null, data.Payload); // successful response + } else { + callback(new Error(JSON.stringify(data.Payload)), null); // error response + } + }); + } + + static _generateGetSecretValueRequestBytes(secretId, versionId, versionStage) { + const request = { + SecretId: secretId, + }; + + if (versionStage !== undefined) { + request.VersionStage = versionStage; + } + + if (versionId !== undefined) { + request.VersionId = versionId; + } + + return Buffer.from(JSON.stringify(request)); + } + + static _is200Response(payload) { + const hasSecretArn = this._stringContains(payload, KEY_SECRET_ARN); + const hasSecretName = this._stringContains(payload, KEY_SECRET_NAME); + const hasVersionId = this._stringContains(payload, KEY_VERSION_ID); + const hasCreatedDate = this._stringContains(payload, KEY_CREATED_DATE); + + return hasSecretArn && hasSecretName && hasVersionId && hasCreatedDate; + } + + static _stringContains(src, target) { + return src.indexOf(target) > -1; + } +} + +module.exports = SecretsManager; diff --git a/aws-greengrass-core-sdk/util.js b/aws-greengrass-core-sdk/util.js new file mode 100644 index 0000000..b02fa8e --- /dev/null +++ b/aws-greengrass-core-sdk/util.js @@ -0,0 +1,41 @@ +/* + * Copyright 2010-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. + */ + +const base64Regex = /^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$/; +const qualifierRegex = /(|[a-zA-Z0-9$_-]+)/; + +exports.getRequiredParameter = function _getRequiredParameter(params, requiredParam) { + if (!Object.prototype.hasOwnProperty.call(params, requiredParam)) { + return; + } + return params[requiredParam]; +}; + +exports.isValidJSON = function _isValidJSON(str) { + try { + JSON.parse(str); + } catch (e) { + return false; + } + return true; +}; + +exports.isValidContext = function _isValidContext(context) { + if (!base64Regex.test(context)) { + return false; + } + try { + JSON.stringify(context); + } catch (e) { + return false; + } + return true; +}; + +exports.isValidQualifier = function _isValidQualifier(qualifier) { + if (!qualifierRegex.test(qualifier)) { + return false; + } + return true; +}; diff --git a/sdk/aws-greengrass-core-sdk-js.tar.gz b/sdk/aws-greengrass-core-sdk-js.tar.gz deleted file mode 100644 index def31fc..0000000 Binary files a/sdk/aws-greengrass-core-sdk-js.tar.gz and /dev/null differ