@saulwade/swl-ses 1.4.1 → 1.5.0

package/hooks/lib/rate-limit-tracker.js

@@ -1,253 +1,253 @@
-'use strict';
-
-/**
- * Rate Limit Tracker — Awareness de límites de tasa per-provider.
- *
- * Patrón adoptado de Hermes Agent (agent/rate_limit_tracker.py).
- * Registra respuestas 429 y headers de rate limit para ajustar
- * timing de llamadas y prevenir cascadas de error.
- *
- * Zero dependencias externas.
- *
- * Uso:
- *   const { tracker } = require('./lib/rate-limit-tracker');
- *
- *   // Registrar un 429
- *   tracker.registrar429('anthropic', { retryAfter: 30, modelo: 'claude-sonnet-4-6' });
- *
- *   // Consultar antes de llamar
- *   if (tracker.estaThrottled('anthropic')) {
- *     const espera = tracker.tiempoEspera('anthropic');
- *     console.log(`Provider throttled, esperar ${espera}s`);
- *   }
- *
- *   // Registrar éxito (resetea contadores)
- *   tracker.registrarExito('anthropic');
- *
- * @module hooks/lib/rate-limit-tracker
- */
-
-// ---------------------------------------------------------------------------
-// Constantes
-// ---------------------------------------------------------------------------
-
-/** Máximo de 429s consecutivos antes de marcar provider como BLOQUEADO. */
-const MAX_429_CONSECUTIVOS = 5;
-
-/** Tiempo base de backoff en ms tras un 429 (si no hay Retry-After). */
-const BACKOFF_BASE_MS = 10_000;
-
-/** Multiplicador de backoff exponencial por 429 consecutivo. */
-const BACKOFF_MULTIPLICADOR = 2;
-
-/** Tiempo máximo de backoff en ms (5 minutos). */
-const BACKOFF_MAX_MS = 300_000;
-
-/** Tiempo de recuperación half-open en ms (1 minuto). */
-const HALF_OPEN_MS = 60_000;
-
-/** Tiempo para considerar un registro como stale y limpiar (30 minutos). */
-const STALE_MS = 1_800_000;
-
-// ---------------------------------------------------------------------------
-// Estado del tracker (en memoria, por sesión)
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {object} ProviderState
- * @property {number} consecutivos429   - Conteo de 429s consecutivos
- * @property {number} ultimoTimestamp    - Timestamp del último 429
- * @property {number} esperaHastaMs     - Timestamp hasta el cual esperar
- * @property {string} estado            - 'ok' | 'throttled' | 'bloqueado' | 'half-open'
- * @property {string|null} modelo       - Último modelo que causó 429
- * @property {number} totalHistorico    - Total de 429s en la sesión
- */
-
-/** @type {Map<string, ProviderState>} */
-const _providers = new Map();
-
-// ---------------------------------------------------------------------------
-// Funciones internas
-// ---------------------------------------------------------------------------
-
-/**
- * Obtiene o crea el estado de un provider.
- * @param {string} provider
- * @returns {ProviderState}
- */
-function _obtenerEstado(provider) {
-  if (!_providers.has(provider)) {
-    _providers.set(provider, {
-      consecutivos429: 0,
-      ultimoTimestamp: 0,
-      esperaHastaMs: 0,
-      estado: 'ok',
-      modelo: null,
-      totalHistorico: 0,
-    });
-  }
-  return _providers.get(provider);
-}
-
-/**
- * Calcula el delay de backoff para un número de 429s consecutivos.
- * @param {number} consecutivos
- * @param {number|null} retryAfterSeg - Valor de Retry-After del header (en segundos)
- * @returns {number} Delay en milisegundos
- */
-function _calcularBackoff(consecutivos, retryAfterSeg) {
-  if (retryAfterSeg && retryAfterSeg > 0) {
-    return retryAfterSeg * 1000;
-  }
-  const delay = BACKOFF_BASE_MS * Math.pow(BACKOFF_MULTIPLICADOR, consecutivos - 1);
-  return Math.min(delay, BACKOFF_MAX_MS);
-}
-
-// ---------------------------------------------------------------------------
-// API pública
-// ---------------------------------------------------------------------------
-
-const tracker = {
-  /**
-   * Registra una respuesta 429 de un provider.
-   *
-   * @param {string} provider - Nombre del provider ('anthropic', 'openai', etc.)
-   * @param {object} [info]
-   * @param {number} [info.retryAfter]  - Valor del header Retry-After en segundos
-   * @param {string} [info.modelo]      - Modelo que causó el 429
-   */
-  registrar429(provider, info = {}) {
-    const estado = _obtenerEstado(provider);
-    const ahora = Date.now();
-
-    estado.consecutivos429 += 1;
-    estado.ultimoTimestamp = ahora;
-    estado.totalHistorico += 1;
-    estado.modelo = info.modelo || estado.modelo;
-
-    const backoff = _calcularBackoff(estado.consecutivos429, info.retryAfter);
-    estado.esperaHastaMs = ahora + backoff;
-
-    if (estado.consecutivos429 >= MAX_429_CONSECUTIVOS) {
-      estado.estado = 'bloqueado';
-    } else {
-      estado.estado = 'throttled';
-    }
-  },
-
-  /**
-   * Registra una llamada exitosa — resetea contadores del provider.
-   *
-   * @param {string} provider
-   */
-  registrarExito(provider) {
-    const estado = _obtenerEstado(provider);
-    estado.consecutivos429 = 0;
-    estado.esperaHastaMs = 0;
-    estado.estado = 'ok';
-  },
-
-  /**
-   * Verifica si un provider está throttled o bloqueado.
-   *
-   * @param {string} provider
-   * @returns {boolean}
-   */
-  estaThrottled(provider) {
-    const estado = _obtenerEstado(provider);
-    const ahora = Date.now();
-
-    if (estado.estado === 'ok') return false;
-
-    // Verificar si ya pasó el tiempo de espera
-    if (ahora >= estado.esperaHastaMs) {
-      if (estado.estado === 'bloqueado') {
-        // Transición a half-open para permitir un intento de prueba
-        estado.estado = 'half-open';
-        estado.esperaHastaMs = ahora + HALF_OPEN_MS;
-        return false; // permitir un intento
-      }
-      // Throttled normal — ya pasó el backoff
-      estado.estado = 'ok';
-      estado.consecutivos429 = 0;
-      return false;
-    }
-
-    return true;
-  },
-
-  /**
-   * Retorna el tiempo de espera restante en segundos.
-   *
-   * @param {string} provider
-   * @returns {number} Segundos restantes (0 si no está throttled)
-   */
-  tiempoEspera(provider) {
-    const estado = _obtenerEstado(provider);
-    const restante = estado.esperaHastaMs - Date.now();
-    return restante > 0 ? Math.ceil(restante / 1000) : 0;
-  },
-
-  /**
-   * Retorna el estado completo de un provider.
-   *
-   * @param {string} provider
-   * @returns {ProviderState}
-   */
-  estado(provider) {
-    return { ..._obtenerEstado(provider) };
-  },
-
-  /**
-   * Retorna resumen de todos los providers trackeados.
-   *
-   * @returns {Array<{ provider: string, estado: string, consecutivos429: number, totalHistorico: number, tiempoEspera: number }>}
-   */
-  resumen() {
-    const resultado = [];
-    for (const [provider, estado] of _providers) {
-      resultado.push({
-        provider,
-        estado: estado.estado,
-        consecutivos429: estado.consecutivos429,
-        totalHistorico: estado.totalHistorico,
-        tiempoEspera: tracker.tiempoEspera(provider),
-        modelo: estado.modelo,
-      });
-    }
-    return resultado;
-  },
-
-  /**
-   * Limpia registros stale (sin actividad reciente).
-   * Llamar periódicamente para evitar memory leak en sesiones largas.
-   */
-  limpiarStale() {
-    const ahora = Date.now();
-    for (const [provider, estado] of _providers) {
-      if (estado.estado === 'ok' && (ahora - estado.ultimoTimestamp) > STALE_MS) {
-        _providers.delete(provider);
-      }
-    }
-  },
-
-  /**
-   * Resetea todo el tracker (útil para tests).
-   */
-  reset() {
-    _providers.clear();
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-module.exports = {
-  tracker,
-  // Exponer constantes para tests
-  MAX_429_CONSECUTIVOS,
-  BACKOFF_BASE_MS,
-  BACKOFF_MAX_MS,
-  HALF_OPEN_MS,
-};
+'use strict';
+
+/**
+ * Rate Limit Tracker — Awareness de límites de tasa per-provider.
+ *
+ * Patrón adoptado de Hermes Agent (agent/rate_limit_tracker.py).
+ * Registra respuestas 429 y headers de rate limit para ajustar
+ * timing de llamadas y prevenir cascadas de error.
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { tracker } = require('./lib/rate-limit-tracker');
+ *
+ *   // Registrar un 429
+ *   tracker.registrar429('anthropic', { retryAfter: 30, modelo: 'claude-sonnet-4-6' });
+ *
+ *   // Consultar antes de llamar
+ *   if (tracker.estaThrottled('anthropic')) {
+ *     const espera = tracker.tiempoEspera('anthropic');
+ *     console.log(`Provider throttled, esperar ${espera}s`);
+ *   }
+ *
+ *   // Registrar éxito (resetea contadores)
+ *   tracker.registrarExito('anthropic');
+ *
+ * @module hooks/lib/rate-limit-tracker
+ */
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Máximo de 429s consecutivos antes de marcar provider como BLOQUEADO. */
+const MAX_429_CONSECUTIVOS = 5;
+
+/** Tiempo base de backoff en ms tras un 429 (si no hay Retry-After). */
+const BACKOFF_BASE_MS = 10_000;
+
+/** Multiplicador de backoff exponencial por 429 consecutivo. */
+const BACKOFF_MULTIPLICADOR = 2;
+
+/** Tiempo máximo de backoff en ms (5 minutos). */
+const BACKOFF_MAX_MS = 300_000;
+
+/** Tiempo de recuperación half-open en ms (1 minuto). */
+const HALF_OPEN_MS = 60_000;
+
+/** Tiempo para considerar un registro como stale y limpiar (30 minutos). */
+const STALE_MS = 1_800_000;
+
+// ---------------------------------------------------------------------------
+// Estado del tracker (en memoria, por sesión)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} ProviderState
+ * @property {number} consecutivos429   - Conteo de 429s consecutivos
+ * @property {number} ultimoTimestamp    - Timestamp del último 429
+ * @property {number} esperaHastaMs     - Timestamp hasta el cual esperar
+ * @property {string} estado            - 'ok' | 'throttled' | 'bloqueado' | 'half-open'
+ * @property {string|null} modelo       - Último modelo que causó 429
+ * @property {number} totalHistorico    - Total de 429s en la sesión
+ */
+
+/** @type {Map<string, ProviderState>} */
+const _providers = new Map();
+
+// ---------------------------------------------------------------------------
+// Funciones internas
+// ---------------------------------------------------------------------------
+
+/**
+ * Obtiene o crea el estado de un provider.
+ * @param {string} provider
+ * @returns {ProviderState}
+ */
+function _obtenerEstado(provider) {
+  if (!_providers.has(provider)) {
+    _providers.set(provider, {
+      consecutivos429: 0,
+      ultimoTimestamp: 0,
+      esperaHastaMs: 0,
+      estado: 'ok',
+      modelo: null,
+      totalHistorico: 0,
+    });
+  }
+  return _providers.get(provider);
+}
+
+/**
+ * Calcula el delay de backoff para un número de 429s consecutivos.
+ * @param {number} consecutivos
+ * @param {number|null} retryAfterSeg - Valor de Retry-After del header (en segundos)
+ * @returns {number} Delay en milisegundos
+ */
+function _calcularBackoff(consecutivos, retryAfterSeg) {
+  if (retryAfterSeg && retryAfterSeg > 0) {
+    return retryAfterSeg * 1000;
+  }
+  const delay = BACKOFF_BASE_MS * Math.pow(BACKOFF_MULTIPLICADOR, consecutivos - 1);
+  return Math.min(delay, BACKOFF_MAX_MS);
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+const tracker = {
+  /**
+   * Registra una respuesta 429 de un provider.
+   *
+   * @param {string} provider - Nombre del provider ('anthropic', 'openai', etc.)
+   * @param {object} [info]
+   * @param {number} [info.retryAfter]  - Valor del header Retry-After en segundos
+   * @param {string} [info.modelo]      - Modelo que causó el 429
+   */
+  registrar429(provider, info = {}) {
+    const estado = _obtenerEstado(provider);
+    const ahora = Date.now();
+
+    estado.consecutivos429 += 1;
+    estado.ultimoTimestamp = ahora;
+    estado.totalHistorico += 1;
+    estado.modelo = info.modelo || estado.modelo;
+
+    const backoff = _calcularBackoff(estado.consecutivos429, info.retryAfter);
+    estado.esperaHastaMs = ahora + backoff;
+
+    if (estado.consecutivos429 >= MAX_429_CONSECUTIVOS) {
+      estado.estado = 'bloqueado';
+    } else {
+      estado.estado = 'throttled';
+    }
+  },
+
+  /**
+   * Registra una llamada exitosa — resetea contadores del provider.
+   *
+   * @param {string} provider
+   */
+  registrarExito(provider) {
+    const estado = _obtenerEstado(provider);
+    estado.consecutivos429 = 0;
+    estado.esperaHastaMs = 0;
+    estado.estado = 'ok';
+  },
+
+  /**
+   * Verifica si un provider está throttled o bloqueado.
+   *
+   * @param {string} provider
+   * @returns {boolean}
+   */
+  estaThrottled(provider) {
+    const estado = _obtenerEstado(provider);
+    const ahora = Date.now();
+
+    if (estado.estado === 'ok') return false;
+
+    // Verificar si ya pasó el tiempo de espera
+    if (ahora >= estado.esperaHastaMs) {
+      if (estado.estado === 'bloqueado') {
+        // Transición a half-open para permitir un intento de prueba
+        estado.estado = 'half-open';
+        estado.esperaHastaMs = ahora + HALF_OPEN_MS;
+        return false; // permitir un intento
+      }
+      // Throttled normal — ya pasó el backoff
+      estado.estado = 'ok';
+      estado.consecutivos429 = 0;
+      return false;
+    }
+
+    return true;
+  },
+
+  /**
+   * Retorna el tiempo de espera restante en segundos.
+   *
+   * @param {string} provider
+   * @returns {number} Segundos restantes (0 si no está throttled)
+   */
+  tiempoEspera(provider) {
+    const estado = _obtenerEstado(provider);
+    const restante = estado.esperaHastaMs - Date.now();
+    return restante > 0 ? Math.ceil(restante / 1000) : 0;
+  },
+
+  /**
+   * Retorna el estado completo de un provider.
+   *
+   * @param {string} provider
+   * @returns {ProviderState}
+   */
+  estado(provider) {
+    return { ..._obtenerEstado(provider) };
+  },
+
+  /**
+   * Retorna resumen de todos los providers trackeados.
+   *
+   * @returns {Array<{ provider: string, estado: string, consecutivos429: number, totalHistorico: number, tiempoEspera: number }>}
+   */
+  resumen() {
+    const resultado = [];
+    for (const [provider, estado] of _providers) {
+      resultado.push({
+        provider,
+        estado: estado.estado,
+        consecutivos429: estado.consecutivos429,
+        totalHistorico: estado.totalHistorico,
+        tiempoEspera: tracker.tiempoEspera(provider),
+        modelo: estado.modelo,
+      });
+    }
+    return resultado;
+  },
+
+  /**
+   * Limpia registros stale (sin actividad reciente).
+   * Llamar periódicamente para evitar memory leak en sesiones largas.
+   */
+  limpiarStale() {
+    const ahora = Date.now();
+    for (const [provider, estado] of _providers) {
+      if (estado.estado === 'ok' && (ahora - estado.ultimoTimestamp) > STALE_MS) {
+        _providers.delete(provider);
+      }
+    }
+  },
+
+  /**
+   * Resetea todo el tracker (útil para tests).
+   */
+  reset() {
+    _providers.clear();
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  tracker,
+  // Exponer constantes para tests
+  MAX_429_CONSECUTIVOS,
+  BACKOFF_BASE_MS,
+  BACKOFF_MAX_MS,
+  HALF_OPEN_MS,
+};