AWS SSM Parameter Store based discovery client

Library that provides an easier access to AWS SSM Parameter store to use it as a resilient distributed key/value storage for service discovery.

Read about AWS SSM Parameter Store here.

Install

npm i --save aws-sdk @assetchain/parameter-store-discovery-client

Example

Here is the example how to use parameter discovery service in your lambda

import { ParameterDiscoveryService } from '@assetchain/parameter-store-discovery-client';

// Init parameter
const store = new ParameterDiscoveryService({}, {stage: 'dev'});
// You can prefetch some parameters outside of your lambda handler
// Be aware that this is an async call and it may not be complete before handler executed
store.get([
    '/services/accounts/baseUrl',
    '/services/transactions/baseUrl',
    '/services/transactions/timeout'
]);

export async function handler(event, context, callback) {
    // if you already have parameter fetched in line #26 then this will load it from a cache
    const response = await fetch(store.get('/services/accounts/baseUrl'));
    // if you don't have parameter fetched already - it will make a call and cache it for a some time
    const response = await fetch(store.get('/services/accounts/random'));
}

Docs

new ParameterDiscoveryService([awsConfig: Object], [options: Object])

Where awsConfig is AWS SDK Configuration object that will be passed directly. It has many configuration options and uses this one as a default:

• region (defaults to process.env.REGION)

Optional arguments within options object are these:

• stage (defaults to process.env.STAGE) - stage that will be used as a prefix for all your keys like /${stage}/my/key/name
• ttl (30000) - time to live for your cache, new call will be made to AWS API if cache expired
• isFallbackEnabled (true) - enable or disable Fallback Mode (read below)
• fallbackStage ('master') - stage that will be used to search for parameter if main stage parameter not found
• isAutoRefreshEnabled (false) - set a timeout to automatically refresh cache when it expires even if no get calls have been made. Be careful as internal SetInterval may prevent a shutdown of your lambda as you have to manually cancel this.timeout

Example

const parameterDiscoveryService = new ParameterDiscoveryService({region: 'ap-southeast-2'}, {stage: 'dev', ttl: 120000});

ParameterDiscoveryService.get(path: String, [options: Object]): Promise

ParameterDiscoveryService.get(paths: Array, [options: Object]): Promise<Map>

Retrieves a parameter or multiple parameters from the storage. It will automatically decrypt them if needed as WithDecryption: true option is set by default. Retrieved value will be stored in internal cache and retrived from there if it's not expired.

Parameter has structure like

{
    "Name": "string",
    "Type": "string",
    "Value": "string",
    "Version": number
}

Promise from ParameterDiscoveryService.get(['something'], options) will return a HashMap with parameters objects where promise from ParameterDiscoveryService.get('something', options) will return parameter object

const parameterDiscoveryService = new ParameterDiscoveryService({region: 'ap-southeast-2'}, {stage: 'dev'});

async printBaseUrl() {
  const baseUrl = await parameterDiscoveryService.get('/service/accounts/baseUrl'); 
  
  console.log(baseUrl.Value) // prints parameter from /dev/service/accounts/baseUrl
}

async printManyParams() {
  const parameters = await parameterDiscoveryService.get(['/service/accounts/baseUrl', '/service/transactions/limit']);
  
  console.log(parameters) // this is a hashMap so...
  console.log(parameters.get('/service/accounts/baseUrl').Value) // prints parameter from /dev/service/accounts/baseUrl
  console.log(parameters.get('/service/transactions/limit').Value) // prints parameter from /dev/service/transactions/limit
}

ParameterDiscoveryService.set(path: String, value: String|Array, [options]): Promise

Set parameter in AWS SSM Parameter Store. You can pass either string or array of strings here. Non strings values will be converted to strings.

AWS Option for Overwrite set to true by default but you can overwrite it. You can check AWS API reference for PutParameter to get a better idea what options you can pass through

const parameterDiscoveryService = new ParameterDiscoveryService({region: 'ap-southeast-2'}, {stage: 'dev'});

async updateBaseUrl(url) {
  const result = await parameterDiscoveryService.set('/service/accounts/baseUrl', url);
  console.log(result); // Something like {Version: 12}
}

ParameterDiscoveryService.setEncrypted(path: String, value: String, [options]): Promise

The same as .set() described above but option for parameter type set to SecureString. If you don't specify a KMS key ID (KeyId), the system uses the default key associated with your AWS account.

Fallback Mode

By default this library operates with enabled Fallback Mode. That means if parameter wasn't found by /${stage}/path/to/param path then library will try to retrieve it from /${fallbackStage/path/to/param. This is extremely useful if you deploy your branches next to master when they can reach each other. If your branch don't have any configuration - it will fallback to use master parameters.

You can disable that behaviour or change fallback stage by defining and passing isFallbackEnabled and fallbackStage arguments to the constructor

Development

Build this library using npm build - that will run eslint + prettier checks and unit tests

License

The MIT License (MIT)

Copyright © 2017 AssetChain

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.