Metadata-Version: 2.4
Name: boreal-push-queue
Version: 0.2.1
Summary: RabbitMQ-based Push Queue client for HTTP task dispatching
Requires-Python: >=3.8
Requires-Dist: croniter>=2.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pika>=1.3.0
Description-Content-Type: text/markdown

# Boreal Push Queue 🌲🐇

**Boreal Push Queue** é uma biblioteca Python que simula o comportamento de *Push Queues* do Google Cloud Tasks, utilizando o **RabbitMQ** como infraestrutura de mensageria.

A ideia é simples: você enfileira uma tarefa (Publisher) e um serviço (Worker) escuta essa fila, disparando automaticamente uma requisição HTTP para um endpoint pré-definido.

## ✨ Funcionalidades

- **Abstração Simples**: Interface amigável para enfileirar tarefas.
- **Push Pattern**: O Worker converte mensagens da fila em chamadas HTTP (POST/GET).
- **Concorrência Controlada**: Define o limite de requisições simultâneas.
- **Configurável**: Suporte a diferentes métodos HTTP e cabeçalhos.
- **Cron Embutido (Opcional)**: O Worker pode chamar `GET` na URL do PushQueue em um agendamento crontab.

## 🚀 Instalação

```bash
pip install boreal-push-queue
```

## 🛠️ Como usar

### 1. Enfileirando Tarefas (Publisher)

```python
from boreal_push_queue import BorealPushQueue

# Inicializa a fila definindo o destino das tarefas
boreal_queue = BorealPushQueue(
    queue_name="minha-fila-de-emails",
    url="https://api.meuservico.com/v1/send-email",
    method="POST",
    max_requests=10,
)

# Define os dados da tarefa
task = {
    "id": "12345",
    "name": "Enviar Boas-vindas",
}

# Envia para o RabbitMQ
boreal_queue.add(task)
```

### 2. Executando o Worker

O Worker é responsável por ler as mensagens e disparar os gatilhos HTTP.

```python
from boreal_push_queue import BorealPushQueue, BorealWorker

push_queue = BorealPushQueue(
    queue_name="minha-fila-de-emails",
    url="https://api.meuservico.com/v1/send-email",
    method="POST",
    max_requests=10,
    cron=True,
    crontab="*/5 * * * *",
)

worker = BorealWorker(push_queue)
worker.start()
```

Ou via CLI:

```bash
boreal-worker --queue-name minha-fila-de-emails --url https://api.meuservico.com/v1/send-email --cron --crontab "*/5 * * * *"
```

## ⚙️ Configurações Necessárias

A biblioteca utiliza variáveis de ambiente para conexão e comportamento:

- `BOREAL_RABBITMQ_URL`: URL de conexão (Ex: `amqp://guest:guest@localhost:5672/`)
- `BOREAL_MAX_REQUESTS`: concorrência/prefetch do Worker (default: `10`; usado principalmente no CLI)
- `BOREAL_HTTP_TIMEOUT`: timeout HTTP em segundos (default: `10`)
- `BOREAL_REQUEUE_ON_FAILURE`: `true/false` (default: `true`)

---

## 🏗️ Arquitetura e Funcionamento (Documentação Interna)

### Fluxo de Dados

1. **Instanciação**: Ao criar o `BorealPushQueue`, os metadados do endpoint (URL, Método) são armazenados.
2. **Produção (add)**: Quando `add(task)` é chamado, a biblioteca encapsula a tarefa junto com as informações de destino em um envelope JSON e envia para o RabbitMQ.
3. **Persistência**: O RabbitMQ garante que a mensagem não seja perdida se o serviço de destino estiver fora do ar.
4. **Consumo (Worker)**: O `BorealWorker` fica em loop (consumidor persistente). Ao receber uma mensagem:
   - Extrai os dados da tarefa e a URL de destino.
   - Executa a chamada HTTP com controle de vazão/concorrência via `prefetch_count`.
   - Se o endpoint responder com sucesso (2xx), envia um `ACK` para o RabbitMQ remover a mensagem da fila.

### Componentes Principais

#### `BorealPushQueue` (Client)

Responsável pela interface com o desenvolvedor. Ele não faz chamadas HTTP, apenas prepara a mensagem para que alguém a execute no futuro.

#### `BorealWorker` (Dispatcher)

É o motor de execução. Ele utiliza internamente um cliente HTTP (`httpx`) para transformar eventos de fila em requisições Web.

#### Gerenciamento de Falhas

Caso a requisição HTTP falhe (ex: erro 500 ou Timeout), a mensagem é **re-enfileirada** por padrão (`nack` com `requeue=True`), garantindo o modelo de entrega *at-least-once*.

### Para que serve o Cron?

Quando `cron=True`, o `BorealWorker` executa um cron embutido e faz `GET` na `url` do `BorealPushQueue` no intervalo definido por `crontab`.

A intenção é usar o `GET` **na mesma rota** como um “deadcase/rotina de manutenção” (ex.: reprocessar pendências, verificar consistência, disparar rotinas idempotentes), enquanto o `POST` continua sendo o processamento das mensagens vindas do RabbitMQ.

Obs.: o cron roda **por instância do worker**. Se você subir múltiplos workers com `cron=True`, cada um fará o `GET` no mesmo agendamento.

---

## 📄 Licença

Distribuído sob a licença MIT.
