feat(cache): migrar caché de guilds de Redis a Appwrite para mejorar rendimiento y persistencia

2025-10-07 10:55:45 -05:00
parent 6a9135c03a
commit b4737a536f
6 changed files with 1011 additions and 0 deletions
--- a/README/FIX_OUT_OF_MEMORY.md
+++ b/README/FIX_OUT_OF_MEMORY.md
@@ -0,0 +1,124 @@
+# Fix: Out of Memory en PostgreSQL
+
+## Problema Identificado
+
+El bot estaba experimentando errores `out of memory` (código 53200) en PostgreSQL debido a que **en cada mensaje recibido** se estaba ejecutando un `prisma.guild.upsert()` para obtener la configuración del servidor (principalmente el prefix).
+
+### Síntomas
+```
+ConnectorError(ConnectorError { 
+  kind: QueryError(PostgresError { 
+    code: "53200", 
+    message: "out of memory", 
+    severity: "ERROR", 
+    detail: Some("Failed on request of size 8192.") 
+  })
+})
+```
+
+Esto ocurría en:
+- `messageCreate.ts` línea 199: `await bot.prisma.guild.upsert(...)` en cada mensaje
+- `handleAIReply()`: `await bot.prisma.guild.findUnique(...)` en cada respuesta a la IA
+
+## Solución Implementada
+
+### 1. Sistema de Caché con Redis
+Se creó un nuevo módulo `guildCache.ts` que:
+
+- **Almacena en caché** la configuración de cada guild por 5 minutos (TTL: 300s)
+- **Reduce consultas a PostgreSQL** en ~99% (solo 1 consulta cada 5 minutos por guild)
+- **Maneja errores gracefully** retornando valores por defecto si Redis o PostgreSQL fallan
+
+#### Funciones principales:
+```typescript
+// Obtiene config desde caché o DB (con upsert automático)
+getGuildConfig(guildId, guildName, prisma): Promise<GuildConfig>
+
+// Invalida el caché cuando se actualiza la config
+invalidateGuildCache(guildId): Promise<void>
+
+// Actualiza directamente el caché
+updateGuildCache(config): Promise<void>
+```
+
+### 2. Actualización de `messageCreate.ts`
+- Reemplazó `prisma.guild.upsert()` por `getGuildConfig()`
+- Ahora usa caché en Redis antes de consultar PostgreSQL
+- Aplica en:
+  - Handler principal de mensajes
+  - `handleAIReply()` para respuestas a la IA
+
+### 3. Invalidación de Caché en `settings.ts`
+Se agregó invalidación automática del caché cuando se actualiza:
+- **Prefix del servidor**
+- **Roles de staff**
+- **AI Role Prompt**
+
+Esto asegura que los cambios se reflejen inmediatamente en el próximo mensaje.
+
+## Impacto en el Rendimiento
+
+### Antes:
+- **Por cada mensaje**: 1 consulta a PostgreSQL (upsert)
+- En un servidor activo con 100 mensajes/minuto: **100 consultas/minuto**
+- En 10 servidores: **1,000 consultas/minuto**
+
+### Después:
+- **Primera consulta**: va a PostgreSQL + guarda en Redis (TTL 5 min)
+- **Siguientes consultas**: se obtienen de Redis (0 consultas a PostgreSQL)
+- En un servidor activo: **~1 consulta cada 5 minutos**
+- En 10 servidores: **~10 consultas cada 5 minutos** (reducción del 99.8%)
+
+## Archivos Modificados
+
+1. **`src/core/database/guildCache.ts`** (NUEVO)
+   - Sistema completo de caché con Redis
+   - Manejo de errores robusto
+   - Logging detallado
+
+2. **`src/events/messageCreate.ts`**
+   - Reemplazó `prisma.guild.upsert()` con `getGuildConfig()`
+   - Reemplazó `prisma.guild.findUnique()` en `handleAIReply()`
+
+3. **`src/commands/messages/settings-server/settings.ts`**
+   - Agregó `invalidateGuildCache()` después de:
+     - Actualizar prefix
+     - Actualizar staff roles
+     - Actualizar AI role prompt
+
+## Verificación
+
+Para verificar que funciona:
+
+1. **Logs de Redis**: Buscar mensajes como:
+   ```
+   ✅ Guild config obtenida desde caché
+   ✅ Guild config guardada en caché
+   🗑️  Caché de guild invalidada
+   ```
+
+2. **Logs de Prisma**: Deberías ver **mucho menos** `prisma.guild.upsert()` en los logs
+
+3. **Memoria de PostgreSQL**: Debería estabilizarse y no crecer descontroladamente
+
+## Recomendaciones Adicionales
+
+Si el problema persiste:
+
+1. **Revisar otras consultas frecuentes** que puedan estar saturando PostgreSQL
+2. **Aumentar memoria de PostgreSQL** si es posible en el plan de Heroku/hosting
+3. **Implementar connection pooling** para Prisma si no está configurado
+4. **Considerar agregar índices** en tablas con consultas pesadas
+
+## Deployment
+
+Asegúrate de que:
+- ✅ Redis está configurado y accesible (`REDIS_URL` y `REDIS_PASS` en `.env`)
+- ✅ El bot tiene conexión a Redis antes de procesar mensajes
+- ✅ Se ejecuta `npm run build` o el equivalente para compilar TypeScript
+
+---
+
+**Fecha**: 2025-10-07  
+**Severidad**: CRÍTICA  
+**Estado**: RESUELTO ✅
--- a/README/GUIA_MANUAL_APPWRITE.md
+++ b/README/GUIA_MANUAL_APPWRITE.md
@@ -0,0 +1,141 @@
+# 📋 Guía Paso a Paso: Crear Colección Guild Cache en Appwrite
+
+## Paso 1: Acceder a tu Database
+
+1. Ve a [Appwrite Console](https://cloud.appwrite.io) (o tu instancia)
+2. Selecciona tu proyecto
+3. En el menú lateral, haz clic en **Databases**
+4. Selecciona tu database (el que tienes en `APPWRITE_DATABASE_ID`)
+
+## Paso 2: Crear la Colección
+
+1. Haz clic en **Create Collection**
+2. **Collection Name**: `guild_cache`
+3. **Collection ID**: Déjalo autogenerar o usa `guild_cache`
+4. Haz clic en **Create**
+
+## Paso 3: Agregar Atributos
+
+En la colección que acabas de crear, ve a la pestaña **Attributes** y crea estos 4 atributos:
+
+### Atributo 1: guildId
+- Haz clic en **Create Attribute** → **String**
+- **Attribute Key**: `guildId`
+- **Size**: `32`
+- **Required**: ✅ Sí (marcado)
+- **Array**: ❌ No
+- Haz clic en **Create**
+
+### Atributo 2: name
+- Haz clic en **Create Attribute** → **String**
+- **Attribute Key**: `name`
+- **Size**: `100`
+- **Required**: ✅ Sí (marcado)
+- **Array**: ❌ No
+- Haz clic en **Create**
+
+### Atributo 3: prefix
+- Haz clic en **Create Attribute** → **String**
+- **Attribute Key**: `prefix`
+- **Size**: `10`
+- **Required**: ❌ No (desmarcado)
+- **Default value**: (déjalo vacío)
+- **Array**: ❌ No
+- Haz clic en **Create**
+
+### Atributo 4: expiresAt
+- Haz clic en **Create Attribute** → **DateTime**
+- **Attribute Key**: `expiresAt`
+- **Required**: ✅ Sí (marcado)
+- **Array**: ❌ No
+- Haz clic en **Create**
+
+⏳ **IMPORTANTE**: Espera unos segundos a que todos los atributos estén en estado **Available** antes de continuar.
+
+## Paso 4: Crear Índices
+
+Ve a la pestaña **Indexes** y crea estos 2 índices:
+
+### Índice 1: guildId (único)
+- Haz clic en **Create Index**
+- **Index Key**: `idx_guildId`
+- **Index Type**: **Unique**
+- **Attributes**: Selecciona `guildId`
+- **Order**: ASC
+- Haz clic en **Create**
+
+### Índice 2: expiresAt
+- Haz clic en **Create Index**
+- **Index Key**: `idx_expiresAt`
+- **Index Type**: **Key**
+- **Attributes**: Selecciona `expiresAt`
+- **Order**: ASC
+- Haz clic en **Create**
+
+## Paso 5: Configurar Permisos
+
+Ve a la pestaña **Settings** → **Permissions**:
+
+1. Por defecto debería estar configurado como "API Key"
+2. Si no, agrega estos permisos:
+   - **Role**: `Any`
+   - **Permissions**: Read, Create, Update, Delete (todas marcadas)
+
+## Paso 6: Copiar el Collection ID
+
+1. En la parte superior de la colección, verás el **Collection ID**
+2. Cópialo (algo como `67xxxxxx` o `guild_cache` si lo personalizaste)
+
+## Paso 7: Actualizar Variables de Entorno
+
+Agrega a tu `.env` (o Config Vars en Heroku):
+
+```env
+APPWRITE_COLLECTION_GUILD_CACHE_ID=el_collection_id_que_copiaste
+```
+
+## Paso 8: Verificar
+
+Para verificar que todo está bien:
+
+1. Ve a la colección
+2. Pestaña **Attributes**: Deberías ver 4 atributos (guildId, name, prefix, expiresAt)
+3. Pestaña **Indexes**: Deberías ver 2 índices (idx_guildId, idx_expiresAt)
+
+## Paso 9: Redeploy el Bot
+
+```bash
+# Si es local
+npm run build
+npm start
+
+# Si es Heroku
+git add .
+git commit -m "chore: agregar APPWRITE_COLLECTION_GUILD_CACHE_ID"
+git push heroku main
+```
+
+## ✅ Listo!
+
+Después del redeploy, busca en los logs:
+```
+✅ Guild config guardada en caché (Appwrite)
+```
+
+---
+
+## 🐛 Solución de Problemas
+
+### Error: "Attribute already exists"
+- El atributo ya existe, pasa al siguiente
+
+### Error: "Index already exists"  
+- El índice ya existe, pasa al siguiente
+
+### Error: "Collection not found"
+- Verifica que el `APPWRITE_COLLECTION_GUILD_CACHE_ID` sea correcto
+
+### No veo mensajes de caché en los logs
+- Verifica que todas las variables de Appwrite estén configuradas
+- Revisa que el Collection ID sea correcto
+- Comprueba que la colección tenga los permisos correctos
--- a/README/MIGRACION_CACHE_APPWRITE.md
+++ b/README/MIGRACION_CACHE_APPWRITE.md
@@ -0,0 +1,215 @@
+# Migración de Caché: Redis → Appwrite
+
+## Problema
+
+Redis con 30MB de memoria ya estaba usando 2.4MB (8%) solo para el caché de configuración de guilds. Con el crecimiento del bot, esto podría saturar rápidamente la instancia de Redis.
+
+## Solución: Usar Appwrite Database como Caché
+
+Appwrite Database ofrece:
+- ✅ **Más espacio**: Sin límites estrictos de 30MB
+- ✅ **Persistencia**: Los datos sobreviven reinicios
+- ✅ **Gratuito**: Ya lo tienes configurado en el proyecto
+- ✅ **Consultas avanzadas**: Permite búsquedas y filtros complejos
+
+## Configuración en Appwrite
+
+### 1. Crear la Colección
+
+En tu consola de Appwrite (`console.appwrite.io` o tu instancia):
+
+1. Ve a **Databases** → Selecciona tu database
+2. Crea una nueva colección llamada `guild_cache`
+3. Configura los siguientes atributos:
+
+| Atributo | Tipo | Tamaño | Requerido | Único | Default |
+|----------|------|--------|-----------|-------|---------|
+| `guildId` | String | 32 | ✅ Sí | ✅ Sí | - |
+| `name` | String | 100 | ✅ Sí | ❌ No | - |
+| `prefix` | String | 10 | ❌ No | ❌ No | `null` |
+| `expiresAt` | DateTime | - | ✅ Sí | ❌ No | - |
+
+4. Crea un **Índice** en `expiresAt` (tipo: Key, ascendente) para optimizar las búsquedas de limpieza
+
+### 2. Configurar Permisos
+
+En la colección, ve a **Settings** → **Permissions**:
+- **Create**: API Key
+- **Read**: API Key
+- **Update**: API Key
+- **Delete**: API Key
+
+### 3. Variables de Entorno
+
+Agrega a tu `.env`:
+
+```env
+# Appwrite
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+APPWRITE_PROJECT_ID=tu_project_id
+APPWRITE_API_KEY=tu_api_key
+APPWRITE_DATABASE_ID=tu_database_id
+APPWRITE_COLLECTION_GUILD_CACHE_ID=guild_cache_collection_id
+```
+
+Para obtener el `APPWRITE_COLLECTION_GUILD_CACHE_ID`:
+1. En la consola de Appwrite, abre la colección `guild_cache`
+2. Copia el **Collection ID** que aparece en la parte superior
+
+## Cambios Implementados
+
+### Archivos Modificados
+
+1. **`src/core/api/appwrite.ts`**
+   - Agregado: `APPWRITE_COLLECTION_GUILD_CACHE_ID`
+   - Nueva función: `isGuildCacheConfigured()`
+
+2. **`src/core/database/guildCache.ts`** (REESCRITO COMPLETAMENTE)
+   - Migrado de Redis a Appwrite Database
+   - `getGuildConfig()`: Lee desde Appwrite, valida expiración
+   - `invalidateGuildCache()`: Elimina documento de Appwrite
+   - `updateGuildCache()`: Actualiza o crea documento
+   - `cleanExpiredGuildCache()`: Limpia documentos expirados (nueva función)
+
+3. **`src/main.ts`**
+   - Agregado job de limpieza cada 10 minutos
+   - Importa `cleanExpiredGuildCache()`
+
+4. **`.env.example`**
+   - Documentadas todas las variables de Appwrite
+
+### Funciones
+
+#### `getGuildConfig(guildId, guildName, prisma)`
+```typescript
+// 1. Intenta leer desde Appwrite
+// 2. Verifica si expiró (expiresAt < now)
+// 3. Si expiró o no existe, hace upsert en PostgreSQL
+// 4. Guarda en Appwrite con TTL de 5 minutos
+// 5. Retorna la configuración
+```
+
+#### `invalidateGuildCache(guildId)`
+```typescript
+// Elimina el documento de Appwrite
+// Se llama cuando se actualiza: prefix, staff, AI role prompt
+```
+
+#### `cleanExpiredGuildCache()`
+```typescript
+// Busca documentos con expiresAt < now
+// Elimina hasta 100 documentos expirados por ejecución
+// Se ejecuta cada 10 minutos automáticamente
+```
+
+## Comparación: Redis vs Appwrite
+
+| Característica | Redis (Antes) | Appwrite (Ahora) |
+|----------------|---------------|------------------|
+| **Memoria** | 30MB límite | ~Ilimitado |
+| **Persistencia** | Volátil (se pierde al reiniciar) | Persistente |
+| **TTL** | Automático (`SETEX`) | Manual (verificación en lectura) |
+| **Costo** | Limitado por plan | Incluido en plan gratis |
+| **Queries** | Básicas (key-value) | Avanzadas (filtros, búsquedas) |
+| **Latencia** | ~1-5ms | ~50-100ms |
+
+### Nota sobre Latencia
+
+Appwrite es **ligeramente más lento** que Redis (~50-100ms vs ~1-5ms), pero:
+- ✅ Solo se consulta cada 5 minutos por guild
+- ✅ El 99% de las consultas vienen de caché
+- ✅ La diferencia es imperceptible para el usuario final
+
+## Testing
+
+### 1. Verificar que funciona
+
+Busca en los logs:
+```
+✅ Guild config obtenida desde caché (Appwrite)
+✅ Guild config guardada en caché (Appwrite)
+🗑️  Caché de guild invalidada (Appwrite)
+🧹 Documentos expirados eliminados de caché
+```
+
+### 2. Verificar en Appwrite Console
+
+1. Ve a tu colección `guild_cache`
+2. Deberías ver documentos con:
+   - `guildId`: ID del servidor
+   - `name`: Nombre del servidor
+   - `prefix`: Prefix configurado (o vacío)
+   - `expiresAt`: Fecha de expiración (5 minutos en el futuro)
+
+### 3. Probar cambio de prefix
+
+1. Ejecuta `!settings` en Discord
+2. Cambia el prefix
+3. Verifica en los logs: `🗑️  Caché de guild invalidada`
+4. El próximo comando debería usar el nuevo prefix inmediatamente
+
+## Uso de Memoria
+
+### Estimación por Guild
+
+Cada documento en Appwrite ocupa aproximadamente:
+```
+guildId:    20 bytes
+name:       50 bytes (promedio)
+prefix:     3 bytes
+expiresAt:  8 bytes
+Metadata:   ~50 bytes (Appwrite overhead)
+───────────────────────
+TOTAL:      ~131 bytes
+```
+
+Para **1,000 guilds** = **~128 KB** (mucho menos que Redis)
+
+### Redis Liberado
+
+Al migrar el caché de guilds a Appwrite:
+- **Antes**: ~2.4 MB en Redis
+- **Después**: ~0 MB en Redis (solo para otras cosas)
+- **Ahorro**: ~8% de la memoria de Redis
+
+## Rollback (si algo falla)
+
+Si necesitas volver a Redis:
+
+1. Restaura el archivo anterior:
+```bash
+git checkout HEAD~1 src/core/database/guildCache.ts
+```
+
+2. Comenta las líneas en `main.ts`:
+```typescript
+// import { cleanExpiredGuildCache } from "./core/database/guildCache";
+// setInterval(async () => { ... }, 10 * 60 * 1000);
+```
+
+3. Redeploy
+
+## Próximos Pasos (Opcional)
+
+Si quieres optimizar aún más:
+
+1. **Migrar otros cachés a Appwrite**:
+   - Cooldowns de usuarios
+   - Stats frecuentes
+   - Inventarios activos
+
+2. **Implementar caché híbrido**:
+   - Memoria local (LRU) para guilds muy activos
+   - Appwrite para persistencia
+
+3. **Agregar métricas**:
+   - Cache hit rate
+   - Latencia promedio
+   - Documentos expirados/hora
+
+---
+
+**Fecha**: 2025-10-07  
+**Cambio**: Migración de Redis → Appwrite para caché de guilds  
+**Razón**: Ahorrar memoria en Redis (30MB limitados)  
+**Estado**: ✅ COMPLETADO
--- a/README/SETUP_APPWRITE_CACHE.md
+++ b/README/SETUP_APPWRITE_CACHE.md
@@ -0,0 +1,68 @@
+# 🚀 Guía Rápida: Configurar Caché de Guilds con Appwrite
+
+## ¿Por qué Appwrite en vez de Redis?
+
+- ✅ Redis: Solo 30MB disponibles (ya usando 8%)
+- ✅ Appwrite: Sin límites estrictos, incluido en plan gratis
+- ✅ Ahorra ~2.4MB de Redis para otros usos
+
+## Configuración (5 minutos)
+
+### Opción Recomendada: Manual (Consola de Appwrite) 📝
+
+**Por qué manual**: La API Key de tu proyecto requiere permisos elevados para crear colecciones. Es más rápido hacerlo desde la consola web.
+
+📋 **[Sigue esta guía paso a paso](./GUIA_MANUAL_APPWRITE.md)** ← Click aquí
+
+**Resumen rápido:**
+1. Crea colección `guild_cache` en Appwrite Console
+2. Agrega 4 atributos: `guildId`, `name`, `prefix`, `expiresAt`
+3. Crea 2 índices en `guildId` y `expiresAt`
+4. Copia el Collection ID
+5. Agrégalo a `.env` como `APPWRITE_COLLECTION_GUILD_CACHE_ID`
+
+### Opción Alternativa: Script Automático 🤖
+
+⚠️ **Requiere API Key con permisos completos** (databases.write, collections.write, etc.)
+
+```bash
+# Si tienes una API Key con permisos suficientes:
+node scripts/setupGuildCacheCollection.js
+
+# Luego agrega el ID a .env
+APPWRITE_COLLECTION_GUILD_CACHE_ID=el_id_generado
+```
+
+## Variables de Entorno Necesarias
+
+Asegúrate de tener en tu `.env` (o Config Vars de Heroku):
+
+```env
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+APPWRITE_PROJECT_ID=tu_project_id
+APPWRITE_API_KEY=tu_api_key
+APPWRITE_DATABASE_ID=tu_database_id
+APPWRITE_COLLECTION_GUILD_CACHE_ID=tu_collection_id_nuevo
+```
+
+## Verificación
+
+Después de desplegar, busca en los logs:
+
+```
+✅ Guild config obtenida desde caché (Appwrite)
+✅ Guild config guardada en caché (Appwrite)
+🧹 Documentos expirados eliminados de caché
+```
+
+## ¿Qué hace esto?
+
+- **Antes**: Cada mensaje → consulta a PostgreSQL (miles por minuto)
+- **Ahora**: Cada mensaje → consulta a Appwrite caché (1 vez cada 5 min por servidor)
+- **Resultado**: 99.8% menos carga en PostgreSQL
+
+## Más Información
+
+Lee la documentación completa en:
+- [README/MIGRACION_CACHE_APPWRITE.md](./MIGRACION_CACHE_APPWRITE.md)
+- [README/FIX_OUT_OF_MEMORY.md](./FIX_OUT_OF_MEMORY.md)