@vtexlab/planner-message-bus/README.md

A Message Bus that uses AWS SNS, AWS SQS, and AWS EventBridge

# <p align="center">Planner MessageBus</p>

<p align="center">
  <a href="#configure-your-environment">Configure Your Environment</a> &nbsp;&bull;&nbsp;
  <a href="#getting-Started">Getting Started</a> &nbsp;&bull;&nbsp;
  <a href="#test">Test</a> &nbsp;&bull;&nbsp;
  <a href="#api">API</a>
</p>

---

## ⚙️ 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:

```shell
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:

```shell
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:

```shelL
OPENTELEMETRY_ENDPOINT="[YOUR_PROVIDER_ENDPOINT]"
```

## 💻 Getting Started

**1. Install the package**

NPM:
```shell
npm i @vtexlab/planner-message-bus
```

Yarn:
```shell
yarn add @vtexlab/planner-message-bus
```

**2. Initial Configuration**

Configure your startup
```javascript
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

```shell
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](https://testcontainers.com/)_: an open source framework for providing any resources that can run in a Docker container.
* _[Docker](https://www.docker.com/)_

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](https://medium.com/@NelsonBN/how-to-run-integration-tests-using-testcontainers-with-wsl-52c77a2acbbb) 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

```json
{
    "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

```json
{
    "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](./CONTRIBUTING.md) guide.

### Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/vtex/planner-message-bus/tags).

## Authors

> See the list of [contributors](https://github.com/vtex/planner-message-bus/graphs/contributors) who participated in this project.

### License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.