Metadata-Version: 2.4
Name: buffalomq
Version: 0.1.3
Summary: A production-grade, Redis-backed job queue system in Python
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: redis>=5.0.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.28.0
Requires-Dist: pydantic>=2.6.0

# 🦬 BuffaloMQ

> A lightweight, production-grade Redis job queue for Python with a built-in real-time Web Dashboard.

BuffaloMQ provides a simple, reliable, and dependency-light alternative to heavy task queues like Celery. It leverages Redis and atomic Lua scripts for crash resilience, delayed scheduling, visibility timeouts, and DLQ management — complete with a zero-config web dashboard CLI.

---

## 🛠 Tech Stack

* **Core & Broker:** Python 3.9+ & Redis (via atomic Lua scripts)
* **Dashboard Server:** FastAPI & Uvicorn
* **Dashboard Frontend:** React 18, TypeScript, Vite

---

## ✨ Features

* **⚡ Lightweight & Fast:** Pure Python API powered by atomic Redis Lua operations.
* **🖥 Zero-Config Web Dashboard:** Launch a real-time monitoring UI with a single CLI command (`buffalomq dashboard`).
* **🔄 Job Retries & Backoff:** Configurable retry limits and exponential backoff.
* **⏱ Delayed Jobs:** Schedule tasks to run after a specific delay.
* **🔒 Crash Recovery:** Visibility timeouts & heartbeat threads prevent lost jobs if a worker crashes.
* **⏸ Queue Controls & DLQ Re-drive:** Pause/resume queues and re-drive failed jobs straight from the dashboard or API.

---

## 📦 Installation

```bash
pip install buffalomq
```

---

## 🚀 Quickstart

### 1. Submit Jobs (Producer)

```python
import redis
from buffalomq import Queue

r = redis.Redis(host='localhost', port=6379, db=0)
queue = Queue("email-notifications", r)

# Enqueue immediate job
queue.add({"to": "user@example.com", "subject": "Welcome!"})

# Enqueue delayed job (runs after 30s) with 3 max retries
queue.add({"to": "user@example.com", "subject": "Reminder"}, options={"delay": 30, "max_attempts": 3})
```

### 2. Process Jobs (Worker)

```python
import redis
from buffalomq import Worker

def process_email(job_data):
    print(f"Sending email to: {job_data['to']}")

r = redis.Redis(host='localhost', port=6379, db=0)
worker = Worker("email-notifications", r, process_email)

# Start listening for jobs
worker.run()
```

### 3. Launch Web Dashboard

```bash
buffalomq dashboard --redis redis://localhost:6379/0
```
*Automatically opens `http://127.0.0.1:8000` in your browser to monitor queues, inspect payloads, pause workers, and re-drive failed jobs.*

