boreal-push-queue 0.1.0__tar.gz

boreal_push_queue-0.1.0/.idea/boreal-push-queue.iml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3.14 (boreal-push-queue)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

boreal_push_queue-0.1.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,50 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="PyPackageRequirementsInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ignoredPackages">
+        <list>
+          <option value="amqp" />
+          <option value="billiard" />
+          <option value="celery" />
+          <option value="certifi" />
+          <option value="charset-normalizer" />
+          <option value="click" />
+          <option value="click-didyoumean" />
+          <option value="click-plugins" />
+          <option value="click-repl" />
+          <option value="colorama" />
+          <option value="cron-descriptor" />
+          <option value="django-celery-beat" />
+          <option value="django-environ" />
+          <option value="django-fsm" />
+          <option value="django-redis" />
+          <option value="django-timezone-field" />
+          <option value="django-unfold" />
+          <option value="idna" />
+          <option value="kombu" />
+          <option value="prompt_toolkit" />
+          <option value="python-crontab" />
+          <option value="python-dateutil" />
+          <option value="redis" />
+          <option value="requests" />
+          <option value="six" />
+          <option value="tzdata" />
+          <option value="urllib3" />
+          <option value="vine" />
+          <option value="watchdog" />
+          <option value="wcwidth" />
+          <option value="django-admin-sso" />
+          <option value="django-cors-headers" />
+          <option value="psycopg2-binary" />
+          <option value="drf-yasg" />
+          <option value="beautifulsoup4" />
+          <option value="weasyprint" />
+          <option value="pika" />
+          <option value="django-filter" />
+          <option value="paho-mqtt" />
+        </list>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>

boreal_push_queue-0.1.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

boreal_push_queue-0.1.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.14 (boreal-push-queue)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.14 (boreal-push-queue)" project-jdk-type="Python SDK" />
+</project>

boreal_push_queue-0.1.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/boreal-push-queue.iml" filepath="$PROJECT_DIR$/.idea/boreal-push-queue.iml" />
+    </modules>
+  </component>
+</project>

boreal_push_queue-0.1.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

boreal_push_queue-0.1.0/.idea/workspace.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="b945df4d-0a45-4467-a660-0cc68c15cae1" name="Changes" comment="" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="FileTemplateManagerImpl">
+    <option name="RECENT_TEMPLATES">
+      <list>
+        <option value="Python Script" />
+      </list>
+    </option>
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 5
+}]]></component>
+  <component name="ProjectId" id="39MfYVIrUc8h6scLLSS6qrsWiLK" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "git-widget-placeholder": "main",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-3aa1da707db6-JavaScript-PY-252.27397.106" />
+        <option value="bundled-python-sdk-4e2b1448bda8-9a97661f3031-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-252.27397.106" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="b945df4d-0a45-4467-a660-0cc68c15cae1" name="Changes" comment="" />
+      <created>1770510908123</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1770510908123</updated>
+      <workItem from="1770510909208" duration="1855000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

boreal_push_queue-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: boreal-push-queue
+Version: 0.1.0
+Summary: RabbitMQ-based Push Queue client for HTTP task dispatching
+Requires-Python: >=3.8
+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.
+
+## 🚀 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 BorealWorker
+
+worker = BorealWorker(queue_name="minha-fila-de-emails")
+worker.start()
+```
+
+Ou via CLI:
+
+```bash
+boreal-worker --queue-name minha-fila-de-emails
+```
+
+## ⚙️ 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 (opcional; se não setado, pode ser inferido do `max_requests` enviado no envelope)
+- `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*.
+
+---
+
+## 📄 Licença
+
+Distribuído sob a licença MIT.
+

boreal_push_queue-0.1.0/README.md

@@ -0,0 +1,104 @@
+# 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.
+
+## 🚀 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 BorealWorker
+
+worker = BorealWorker(queue_name="minha-fila-de-emails")
+worker.start()
+```
+
+Ou via CLI:
+
+```bash
+boreal-worker --queue-name minha-fila-de-emails
+```
+
+## ⚙️ 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 (opcional; se não setado, pode ser inferido do `max_requests` enviado no envelope)
+- `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*.
+
+---
+
+## 📄 Licença
+
+Distribuído sob a licença MIT.
+

