@arela/uploader 1.0.23 → 1.1.0

package/docs/WATCHER_API_IMPLEMENTATION.md

@@ -0,0 +1,520 @@
+# Archivo de Ejemplo: watcher.routes.js para arela-api
+
+**Ubicación:** `arela-api/src/routes/watcher.routes.js`
+
+Este archivo contiene la implementación completa de los endpoints REST para exposer el WatchService.
+
+```javascript
+import express from 'express';
+import logger from '../services/LoggingService.js';
+
+const router = express.Router();
+
+/**
+ * Inicializar rutas del watcher
+ * Requiere que watchService esté disponible en el contexto de la app
+ * @param {Object} watchService - Instancia de WatchService desde arela-uploader
+ */
+export function initWatcherRoutes(app, watchService) {
+  /**
+   * GET /api/watcher/status
+   * Obtener estado actual del watcher
+   * 
+   * @returns {Object} Estado del watcher incluyendo estadísticas
+   */
+  router.get('/status', (req, res) => {
+    try {
+      const stats = watchService.getStats();
+      
+      res.json({
+        isRunning: stats.isRunning,
+        autoProcessingEnabled: stats.autoProcessingEnabled,
+        watchedDirectories: stats.watchedDirectories,
+        activeWatchers: stats.activeWatchers,
+        allWatchersReady: watchService.allWatchersReady,
+        lastUpdated: new Date().toISOString(),
+        stats: {
+          filesAdded: stats.filesAdded,
+          filesModified: stats.filesModified,
+          filesRemoved: stats.filesRemoved,
+          uploadsTriggered: stats.uploadsTriggered,
+          pipelinesTriggered: stats.pipelinesTriggered,
+          errorsEncountered: stats.errorsEncountered,
+        },
+      });
+    } catch (error) {
+      logger.error(`Error getting watcher status: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to get watcher status',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * GET /api/watcher/queue-stats
+   * Obtener estadísticas de la cola de procesamiento
+   * 
+   * @returns {Object} Estadísticas de la cola y progreso
+   */
+  router.get('/queue-stats', async (req, res) => {
+    try {
+      const queueStats = await watchService.getQueueStats();
+      
+      if (!queueStats) {
+        return res.status(500).json({
+          error: 'Could not fetch queue stats',
+        });
+      }
+
+      res.json({
+        queue: queueStats.queue,
+        progress: queueStats.progress,
+        timestamp: queueStats.timestamp,
+        metadata: {
+          totalCapacity: queueStats.queue.total,
+          utilization:
+            ((queueStats.queue.total - queueStats.queue.pending) /
+              queueStats.queue.total) *
+            100,
+        },
+      });
+    } catch (error) {
+      logger.error(`Error getting queue stats: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to get queue stats',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * GET /api/watcher/directories
+   * Obtener lista de directorios monitoreados
+   * 
+   * @returns {Object} Lista de directorios con detalles
+   */
+  router.get('/directories', (req, res) => {
+    try {
+      const directories = Array.from(watchService.watchedDirs).map((dir) => {
+        const config = watchService.directoryConfigs.get(dir);
+        const isReady = watchService.watcherReady.get(dir) === true;
+
+        return {
+          path: dir,
+          isReady,
+          folderStructure: config?.folderStructure || 'default',
+          config: {
+            ignored: config?.ignored || 'hidden files, node_modules, .git',
+            awaitWriteFinish: config?.awaitWriteFinish || {
+              stabilityThreshold: 300,
+              pollInterval: 100,
+            },
+          },
+        };
+      });
+
+      res.json({
+        directories,
+        totalDirectories: directories.length,
+        readyCount: directories.filter((d) => d.isReady).length,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.error(`Error getting watched directories: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to get watched directories',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * POST /api/watcher/start
+   * Iniciar el watcher con directorios específicos
+   * 
+   * @param {string[]} directories - Array de rutas a monitorear
+   * @param {boolean} autoProcessing - Habilitar procesamiento automático
+   * @param {string} folderStructure - Estructura de carpetas (arela, custom, etc)
+   * @returns {Object} Estado después de iniciar
+   */
+  router.post('/start', async (req, res) => {
+    try {
+      const {
+        directories,
+        autoProcessing = true,
+        folderStructure = 'arela',
+      } = req.body;
+
+      // Validación
+      if (!directories || !Array.isArray(directories) || directories.length === 0) {
+        return res.status(400).json({
+          error: 'Invalid request',
+          details: 'directories must be a non-empty array of strings',
+        });
+      }
+
+      // Validar que sean rutas válidas
+      const invalidPaths = directories.filter(
+        (dir) => typeof dir !== 'string' || dir.trim().length === 0
+      );
+
+      if (invalidPaths.length > 0) {
+        return res.status(400).json({
+          error: 'Invalid paths provided',
+          details: `${invalidPaths.length} invalid path(s)`,
+        });
+      }
+
+      logger.info(`[API] Starting watcher for ${directories.length} directories`);
+
+      // Agregar watchers para cada directorio
+      for (const dir of directories) {
+        await watchService.addWatcher(
+          dir,
+          {},
+          { folderStructure: folderStructure || 'arela' }
+        );
+      }
+
+      // Habilitar procesamiento automático si se solicita
+      if (autoProcessing) {
+        watchService.enableAutoProcessing({ batchSize: 10 });
+      }
+
+      // Iniciar watchers
+      await watchService.start();
+
+      // Esperar a que todos los watchers estén listos
+      await watchService.waitForWatchersReady();
+
+      res.json({
+        success: true,
+        message: 'Watcher started successfully',
+        stats: watchService.getStats(),
+        directoryCount: directories.length,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.error(`Error starting watcher: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to start watcher',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * POST /api/watcher/stop
+   * Detener el watcher
+   * 
+   * @returns {Object} Estadísticas finales
+   */
+  router.post('/stop', async (req, res) => {
+    try {
+      logger.info('[API] Stopping watcher');
+
+      const finalStats = watchService.getStats();
+      await watchService.stop('API request');
+
+      res.json({
+        success: true,
+        message: 'Watcher stopped successfully',
+        finalStats,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.error(`Error stopping watcher: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to stop watcher',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * POST /api/watcher/enable-auto-processing
+   * Habilitar procesamiento automático
+   * 
+   * @param {number} batchSize - Tamaño de lote para procesamiento
+   * @returns {Object} Estado actualizado
+   */
+  router.post('/enable-auto-processing', (req, res) => {
+    try {
+      const { batchSize = 10 } = req.body;
+
+      if (typeof batchSize !== 'number' || batchSize < 1) {
+        return res.status(400).json({
+          error: 'Invalid batchSize',
+          details: 'batchSize must be a positive number',
+        });
+      }
+
+      logger.info(`[API] Enabling auto-processing with batchSize=${batchSize}`);
+
+      watchService.enableAutoProcessing({ batchSize });
+
+      res.json({
+        success: true,
+        message: 'Auto-processing enabled',
+        autoProcessingEnabled: watchService.isAutoProcessingEnabled(),
+        batchSize,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.error(`Error enabling auto-processing: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to enable auto-processing',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * POST /api/watcher/disable-auto-processing
+   * Deshabilitar procesamiento automático
+   * 
+   * @returns {Object} Estado actualizado
+   */
+  router.post('/disable-auto-processing', (req, res) => {
+    try {
+      logger.info('[API] Disabling auto-processing');
+
+      watchService.disableAutoProcessing();
+
+      res.json({
+        success: true,
+        message: 'Auto-processing disabled',
+        autoProcessingEnabled: watchService.isAutoProcessingEnabled(),
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.error(`Error disabling auto-processing: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to disable auto-processing',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * GET /api/watcher/pipeline-status
+   * Obtener estado de pipelines en ejecución y recientes
+   * 
+   * @returns {Object} Estado de pipelines y recientes
+   */
+  router.get('/pipeline-status', (req, res) => {
+    try {
+      const stats = watchService.getStats();
+
+      res.json({
+        isProcessing: stats.pipelinesTriggered > 0,
+        activePipelines: 0, // Valor placeholder - actualizar si se mantiene historial
+        recentPipelines: {
+          total: stats.pipelinesTriggered,
+          successful: stats.pipelinesTriggered - stats.errorsEncountered,
+          failed: stats.errorsEncountered,
+        },
+        errorStats: {
+          totalErrors: stats.errorsEncountered,
+          lastError: null, // Obtener de errorTracker si es necesario
+        },
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.error(`Error getting pipeline status: ${error.message}`);
+      res.status(500).json({
+        error: 'Failed to get pipeline status',
+        details: error.message,
+      });
+    }
+  });
+
+  /**
+   * GET /api/watcher/health
+   * Health check del watcher
+   * 
+   * @returns {Object} Estado de salud
+   */
+  router.get('/health', (req, res) => {
+    try {
+      const stats = watchService.getStats();
+
+      const health = {
+        status: stats.isRunning ? 'healthy' : 'stopped',
+        isRunning: stats.isRunning,
+        activeWatchers: stats.activeWatchers,
+        errors: stats.errorsEncountered,
+        uptime: stats.isRunning ? 'tracking' : 'not running',
+        timestamp: new Date().toISOString(),
+      };
+
+      const statusCode = stats.isRunning && stats.errorsEncountered === 0 ? 200 : 503;
+      res.status(statusCode).json(health);
+    } catch (error) {
+      res.status(500).json({
+        status: 'error',
+        error: error.message,
+      });
+    }
+  });
+
+  // Montar el router en la app
+  app.use('/api/watcher', router);
+  
+  logger.info('✅ Watcher API routes initialized');
+}
+
+export default router;
+```
+
+---
+
+## 📋 Integración en app.js
+
+```javascript
+// app.js (o main.js, index.js)
+
+import express from 'express';
+import { initWatcherRoutes } from './routes/watcher.routes.js';
+import watchService from '@arela/uploader/services'; // O importar directamente
+
+const app = express();
+
+// Middleware
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// ... otras rutas ...
+
+// Inicializar rutas del watcher
+initWatcherRoutes(app, watchService);
+
+// Error handling
+app.use((err, req, res, next) => {
+  console.error(err);
+  res.status(500).json({
+    error: 'Internal server error',
+    message: err.message,
+  });
+});
+
+// Iniciar servidor
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`🚀 Server running on port ${PORT}`);
+});
+
+export default app;
+```
+
+---
+
+## 🧪 Ejemplo de uso desde el frontend
+
+```javascript
+// hooks/useWatcherMonitor.js
+import { useState, useEffect, useCallback } from 'react';
+
+export const useWatcherMonitor = (pollInterval = 5000) => {
+  const [status, setStatus] = useState(null);
+  const [queue, setQueue] = useState(null);
+  const [directories, setDirectories] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  // Refrescar datos
+  const refresh = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      const [statusRes, queueRes, dirRes] = await Promise.all([
+        fetch('/api/watcher/status'),
+        fetch('/api/watcher/queue-stats'),
+        fetch('/api/watcher/directories'),
+      ]);
+
+      if (!statusRes.ok || !queueRes.ok || !dirRes.ok) {
+        throw new Error('Failed to fetch watcher data');
+      }
+
+      setStatus(await statusRes.json());
+      setQueue(await queueRes.json());
+      setDirectories(await dirRes.json());
+    } catch (err) {
+      setError(err.message);
+      console.error('Error fetching watcher data:', err);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  // Poll automático
+  useEffect(() => {
+    refresh(); // Fetch inicial
+
+    const interval = setInterval(refresh, pollInterval);
+    return () => clearInterval(interval);
+  }, [pollInterval, refresh]);
+
+  // Acciones
+  const startWatcher = useCallback(
+    async (dirs) => {
+      const res = await fetch('/api/watcher/start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          directories: dirs,
+          autoProcessing: true,
+        }),
+      });
+      if (!res.ok) throw new Error('Failed to start watcher');
+      await refresh();
+      return res.json();
+    },
+    [refresh]
+  );
+
+  const stopWatcher = useCallback(async () => {
+    const res = await fetch('/api/watcher/stop', { method: 'POST' });
+    if (!res.ok) throw new Error('Failed to stop watcher');
+    await refresh();
+    return res.json();
+  }, [refresh]);
+
+  const enableAutoProcessing = useCallback(async () => {
+    const res = await fetch('/api/watcher/enable-auto-processing', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ batchSize: 10 }),
+    });
+    if (!res.ok) throw new Error('Failed to enable auto-processing');
+    await refresh();
+    return res.json();
+  }, [refresh]);
+
+  return {
+    status,
+    queue,
+    directories,
+    loading,
+    error,
+    refresh,
+    startWatcher,
+    stopWatcher,
+    enableAutoProcessing,
+  };
+};
+```
+
+---
+
+## 📌 Resumen de cambios necesarios en arela-api
+
+1. ✅ Crear `routes/watcher.routes.js` (archivo completo arriba)
+2. ✅ Importar en `app.js` o `index.js`
+3. ✅ Asegurar que WatchService de arela-uploader esté disponible
+4. ✅ Agregar autenticación si es necesario
+5. ✅ Documentar endpoints en Swagger/OpenAPI
+