https://github.com/godaddy/aws-liveness
AWS Liveness tools.
https://github.com/godaddy/aws-liveness
Last synced: 11 months ago
JSON representation
AWS Liveness tools.
- Host: GitHub
- URL: https://github.com/godaddy/aws-liveness
- Owner: godaddy
- License: mit
- Created: 2019-01-31T17:19:05.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-05-23T21:32:25.000Z (about 1 year ago)
- Last Synced: 2025-07-18T09:59:24.267Z (11 months ago)
- Language: JavaScript
- Homepage:
- Size: 484 KB
- Stars: 6
- Watchers: 12
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.com/godaddy/aws-liveness) [](https://greenkeeper.io/)
# aws-liveness
Waits for AWS/localstack services to be up and running.
## Install
```console
npm i --save aws-liveness
```
## Usage
```javascript
import AWSLiveness from '@godaddy/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.
```js
import AWSLiveness from '@godaddy/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](https://www.npmjs.com/package/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](https://www.localstack.cloud/) services are up and running before you test and/or start your application.
```js
// 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);
}
```
```json
{
"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](https://www.npmjs.com/package/@commitlint/config-conventional).