aws-liveness

Waits for AWS/localstack services to be up and running.

Install

npm i --save aws-liveness

Usage

import AWSLiveness from 'aws-liveness';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

const awsLiveness = new AWSLiveness();

// ping and wait services up to 10 seconds
try {
  await awsLiveness.waitForServices({
    clients: [new DynamoDBClient()],
    waitSeconds: 10
  });
  console.log('services are live');
} catch (err) {
  console.error('service liveness failed', err);
}

// ping a service
try {
  await awsLiveness.ping({ client: new DynamoDBClient() });
  console.log('dynamodb ping success');
} catch (err) {
  console.error('dynamodb ping failed', err);
}

Customization

By default, AWSLiveness supports running the following liveness commands for the following client types:

Client	Method
DynamoDBClient	ListTablesCommand
KinesisClient	ListStreamsCommand
S3Client	ListBucketsCommand
SNSClient	ListPlatformApplicationsCommand
SQSClient	ListQueuesCommand

You can also create additional checks to customize liveness.

import AWSLiveness from 'aws-liveness';
import { DynamoDBClient, DescribeTableCommand } from '@aws-sdk/client-dynamodb';

class MyCustomService {
  async fetchSomeData () {
    return { foo: 'bar' }
  }
}

const customServices = [{
  test: client => client instanceof DynamoDBClient,
  ping: client => client.send(new DescribeTableCommand({ TableName: 'Foo' }))
}, {
  test: client => client instanceof MyCustomService,
  ping: client => client.fetchSomeData()
}]

const awsLiveness = new AWSLiveness({ services: customServices });
const dynamoDBClient = new DynamoDBClient();
const myCustomService = new MyCustomService();

awsLiveness.ping({ client: dynamoDBClient })
  .then(() => console.log('dynamodb ping success'))
  .catch(console.error);

awsLiveness.ping({ client: myCustomService })
  .then(() => console.log('my custom service ping success'))
  .catch(console.error);

Debug

AWS Liveness uses debug module internally to log information about ping requests and services status. Logging is turned off by default and can be conditionally turned on by setting the DEBUG environment variable equals to aws-liveness.

Examples

Localstack

You can use this module to ensure that LocalStack services are up and running before you test and/or start your application.

// ping-localstack.js
const dynamoDBClient = new DynamoDBClient({
  endpoint: process.env.DYNAMODB_ENDPOINT
});

try {
  await awsLiveness.waitForServices({
    clients: [dynamoDBClient],
    waitSeconds: process.env.WAIT_SECONDS || 10
  });
} catch (err) {
  console.error('service liveness failed', err);
  process.exit(1);
}

{
  "scripts": {
    "localstack": "docker run -it -p 4569:4569 -p 9999:8080 --rm localstack/localstack",
    "localstack-wait": "AWS_ACCESS_KEY_ID=fakeid AWS_SECRET_ACCESS_KEY=fakekey node ping-localstack.js",
    "test-e2e": "npm run localstack && npm run localstack-wait && AWS_ACCESS_KEY_ID=fakeid AWS_SECRET_ACCESS_KEY=fakekey mocha test-e2e/**/*.test.js"
  }
}

Contributing

1. Commits to master must be done through a Pull Request and Squash and Merge option.

2. Add a title and body that follows the Conventional Commits Specification.