---
name: backend-production-resilience
description: >
  Patrones de resiliencia para servicios backend en producción. Cubre timeouts
  obligatorios, retries con jitter+backoff e idempotency, circuit breakers,
  bulkheads, backpressure, graceful degradation, blast radius, fault isolation
  y observabilidad operacional. Cargar cuando se diseñe o revise un servicio
  que llame a dependencias externas (BD, APIs, colas, caches), cuando se
  diagnostique un incidente de producción, o cuando se quiera endurecer
  endpoints contra sobrecarga, latencia y fallas en cascada.
version: "1.0.0"
evolved: false
herramientasPermitidas: [Read]
exclusiones:
  - "No cargar para resiliencia de agentes IA o cadenas de delegación — cargar `seguridad-agentes` o `guardrail-semantico`. Este skill cubre servicios web/API/backend, no orquestación de agentes."
  - "No cargar para definición de SLO/SLI o error budgets — cargar `sre-patrones`. Este skill cubre patrones de implementación; SRE cubre el framework de confiabilidad."
  - "No cargar para configuración de monitoreo (Prometheus, Grafana, alertas) — cargar `monitoring-alertas`. Este skill cubre qué emitir desde el código; monitoreo cubre cómo capturarlo y graficarlo."
  - "No cargar para manejo de errores genérico (jerarquía de excepciones, códigos de dominio) — cargar `manejo-errores`. Este skill asume que ese ya está aplicado y agrega patrones de resiliencia operacional encima."
evolvable: true
---

# Backend Production Resilience

## Cuándo cargar

- Se diseña o revisa un servicio que llama dependencias externas (BD, APIs HTTP, colas, caches, filesystem remoto).
- Se diagnostica un incidente de producción: latencia, timeouts en cascada, OOM, retry storms.
- Se prepara un endpoint público para tráfico real (no solo el happy path).
- Se va a integrar un nuevo cliente HTTP o driver de BD: aplicar timeouts y circuit breaker desde el inicio.
- Se hace code review de un PR que toca integración con sistemas externos.

## Cuándo NO cargar

- La tarea es definir SLO/SLI o calcular error budgets — usar `sre-patrones`.
- La tarea es configurar dashboards o alertas en Prometheus/Grafana — usar `monitoring-alertas`.
- El problema es resiliencia de cadenas de agentes IA o blast radius de delegación — usar `seguridad-agentes`.
- El servicio aún no maneja errores correctamente — primero cargar `manejo-errores` y aplicar la jerarquía base; este skill asume manejo de errores ya correcto.

## Directiva primaria

**La producción es desordenada por defecto.** Toda dependencia externa puede ser
lenta, no estar disponible o devolver datos incorrectos. Toda cola se llena.
Todo cache puede fallar o sufrir stampede. Todo timeout puede cascadear.

Diseñar para que el servicio:

1. **Falle visible** en lugar de colgarse en silencio.
2. **Limite el blast radius** en lugar de propagar la falla.
3. **Descarte carga** en lugar de colapsar bajo presión.
4. **Preserve servicios core** cuando hay degradación.
5. **Permita diagnóstico** desde los logs, métricas y trazas.

No diseñar solo para el happy path.

## Mindset de estabilidad — 6 axiomas

1. Toda dependencia puede ser lenta, no responder o estar mal.
2. Toda cola se puede llenar.
3. Todo cache puede fallar o sufrir stampede.
4. Todo timeout puede cascadear hacia arriba.
5. Todo caller puede reintentar mal (DDoSearte sin querer).
6. Todo estado "temporal degradado" puede convertirse en normal por horas.

El código debe asumir estas condiciones por construcción, no tolerarlas por accidente.

---

## Timeouts — obligatorios, no opcionales

- Toda llamada de salida (HTTP, DB query, cache get, cola publish) DEBE tener
  un timeout explícito.
- El timeout va en el código, NO se hereda del default de la librería.
  Los defaults suelen ser infinitos o demasiado largos.
- Distintas dependencias pueden tener distintos presupuestos de timeout
  según su SLA conocido. No usar un único valor global.
- Esperas infinitas están prohibidas. Sin excepción.

```python
# MAL — sin timeout, defaults dependen de la librería
async with httpx.AsyncClient() as client:
    r = await client.get(url)  # puede colgar indefinidamente

# BIEN — timeout explícito por nivel (connect, read, write, pool)
TIMEOUT = httpx.Timeout(connect=2.0, read=5.0, write=2.0, pool=1.0)
async with httpx.AsyncClient(timeout=TIMEOUT) as client:
    r = await client.get(url)
```

Para BD: el timeout va en el statement (`statement_timeout` en PostgreSQL,
`maxTimeMS` en MongoDB), no solo en el connection pool.