boreal_push_queue-0.1.0/docs/architecture.md

@@ -0,0 +1,35 @@
+# Boreal Push Queue — Architecture (Deep Dive)
+
+## Filosofia do Projeto
+
+O projeto resolve o problema de **Worker Bloqueante**. Em sistemas tradicionais, o worker precisa ter o código da lógica de negócio. No **Boreal Push Queue**, o worker é **genérico**: ele apenas recebe uma instrução de **onde bater** (URL) e **o que levar** (payload).
+
+## Envelope da Mensagem
+
+Quando você faz `boreal_queue.add(task)`, a mensagem enviada ao RabbitMQ não é apenas o dicionário `task`. A lib cria um envelope JSON com metadados e payload:
+
+```json
+{
+  "metadata": {
+    "target_url": "https://api.servico.com/endpoint",
+    "method": "POST",
+    "max_requests": 10,
+    "timestamp": "2023-10-27T10:00:00Z"
+  },
+  "payload": {
+    "id": 123,
+    "name": "minha-task"
+  }
+}
+```
+
+## Por que isso é bom?
+
+1. **Desacoplamento Total**: o serviço que envia a tarefa não precisa que o Worker seja atualizado toda vez que um novo endpoint for criado.
+2. **Escalabilidade**: você pode subir múltiplas instâncias do `BorealWorker` para processar a mesma fila.
+3. **Simulação de Serverless**: funciona de forma similar ao *Google Cloud Tasks* (push) — o receptor é apenas uma API REST comum.
+
+## Controle de Fluxo (QoS)
+
+O `max_requests` define o `basic_qos(prefetch_count=X)` no RabbitMQ, limitando quantas mensagens podem ficar pendentes de ACK ao mesmo tempo, evitando que o Worker tente processar um volume muito alto de requisições simultâneas.
+

boreal_push_queue-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "boreal-push-queue"
+version = "0.1.0"
+description = "RabbitMQ-based Push Queue client for HTTP task dispatching"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "pika>=1.3.0",
+    "httpx>=0.24.0",
+]
+
+[project.scripts]
+# Isso permite que o usuário rode o worker via terminal se desejar
+boreal-worker = "boreal_push_queue.worker:main"

boreal_push_queue-0.1.0/src/boreal_push_queue/__init__.py

@@ -0,0 +1,4 @@
+from .client import BorealPushQueue
+from .worker import BorealWorker
+
+__all__ = ["BorealPushQueue", "BorealWorker"]

