bgustscraper 0.2.0

Advanced semantic scraping engine with AI-driven compliance checks and legal terms validation
Documentation
# Método de Scraping 3: Bypass TLS y Evasión Anti-Bot (Cloudscraper) 📡

Los sistemas modernos de seguridad perimetral (como Cloudflare, Akamai, Imperva) utilizan **perfilado pasivo de TLS (huellas JA3/JA4)** para detectar si una petición HTTP proviene de una biblioteca de desarrollo (como `curl`, `reqwest`, o `axios` estándar) o de un navegador web legítimo. Si detecta un cliente sospechoso, bloquea la conexión antes de servir el HTML. Para contrarrestar esto, `bgustscraper` cuenta con el motor de **Bypass TLS**.

---

## ⚙️ Principio de Funcionamiento

Cuando el motor principal de Playwright es bloqueado (por ejemplo, al retornar un código HTTP de error o un HTML que contiene el reto anti-bot de Cloudflare), el orquestador Rust activa la transición rápida al **Motor 2 (Bypass TLS)**:

1. **Destrucción de Instancia Bloqueada:** Libera la memoria de Playwright cerrando el Chromium bloqueado.
2. **Negociación de Firmas TLS (Fingerprinting Spoofing):**
   * El subproceso utiliza la biblioteca `cloudscraper` en Node.js.
   * Modifica la configuración de sockets y la negociación SSL/TLS a bajo nivel.
   * Envía un saludo TLS (*Client Hello*) con cifrados y extensiones idénticos a los de navegadores comerciales reales (como Google Chrome o Mozilla Firefox).
3. **Resolución de Retos de JavaScript en Caliente:**
   * Si la página sirve un reto básico de JS de Cloudflare, `cloudscraper` ejecuta de forma aislada y veloz la expresión matemática del reto en el motor de V8.
   * Retorna las cookies autorizadas de la sesión.
4. **Entrega de HTML Limpio:** Descarga y sirve el HTML limpio al motor central en milisegundos.

---

## 🛠️ Código y Archivos Relacionados

* **Implementación en Node.js:** [worker/index.js]file:///home/august/code/bgust-nlp-ecosystem/bgustscraper/worker/index.js (e integración con librerías nativas de HTTP en JS).
* **Controlador en Rust:** [src/main.rs]file:///home/august/code/bgust-nlp-ecosystem/bgustscraper/src/main.rs
  * Código de recuperación ante fallos en líneas 202-207:
    ```rust
    if resp.status == "error" || resp.html.as_ref().map_or(true, |h| h.contains("cf-challenge") || h.contains("Checking your browser")) {
        pb.set_message("🔄 Playwright bloqueado. Intentando Motor 2 (Cloudscraper)...");
        worker.exit()?;
        worker = PlaywrightWorker::new(true, ScrapingEngine::Cloudscraper)?;
        resp = worker.scrape(&url, None)?;
    }
    ```

---

## ⚡ Flujo de Entrada y Salida

* **Entrada:**
  * URL bloqueada y cabeceras deseadas.
* **Salida:**
  * Estructura JSON con el HTML limpio evadiendo la protección perimetral del sitio web.

---

## ⚖️ Ventajas y Desventajas

### Ventajas:
* **Evasión de Firewalls de Red:** Supera con creces las restricciones que bloquean las llamadas clásicas de `reqwest`/`axios`.
* **Rendimiento Exponencial:** Al operar a nivel HTTP sin renderizar estilos, imágenes ni frames de navegador, consume hasta **10 veces menos memoria RAM** y se ejecuta hasta **8 veces más rápido** que Playwright.
* **Consumo de CPU Prácticamente Nulo:** Ideal para raspados de alta frecuencia en servidores ligeros de bajos recursos.

### Desventajas:
* **Sin Soporte de SPA:** Solo captura el HTML inicial enviado por el servidor. Si el contenido de interés se genera mediante React/Vue después de cargar la página, este motor no lo capturará.
* **No Resuelve CAPTCHAs Complejos:** Los retos visuales interactivos de hCaptcha o reCAPTCHA v3 requieren la simulación visual interactiva de Playwright (con intervención manual si aplica).