---

## Retries — disciplinados o ninguno

- Reintenta solo operaciones **idempotentes** (GET, PUT, DELETE) o
  explícitamente diseñadas con idempotency key (POST con header
  `Idempotency-Key: <uuid>`).
- Acotar el conteo de reintentos Y el tiempo total de reintentos.
- Aplicar **jitter** y **backoff exponencial** para evitar tormentas de
  reintentos sincronizados.
- NUNCA reintentes errores 4xx (client error). Reintenta solo 408, 429,
  5xx (excepto 501, 505) y errores de red transitorios.
- Si el caller también reintenta, los reintentos se multiplican
  exponencialmente — preferir un solo nivel de retry en la cadena.

```python
import random
async def retry_con_jitter(fn, intentos=3, base_delay=0.5, max_delay=8.0):
    """Backoff exponencial completo + jitter aleatorio (AWS Architecture Blog)."""
    for intento in range(intentos):
        try:
            return await fn()
        except (httpx.TimeoutException, httpx.NetworkError) as e:
            if intento == intentos - 1:
                raise
            cap = min(max_delay, base_delay * (2 ** intento))
            await asyncio.sleep(random.uniform(0, cap))  # full jitter
```

---

## Circuit breakers

Cuando una dependencia está fallando, **dejar de llamarla** durante un
período corto en lugar de seguir intentando y consumir threads/conexiones.

Estados:
- **CLOSED**: peticiones pasan normalmente.
- **OPEN**: peticiones fallan inmediatamente (no se llama a la dependencia).
- **HALF_OPEN**: tras un timeout, se permiten N peticiones de prueba; si
  pasan, vuelve a CLOSED; si fallan, vuelve a OPEN.

Reglas:
- Definir thresholds explícitos: tasa de error (ej: ≥50% de las últimas
  20 llamadas) y tiempo de cooldown (ej: 30s).
- El circuit breaker DEBE emitir métricas con el cambio de estado para
  que se monitoree.
- En estado OPEN, devolver una respuesta degradada (cache, default, error
  visible al caller) — nunca colgar.
- Probar el comportamiento del CB con tests específicos: simular dependencia
  caída y verificar que el CB abre, sostiene y vuelve a HALF_OPEN.

Librerías recomendadas: `pybreaker` (Python), `opossum` (Node.js),
`resilience4j` (Java).

---

## Bulkheads — aislamiento de fallos

Aislar pools de recursos por dependencia para que una dependencia lenta
no agote todos los threads/conexiones del servicio:

- Pools separados de conexiones HTTP por upstream crítico.
- Pools separados de threads/workers por tipo de tarea.
- Tamaño máximo del pool acotado: si hay tráfico que excede capacidad,
  fallar rápido en lugar de hacer cola infinita.

```python
# Cliente HTTP con pool dedicado por upstream (httpx)
cliente_pagos = httpx.AsyncClient(
    timeout=TIMEOUT_PAGOS,
    limits=httpx.Limits(max_connections=20, max_keepalive_connections=10),
)
cliente_inventario = httpx.AsyncClient(
    timeout=TIMEOUT_INVENTARIO,
    limits=httpx.Limits(max_connections=50, max_keepalive_connections=20),
)
```

Sin bulkheads, una dependencia lenta puede consumir todos los workers y
dejar al servicio sin capacidad para responder otros endpoints.

---

## Backpressure y descarte de carga

Cuando el servicio recibe más peticiones de las que puede procesar, debe
DESCARTAR carga rápidamente en lugar de hacer cola y degradar a todos.

Patrones:
- **Rate limiting** por cliente/endpoint (token bucket, sliding window).
  Devolver `429 Too Many Requests` con header `Retry-After`.
- **Cola acotada**: si la cola interna excede N items, rechazar nuevas
  con `503 Service Unavailable`.
- **Load shedding**: bajo CPU/memoria altos, rechazar peticiones no-críticas
  primero, preservar servicios core.
- **Admission control**: rechazar peticiones que probablemente excederán
  el deadline antes de empezar a procesarlas.

NO usar colas en memoria ilimitadas — un upstream lento las llena hasta
provocar OOM.

---

## Graceful degradation

Cuando una dependencia no-crítica falla, el servicio debe seguir
funcionando con funcionalidad reducida en lugar de devolver error
completo:

- Catalogar dependencias en críticas vs. mejoradoras (recommendations,
  analytics, notifications son típicamente mejoradoras).
- Si una dependencia mejoradora falla: registrar la falla, devolver
  resultado degradado (sin recommendations, sin notification enviada
  pero encolada para retry).
- El cliente debe poder distinguir entre respuesta completa y
  respuesta degradada (ej: header `X-Service-Degraded: notifications`).

