@saulwade/swl-ses 1.3.7 → 1.4.0

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

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * rate-limit-ip.js — Token bucket per-IP para webhook entrante.
+ *
+ * Implementa rate limiting con algoritmo de token bucket por dirección IP:
+ *
+ *   - Cada IP recibe un bucket de capacidad `capacidad` (default = rpm).
+ *   - El bucket se rellena a razón de `rpm/60` tokens por segundo.
+ *   - Cada request consume 1 token. Si no hay tokens, rechazo.
+ *   - Burst handling: hasta `capacidad` requests instantáneos antes del
+ *     refill, lo que permite picos legítimos (ej: GitHub push con muchos
+ *     events en segundos).
+ *
+ * El reloj se inyecta vía parámetro `ahora` (ms epoch) para tests
+ * deterministas. Sin parámetro, usa `Date.now()`.
+ *
+ * Origen: port reducido de `temp/claude-code-telegram-main/src/security/rate_limiter.py`
+ * (294 LOC Python → ~150 LOC JS, eliminando cost-based limiting y locks
+ * asíncronos que no aplican a un servidor HTTP síncrono en Node).
+ *
+ * Zero-deps (sólo módulos nativos).
+ *
+ * @module hooks/lib/rate-limit-ip
+ */
+
+const INTERVALO_LIMPIEZA_MS = 5 * 60 * 1000;  // 5 minutos
+
+/**
+ * Bucket individual de tokens. No es thread-safe (Node es single-threaded).
+ */
+class RateLimitBucket {
+  /**
+   * @param {number} capacidad Tokens máximos (también valor inicial).
+   * @param {number} refillRate Tokens por segundo.
+   * @param {number} ahora Timestamp en ms (Date.now()).
+   */
+  constructor(capacidad, refillRate, ahora) {
+    if (!Number.isFinite(capacidad) || capacidad <= 0) {
+      throw new Error('rate-limit-ip: capacidad debe ser número positivo');
+    }
+    if (!Number.isFinite(refillRate) || refillRate <= 0) {
+      throw new Error('rate-limit-ip: refillRate debe ser número positivo');
+    }
+    this.capacidad = capacidad;
+    this.tokens = capacidad;
+    this.refillRate = refillRate;
+    this.ultimaActualizacion = ahora;
+  }
+
+  /**
+   * Intenta consumir tokens.
+   * @param {number} tokens Cantidad a consumir (default 1).
+   * @param {number} ahora Timestamp en ms.
+   * @returns {boolean} true si se consumieron; false si no había suficientes.
+   */
+  consumir(tokens, ahora) {
+    this._rellenar(ahora);
+    if (this.tokens >= tokens) {
+      this.tokens -= tokens;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Rellena tokens según el tiempo transcurrido desde la última actualización.
+   * @param {number} ahora Timestamp en ms.
+   */
+  _rellenar(ahora) {
+    const transcurridoSeg = Math.max(0, (ahora - this.ultimaActualizacion) / 1000);
+    this.tokens = Math.min(this.capacidad, this.tokens + transcurridoSeg * this.refillRate);
+    this.ultimaActualizacion = ahora;
+  }
+
+  /**
+   * Estado actual del bucket (para diagnostics).
+   * @param {number} ahora Timestamp en ms.
+   * @returns {{capacidad: number, tokens: number, refillRate: number}}
+   */
+  estado(ahora) {
+    this._rellenar(ahora);
+    return {
+      capacidad: this.capacidad,
+      tokens: this.tokens,
+      refillRate: this.refillRate,
+    };
+  }
+}
+
+/**
+ * Limitador per-IP con cleanup periódico de buckets inactivos.
+ */
+class RateLimiterIP {
+  /**
+   * @param {object} opciones
+   * @param {number} [opciones.rpm=60] Requests permitidos por minuto.
+   * @param {number} [opciones.capacidad] Burst máximo (default = rpm).
+   * @param {number} [opciones.intervaloLimpiezaMs=300000] Cada cuánto eliminar buckets llenos.
+   */
+  constructor({ rpm = 60, capacidad = null, intervaloLimpiezaMs = INTERVALO_LIMPIEZA_MS } = {}) {
+    if (!Number.isFinite(rpm) || rpm <= 0) {
+      throw new Error('rate-limit-ip: rpm debe ser número positivo');
+    }
+    this.rpm = rpm;
+    this.capacidad = capacidad ?? rpm;
+    this.refillRate = rpm / 60;  // tokens por segundo
+    this.intervaloLimpiezaMs = intervaloLimpiezaMs;
+    this.buckets = new Map();
+    this.ultimaLimpieza = 0;
+  }
+
+  /**
+   * Decide si una IP puede hacer la siguiente request.
+   * @param {string} ip Dirección IP del cliente.
+   * @param {number} [ahora=Date.now()] Timestamp en ms.
+   * @returns {boolean} true si la request está permitida; false si throttled.
+   */
+  permite(ip, ahora) {
+    if (typeof ahora !== 'number') ahora = Date.now();
+    if (!ip || typeof ip !== 'string') return false;
+
+    let bucket = this.buckets.get(ip);
+    if (!bucket) {
+      bucket = new RateLimitBucket(this.capacidad, this.refillRate, ahora);
+      this.buckets.set(ip, bucket);
+    }
+    const permitido = bucket.consumir(1, ahora);
+    this._limpiarSiCorresponde(ahora);
+    return permitido;
+  }
+
+  /**
+   * Estado de una IP específica (sin consumir token).
+   * @param {string} ip
+   * @param {number} [ahora=Date.now()]
+   * @returns {{capacidad: number, tokens: number, refillRate: number}}
+   */
+  estado(ip, ahora) {
+    if (typeof ahora !== 'number') ahora = Date.now();
+    const bucket = this.buckets.get(ip);
+    if (!bucket) {
+      return { capacidad: this.capacidad, tokens: this.capacidad, refillRate: this.refillRate };
+    }
+    return bucket.estado(ahora);
+  }
+
+  /**
+   * Elimina buckets que tienen tokens al máximo (IPs que no usaron su cuota).
+   * Previene crecimiento ilimitado del Map en servidores de larga duración.
+   * @param {number} ahora
+   */
+  _limpiarSiCorresponde(ahora) {
+    if (ahora - this.ultimaLimpieza < this.intervaloLimpiezaMs) return;
+    this.ultimaLimpieza = ahora;
+    for (const [ip, bucket] of this.buckets) {
+      bucket._rellenar(ahora);
+      if (bucket.tokens >= bucket.capacidad) {
+        this.buckets.delete(ip);
+      }
+    }
+  }
+
+  /**
+   * Tamaño actual del Map (para diagnostics y tests).
+   * @returns {number}
+   */
+  tamano() {
+    return this.buckets.size;
+  }
+}
+
+module.exports = {
+  RateLimitBucket,
+  RateLimiterIP,
+  INTERVALO_LIMPIEZA_MS,
+};

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,
+};