async-queue

Sistema de processamento assíncrono com API e worker em processos separados.

A API recebe jobs via HTTP, persiste o status inicial no Redis e publica na fila. O worker consome os jobs de forma assíncrona com asyncio, atualiza o status e aplica retry com backoff em caso de falha.

Stack

• Python 3.12
• FastAPI — API HTTP
• redis-py (async) — fila e persistência de status
• asyncio — concorrência no worker via create_task
• Docker Compose — orquestração de serviços

Arquitetura

┌─────────────┐     POST /jobs      ┌─────────────────────────┐
│   Cliente   │ ──────────────────► │        API (FastAPI)     │
└─────────────┘                     │  1. persiste PENDING     │
                                    │  2. RPUSH → fila Redis   │
      GET /jobs/:id ◄───────────────└──────────┬──────────────┘
   (consulta status)                           │
                                        Redis  │  BLPOP
                                    ┌──────────▼──────────────┐
                                    │       Worker (asyncio)   │
                                    │  1. PROCESSING           │
                                    │  2. processa (+ retry)   │
                                    │  3. DONE ou FAILED       │
                                    └─────────────────────────┘

Fluxo de status

PENDING → PROCESSING → DONE
                     ↘ FAILED  (após MAX_RETRIES tentativas)

Como rodar

docker compose up --build

Enfileirar um job

curl -X POST http://localhost:8000/jobs \
  -H "Content-Type: application/json" \
  -d '{"type": "send_email", "data": {"to": "user@example.com"}}'

Resposta:

{
  "job_id": "uuid-aqui",
  "status": "PENDING",
  "result": null,
  "updated_at": "2024-01-01T00:00:00Z"
}

Consultar status

curl http://localhost:8000/jobs/{job_id}

Simular falha

curl -X POST http://localhost:8000/jobs \
  -H "Content-Type: application/json" \
  -d '{"type": "test", "data": {"fail": true}}'

O worker vai tentar 3 vezes com backoff linear (2s, 4s) e marcar como FAILED.

Por que dois processos?

A API deve responder rápido e não ficar presa ao tempo de processamento. Por isso ela apenas valida, persiste PENDING e publica o job. O worker tem outra responsabilidade: consumir, processar e atualizar o status — com retry e backoff sem impactar as requisições HTTP. Essa separação permite escalar API e worker de forma independente.