@vtexlab/planner-message-bus
v1.2.3
Published
A Message Bus that uses AWS SNS, AWS SQS, and AWS EventBridge
Downloads
171
Readme
Planner MessageBus
⚙️ Configure your Environment
To test this package, we have two options, which are pointing to AWS Console, or using AWS Local Environment with localstack docker image.
To define which environment you will use, we can inform this envVar:
ENVIRONMENT_TEST="local"
Where you can use one of the values:
- "local": for use localstack image
- "aws": for use AWS Cloud
Did this, we need to inform some environment variables (you can use the 'dotenv' package
) to use the AWS:
AWS_ACCOUNT="[YOUR_ACCOUNT]"
AWS_REGION="[YOUR_REGION]"
AWS_ACCESS_KEY_ID="[YOUR_ACCESS_KEY_ID]"
AWS_SECRET_ACCESS_KEY="[YOUR_SECRET_ACCESS_KEY]"
AWS_SESSION_TOKEN="[YOUR_SESSION_TOKEN]"
AWS_PLANNER_ROLE_ARN="[YOUR_SESSION_TOKEN]"
And, to configure the observability, you can inform the endpoint in this envVar:
OPENTELEMETRY_ENDPOINT="[YOUR_PROVIDER_ENDPOINT]"
💻 Getting Started
1. Install the package
NPM:
npm i @vtexlab/planner-message-bus
Yarn:
yarn add @vtexlab/planner-message-bus
2. Initial Configuration
Configure your startup
const { MessageBus } = require('@vtexlab/planner-message-bus');
/*
Configure all tags as you need to attach them
to your AWS infrastructure
*/
MessageBus.configureTags([{ Key: 'appName', Value: 'name' }])
/*
The default is Honeycomb with planner-message-bus as service.name,
but you can inform others like other Honeycomb service.name,
OpenSearhc, and Datadog
*/
const yourTracer: any
MessageBus.configureObservability(yourTracer)
// Each queue will bind to the referenced topic, informed
MessageBus.configureEndpoint([
{
queue: `[QUEUE_NAME]`,
topic: `[TOPIC_NAME]`,
}
]);
🧪 Test
npm test
We use the 'jest' framework to run the test. If you use the AWS environment, you just need to inform the credentials, otherwise, to the local environment, we use:
- Testcontainers: an open source framework for providing any resources that can run in a Docker container.
- Docker
Testcontainers use docker host url to connect to the docker and use it. And, we need some pay attention to how this works in each OS:
- If we use Docker Desktop, or Docker in unix distribution:
- We don't need to do anything
- WSL (Windows Subsytem Linux):
- You need to expose the Docker and inform your DOCKER_HOST as an environment variable
- Let's see how the URL format for each OS:
- MAC:
unix:///var/run/docker.sock
- WINDOWS:
npipe:////./pipe/docker_engine
- WSL:
tcp://localhost:2375
- WSL:
- UNIX:
unix:///var/run/docker.sock
- MAC:
🧰 API
MessageBus.configureTags()
Attach your tags in your AWS infrastructure
MessageBus.configureObservability()
Set your monitoring tool to trace and improve your o11y
MessageBus.configureEndpoint()
Create SQS queue and SNS topic, and then bind to each other
- SQS queue is optional to inform
Bus.publishMessage()
Send a message to SNS topic
Bus.sendMessage()
Send a message to SQS queue
Bus.redeliveryMessage()
Redelivery a message to SQS queue
- Improve your second level of resilience
Bus.schedule.send()
Send a message to EventBridge informing the SNS topic as the destination, and then, it will deliver in a SNS topic when arrives on the scheduled date
{
"id": "Schedule rule ID",
"message": "The object that will be sent",
"scheduleDate": "Scheduled date to deliver the message",
"topicName": "The destination which message will be deliver"
}
Bus.schedule.update()
Update a rule and message, already created, in EventBridge
{
"id": "Schedule rule ID",
"message": "The object that will be sent",
"scheduleDate": "Scheduled date to deliver the message",
"topicName": "The destination which message will be deliver"
}
Bus.schedule.delete()
Delete the rule (or cancel the scheduled message) in EventBridge
Bus.handleConsumerMessage()
Create a consumer to listen queue messages
Contributing
All contributions are welcome. Please take a look at contributing guide.
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
Authors
See the list of contributors who participated in this project.
License
This project is licensed under the MIT License - see the LICENSE file for details.