boreal-push-queue 0.2.1

RabbitMQ-based Push Queue client for HTTP task dispatching

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

pip install boreal-push-queue

🛠️ Como usar

1. Enfileirando Tarefas (Publisher)

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.

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:

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.