¿Cómo ejecutas trabajos en segundo plano robustos (Celery/ARQ)?

Question

Accepted Answer

Para **trabajos en segundo plano robustos y duraderos** (más allá de `BackgroundTasks` ligero de FastAPI), usas una cola de tareas real: **Celery** (el estándar establecido) o **ARQ** (una cola async-nativa moderna). Estos ejecutan trabajo pesado, reintentable y programado en procesos trabajadores separados, respaldados por un broker como Redis.

## Por qué es importante

```text
BackgroundTasks runs in the web process → NO persistence (lost on crash), NO retries,
NO scheduling, and heavy work ties up the worker. Fine only for quick fire-and-forget.
For durable/critical/heavy/scheduled jobs → use a real task queue (Celery / ARQ).
```

## Celery — define y encola tareas

```python
# tasks.py
from celery import Celery
celery_app = Celery("tasks", broker="redis://localhost:6379")

@celery_app.task(bind=True, max_retries=3)
def process_video(self, video_id: int):
    try:
        do_heavy_processing(video_id)        # runs in a WORKER, not the web process
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)   # automatic retry on failure
```

```python
# in a FastAPI endpoint — QUEUE the task, return immediately
@app.post("/videos/{id}/process")
def process(id: int):
    process_video.delay(id)                  # enqueue → returns at once (doesn't block)
    return {"status": "processing started"}
# run workers separately: celery -A tasks worker
```

El endpoint encola el trabajo y responde instantáneamente; un proceso **trabajador** separado lo ejecuta con persistencia y reintentos.

## ARQ — async-nativo (se ajusta al modelo async de FastAPI)

```python
# ARQ is built on asyncio — a natural fit for async FastAPI codebases
async def process_video(ctx, video_id: int):
    await do_async_processing(video_id)

# enqueue from an endpoint
await redis.enqueue_job("process_video", video_id)
```

ARQ es una alternativa más ligera y async-first — atractiva cuando tu código base ya es async.

## Qué proporciona una cola de tareas real

```text
✓ Persistence — jobs survive crashes/restarts (stored in the broker)
✓ Retries with backoff — resilience against transient failures
✓ Scheduling — periodic/cron-like jobs (Celery Beat)
✓ Distribution & scaling — workers scale independently of the web servers
✓ Concurrency & rate limiting, task routing/priorities, result tracking
```

## Por qué es importante

Ejecutar trabajos en segundo plano robustos es esencial para construir aplicaciones FastAPI de nivel de producción que manejen trabajo pesado o diferido de manera confiable — y comprender cuándo y cómo usar una cola de tareas real es conocimiento importante a nivel senior.

El criterio central es reconocer los **límites de `BackgroundTasks`** (sin persistencia, reintentos o programación — bien solo para trabajo rápido y no crítico) y recurrir a **Celery o ARQ** cuando el trabajo debe ser duradero, reintentable, programado, pesado o distribuido (procesamiento de archivos/vídeos, envío de correos masivos, sincronización de datos, generación de reportes).

Estas colas ofrecen capacidades críticas de producción: **persistencia** (los trabajos sobreviven a fallos a través del broker, por lo que el trabajo no se pierde), **reintentos automáticos** (resiliencia contra fallos transitorios), **programación** (trabajos periódicos) e **escalado independiente** de trabajadores desde servidores web.

Saber cómo definir y encolar tareas (`delay()` de Celery, API async-nativa de ARQ), la arquitectura (broker + trabajadores), y especialmente la **decisión de cuándo usar una cola real versus `BackgroundTasks`**, es valioso para arquitectar aplicaciones confiables que deleguen trabajo pesado sin perderlo — un requisito común e importante que distingue sistemas de producción robustos de frágiles.