@vtexlab/planner-message-bus

Planner MessageBus

Configure Your Environment  •  Getting Started  •  Test  •  API

---

⚙️ 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
  • UNIX: unix:///var/run/docker.sock

🧰 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.