Antipatrón: si el servicio de notifications falla, fallar la operación
de checkout completa. Eso convierte una dependencia mejoradora en
crítica.

---

## Blast radius — contención del impacto

Diseñar para que una falla aislada NO se propague a todo el sistema:

- Particionar usuarios/tenants en shards independientes (un shard caído
  no tira a otros tenants).
- Separar workloads críticos de no-críticos en infraestructura distinta
  (un job de reportes pesado no debe usar el mismo pool que el checkout).
- Limitar el alcance de cambios deployable: feature flags por usuario o
  porcentaje, canary deployments, blue-green.

Pregunta de revisión: si esta dependencia se cae a las 3am del sábado,
**¿cuántos usuarios se ven afectados y por cuánto tiempo?**

---

## Observabilidad obligatoria

Sin observabilidad, los patrones anteriores son invisibles cuando fallan.
Mínimo requerido:

- **Métricas RED por endpoint**: Rate (req/s), Errors (count/rate), Duration
  (p50/p95/p99).
- **Estado de circuit breakers**: gauge por dependencia (0=closed, 1=open).
- **Saturación de pools**: utilización de connection pool, queue depth.
- **Latencia por dependencia externa**: histograma separado por upstream.
- **Logs estructurados** con correlation ID que cruce el request completo.
- **Trazas distribuidas** (OpenTelemetry) para diagnosticar latencia
  cross-service.

Si un patrón de resiliencia se activa (CB abre, retry consume budget,
load shedding descarta) DEBE quedar registrado con suficiente contexto
para diagnóstico post-mortem.

---

## Anti-patrones

- **Retry sin jitter**: causa retry storm sincronizado que tira la
  dependencia justo cuando se está recuperando.
- **Timeout en el caller pero no en el callee**: el callee sigue
  procesando una petición ya abandonada — desperdicia recursos.
- **Catch-all `except Exception` con log y continue**: oculta fallas
  reales, hace el servicio "imposible de diagnosticar".
- **Cola en memoria sin límite**: tarde o temprano OOM.
- **Reintentar 4xx**: errores del cliente no se arreglan reintentando.
- **Misma dependencia compartiendo pool con todas las demás**: cuando
  esa dependencia lenta llega, mata todo el servicio.
- **CB sin métricas**: nadie se entera cuando abre, falla en silencio.

---

## Gotchas / Errores comunes no obvios

- **`asyncio.wait_for` no cancela la operación interna en algunas librerías**: el timeout dispara pero la operación sigue corriendo en background consumiendo recursos. Causa: la librería interna no propaga `CancelledError`. Solución: verificar que la librería soporta cancelación cooperativa; si no, ejecutar en thread separado con `loop.run_in_executor` y matarlo explícitamente.
- **Reintento sobre POST sin idempotency key duplica órdenes**: si la red corta antes de recibir la respuesta, el caller no sabe si se procesó. Causa: POST por defecto no es idempotente. Solución: requerir `Idempotency-Key: <uuid>` en POST que muten estado, persistir el key con la respuesta, devolver la misma respuesta si llega una repetición.
- **Circuit breaker con threshold absoluto en lugar de tasa**: el CB nunca abre porque "10 errores" tarda en alcanzarse en bajo tráfico, pero abre falsamente con "10 errores en 1000 req". Causa: threshold absoluto sin ventana temporal. Solución: usar tasa de error sobre ventana deslizante (ej: 50% de errores en últimas 20 peticiones o últimos 10s).
- **Backoff exponencial sin cap**: tras varios fallos, el delay crece a 30 minutos y el caller percibe como cuelgue. Causa: olvidar `max_delay`. Solución: siempre acotar con `min(cap, base * 2**n)` (capped exponential backoff).
- **Bulkhead omitido entre tenants**: un tenant grande consume todo el pool y deja a los demás esperando. Causa: pool global, no por tenant. Solución: pool por tenant o tenant pesos en admission control.

## Checklist antes de poner un servicio en producción

- [ ] Toda llamada externa tiene timeout explícito (no default).
- [ ] Retries acotados, con jitter+backoff, solo en operaciones idempotentes.
- [ ] Circuit breaker configurado para cada dependencia externa crítica.
- [ ] Pools separados por dependencia (bulkheads).
- [ ] Rate limiting en endpoints públicos.
- [ ] Cola interna con límite (rechazar 503 al exceder).
- [ ] Catálogo de dependencias críticas vs. mejoradoras documentado.
- [ ] Métricas RED + estado CB + saturación pools instrumentadas.
- [ ] Logs estructurados con correlation ID.
- [ ] Trazas distribuidas configuradas (OpenTelemetry).
- [ ] Test de chaos: simular latencia/caída de cada dependencia y verificar comportamiento.
