ADR 009: Redis y requerimientos no funcionales¶

Estado¶

Aceptado — 2026-06 · Implementación parcial — rate limit, pool Redis, idempotencia transversal y check_redis en /ready

Relacionado con ADR 001, ADR 005, ADR 008.

Contexto¶

Redis 7 está en docker-compose.yml y REDIS_URL en settings. Se requiere rate limiting, health checks profundos e idempotencia en escrituras según prácticas NFR.

Variables canónicas: Configuración. Los alias CORTEX_* están deprecados (dual-read temporal).

Decisión¶

Rate limiting¶

RateLimitMiddleware con Redis: INCR cortex:rate:{client}:{window} + TTL 60s.
Límite: RATE_LIMIT_PER_MINUTE (default 120).
Respuesta 429 con cuerpo ApiError (RATE_LIMITED).
Excluir: /health, /ready.

Estado actual: el middleware corre cuando RATE_LIMIT_ENABLED=true (opt-in; default false en dev). Fallback en memoria si Redis no está disponible.

Readiness¶

Objetivo: /ready comprueba PostgreSQL, plugins habilitados y Redis cuando NFR lo exija.
Hoy: readiness_report valida DB + plugins + reporte Redis; falla si REDIS_REQUIRED=true y Redis no responde.

Idempotencia (fase 2)¶

Middleware transversal Idempotency-Key en POST/PUT/PATCH mutantes.
Clave Redis: cortex:idempotency:{key}; TTL 24h.
Plugin booking mantiene idempotencia local adicional en creación de reservas.

Caché (fase 3 — diseño)¶

Documentar patrones; no bloquear PMV.

Implementado hoy¶

Pieza	Ubicación
Rate limit Redis + memoria	`framework/cortex_framework/middleware/rate_limit.py`
`check_redis()` en readiness	`framework/cortex_framework/platform/readiness.py`
Flag `REDIS_REQUIRED`	`framework/cortex_framework/settings.py`
Pool Redis compartido	`framework/cortex_framework/redis/client.py`
Idempotencia transversal	`framework/cortex_framework/io/middleware/idempotency.py`
Checkpoints LangGraph	`plugins/ai-agents` (uso Redis aparte)

Pendiente (fases de construcción)¶

Fase	Entregable	Estado
5.3	`check_redis()` en `/ready`	Hecho
5.3	Rate limit con flag independiente de auth	Hecho (`RATE_LIMIT_ENABLED`)
5.3	Redis en CI; tests 429	Hecho
5.4	Pool Redis compartido; idempotencia transversal	Hecho
5.4	Patrones de caché documentados	Pendiente (fase 3)

Consecuencias¶

Positivas: infraestructura Redis ya desplegable en Compose.
Negativas: staging con optional no ejercita rate limit ni readiness de Redis.
Operación: documentar degradación (memoria vs fail-closed) en guía de despliegue.