theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-redis/SKILL.md

@@ -0,0 +1,401 @@
+---
+name: patrones-redis
+description: Patrones de estructuras de datos de Redis, estrategias de caché, locks distribuidos, rate limiting, pub/sub y gestión de conexiones para aplicaciones en producción.
+---
+
+# Patrones de Redis
+
+Referencia rápida de buenas prácticas de Redis para los casos de uso comunes de backend.
+
+## Cómo funciona
+
+Redis es un almacén de estructuras de datos en memoria que soporta strings, hashes, listas, sets, sorted sets, streams y más. Los comandos individuales de Redis son atómicos en una sola instancia; los flujos de varios pasos requieren scripts Lua, transacciones MULTI/EXEC o sincronización explícita para mantenerse atómicos. Los datos se persisten opcionalmente mediante snapshots RDB o logs AOF. Los clientes se comunican por TCP usando el protocolo RESP; los pools de conexiones son esenciales para evitar la sobrecarga del handshake por petición.
+
+## Cuándo activar
+
+- Al añadir caché a una aplicación
+- Al implementar rate limiting o throttling
+- Al construir locks distribuidos o coordinación
+- Al configurar almacenamiento de sesiones o tokens
+- Al usar Pub/Sub o Redis Streams para mensajería
+- Al configurar Redis en producción (pooling, evicción, clustering)
+
+## Tabla rápida de estructuras de datos
+
+| Caso de uso | Estructura | Clave de ejemplo |
+|----------|-----------|-------------|
+| Caché simple | String | `product:123` |
+| Sesión de usuario | Hash | `session:abc` |
+| Tabla de clasificación | Sorted Set | `scores:weekly` |
+| Visitantes únicos | Set | `visitors:2024-01-01` |
+| Feed de actividad | List | `feed:user:456` |
+| Flujo de eventos | Stream | `events:orders` |
+| Contadores / rate limits | String (INCR) | `ratelimit:user:123` |
+| Filtro de Bloom / HLL | HyperLogLog | `hll:pageviews` |
+
+## Patrones centrales
+
+### Cache-aside (carga perezosa)
+
+```python
+import redis
+import json
+
+r = redis.Redis(host='localhost', port=6379, decode_responses=True)
+
+def get_product(product_id: int):
+    cache_key = f"product:{product_id}"
+    cached = r.get(cache_key)
+
+    if cached:
+        return json.loads(cached)
+
+    product = db.query("SELECT * FROM products WHERE id = %s", product_id)
+    r.setex(cache_key, 3600, json.dumps(product))  # TTL: 1 hora
+    return product
+```
+
+### Caché write-through
+
+```python
+def update_product(product_id: int, data: dict):
+    # Escribir primero en la BD
+    db.execute("UPDATE products SET ... WHERE id = %s", product_id)
+
+    # Actualizar la caché de inmediato
+    cache_key = f"product:{product_id}"
+    r.setex(cache_key, 3600, json.dumps(data))
+```
+
+### Invalidación de caché
+
+```python
+# Invalidación por etiquetas — agrupa claves relacionadas en un set
+def cache_product(product_id: int, category_id: int, data: dict):
+    key = f"product:{product_id}"
+    tag = f"tag:category:{category_id}"
+    pipe = r.pipeline(transaction=True)
+    pipe.setex(key, 3600, json.dumps(data))
+    pipe.sadd(tag, key)
+    pipe.expire(tag, 3600)
+    pipe.execute()
+
+def invalidate_category(category_id: int):
+    tag = f"tag:category:{category_id}"
+    keys = r.smembers(tag)
+    if keys:
+        r.delete(*keys)
+    r.delete(tag)
+```
+
+### Almacenamiento de sesiones
+
+```python
+import time
+import uuid
+
+def create_session(user_id: int, ttl: int = 86400) -> str:
+    session_id = str(uuid.uuid4())
+    key = f"session:{session_id}"
+    pipe = r.pipeline(transaction=True)
+    pipe.hset(key, mapping={
+        "user_id": user_id,
+        "created_at": int(time.time()),
+    })
+    pipe.expire(key, ttl)
+    pipe.execute()
+    return session_id
+
+def get_session(session_id: str) -> dict | None:
+    data = r.hgetall(f"session:{session_id}")
+    return data if data else None
+
+def delete_session(session_id: str):
+    r.delete(f"session:{session_id}")
+```
+
+## Rate limiting
+
+### Ventana fija (simple)
+
+```python
+def is_rate_limited(user_id: int, limit: int = 100, window: int = 60) -> bool:
+    key = f"ratelimit:{user_id}:{int(time.time()) // window}"
+    pipe = r.pipeline(transaction=True)
+    pipe.incr(key)
+    pipe.expire(key, window)
+    count, _ = pipe.execute()
+    return count > limit
+```
+
+### Ventana deslizante (Lua — atómico)
+
+```lua
+-- sliding_window.lua
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+
+redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
+local count = redis.call('ZCARD', key)
+
+if count < limit then
+    -- Usa un miembro único (now + secuencia) para evitar colisiones dentro del mismo milisegundo
+    local seq_key = key .. ':seq'
+    local seq = redis.call('INCR', seq_key)
+    redis.call('EXPIRE', seq_key, math.ceil(window / 1000))
+    redis.call('ZADD', key, now, now .. '-' .. seq)
+    redis.call('EXPIRE', key, math.ceil(window / 1000))
+    return 1
+end
+return 0
+```
+
+```python
+sliding_window = r.register_script(open('sliding_window.lua').read())
+
+def allow_request(user_id: int) -> bool:
+    key = f"ratelimit:sliding:{user_id}"
+    now = int(time.time() * 1000)
+    return bool(sliding_window(keys=[key], args=[now, 60000, 100]))
+```
+
+## Locks distribuidos
+
+### Lock distribuido (un solo nodo — SET NX PX)
+
+```python
+import uuid
+
+def acquire_lock(resource: str, ttl_ms: int = 5000) -> str | None:
+    lock_key = f"lock:{resource}"
+    token = str(uuid.uuid4())
+    acquired = r.set(lock_key, token, px=ttl_ms, nx=True)
+    return token if acquired else None
+
+def release_lock(resource: str, token: str) -> bool:
+    release_script = """
+    if redis.call('get', KEYS[1]) == ARGV[1] then
+        return redis.call('del', KEYS[1])
+    else
+        return 0
+    end
+    """
+    result = r.eval(release_script, 1, f"lock:{resource}", token)
+    return bool(result)
+
+# Uso
+token = acquire_lock("order:payment:123")
+if token:
+    try:
+        process_payment()
+    finally:
+        release_lock("order:payment:123", token)
+```
+
+> Para despliegues multi-nodo usa la librería `redlock-py`, que implementa el algoritmo Redlock completo.
+
+## Pub/Sub y Streams
+
+### Pub/Sub (disparar y olvidar)
+
+```python
+# Publicador
+def publish_event(channel: str, payload: dict):
+    r.publish(channel, json.dumps(payload))
+
+# Suscriptor (bloqueante — ejecutar en un hilo/proceso separado)
+def subscribe_events(channel: str):
+    pubsub = r.pubsub()
+    pubsub.subscribe(channel)
+    for message in pubsub.listen():
+        if message['type'] == 'message':
+            handle(json.loads(message['data']))
+```
+
+### Redis Streams (cola durable)
+
+```python
+# Productor
+def emit(stream: str, event: dict):
+    r.xadd(stream, event, maxlen=10000)  # Limita la longitud del stream
+
+# Grupo de consumidores — garantiza entrega al-menos-una-vez
+try:
+    r.xgroup_create('events:orders', 'processor', id='0', mkstream=True)
+except Exception:
+    pass  # El grupo ya existe
+
+def consume(stream: str, group: str, consumer: str):
+    while True:
+        messages = r.xreadgroup(group, consumer, {stream: '>'}, count=10, block=2000)
+        for _, entries in (messages or []):
+            for msg_id, data in entries:
+                process(data)
+                r.xack(stream, group, msg_id)
+```
+
+> Prefiere **Streams** sobre Pub/Sub cuando necesites garantías de entrega, grupos de consumidores o replay.
+
+## Diseño de claves
+
+### Convenciones de nombres
+
+```
+# Patrón: recurso:id:campo
+user:123:profile
+order:456:status
+cache:product:789
+
+# Patrón: namespace:recurso:id
+myapp:session:abc123
+myapp:ratelimit:user:123
+
+# Patrón: recurso:fecha (claves acotadas en el tiempo)
+stats:pageviews:2024-01-01
+```
+
+### Estrategia de TTL
+
+| Tipo de dato | TTL sugerido |
+|-----------|--------------|
+| Sesión de usuario | 24 h (`86400`) |
+| Caché de respuestas de API | 5–15 min |
+| Ventana de rate limit | Igual al tamaño de la ventana |
+| Tokens de corta vida | 5–10 min |
+| Tabla de clasificación | 1 h–24 h |
+| Datos estáticos/de referencia | 1 h–1 semana |
+
+Establece siempre un TTL. Las claves sin TTL se acumulan indefinidamente y provocan presión de memoria.
+
+## Gestión de conexiones
+
+### Pool de conexiones
+
+```python
+from redis import ConnectionPool, Redis
+
+pool = ConnectionPool(
+    host='localhost',
+    port=6379,
+    db=0,
+    max_connections=20,
+    decode_responses=True,
+    socket_connect_timeout=2,
+    socket_timeout=2,
+)
+
+r = Redis(connection_pool=pool)
+```
+
+### Modo clúster
+
+```python
+from redis.cluster import RedisCluster
+
+r = RedisCluster(
+    startup_nodes=[{"host": "redis-1", "port": 6379}],
+    decode_responses=True,
+    skip_full_coverage_check=True,
+)
+```
+
+### Sentinel (alta disponibilidad)
+
+```python
+from redis.sentinel import Sentinel
+
+sentinel = Sentinel(
+    [('sentinel-1', 26379), ('sentinel-2', 26379)],
+    socket_timeout=0.5,
+)
+master = sentinel.master_for('mymaster', decode_responses=True)
+replica = sentinel.slave_for('mymaster', decode_responses=True)
+```
+
+## Políticas de evicción
+
+| Política | Comportamiento | Ideal para |
+|--------|----------|----------|
+| `noeviction` | Error al escribir cuando está lleno | Colas / datos críticos |
+| `allkeys-lru` | Expulsa el menos usado recientemente | Caché general |
+| `volatile-lru` | LRU solo entre claves con TTL | Almacén de datos mixto |
+| `allkeys-lfu` | Expulsa el menos usado en frecuencia | Patrones de acceso sesgados |
+| `volatile-ttl` | Expulsa el que expira antes | Priorizar datos de larga vida |
+
+Se configura en `redis.conf`: `maxmemory-policy allkeys-lru`
+
+## Antipatrones
+
+| Antipatrón | Problema | Solución |
+|---|---|---|
+| Claves sin TTL | La memoria crece sin límite | Establece siempre un TTL |
+| `KEYS *` en producción | Bloquea el servidor (O(N)) | Usa el cursor `SCAN` |
+| Guardar blobs grandes (>100KB) | Serialización lenta, presión de memoria | Guarda una referencia y obtén el dato de un object store |
+| Un solo Redis para todo | Sin aislamiento entre caché y cola | Usa BDs o instancias separadas |
+| Ignorar los límites del pool de conexiones | Agotamiento de conexiones bajo carga | Dimensiona el pool según la carga |
+| No manejar la estampida por fallo de caché | Avalancha (thundering herd) en arranque frío | Usa locks o expiración temprana probabilística |
+| `FLUSHALL` sin pensarlo | Borra la instancia entera | Acota los borrados por patrón de claves |
+
+### Prevención de la estampida por fallo de caché
+
+```python
+import threading
+
+_locks: dict[str, threading.Lock] = {}
+_locks_mutex = threading.Lock()
+
+def get_with_lock(key: str, fetch_fn, ttl: int = 300):
+    cached = r.get(key)
+    if cached:
+        return json.loads(cached)
+
+    with _locks_mutex:
+        if key not in _locks:
+            _locks[key] = threading.Lock()
+        lock = _locks[key]
+    with lock:
+        cached = r.get(key)  # Volver a comprobar tras adquirir el lock
+        if cached:
+            return json.loads(cached)
+        value = fetch_fn()
+        r.setex(key, ttl, json.dumps(value))
+        return value
+```
+
+> Nota: para despliegues multi-proceso, reemplaza el lock en proceso por `acquire_lock`/`release_lock` de la sección de locks distribuidos de arriba.
+
+## Ejemplos
+
+**Añadir caché a un endpoint de API en Django/Flask:**
+Usa cache-aside con `setex` y un TTL de 5 minutos sobre la respuesta. Usa los parámetros de la petición como clave.
+
+**Aplicar rate limit a una API por usuario:**
+Usa ventana fija con `pipeline(transaction=True)` para endpoints de bajo tráfico; usa la ventana deslizante en Lua para throttling preciso por usuario.
+
+**Coordinar un job en segundo plano entre workers:**
+Usa `acquire_lock` con un TTL que supere la duración esperada del job. Libera siempre en un bloque `finally`.
+
+**Difundir notificaciones a múltiples suscriptores:**
+Usa Pub/Sub para disparar y olvidar. Cambia a Streams si necesitas entrega garantizada o replay para consumidores tardíos.
+
+## Referencia rápida
+
+| Patrón | Cuándo usarlo |
+|---------|-------------|
+| Cache-aside | Lectura intensiva, tolera ligera obsolescencia |
+| Write-through | Se requiere consistencia fuerte |
+| Lock distribuido | Prevenir acceso concurrente a un recurso |
+| Rate limit de ventana deslizante | Throttling preciso por usuario |
+| Redis Streams | Cola de eventos durable con grupos de consumidores |
+| Pub/Sub | Broadcast sin necesidad de garantías de entrega |
+| Tabla de clasificación con Sorted Set | Puntuación con ranking, paginación |
+| HyperLogLog | Conteo único aproximado con poca memoria |
+
+## Relacionados
+
+- Skill: `patrones-postgres` — patrones de datos relacionales
+- Skill: `patrones-backend` — patrones de API y capa de servicios
+- Skill: `migraciones-bd` — versionado de esquemas
+- Agente: `revisor-bd` — flujo completo de revisión de bases de datos