boreal_push_queue-0.1.0/src/boreal_push_queue/_envelope.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .exceptions import BorealSerializationError
+
+
+def utc_now_iso() -> str:
+    return (
+        datetime.now(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+def build_envelope(
+    payload: Any,
+    *,
+    target_url: str,
+    method: str,
+    headers: Optional[Dict[str, str]] = None,
+    max_requests: Optional[int] = None,
+    timestamp: Optional[str] = None,
+) -> Dict[str, Any]:
+    metadata: Dict[str, Any] = {
+        "target_url": target_url,
+        "method": method.upper(),
+        "timestamp": timestamp or utc_now_iso(),
+    }
+    if headers:
+        metadata["headers"] = headers
+    if max_requests is not None:
+        metadata["max_requests"] = int(max_requests)
+    return {"metadata": metadata, "payload": payload}
+
+
+def dumps_envelope(envelope: Dict[str, Any]) -> bytes:
+    try:
+        return json.dumps(envelope, ensure_ascii=False).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise BorealSerializationError("Failed to serialize task envelope to JSON.") from exc
+
+
+def loads_envelope(body: bytes) -> Dict[str, Any]:
+    try:
+        decoded = body.decode("utf-8")
+        data = json.loads(decoded)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise BorealSerializationError("Failed to decode task envelope JSON.") from exc
+
+    if not isinstance(data, dict):
+        raise BorealSerializationError("Task envelope must be a JSON object.")
+    if "metadata" not in data or "payload" not in data:
+        raise BorealSerializationError("Task envelope must contain 'metadata' and 'payload'.")
+    if not isinstance(data.get("metadata"), dict):
+        raise BorealSerializationError("'metadata' must be a JSON object.")
+    return data
+

boreal_push_queue-0.1.0/src/boreal_push_queue/client.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+import pika
+
+from ._envelope import build_envelope, dumps_envelope
+from .config import get_rabbitmq_url
+from .exceptions import BorealRabbitMQError
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_headers(headers: Optional[Dict[str, Any]]) -> Optional[Dict[str, str]]:
+    if not headers:
+        return None
+    normalized: Dict[str, str] = {}
+    for key, value in headers.items():
+        normalized[str(key)] = str(value)
+    return normalized
+
+
+class BorealPushQueue:
+    """
+    Publisher: enfileira tarefas para serem executadas no futuro por um Worker.
+
+    A mensagem enviada ao RabbitMQ é um envelope JSON contendo:
+      - metadata: target_url, method, headers, max_requests, timestamp
+      - payload: o dicionário/objeto da tarefa
+    """
+
+    def __init__(
+        self,
+        *,
+        queue_name: str,
+        url: str,
+        method: str = "POST",
+        max_requests: int = 10,
+        headers: Optional[Dict[str, Any]] = None,
+        rabbitmq_url: Optional[str] = None,
+        durable: bool = True,
+    ) -> None:
+        self.queue_name = queue_name
+        self.url = url
+        self.method = method.upper()
+        self.max_requests = int(max_requests)
+        self.headers = _normalize_headers(headers) or {}
+        self.rabbitmq_url = get_rabbitmq_url(rabbitmq_url)
+        self.durable = durable
+
+        self._connection: Optional[pika.BlockingConnection] = None
+        self._channel: Optional[pika.adapters.blocking_connection.BlockingChannel] = None
+
+    def _ensure_channel(self) -> pika.adapters.blocking_connection.BlockingChannel:
+        if self._connection and self._connection.is_open and self._channel and self._channel.is_open:
+            return self._channel
+        try:
+            params = pika.URLParameters(self.rabbitmq_url)
+            self._connection = pika.BlockingConnection(params)
+            self._channel = self._connection.channel()
+            self._channel.queue_declare(queue=self.queue_name, durable=self.durable)
+            return self._channel
+        except Exception as exc:
+            raise BorealRabbitMQError("Failed to connect/declare queue in RabbitMQ.") from exc
+
+    def add(
+        self,
+        payload: Any,
+        *,
+        url: Optional[str] = None,
+        method: Optional[str] = None,
+        headers: Optional[Dict[str, Any]] = None,
+        max_requests: Optional[int] = None,
+    ) -> None:
+        channel = self._ensure_channel()
+        merged_headers = dict(self.headers)
+        merged_headers.update(_normalize_headers(headers) or {})
+
+        envelope = build_envelope(
+            payload,
+            target_url=url or self.url,
+            method=(method or self.method),
+            headers=merged_headers or None,
+            max_requests=max_requests if max_requests is not None else self.max_requests,
+        )
+        body = dumps_envelope(envelope)
+
+        properties = pika.BasicProperties(
+            content_type="application/json",
+            delivery_mode=2,  # persistent
+        )
+
+        try:
+            channel.basic_publish(
+                exchange="",
+                routing_key=self.queue_name,
+                body=body,
+                properties=properties,
+            )
+        except Exception as exc:
+            raise BorealRabbitMQError("Failed to publish message to RabbitMQ.") from exc
+
+    def close(self) -> None:
+        try:
+            if self._connection and self._connection.is_open:
+                self._connection.close()
+        except Exception:
+            logger.exception("Failed to close RabbitMQ connection.")
+        finally:
+            self._channel = None
+            self._connection = None
+
+    def __enter__(self) -> "BorealPushQueue":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+

boreal_push_queue-0.1.0/src/boreal_push_queue/config.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .exceptions import BorealConfigError
+
+ENV_RABBITMQ_URL = "BOREAL_RABBITMQ_URL"
+ENV_QUEUE_NAME = "BOREAL_QUEUE_NAME"
+ENV_MAX_REQUESTS = "BOREAL_MAX_REQUESTS"
+ENV_HTTP_TIMEOUT = "BOREAL_HTTP_TIMEOUT"
+ENV_REQUEUE_ON_FAILURE = "BOREAL_REQUEUE_ON_FAILURE"
+
+DEFAULT_RABBITMQ_URL = "amqp://guest:guest@localhost:5672/"
+DEFAULT_MAX_REQUESTS = 10
+DEFAULT_HTTP_TIMEOUT = 10.0
+DEFAULT_REQUEUE_ON_FAILURE = True
+
+
+def get_rabbitmq_url(explicit: Optional[str] = None) -> str:
+    return explicit or os.getenv(ENV_RABBITMQ_URL) or DEFAULT_RABBITMQ_URL
+
+
+def get_queue_name(explicit: Optional[str] = None) -> str:
+    value = explicit or os.getenv(ENV_QUEUE_NAME)
+    if not value:
+        raise BorealConfigError(
+            f"Queue name is required (pass queue_name or set {ENV_QUEUE_NAME})."
+        )
+    return value
+
+
+def get_int_env(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise BorealConfigError(f"Invalid int for {name}: {raw!r}") from exc
+
+
+def get_float_env(name: str, default: float) -> float:
+    raw = os.getenv(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        return float(raw)
+    except ValueError as exc:
+        raise BorealConfigError(f"Invalid float for {name}: {raw!r}") from exc
+
+
+def get_bool_env(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None or raw == "":
+        return default
+    raw = raw.strip().lower()
+    if raw in {"1", "true", "t", "yes", "y", "on"}:
+        return True
+    if raw in {"0", "false", "f", "no", "n", "off"}:
+        return False
+    raise BorealConfigError(f"Invalid boolean for {name}: {raw!r}")
+

boreal_push_queue-0.1.0/src/boreal_push_queue/exceptions.py

@@ -0,0 +1,19 @@
+class BorealError(Exception):
+    """Base exception for boreal-push-queue."""
+
+
+class BorealConfigError(BorealError):
+    """Raised when configuration is missing or invalid."""
+
+
+class BorealSerializationError(BorealError):
+    """Raised when a message cannot be serialized/deserialized."""
+
+
+class BorealRabbitMQError(BorealError):
+    """Raised when RabbitMQ interaction fails."""
+
+
+class BorealHTTPError(BorealError):
+    """Raised when an HTTP dispatch fails."""
+

boreal_push_queue-0.1.0/src/boreal_push_queue/worker.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, List, Optional
+
+import httpx
+import pika
+
+from ._envelope import loads_envelope
+from .config import (
+    DEFAULT_HTTP_TIMEOUT,
+    DEFAULT_MAX_REQUESTS,
+    DEFAULT_REQUEUE_ON_FAILURE,
+    ENV_HTTP_TIMEOUT,
+    ENV_MAX_REQUESTS,
+    ENV_QUEUE_NAME,
+    ENV_RABBITMQ_URL,
+    ENV_REQUEUE_ON_FAILURE,
+    get_bool_env,
+    get_float_env,
+    get_int_env,
+    get_queue_name,
+    get_rabbitmq_url,
+)
+from .exceptions import BorealRabbitMQError, BorealSerializationError
+
+logger = logging.getLogger(__name__)
+
+
+def _coerce_int(value: Any) -> Optional[int]:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+class BorealWorker:
+    """
+    Consumer/Dispatcher: consome mensagens do RabbitMQ e dispara requisições HTTP.
+
+    - QoS (`prefetch_count`) limita quantas mensagens ficam "in-flight" sem ACK.
+    - Concorrência é controlada por `max_requests` (threads).
+    """
+
+    def __init__(
+        self,
+        *,
+        queue_name: str,
+        rabbitmq_url: Optional[str] = None,
+        max_requests: Optional[int] = None,
+        http_timeout: Optional[float] = None,
+        requeue_on_failure: Optional[bool] = None,
+        durable: bool = True,
+    ) -> None:
+        self.queue_name = queue_name
+        self.rabbitmq_url = get_rabbitmq_url(rabbitmq_url)
+        self._max_requests_configured = max_requests
+        self.http_timeout = (
+            float(http_timeout) if http_timeout is not None else get_float_env(ENV_HTTP_TIMEOUT, DEFAULT_HTTP_TIMEOUT)
+        )
+        self.requeue_on_failure = (
+            bool(requeue_on_failure)
+            if requeue_on_failure is not None
+            else get_bool_env(ENV_REQUEUE_ON_FAILURE, DEFAULT_REQUEUE_ON_FAILURE)
+        )
+        self.durable = durable
+
+        self._connection: Optional[pika.BlockingConnection] = None
+        self._channel: Optional[pika.adapters.blocking_connection.BlockingChannel] = None
+        self._executor: Optional[ThreadPoolExecutor] = None
+        self._http: Optional[httpx.Client] = None
+        self._max_requests_effective: Optional[int] = None
+
+    def _set_concurrency(self, max_requests: int) -> None:
+        if max_requests < 1:
+            max_requests = 1
+        if self._max_requests_effective == max_requests and self._executor is not None:
+            return
+        if self._executor is not None and self._max_requests_effective is not None:
+            logger.warning(
+                "Ignoring max_requests change from %s to %s (dynamic resizing not supported).",
+                self._max_requests_effective,
+                max_requests,
+            )
+            return
+
+        if self._channel is None:
+            raise BorealRabbitMQError("Worker channel is not initialized.")
+
+        self._channel.basic_qos(prefetch_count=max_requests)
+        self._executor = ThreadPoolExecutor(max_workers=max_requests)
+        self._max_requests_effective = max_requests
+
+    def _ensure_runtime(self) -> None:
+        if self._connection and self._connection.is_open and self._channel and self._channel.is_open:
+            return
+        try:
+            params = pika.URLParameters(self.rabbitmq_url)
+            self._connection = pika.BlockingConnection(params)
+            self._channel = self._connection.channel()
+            self._channel.queue_declare(queue=self.queue_name, durable=self.durable)
+        except Exception as exc:
+            raise BorealRabbitMQError("Failed to connect/declare queue in RabbitMQ.") from exc
+
+        self._http = httpx.Client(timeout=self.http_timeout)
+
+        if self._max_requests_configured is not None:
+            self._set_concurrency(int(self._max_requests_configured))
+            return
+
+        if os.getenv(ENV_MAX_REQUESTS) not in (None, ""):
+            self._set_concurrency(get_int_env(ENV_MAX_REQUESTS, DEFAULT_MAX_REQUESTS))
+            return
+
+        # Infer later from message metadata; start safe.
+        self._channel.basic_qos(prefetch_count=1)
+
+    def _schedule_ack(self, delivery_tag: int) -> None:
+        assert self._connection is not None
+        assert self._channel is not None
+
+        def _ack() -> None:
+            if self._channel and self._channel.is_open:
+                self._channel.basic_ack(delivery_tag=delivery_tag)
+
+        self._connection.add_callback_threadsafe(_ack)
+
+    def _schedule_nack(self, delivery_tag: int, *, requeue: bool) -> None:
+        assert self._connection is not None
+        assert self._channel is not None
+
+        def _nack() -> None:
+            if self._channel and self._channel.is_open:
+                self._channel.basic_nack(delivery_tag=delivery_tag, requeue=requeue)
+
+        self._connection.add_callback_threadsafe(_nack)
+
+    def _dispatch_http(self, delivery_tag: int, envelope: Dict[str, Any]) -> None:
+        assert self._http is not None
+
+        metadata = envelope.get("metadata") or {}
+        payload = envelope.get("payload")
+
+        target_url = metadata.get("target_url")
+        http_method = str(metadata.get("method") or "POST").upper()
+        headers = metadata.get("headers") or {}
+
+        if not target_url:
+            logger.error("Dropping message without metadata.target_url.")
+            self._schedule_ack(delivery_tag)
+            return
+
+        request_kwargs: Dict[str, Any] = {"headers": {str(k): str(v) for k, v in headers.items()}}
+        if http_method == "GET":
+            if isinstance(payload, dict):
+                request_kwargs["params"] = payload
+        else:
+            request_kwargs["json"] = payload
+
+        try:
+            response = self._http.request(http_method, str(target_url), **request_kwargs)
+        except Exception:
+            logger.exception("HTTP dispatch failed (exception).")
+            if self.requeue_on_failure:
+                self._schedule_nack(delivery_tag, requeue=True)
+            else:
+                self._schedule_ack(delivery_tag)
+            return
+
+        if 200 <= response.status_code < 300:
+            self._schedule_ack(delivery_tag)
+            return
+
+        logger.warning(
+            "HTTP dispatch failed (status=%s).",
+            response.status_code,
+        )
+        if self.requeue_on_failure:
+            self._schedule_nack(delivery_tag, requeue=True)
+        else:
+            self._schedule_ack(delivery_tag)
+
+    def _on_message(self, ch, method, properties, body: bytes) -> None:  # noqa: ANN001
+        delivery_tag = method.delivery_tag
+
+        try:
+            envelope = loads_envelope(body)
+        except BorealSerializationError:
+            logger.exception("Dropping message that is not a valid Boreal envelope JSON.")
+            ch.basic_ack(delivery_tag=delivery_tag)
+            return
+
+        if self._executor is None:
+            message_max = _coerce_int((envelope.get("metadata") or {}).get("max_requests"))
+            self._set_concurrency(message_max or DEFAULT_MAX_REQUESTS)
+
+        assert self._executor is not None
+        self._executor.submit(self._dispatch_http, delivery_tag, envelope)
+
+    def start(self) -> None:
+        self._ensure_runtime()
+        assert self._channel is not None
+
+        self._channel.basic_consume(queue=self.queue_name, on_message_callback=self._on_message, auto_ack=False)
+        try:
+            logger.info("Worker started. Consuming queue=%s", self.queue_name)
+            self._channel.start_consuming()
+        except KeyboardInterrupt:
+            logger.info("Worker stopping (KeyboardInterrupt).")
+        finally:
+            self.stop()
+
+    def stop(self) -> None:
+        try:
+            if self._channel and self._channel.is_open:
+                try:
+                    self._channel.stop_consuming()
+                except Exception:
+                    pass
+        finally:
+            if self._executor is not None:
+                self._executor.shutdown(wait=True)
+                self._executor = None
+
+            if self._http is not None:
+                self._http.close()
+                self._http = None
+
+            if self._connection and self._connection.is_open:
+                try:
+                    self._connection.close()
+                except Exception:
+                    logger.exception("Failed to close RabbitMQ connection.")
+            self._channel = None
+            self._connection = None
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    parser = argparse.ArgumentParser(prog="boreal-worker", description="Consume a Boreal Push Queue and dispatch HTTP.")
+    parser.add_argument("--queue-name", default=os.getenv(ENV_QUEUE_NAME), help=f"Queue name (env: {ENV_QUEUE_NAME}).")
+    parser.add_argument(
+        "--rabbitmq-url",
+        default=os.getenv(ENV_RABBITMQ_URL),
+        help=f"RabbitMQ URL (env: {ENV_RABBITMQ_URL}).",
+    )
+    parser.add_argument(
+        "--max-requests",
+        type=int,
+        default=None,
+        help=f"Concurrency/prefetch (env: {ENV_MAX_REQUESTS} or message metadata.max_requests).",
+    )
+    parser.add_argument(
+        "--http-timeout",
+        type=float,
+        default=None,
+        help=f"HTTP timeout seconds (env: {ENV_HTTP_TIMEOUT}).",
+    )
+    requeue_group = parser.add_mutually_exclusive_group()
+    requeue_group.add_argument(
+        "--requeue-on-failure",
+        dest="requeue_on_failure",
+        action="store_true",
+        help=f"Requeue message on HTTP failure (env: {ENV_REQUEUE_ON_FAILURE}).",
+    )
+    requeue_group.add_argument(
+        "--no-requeue-on-failure",
+        dest="requeue_on_failure",
+        action="store_false",
+        help="Do not requeue on HTTP failure (ACK and drop).",
+    )
+    parser.set_defaults(requeue_on_failure=None)
+    parser.add_argument("--log-level", default="INFO", help="Logging level (e.g. DEBUG, INFO, WARNING).")
+
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=getattr(logging, str(args.log_level).upper(), logging.INFO))
+
+    queue_name = get_queue_name(args.queue_name)
+    rabbitmq_url = get_rabbitmq_url(args.rabbitmq_url)
+
+    worker = BorealWorker(
+        queue_name=queue_name,
+        rabbitmq_url=rabbitmq_url,
+        max_requests=args.max_requests,
+        http_timeout=args.http_timeout,
+        requeue_on_failure=args.requeue_on_failure,
+    )
+    worker.start()