theus-cli-linux-x64 1.2.2 → 1.3.0

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

@@ -1,401 +0,0 @@
----
-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