@wenathlan/saddle 1.8.17 → 2.0.2

package/docs/plans/14.research.proxy.md

@@ -1,1495 +0,0 @@
-# Pesquisa: Proxy Rotation e Management (2026)
-
-## Sumário
-
-1. [Pacotes de Proxy Rotation](#1-pacotes-de-proxy-rotation)
-2. [HTTP Agent Packages](#2-http-agent-packages)
-3. [Crawlee ProxyConfiguration](#3-crawlee-proxyconfiguration)
-4. [Session-Based Proxy Pinning](#4-session-based-proxy-pinning)
-5. [Protocolos Suportados](#5-protocolos-suportados)
-6. [Health Checking de Proxies](#6-health-checking-de-proxies)
-7. [Proxy Pool com Remoção Automática](#7-proxy-pool-com-remoção-automática)
-8. [Melhores Práticas](#8-melhores-práticas)
-9. [Exemplos de Implementação](#9-exemplos-de-implementação)
-
----
-
-## 1. Pacotes de Proxy Rotation
-
-### 1.1 proxy-rotator-js
-
-**Versão:** 1.3.2  
-**Descrição:** Rotação simples de proxies com suporte a múltiplos protocolos  
-**Última atualização:** 2025
-
-```javascript
-import { ProxyRotator } from 'proxy-rotator-js';
-
-const rotator = new ProxyRotator({
-  proxies: [
-    { host: 'proxy1.example.com', port: 8080, protocol: 'http' },
-    { host: 'proxy2.example.com', port: 8080, protocol: 'http' },
-    { host: 'proxy3.example.com', port: 1080, protocol: 'socks5' },
-  ],
-  strategy: 'round-robin',  // round-robin, random, least-used
-  healthCheck: true,
-  healthCheckInterval: 60000,  // 1 minuto
-  retryDelay: 5000,
-  maxRetries: 3,
-});
-
-// Obter próximo proxy
-const proxy = rotator.getNextProxy();
-console.log(proxy);
-// { host: 'proxy1.example.com', port: 8080, protocol: 'http', url: 'http://proxy1.example.com:8080' }
-
-// Marcar proxy como falho
-rotator.markFailed(proxy.host);
-
-// Obter proxy com retry automático
-const safeProxy = await rotator.getProxyWithRetry();
-```
-
-### 1.2 rezo
-
-**Versão:** 1.x  
-**Descrição:** Proxy management com health checking integrado  
-**Última atualização:** 2026
-
-```javascript
-import { ProxyManager } from 'rezo';
-
-const manager = new ProxyManager({
-  proxies: [
-    'http://user:pass@proxy1.com:8080',
-    'http://user:pass@proxy2.com:8080',
-    'socks5://user:pass@proxy3.com:1080',
-  ],
-  healthCheck: {
-    enabled: true,
-    interval: 30000,  // 30 segundos
-    timeout: 5000,
-    testUrl: 'http://httpbin.org/ip',
-  },
-  rotation: {
-    strategy: 'round-robin',
-    stickySession: false,
-  },
-});
-
-// Obter proxy saudável
-const proxy = await manager.getProxy();
-
-// Usar com fetch
-const response = await fetch('https://example.com', {
-  agent: manager.getAgent(proxy),
-});
-
-// Reportar sucesso/falha
-manager.reportSuccess(proxy);
-manager.reportFailure(proxy);
-
-// Obter estatísticas
-const stats = manager.getStats();
-console.log(stats);
-// { total: 10, healthy: 8, unhealthy: 2, avgResponseTime: 245 }
-```
-
-### 1.3 Crawlee ProxyConfiguration
-
-**Versão:** 3.x  
-**Descrição:** Proxy management integrado ao Crawlee  
-**Última atualização:** 2026
-
-```javascript
-import { ProxyConfiguration } from 'crawlee';
-
-// Lista estática de proxies
-const proxyConfiguration = new ProxyConfiguration({
-  proxyUrls: [
-    'http://user:pass@proxy1.com:8080',
-    'http://user:pass@proxy2.com:8080',
-    'socks5://user:pass@proxy3.com:1080',
-  ],
-});
-
-// Função personalizada de proxy
-const proxyConfigurationCustom = new ProxyConfiguration({
-  newUrlFunction: (sessionId) => {
-    const proxies = [
-      'http://proxy1.com:8080',
-      'http://proxy2.com:8080',
-      'http://proxy3.com:8080',
-    ];
-    const index = sessionId.charCodeAt(0) % proxies.length;
-    return proxies[index];
-  },
-});
-
-// Usar com crawler
-const crawler = new PlaywrightCrawler({
-  proxyConfiguration,
-  // ou
-  proxyConfiguration: proxyConfigurationCustom,
-});
-```
-
----
-
-## 2. HTTP Agent Packages
-
-### 2.1 https-proxy-agent
-
-**Versão:** 7.x  
-**Descrição:** HTTP/HTTPS proxy agent para Node.js  
-**Última atualização:** 2024
-
-```javascript
-import { HttpsProxyAgent } from 'https-proxy-agent';
-
-const agent = new HttpsProxyAgent('http://user:pass@proxy.example.com:8080');
-
-// Usar com fetch (Node 18+)
-const response = await fetch('https://example.com', {
-  dispatcher: agent,
-});
-
-// Usar com axios
-import axios from 'axios';
-const response = await axios.get('https://example.com', {
-  httpsAgent: agent,
-});
-
-// Usar com got
-import got from 'got';
-const response = await got('https://example.com', {
-  agent: { https: agent },
-});
-
-// Configurações avançadas
-const agentAdvanced = new HttpsProxyAgent('http://proxy.example.com:8080', {
-  auth: 'user:password',
-  headers: { 'X-Custom-Header': 'value' },
-  rejectUnauthorized: false,
-});
-```
-
-### 2.2 socks-proxy-agent
-
-**Versão:** 8.x  
-**Descrição:** SOCKS proxy agent para Node.js  
-**Última atualização:** 2024
-
-```javascript
-import { SocksProxyAgent } from 'socks-proxy-agent';
-
-// SOCKS5 proxy
-const agent5 = new SocksProxyAgent('socks5://user:pass@proxy.example.com:1080');
-
-// SOCKS4 proxy
-const agent4 = new SocksProxyAgent('socks4://proxy.example.com:1080');
-
-// SOCKS4a proxy
-const agent4a = new SocksProxyAgent('socks4a://proxy.example.com:1080');
-
-// SOCKS5h proxy (DNS via proxy)
-const agent5h = new SocksProxyAgent('socks5h://proxy.example.com:1080');
-
-// Usar com HTTPS
-import https from 'https';
-const options = {
-  agent: agent5,
-  hostname: 'example.com',
-  port: 443,
-  path: '/',
-  method: 'GET',
-};
-
-const req = https.request(options);
-req.end();
-```
-
-### 2.3 socks
-
-**Versão:** 2.8.9  
-**Descrição:** Cliente SOCKS puro para Node.js  
-**Última atualização:** 2024
-
-```javascript
-import { SocksClient } from 'socks';
-
-// Conexão SOCKS5
-const info = await SocksClient.createConnection({
-  proxy: {
-    host: 'proxy.example.com',
-    port: 1080,
-    type: 5,
-    userId: 'user',
-    password: 'pass',
-  },
-  command: 'connect',
-  destination: {
-    host: 'example.com',
-    port: 443,
-  },
-});
-
-// info.socket = socket conectado via SOCKS
-
-// Usar com TLS
-import tls from 'tls';
-const tlsSocket = tls.connect({
-  socket: info.socket,
-  servername: 'example.com',
-});
-
-// Connecção SOCKS4
-const info4 = await SocksClient.createConnection({
-  proxy: {
-    host: 'proxy.example.com',
-    port: 1080,
-    type: 4,
-  },
-  command: 'connect',
-  destination: {
-    host: '93.184.216.34',  // SOCK4 não suporta DNS
-    port: 443,
-  },
-});
-```
-
-### 2.4 proxy-chain
-
-**Versão:** 2.4.0  
-**Descrição:** Proxy chaining e roteamento avançado  
-**Última atualização:** 2023
-
-```javascript
-import { ProxyChain } from 'proxy-chain';
-
-// Criar proxy local que encaminha para proxy remoto
-const server = ProxyChain.createServer({
-  targetHost: 'proxy.example.com',
-  targetPort: 8080,
-  auth: function(url) {
-    return {
-      username: 'user',
-      password: 'pass',
-    };
-  },
-});
-
-server.listen(8000, () => {
-  console.log('Proxy local rodando na porta 8000');
-});
-
-// Usar com Playwright
-import { chromium } from 'playwright';
-const browser = await chromium.launch({
-  proxy: {
-    server: 'http://localhost:8000',
-  },
-});
-```
-
----
-
-## 3. Crawlee ProxyConfiguration
-
-### 3.1 Proxy Estático (Round-Robin)
-
-```javascript
-import { ProxyConfiguration, PlaywrightCrawler } from 'crawlee';
-
-const proxyConfiguration = new ProxyConfiguration({
-  proxyUrls: [
-    'http://user:pass@proxy1.com:8080',
-    'http://user:pass@proxy2.com:8080',
-    'http://user:pass@proxy3.com:8080',
-  ],
-});
-
-const crawler = new PlaywrightCrawler({
-  proxyConfiguration,
-  requestHandler: async ({ request, page, proxyInfo }) => {
-    console.log(`Usando proxy: ${proxyInfo.url}`);
-    await page.goto(request.url);
-    return { title: await page.title() };
-  },
-});
-
-await crawler.run(['https://example.com']);
-```
-
-**Comportamento:**
-- Rotaciona proxies em ordem (round-robin)
-- Cada request usa um proxy diferente
-- Se um proxy falhar, tenta o próximo
-- Não mantém sessão por proxy
-
-### 3.2 Função Personalizada de Proxy
-
-```javascript
-import { ProxyConfiguration, PlaywrightCrawler } from 'crawlee';
-
-const proxyConfiguration = new ProxyConfiguration({
-  newUrlFunction: (sessionId) => {
-    // Baseado no sessionId, retorna um proxy específico
-    const proxies = {
-      'session1': 'http://proxy1.com:8080',
-      'session2': 'http://proxy2.com:8080',
-      'session3': 'socks5://proxy3.com:1080',
-    };
-    return proxies[sessionId] || 'http://default-proxy.com:8080';
-  },
-});
-
-const crawler = new PlaywrightCrawler({
-  proxyConfiguration,
-  useSessionPool: true,
-  sessionOptions: {
-    maxAgeSecs: 3600,
-    maxUsageCount: 50,
-  },
-  requestHandler: async ({ request, page, session, proxyInfo }) => {
-    console.log(`Sessão: ${session.id}, Proxy: ${proxyInfo.url}`);
-    await page.goto(request.url);
-    return { title: await page.title() };
-  },
-});
-```
-
-### 3.3 Proxies em Cascata (Tiered)
-
-```javascript
-import { ProxyConfiguration, PlaywrightCrawler } from 'crawlee';
-
-// Sistema de proxies em camadas
-class TieredProxyConfiguration {
-  constructor() {
-    this.tiers = [
-      // Tier 1: Proxies residenciais (mais caros, menos bloqueio)
-      {
-        proxies: [
-          'http://residential1.com:8080',
-          'http://residential2.com:8080',
-        ],
-        priority: 1,
-        costPer1000: 15.00,
-      },
-      // Tier 2: Proxies datacenter (mais baratos, mais bloqueio)
-      {
-        proxies: [
-          'http://datacenter1.com:8080',
-          'http://datacenter2.com:8080',
-        ],
-        priority: 2,
-        costPer1000: 0.50,
-      },
-      // Tier 3: Proxies públicos (gratuitos, instáveis)
-      {
-        proxies: [
-          'http://public1.com:8080',
-          'http://public2.com:8080',
-        ],
-        priority: 3,
-        costPer1000: 0,
-      },
-    ];
-    this.currentTier = 0;
-  }
-
-  getNextProxy() {
-    const tier = this.tiers[this.currentTier];
-    const proxy = tier.proxies[Math.floor(Math.random() * tier.proxies.length)];
-    return { proxy, tier: this.currentTier };
-  }
-
-  downgradeTier() {
-    if (this.currentTier < this.tiers.length - 1) {
-      this.currentTier++;
-      console.log(`Downgrading to tier ${this.currentTier}`);
-    }
-  }
-
-  upgradeTier() {
-    if (this.currentTier > 0) {
-      this.currentTier--;
-      console.log(`Upgrading to tier ${this.currentTier}`);
-    }
-  }
-}
-
-// Usar com Crawlee
-const tieredConfig = new TieredProxyConfiguration();
-
-const crawler = new PlaywrightCrawler({
-  proxyConfiguration: new ProxyConfiguration({
-    newUrlFunction: () => tieredConfig.getNextProxy().proxy,
-  }),
-  requestHandler: async ({ request, page }) => {
-    await page.goto(request.url);
-    return { title: await page.title() };
-  },
-});
-```
-
----
-
-## 4. Session-Based Proxy Pinning
-
-### 4.1 Pinner de Sessão com Scoring
-
-```javascript
-import { SessionPool, ProxyConfiguration } from 'crawlee';
-
-class SessionProxyPinner {
-  constructor(proxies) {
-    this.proxies = proxies;
-    this.sessions = new Map();
-    this.errorScores = new Map();
-    this.maxErrorScore = 5;
-  }
-
-  getProxyForSession(sessionId) {
-    // Se já tem proxy atribuído, retorna o mesmo
-    if (this.sessions.has(sessionId)) {
-      return this.sessions.get(sessionId);
-    }
-
-    // Encontrar proxy com menor score de erro
-    const availableProxies = this.proxies
-      .filter(p => (this.errorScores.get(p) || 0) < this.maxErrorScore)
-      .sort((a, b) => (this.errorScores.get(a) || 0) - (this.errorScores.get(b) || 0));
-
-    if (availableProxies.length === 0) {
-      // Resetar scores se todos falharam
-      this.errorScores.clear();
-      return this.proxies[0];
-    }
-
-    const selectedProxy = availableProxies[0];
-    this.sessions.set(sessionId, selectedProxy);
-    return selectedProxy;
-  }
-
-  reportSuccess(sessionId) {
-    const proxy = this.sessions.get(sessionId);
-    if (proxy) {
-      this.errorScores.set(proxy, 0);
-    }
-  }
-
-  reportFailure(sessionId) {
-    const proxy = this.sessions.get(sessionId);
-    if (proxy) {
-      const currentScore = this.errorScores.get(proxy) || 0;
-      this.errorScores.set(proxy, currentScore + 1);
-    }
-  }
-
-  getStats() {
-    const stats = {
-      totalProxies: this.proxies.length,
-      healthyProxies: 0,
-      unhealthyProxies: 0,
-      activeSessions: this.sessions.size,
-    };
-
-    for (const proxy of this.proxies) {
-      const score = this.errorScores.get(proxy) || 0;
-      if (score < this.maxErrorScore) {
-        stats.healthyProxies++;
-      } else {
-        stats.unhealthyProxies++;
-      }
-    }
-
-    return stats;
-  }
-}
-
-// Usar com Crawlee
-const pinner = new SessionProxyPinner([
-  'http://proxy1.com:8080',
-  'http://proxy2.com:8080',
-  'http://proxy3.com:8080',
-]);
-
-const crawler = new PlaywrightCrawler({
-  useSessionPool: true,
-  sessionOptions: {
-    maxAgeSecs: 3600,
-    maxUsageCount: 50,
-  },
-  proxyConfiguration: new ProxyConfiguration({
-    newUrlFunction: (sessionId) => pinner.getProxyForSession(sessionId),
-  }),
-  requestHandler: async ({ request, page, session, proxyInfo }) => {
-    try {
-      await page.goto(request.url);
-      pinner.reportSuccess(session.id);
-      return { title: await page.title() };
-    } catch (error) {
-      pinner.reportFailure(session.id);
-      throw error;
-    }
-  },
-});
-```
-
-### 4.2 Sticky Sessions por Dominio
-
-```javascript
-import { SessionPool } from 'crawlee';
-
-class DomainStickyProxy {
-  constructor(proxies) {
-    this.proxies = proxies;
-    this.domainProxies = new Map();
-  }
-
-  getProxyForDomain(domain) {
-    if (this.domainProxies.has(domain)) {
-      return this.domainProxies.get(domain);
-    }
-
-    // Selecionar proxy baseado no hash do domínio
-    const hash = this.hashCode(domain);
-    const index = Math.abs(hash) % this.proxies.length;
-    const proxy = this.proxies[index];
-
-    this.domainProxies.set(domain, proxy);
-    return proxy;
-  }
-
-  hashCode(str) {
-    let hash = 0;
-    for (let i = 0; i < str.length; i++) {
-      const char = str.charCodeAt(i);
-      hash = ((hash << 5) - hash) + char;
-      hash = hash & hash; // Convert to 32bit integer
-    }
-    return hash;
-  }
-}
-
-// Usar
-const stickyProxy = new DomainStickyProxy([
-  'http://proxy1.com:8080',
-  'http://proxy2.com:8080',
-  'http://proxy3.com:8080',
-]);
-
-const crawler = new PlaywrightCrawler({
-  proxyConfiguration: new ProxyConfiguration({
-    newUrlFunction: (sessionId) => {
-      const domain = new URL(sessionId).hostname;
-      return stickyProxy.getProxyForDomain(domain);
-    },
-  }),
-});
-```
-
----
-
-## 5. Protocolos Suportados
-
-### Tabela de Protocolos
-
-| Protocolo | Porta Padrão | Autenticação | DNS Resolution | Velocidade | Segurança |
-|-----------|--------------|--------------|----------------|------------|-----------|
-| HTTP | 80/8080 | Opcional | Cliente | Rápido | Baixa |
-| HTTPS | 443/8443 | Opcional | Cliente | Rápido | Alta |
-| SOCKS4 | 1080 | Não | Cliente | Média | Baixa |
-| SOCKS4a | 1080 | Não | Proxy | Média | Baixa |
-| SOCKS5 | 1080 | Sim | Ambos | Média | Média |
-| SOCKS5h | 1080 | Sim | Proxy | Média | Média |
-
-### Detalhes por Protocolo
-
-**HTTP Proxy:**
-```
-- Mais comum e amplamente suportado
-- Não criptografa tráfego
-- Suitable para scraping básico
-- Autenticação via headers ou URL
-```
-
-**HTTPS Proxy:**
-```
-- Criptografa tráfego entre cliente e proxy
-- Suporta CONNECT method
-- Ideal para sites HTTPS
-- Mais seguro que HTTP
-```
-
-**SOCKS4:**
-```
-- Proxy de camada de transporte
-- Não suporta autenticação
-- Apenas TCP
-- Não resolve DNS (precisa de IP)
-```
-
-**SOCKS4a:**
-```
-- Extensão do SOCKS4
-- Suporta DNS resolution via proxy
-- Não suporta autenticação
-- Apenas TCP
-```
-
-**SOCKS5:**
-```
-- Proxy completo de camada de transporte
-- Suporta autenticação (user/pass)
-- Suporta TCP e UDP
-- Suporta DNS resolution
-- Mais flexível e seguro
-```
-
-**SOCKS5h:**
-```
-- SOCKS5 com DNS resolution forçada via proxy
-- Mais seguro para privacidade
-- Evita DNS leaks
-- Recomendado para scraping avançado
-```
-
-### Exemplos de Uso por Protocolo
-
-```javascript
-// HTTP
-const httpProxy = 'http://user:pass@proxy.com:8080';
-
-// HTTPS
-const httpsProxy = 'https://user:pass@proxy.com:8443';
-
-// SOCKS4
-const socks4Proxy = 'socks4://proxy.com:1080';
-
-// SOCKS4a
-const socks4aProxy = 'socks4a://proxy.com:1080';
-
-// SOCKS5
-const socks5Proxy = 'socks5://user:pass@proxy.com:1080';
-
-// SOCKS5h
-const socks5hProxy = 'socks5h://user:pass@proxy.com:1080';
-
-// Usar com Playwright
-import { chromium } from 'playwright';
-
-const browser = await chromium.launch({
-  proxy: {
-    server: socks5Proxy,
-    username: 'user',
-    password: 'pass',
-  },
-});
-```
-
----
-
-## 6. Health Checking de Proxies
-
-### 6.1 Health Checking Ativo (Pre-Use)
-
-```javascript
-class ActiveHealthChecker {
-  constructor(proxies, options = {}) {
-    this.proxies = proxies;
-    this.testUrl = options.testUrl || 'http://httpbin.org/ip';
-    this.timeout = options.timeout || 5000;
-    this.retries = options.retries || 2;
-    this.results = new Map();
-  }
-
-  async checkProxy(proxy) {
-    const startTime = Date.now();
-    
-    for (let i = 0; i < this.retries; i++) {
-      try {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-
-        const response = await fetch(this.testUrl, {
-          signal: controller.signal,
-          dispatcher: this.getAgent(proxy),
-        });
-
-        clearTimeout(timeoutId);
-
-        const endTime = Date.now();
-        const responseTime = endTime - startTime;
-
-        this.results.set(proxy, {
-          healthy: true,
-          responseTime,
-          lastChecked: new Date(),
-          status: response.status,
-        });
-
-        return { healthy: true, responseTime };
-      } catch (error) {
-        if (i === this.retries - 1) {
-          this.results.set(proxy, {
-            healthy: false,
-            error: error.message,
-            lastChecked: new Date(),
-          });
-          return { healthy: false, error: error.message };
-        }
-      }
-    }
-  }
-
-  getAgent(proxy) {
-    if (proxy.startsWith('socks')) {
-      const { SocksProxyAgent } = require('socks-proxy-agent');
-      return new SocksProxyAgent(proxy);
-    } else {
-      const { HttpsProxyAgent } = require('https-proxy-agent');
-      return new HttpsProxyAgent(proxy);
-    }
-  }
-
-  async checkAll() {
-    const results = await Promise.allSettled(
-      this.proxies.map(proxy => this.checkProxy(proxy))
-    );
-
-    return results.map((result, index) => ({
-      proxy: this.proxies[index],
-      ...result.value,
-    }));
-  }
-
-  getHealthyProxies() {
-    return this.proxies.filter(proxy => {
-      const result = this.results.get(proxy);
-      return result && result.healthy;
-    });
-  }
-
-  getUnhealthyProxies() {
-    return this.proxies.filter(proxy => {
-      const result = this.results.get(proxy);
-      return result && !result.healthy;
-    });
-  }
-}
-
-// Uso
-const checker = new ActiveHealthChecker([
-  'http://proxy1.com:8080',
-  'http://proxy2.com:8080',
-  'socks5://proxy3.com:1080',
-], {
-  testUrl: 'http://httpbin.org/ip',
-  timeout: 5000,
-  retries: 2,
-});
-
-const results = await checker.checkAll();
-console.log('Healthy proxies:', checker.getHealthyProxies());
-```
-
-### 6.2 Health Checking Passivo (Runtime)
-
-```javascript
-class PassiveHealthChecker {
-  constructor(options = {}) {
-    this.failureThreshold = options.failureThreshold || 3;
-    this.recoveryTime = options.recoveryTime || 300000; // 5 minutos
-    this.stats = new Map();
-  }
-
-  reportSuccess(proxy) {
-    const stat = this.stats.get(proxy) || {
-      successes: 0,
-      failures: 0,
-      lastFailure: null,
-      isHealthy: true,
-    };
-
-    stat.successes++;
-    stat.isHealthy = true;
-    this.stats.set(proxy, stat);
-  }
-
-  reportFailure(proxy) {
-    const stat = this.stats.get(proxy) || {
-      successes: 0,
-      failures: 0,
-      lastFailure: null,
-      isHealthy: true,
-    };
-
-    stat.failures++;
-    stat.lastFailure = Date.now();
-
-    if (stat.failures >= this.failureThreshold) {
-      stat.isHealthy = false;
-    }
-
-    this.stats.set(proxy, stat);
-  }
-
-  isHealthy(proxy) {
-    const stat = this.stats.get(proxy);
-    if (!stat) return true;
-
-    if (!stat.isHealthy) {
-      // Verificar se já passou tempo de recuperação
-      if (Date.now() - stat.lastFailure > this.recoveryTime) {
-        stat.isHealthy = true;
-        stat.failures = 0;
-        this.stats.set(proxy, stat);
-        return true;
-      }
-      return false;
-    }
-
-    return true;
-  }
-
-  getStats() {
-    const stats = {
-      total: 0,
-      healthy: 0,
-      unhealthy: 0,
-      details: [],
-    };
-
-    for (const [proxy, stat] of this.stats) {
-      stats.total++;
-      if (stat.isHealthy) {
-        stats.healthy++;
-      } else {
-        stats.unhealthy++;
-      }
-      stats.details.push({ proxy, ...stat });
-    }
-
-    return stats;
-  }
-}
-
-// Usar com Crawlee
-const passiveChecker = new PassiveHealthChecker({
-  failureThreshold: 3,
-  recoveryTime: 300000,
-});
-
-const crawler = new PlaywrightCrawler({
-  requestHandler: async ({ request, page, session }) => {
-    try {
-      await page.goto(request.url);
-      passiveChecker.reportSuccess(session.id);
-      return { title: await page.title() };
-    } catch (error) {
-      passiveChecker.reportFailure(session.id);
-      throw error;
-    }
-  },
-});
-```
-
-### 6.3 Health Checking Integrado (rezo)
-
-```javascript
-import { ProxyManager } from 'rezo';
-
-const manager = new ProxyManager({
-  proxies: [
-    'http://proxy1.com:8080',
-    'http://proxy2.com:8080',
-    'socks5://proxy3.com:1080',
-  ],
-  healthCheck: {
-    enabled: true,
-    interval: 30000,  // Verificar a cada 30 segundos
-    timeout: 5000,
-    testUrl: 'http://httpbin.org/ip',
-    retries: 2,
-  },
-});
-
-// O manager automaticamente:
-// 1. Verifica saúde dos proxies periodicamente
-// 2. Remove proxies não saudáveis do pool
-// 3. Tenta recuperar proxies após timeout
-// 4. Reporta estatísticas
-
-const proxy = await manager.getProxy(); // Sempre retorna proxy saudável
-```
-
----
-
-## 7. Proxy Pool com Remoção Automática
-
-### 7.1 Sistema de Cemetery (Graveyard)
-
-```javascript
-class ProxyPool {
-  constructor(proxies, options = {}) {
-    this.proxies = new Map();
-    this.graveyard = new Map();
-    this.maxFailures = options.maxFailures || 3;
-    this.reviveTimer = options.reviveTimer || 300000; // 5 minutos
-    this.currentIndex = 0;
-
-    // Inicializar proxies
-    for (const proxy of proxies) {
-      this.proxies.set(proxy, {
-        failures: 0,
-        successes: 0,
-        lastUsed: null,
-        lastError: null,
-        status: 'healthy',
-      });
-    }
-  }
-
-  getNextProxy() {
-    const healthyProxies = Array.from(this.proxies.entries())
-      .filter(([_, stat]) => stat.status === 'healthy');
-
-    if (healthyProxies.length === 0) {
-      // Tentar reviver proxies do graveyard
-      this.reviveProxies();
-      
-      // Se ainda não há proxies saudáveis, usar qualquer um
-      const allProxies = Array.from(this.proxies.entries());
-      if (allProxies.length === 0) {
-        throw new Error('No proxies available');
-      }
-      
-      return allProxies[this.currentIndex % allProxies.length][0];
-    }
-
-    const proxy = healthyProxies[this.currentIndex % healthyProxies.length][0];
-    this.currentIndex++;
-    
-    const stat = this.proxies.get(proxy);
-    stat.lastUsed = Date.now();
-    
-    return proxy;
-  }
-
-  reportSuccess(proxy) {
-    const stat = this.proxies.get(proxy);
-    if (stat) {
-      stat.successes++;
-      stat.failures = Math.max(0, stat.failures - 1); // Reduzir falhas
-    }
-  }
-
-  reportFailure(proxy, error) {
-    const stat = this.proxies.get(proxy);
-    if (stat) {
-      stat.failures++;
-      stat.lastError = error;
-
-      if (stat.failures >= this.maxFailures) {
-        this.buryProxy(proxy);
-      }
-    }
-  }
-
-  buryProxy(proxy) {
-    const stat = this.proxies.get(proxy);
-    if (stat) {
-      stat.status = 'dead';
-      this.graveyard.set(proxy, {
-        ...stat,
-        buriedAt: Date.now(),
-      });
-      this.proxies.delete(proxy);
-      console.log(`Proxy buried: ${proxy}`);
-    }
-  }
-
-  reviveProxies() {
-    const now = Date.now();
-    
-    for (const [proxy, stat] of this.graveyard) {
-      if (now - stat.buriedAt >= this.reviveTimer) {
-        // Reviver proxy com contadores resetados
-        this.proxies.set(proxy, {
-          failures: 0,
-          successes: 0,
-          lastUsed: null,
-          lastError: null,
-          status: 'healthy',
-        });
-        this.graveyard.delete(proxy);
-        console.log(`Proxy revived: ${proxy}`);
-      }
-    }
-  }
-
-  getStats() {
-    return {
-      healthy: Array.from(this.proxies.values()).filter(s => s.status === 'healthy').length,
-      dead: this.graveyard.size,
-      total: this.proxies.size + this.graveyard.size,
-      details: {
-        proxies: Object.fromEntries(this.proxies),
-        graveyard: Object.fromEntries(this.graveyard),
-      },
-    };
-  }
-}
-
-// Usar com Crawlee
-const pool = new ProxyPool([
-  'http://proxy1.com:8080',
-  'http://proxy2.com:8080',
-  'socks5://proxy3.com:1080',
-], {
-  maxFailures: 3,
-  reviveTimer: 300000,
-});
-
-const crawler = new PlaywrightCrawler({
-  proxyConfiguration: new ProxyConfiguration({
-    newUrlFunction: () => pool.getNextProxy(),
-  }),
-  requestHandler: async ({ request, page, proxyInfo }) => {
-    try {
-      await page.goto(request.url);
-      pool.reportSuccess(proxyInfo.url);
-      return { title: await page.title() };
-    } catch (error) {
-      pool.reportFailure(proxyInfo.url, error.message);
-      throw error;
-    }
-  },
-});
-```
-
-### 7.2 Integração com Crawlee
-
-```javascript
-import { PlaywrightCrawler, ProxyConfiguration } from 'crawlee';
-
-class CrawleeProxyPool {
-  constructor(proxies, options = {}) {
-    this.pool = new ProxyPool(proxies, options);
-    this.proxyConfiguration = new ProxyConfiguration({
-      newUrlFunction: () => this.pool.getNextProxy(),
-    });
-  }
-
-  getCrawlerOptions() {
-    return {
-      proxyConfiguration: this.proxyConfiguration,
-      requestHandler: async ({ request, page, proxyInfo }) => {
-        try {
-          await page.goto(request.url);
-          this.pool.reportSuccess(proxyInfo.url);
-          return { title: await page.title() };
-        } catch (error) {
-          this.pool.reportFailure(proxyInfo.url, error.message);
-          throw error;
-        }
-      },
-    };
-  }
-
-  getStats() {
-    return this.pool.getStats();
-  }
-}
-
-// Uso
-const crawlerPool = new CrawleeProxyPool([
-  'http://proxy1.com:8080',
-  'http://proxy2.com:8080',
-  'socks5://proxy3.com:1080',
-], {
-  maxFailures: 3,
-  reviveTimer: 300000,
-});
-
-const crawler = new PlaywrightCrawler(crawlerPool.getCrawlerOptions());
-await crawler.run(['https://example.com']);
-
-console.log(crawlerPool.getStats());
-```
-
----
-
-## 8. Melhores Práticas
-
-### 8.1 Correspondência Tipo de Proxy ↔ Target
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Tipo de Target                            │
-├─────────────────────────────────────────────────────────────┤
-│ Site Básico → HTTP/HTTPS Proxy (datacenter)                │
-│ Site Médio → HTTPS Proxy (residential)                     │
-│ Site Avançado → SOCKS5 Proxy (residential)                 │
-│ Site Premium → Mobile Proxy (4G/5G)                        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Recomendações por tipo de target:**
-
-| Target | Tipo Proxy | Localização | Velocidade | Custo |
-|--------|------------|-------------|------------|-------|
-| Sites governamentais | Residencial | País específico | Média | Alto |
-| E-commerce | Residencial/Mobile | País do target | Média | Alto |
-| Redes sociais | Mobile (4G) | País do target | Baixa | Muito Alto |
-| APIs públicas | Datacenter | Qualquer | Alta | Baixo |
-| Sites de notícias | Residencial | País do target | Média | Médio |
-
-### 8.2 Rotação Inteligente vs Cega
-
-**Rotação cega (NÃO fazer):**
-```javascript
-// NÃO: Rotacionar proxy a cada request
-const proxy = proxies[requestCount % proxies.length];
-```
-
-**Rotação inteligente (FAZER):**
-```javascript
-// SIM: Rotacionar baseado em contexto
-const getSmartProxy = (target, session) => {
-  // 1. Manter mesma sessão para requests relacionados
-  if (session && session.proxy) {
-    return session.proxy;
-  }
-
-  // 2. Usar proxy do mesmo país do target
-  const targetCountry = getCountryFromDomain(target);
-  const countryProxies = proxies.filter(p => p.country === targetCountry);
-
-  // 3. Selecionar proxy menos usado
-  return selectLeastUsedProxy(countryProxies);
-};
-```
-
-### 8.3 Monitorar e Reagir
-
-```javascript
-class ProxyMonitor {
-  constructor(pool) {
-    this.pool = pool;
-    this.alerts = [];
-    this.thresholds = {
-      failureRate: 0.3,  // 30% de falhas
-      avgResponseTime: 5000,  // 5 segundos
-    };
-  }
-
-  async monitor() {
-    setInterval(() => {
-      const stats = this.pool.getStats();
-      
-      // Verificar taxa de falha
-      const failureRate = stats.failures / (stats.successes + stats.failures);
-      if (failureRate > this.thresholds.failureRate) {
-        this.alert('High failure rate detected', {
-          failureRate,
-          threshold: this.thresholds.failureRate,
-        });
-      }
-
-      // Verificar tempo de resposta
-      if (stats.avgResponseTime > this.thresholds.avgResponseTime) {
-        this.alert('High response time detected', {
-          responseTime: stats.avgResponseTime,
-          threshold: this.thresholds.avgResponseTime,
-        });
-      }
-    }, 60000); // Verificar a cada minuto
-  }
-
-  alert(message, data) {
-    console.error(`[PROXY ALERT] ${message}`, data);
-    this.alerts.push({ message, data, timestamp: new Date() });
-  }
-}
-```
-
-### 8.4 Combinar com Rotação de Fingerprint
-
-```javascript
-import { PlaywrightCrawler, ProxyConfiguration } from 'crawlee';
-
-class FingerprintProxyRotator {
-  constructor(proxies) {
-    this.proxies = proxies;
-    this.fingerprintProxyMap = new Map();
-  }
-
-  getProxyForFingerprint(fingerprint) {
-    // Mapear fingerprint para proxy específico
-    if (!this.fingerprintProxyMap.has(fingerprint)) {
-      const proxy = this.proxies[this.fingerprintProxyMap.size % this.proxies.length];
-      this.fingerprintProxyMap.set(fingerprint, proxy);
-    }
-    return this.fingerprintProxyMap.get(fingerprint);
-  }
-}
-
-// Usar com Crawlee
-const rotator = new FingerprintProxyRotator(proxies);
-
-const crawler = new PlaywrightCrawler({
-  browserPoolOptions: {
-    useFingerprints: true,
-  },
-  proxyConfiguration: new ProxyConfiguration({
-    newUrlFunction: (sessionId) => {
-      // sessionId contém informação do fingerprint
-      return rotator.getProxyForFingerprint(sessionId);
-    },
-  }),
-});
-```
-
----
-
-## 9. Exemplos de Implementação
-
-### 9.1 Exemplo Completo: Proxy Pool com Health Checking
-
-```javascript
-import { PlaywrightCrawler, ProxyConfiguration } from 'crawlee';
-import { HttpsProxyAgent } from 'https-proxy-agent';
-import { SocksProxyAgent } from 'socks-proxy-agent';
-
-class ProductionProxyPool {
-  constructor(proxies, options = {}) {
-    this.proxies = new Map();
-    this.graveyard = new Map();
-    this.maxFailures = options.maxFailures || 3;
-    this.reviveTimer = options.reviveTimer || 300000;
-    this.healthCheckInterval = options.healthCheckInterval || 60000;
-    this.currentIndex = 0;
-
-    // Inicializar proxies
-    for (const proxy of proxies) {
-      this.proxies.set(proxy, {
-        failures: 0,
-        successes: 0,
-        lastUsed: null,
-        lastError: null,
-        status: 'healthy',
-        responseTime: 0,
-      });
-    }
-
-    // Iniciar health check periódico
-    this.startHealthCheck();
-  }
-
-  startHealthCheck() {
-    setInterval(() => this.performHealthCheck(), this.healthCheckInterval);
-  }
-
-  async performHealthCheck() {
-    console.log('Performing health check...');
-    
-    for (const [proxy, stat] of this.proxies) {
-      if (stat.status !== 'healthy') continue;
-
-      try {
-        const agent = this.createAgent(proxy);
-        const startTime = Date.now();
-        
-        await fetch('http://httpbin.org/ip', {
-          signal: AbortSignal.timeout(5000),
-          dispatcher: agent,
-        });
-
-        const responseTime = Date.now() - startTime;
-        stat.responseTime = responseTime;
-        stat.status = 'healthy';
-      } catch (error) {
-        stat.failures++;
-        if (stat.failures >= this.maxFailures) {
-          stat.status = 'dead';
-          this.graveyard.set(proxy, { ...stat, buriedAt: Date.now() });
-          this.proxies.delete(proxy);
-          console.log(`Proxy buried: ${proxy}`);
-        }
-      }
-    }
-
-    // Reviver proxies
-    this.reviveProxies();
-  }
-
-  createAgent(proxy) {
-    if (proxy.startsWith('socks')) {
-      return new SocksProxyAgent(proxy);
-    }
-    return new HttpsProxyAgent(proxy);
-  }
-
-  reviveProxies() {
-    const now = Date.now();
-    for (const [proxy, stat] of this.graveyard) {
-      if (now - stat.buriedAt >= this.reviveTimer) {
-        this.proxies.set(proxy, {
-          failures: 0,
-          successes: 0,
-          lastUsed: null,
-          lastError: null,
-          status: 'healthy',
-          responseTime: 0,
-        });
-        this.graveyard.delete(proxy);
-        console.log(`Proxy revived: ${proxy}`);
-      }
-    }
-  }
-
-  getNextProxy() {
-    const healthyProxies = Array.from(this.proxies.entries())
-      .filter(([_, stat]) => stat.status === 'healthy')
-      .sort((a, b) => a[1].responseTime - b[1].responseTime);
-
-    if (healthyProxies.length === 0) {
-      throw new Error('No healthy proxies available');
-    }
-
-    const proxy = healthyProxies[0][0];
-    const stat = this.proxies.get(proxy);
-    stat.lastUsed = Date.now();
-    
-    return proxy;
-  }
-
-  reportSuccess(proxy) {
-    const stat = this.proxies.get(proxy);
-    if (stat) {
-      stat.successes++;
-      stat.failures = Math.max(0, stat.failures - 1);
-    }
-  }
-
-  reportFailure(proxy, error) {
-    const stat = this.proxies.get(proxy);
-    if (stat) {
-      stat.failures++;
-      stat.lastError = error;
-      if (stat.failures >= this.maxFailures) {
-        stat.status = 'dead';
-        this.graveyard.set(proxy, { ...stat, buriedAt: Date.now() });
-        this.proxies.delete(proxy);
-      }
-    }
-  }
-
-  getStats() {
-    const healthy = Array.from(this.proxies.values()).filter(s => s.status === 'healthy').length;
-    return {
-      healthy,
-      dead: this.graveyard.size,
-      total: this.proxies.size + this.graveyard.size,
-    };
-  }
-}
-
-// Uso principal
-const pool = new ProductionProxyPool([
-  'http://user:pass@proxy1.com:8080',
-  'http://user:pass@proxy2.com:8080',
-  'socks5://user:pass@proxy3.com:1080',
-], {
-  maxFailures: 3,
-  reviveTimer: 300000,
-  healthCheckInterval: 60000,
-});
-
-const crawler = new PlaywrightCrawler({
-  proxyConfiguration: new ProxyConfiguration({
-    newUrlFunction: () => pool.getNextProxy(),
-  }),
-  requestHandler: async ({ request, page, proxyInfo }) => {
-    try {
-      await page.goto(request.url, { timeout: 30000 });
-      pool.reportSuccess(proxyInfo.url);
-      return { url: request.url, title: await page.title() };
-    } catch (error) {
-      pool.reportFailure(proxyInfo.url, error.message);
-      throw error;
-    }
-  },
-  maxConcurrency: 5,
-  retryOnBlocked: true,
-});
-
-await crawler.run(['https://example.com']);
-console.log('Pool stats:', pool.getStats());
-```
-
-### 9.2 Exemplo: Session-Based Proxy com Crawlee
-
-```javascript
-import { PlaywrightCrawler, SessionPool, ProxyConfiguration } from 'crawlee';
-
-class SessionProxyManager {
-  constructor(proxies) {
-    this.proxies = proxies;
-    this.sessionProxies = new Map();
-  }
-
-  getProxyForSession(sessionId) {
-    if (!this.sessionProxies.has(sessionId)) {
-      const proxy = this.proxies[this.sessionProxies.size % this.proxies.length];
-      this.sessionProxies.set(sessionId, proxy);
-    }
-    return this.sessionProxies.get(sessionId);
-  }
-}
-
-const manager = new SessionProxyManager([
-  'http://proxy1.com:8080',
-  'http://proxy2.com:8080',
-  'http://proxy3.com:8080',
-]);
-
-const crawler = new PlaywrightCrawler({
-  useSessionPool: true,
-  sessionOptions: {
-    maxAgeSecs: 3600,
-    maxUsageCount: 50,
-  },
-  proxyConfiguration: new ProxyConfiguration({
-    newUrlFunction: (sessionId) => manager.getProxyForSession(sessionId),
-  }),
-  requestHandler: async ({ request, page, session }) => {
-    console.log(`Session: ${session.id}, Proxy: ${manager.getProxyForSession(session.id)}`);
-    
-    await page.goto(request.url);
-    const title = await page.title();
-    
-    session.retireOnBlocked(); // Retirar sessão se bloqueada
-    
-    return { url: request.url, title, sessionId: session.id };
-  },
-});
-
-await crawler.run(['https://example.com']);
-```
-
----
-
-## Referências
-
-1. Crawlee ProxyConfiguration - https://crawlee.dev/docs/api/proxy-configuration
-2. https-proxy-agent - https://github.com/TooTallNate/node-https-proxy-agent
-3. socks-proxy-agent - https://github.com/TooTallNate/node-socks-proxy-agent
-4. socks - https://github.com/JoshGlazebrook/socks
-5. proxy-chain - https://github.com/apify/proxy-chain
-6. rezo - https://github.com/rezo-proxy/manager
-7. proxy-rotator-js - https://github.com/nicedoc/proxy-rotator