A fault-tolerant, distributed job processing engine built in Go. Built for teams who can't afford to lose a single job.

---

🤔 Why GoQueue?

Processing everything inside a synchronous HTTP request is fragile:

❌ Timeouts kill long-running work
❌ Retries duplicate side effects
❌ A single crash silently swallows jobs

GoQueue solves this by decoupling job creation from job execution:

✅ Persists every job to PostgreSQL the moment it's created
✅ Pushes to Redis for fast async dispatch
✅ Executes through concurrent Go workers
✅ Full crash recovery, priority scheduling, and tracing built in

---

✨ Core Features

Feature	Description
🗄️ Dual-layer persistence	PostgreSQL for durability · Redis for throughput
👷 Concurrent worker pools	Scalable goroutine-based workers process jobs in parallel
🔄 Smart retry + backoff	Non-blocking delayed queues with exponential backoff
☠️ Dead Letter Queue	Permanently failed jobs routed for inspection and replay
💀 Crash recovery	Visibility timeouts + Reaper service recover stuck jobs
🎯 Priority dispatching	High · Medium · Low priority queues
🔑 Idempotency keys	Safe job creation - no accidental duplicates
🔍 Correlation IDs	Every job traceable end-to-end via structured JSON logs
🛑 Backpressure shedding	Returns HTTP 429 when queue capacity is exceeded
📊 Full observability	Prometheus metrics + Grafana dashboards out of the box
🧹 Graceful shutdown	Workers drain in-flight jobs safely on termination signals

---

---

🏗️ Architecture

End-to-end architecture of GoQueue showing job creation, reliable delivery, distributed workers, retry orchestration, crash recovery, and observability.

---

🚀 Quick Start

The fastest way to run GoQueue is via Docker Compose - spins up the API, workers, PostgreSQL, Redis, Prometheus, and Grafana in one command.

Prerequisites

• 🐳 Docker & Docker Compose
• make (optional but recommended)

1. Clone the repository

git clone https://github.com/bhusaremayur/goqueue.git
cd goqueue

2. Start all services

# With Docker Compose
docker-compose -f deployments/docker-compose.yml up -d

# Or with Make
make up

3. Verify services are running

docker-compose ps

Service	URL	Description
🟢 Go API Server	http://localhost:8080	Job submission & status
📊 Grafana Dashboard	http://localhost:3000	Pre-built dashboards
📈 Prometheus	http://localhost:9090	Raw metrics

---

📁 Repository Structure

goqueue/
│
├── cmd/
│   ├── api/                →  API server entry point
│   ├── worker/             →  Worker process entry point
│   └── example-app/        →  Example usage
│
├── internal/
│   ├── job/                →  Core job domain logic
│   ├── storage/
│   │   ├── postgres/       →  PostgreSQL repositories
│   │   │   └── migrations/ →  SQL schema migrations
│   │   └── redis/          →  Redis queue implementation
│   ├── scheduler/          →  Job scheduling logic
│   └── reaper/             →  Crash recovery service
│
├── pkg/
│   ├── logging/            →  Structured JSON logger
│   ├── metrics/            →  Prometheus metric definitions
│   ├── middleware/          →  HTTP middleware (correlation IDs, etc.)
│   └── retry/              →  Exponential backoff policies
│
└── deployments/
    ├── docker-compose.yml
    └── prometheus.yml

---

🔍 Observability

GoQueue treats observability as a first-class concern - not an afterthought.

Structured JSON Logging

Every log line carries a correlation_id for full request traceability:

{
  "level": "info",
  "correlation_id": "REQ-8472",
  "event": "job_processed",
  "job_id": "a1b2c3",
  "queue": "high",
  "worker": "worker-1",
  "duration_ms": 142
}

Prometheus Metrics

Exposed at /metrics - all critical signals tracked:

goqueue_jobs_enqueued_total        →  Total jobs submitted
goqueue_jobs_processed_total       →  Successfully processed
goqueue_jobs_failed_total          →  Failed jobs (by queue)
goqueue_queue_depth                →  Current queue depth (by priority)
goqueue_worker_utilization         →  Worker pool saturation %
goqueue_retry_count                →  Retry attempts in flight
goqueue_dlq_size                   →  Dead Letter Queue depth
goqueue_processing_latency_seconds →  Job processing duration histogram

Grafana Dashboards

Pre-built dashboards ship with the repo.

open http://localhost:3000   # after docker-compose up

---

⚡ Load Testing Results

Tested with k6 at high concurrency:

┌─────────────────────────────────────────────┐
│           Load Test Summary (k6)            │
├──────────────────────┬──────────────────────┤
│  Virtual Users       │  10,000              │
│  Total Requests      │  40,000+             │
├──────────────────────┼──────────────────────┤
│  Backpressure (429)  │  ✅ Validated        │
│  Crash Recovery      │  ✅ All jobs back    │
│  DLQ Routing         │  ✅ Clean isolation  │
└──────────────────────┴──────────────────────┘

---

🛠️ Tech Stack

Language        →  Go
Persistence     →  PostgreSQL
Queue / Cache   →  Redis
Observability   →  Prometheus + Grafana
Infrastructure  →  Docker + Docker Compose

---

🤝 Contributing

Contributions are welcome - bug reports, feature suggestions, and pull requests alike.

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m 'feat: add your feature'
4. Push to the branch: git push origin feat/your-feature
5. Open a Pull Request

Please read CONTRIBUTING.md before submitting - it covers running the test suite locally and the PR process.

---

📄 License

Licensed under the terms in LICENSE.

---

GoQueue v1.0

Built with ❤️ using Go · Redis · PostgreSQL · Prometheus · Grafana

⭐ Star this repo if GoQueue helped you! ⭐