nwinread 1.1.1 → 1.2.0

package/doc/RESUMABLE_READER.md

@@ -0,0 +1,250 @@
+# Resumable Event Reader - Sistema Resiliente
+
+El **Resumable Event Reader** es una clase que implementa un sistema robusto de procesamiento de eventos de Windows que puede recuperarse automáticamente después de reinicios del proceso.
+
+## ✨ Características
+
+- 🔄 **Recuperación automática** después de reinicios
+- 💾 **Persistencia de estado** en archivo JSON
+- 🎯 **Procesamiento sin pérdidas** usando patrón híbrido sync/async
+- 📊 **Estadísticas** de procesamiento en tiempo real
+- 🛡️ **Manejo de errores** robusto
+
+## 🚀 Uso Rápido
+
+```javascript
+const ResumableEventReader = require('./lib/ResumableEventReader');
+
+const reader = new ResumableEventReader('Application', {
+    onEvent: (event) => {
+        console.log(`Evento: ${event.recordId} [${event.source}]`);
+        // Tu lógica de procesamiento aquí
+    },
+    onError: (error) => {
+        console.error(`Error: ${error.message}`);
+    }
+});
+
+reader.start();
+```
+
+## 📋 Opciones de Configuración
+
+```javascript
+const options = {
+    // Filtro opcional por Event IDs
+    eventIds: [1000, 1001, 1002],
+    
+    // Archivo donde guardar el estado (default: channel_state.json)
+    stateFile: './mi_estado.json',
+    
+    // Tamaño de lote para recuperación (default: 100)
+    catchUpBatchSize: 50,
+    
+    // Callback para cada evento procesado
+    onEvent: (event) => {
+        // event.recordId - ID del evento
+        // event.xml - XML completo del evento
+        // event.source - 'CATCH_UP' o 'LIVE'
+        // event.processingInfo.totalProcessed - Total eventos procesados
+        // event.processingInfo.lastRecordId - Último ID procesado
+    },
+    
+    // Callback para errores
+    onError: (error) => {
+        console.error(error);
+    }
+};
+```
+
+## 🔄 Flujo de Funcionamiento
+
+### 1. Primera Ejecución
+```
+🆕 Inicialización
+    ↓
+📍 Obtener último Record ID del log
+    ↓
+📡 Suscripción a eventos futuros
+    ↓
+💾 Guardar estado
+```
+
+### 2. Ejecuciones Posteriores (Recuperación)
+```
+📂 Cargar estado desde archivo
+    ↓ 
+🔄 Catch-up: Leer eventos perdidos (SYNC)
+    ↓
+📡 Suscripción a eventos futuros (ASYNC)  
+    ↓
+💾 Guardar estado continuamente
+```
+
+## 📊 Métodos
+
+### `start()`
+Inicia el reader. Se encarga automáticamente de:
+- Cargar estado persistido
+- Ejecutar catch-up si es necesario
+- Iniciar suscripción en vivo
+
+### `stop()`
+Detiene el reader gracefully:
+- Cancela suscripción activa
+- Guarda estado final
+- Marca como no-running
+
+### `getStats()`
+Retorna estadísticas actuales:
+```javascript
+{
+    channel: "Application",
+    lastRecordId: 12345,
+    totalEventsProcessed: 150,
+    isRunning: true,
+    hasSubscription: true,
+    stateFile: "./estado.json"
+}
+```
+
+### `reset()`
+Resetea el estado (solo para testing):
+- Borra archivo de estado
+- Reinicia contadores
+
+## 💾 Formato del Archivo de Estado
+
+```json
+{
+  "lastRecordId": 123456,
+  "isRunning": false,
+  "totalEventsProcessed": 1500
+}
+```
+
+## 🎯 Casos de Uso
+
+### Monitoreo de Aplicaciones 24/7
+```javascript
+const appMonitor = new ResumableEventReader('Application', {
+    eventIds: [1000, 1001, 1002], // Solo errores críticos
+    onEvent: (event) => {
+        if (event.xml.includes('Error')) {
+            sendAlert(event);
+        }
+        logToDatabase(event);
+    }
+});
+
+appMonitor.start();
+```
+
+### Auditoría de Seguridad
+```javascript
+const securityAuditor = new ResumableEventReader('Security', {
+    eventIds: [4624, 4625, 4634], // Logins/logouts
+    stateFile: './security_audit_state.json',
+    onEvent: (event) => {
+        analyzeSecurityEvent(event);
+        updateComplianceReport(event);
+    }
+});
+```
+
+### Integración con Sistemas Externos
+```javascript
+const systemIntegrator = new ResumableEventReader('System', {
+    catchUpBatchSize: 200,
+    onEvent: async (event) => {
+        // Enviar eventos a SIEM, Elasticsearch, etc.
+        await sendToExternalSystem(event);
+    },
+    onError: (error) => {
+        // Implementar retry logic
+        scheduleRetry(error);
+    }
+});
+```
+
+## 🛡️ Manejo de Errores y Reintentos
+
+```javascript
+const reader = new ResumableEventReader('Application', {
+    onEvent: (event) => {
+        try {
+            processEvent(event);
+        } catch (error) {
+            console.error(`Error procesando evento ${event.recordId}:`, error);
+            // El estado aún se actualiza - el evento no se reprocesará
+        }
+    },
+    
+    onError: (error) => {
+        console.error('Error del reader:', error);
+        
+        // Implementar lógica de reconexión
+        setTimeout(() => {
+            reader.start(); // Reintentar
+        }, 5000);
+    }
+});
+```
+
+## ⚠️ Consideraciones Importantes
+
+### Permisos
+- **System, Application**: No requieren privilegios especiales
+- **Security**: Requiere ejecutar como Administrador
+
+### Rendimiento
+- Los catch-ups grandes pueden tomar tiempo
+- Ajusta `catchUpBatchSize` según tus necesidades
+- El estado se guarda cada 10 eventos para optimizar I/O
+
+### Tolerancia a Fallos
+- Si el archivo de estado se corrompe, el reader reinicia desde cero
+- Los eventos duplicados se filtran automáticamente por Record ID
+- Las suscripciones se reestablecen automáticamente en caso de error
+
+## 🧪 Testing
+
+```bash
+# Ejemplo básico
+npm run example:resumable
+
+# Test de recuperación (simula reinicio)
+npm run test:recovery
+```
+
+## 📈 Monitoreo
+
+Para monitorear la salud del reader:
+
+```javascript
+setInterval(() => {
+    const stats = reader.getStats();
+    console.log(`Eventos procesados: ${stats.totalEventsProcessed}`);
+    console.log(`Último Record ID: ${stats.lastRecordId}`);
+    console.log(`Running: ${stats.isRunning}`);
+}, 60000); // Cada minuto
+```
+
+## 🔧 Troubleshooting
+
+### "No events received"
+- Verifica permisos del canal
+- Confirma que hay actividad en el log
+- Revisa que el canal existe
+
+### "State file corruption"
+- El archivo se regenera automáticamente
+- Pérdida del progreso - reinicia desde cero
+
+### "High memory usage"
+- Reduce `catchUpBatchSize`
+- Implementa procesamiento asíncrono eficiente
+
+## 🎉 Conclusión
+
+El Resumable Event Reader proporciona una solución robusta para el procesamiento continuo de eventos de Windows con capacidades de recuperación automática, ideal para sistemas de producción que requieren alta disponibilidad y no pueden permitirse pérdida de eventos.