# Proxy Scraping Service

Sistema completo de scraping, validação e armazenamento de proxies anônimos em PostgreSQL. O serviço roda automaticamente uma vez ao dia, coletando proxies de múltiplas fontes, validando sua funcionalidade e anonimato, e armazenando apenas proxies ativos e anônimos no banco de dados.

## Características

- **Scraping Multi-Fonte**: Suporta scraping de múltiplas URLs listadas em arquivo de configuração
- **Suporte a Conteúdo Dinâmico**: Utiliza Selenium para sites com JavaScript e paginação
- **Validação Robusta**: Testa conectividade e verifica anonimato de cada proxy antes de armazenar
- **Filtro de Anonimato**: Armazena APENAS proxies anônimos (sem vazamento de IP real)
- **Prevenção de Duplicatas**: Valida existência antes de inserir no banco
- **Agendamento Inteligente**: Executa automaticamente entre 2h-4h da madrugada (horário configurável)
- **Containerizado**: Deploy completo com Docker e Docker Compose
- **Banco PostgreSQL**: Schema otimizado com índices e constraints
- **Logging Estruturado**: Logs coloridos e níveis configuráveis
- **Health Checks**: Monitoramento de saúde dos containers

## Arquitetura

```
proxy/
├── src/
│   ├── main.py           # Serviço principal e orquestração
│   ├── config.py         # Gerenciamento de configurações
│   ├── database.py       # Operações PostgreSQL
│   ├── validator.py      # Validação de proxies
│   └── scrapers.py       # Scrapers para múltiplas fontes
├── root/
│   └── proxy/
│       └── proxies.txt   # Lista de URLs para scraping
├── Dockerfile            # Build do container Python
├── docker-compose.yml    # Orquestração de serviços
├── init-db.sql          # Inicialização do banco
├── requirements.txt      # Dependências Python
├── .env.example         # Exemplo de variáveis de ambiente
└── README.md            # Esta documentação
```

## Tecnologias Utilizadas

### Core

- **Python 3.11**: Linguagem principal
- **PostgreSQL 16**: Banco de dados
- **Docker & Docker Compose**: Containerização

### Bibliotecas Python

- **psycopg2**: Driver PostgreSQL
- **requests**: HTTP client para scraping e validação
- **BeautifulSoup4**: Parsing HTML
- **Selenium**: Scraping de conteúdo dinâmico
- **APScheduler**: Agendamento de tarefas
- **pydantic**: Validação de configurações
- **colorlog**: Logging estruturado

## Instalação e Deploy

### Pré-requisitos

- Docker 20.10+
- Docker Compose 2.0+
- 2GB RAM livre
- Conexão com internet

### Deploy Rápido

1. **Clone ou baixe o projeto**:

```bash
git clone
```

2. **Configure as variáveis de ambiente**:

```bash
cp .env.example .env
```

Edite o arquivo `.env` e configure suas credenciais:

```bash
nano .env
```

Mínimo necessário:

```env
POSTGRES_PASSWORD=your_secure_password_here
```

3. **Verifique o arquivo de URLs**:

```bash
cat root/proxy/proxies.txt
```

Adicione ou remova URLs conforme necessário. O arquivo já vem com fontes pré-configuradas.

4. **Execute o serviço**:

```bash
docker-compose up -d
```

5. **Acompanhe os logs**:

```bash
docker-compose logs -f proxy-scraper
```

## Configuração

### Variáveis de Ambiente

Todas as configurações podem ser ajustadas via arquivo `.env`:

#### PostgreSQL

```env
POSTGRES_HOST=postgres          # Host do banco (padrão: postgres)
POSTGRES_PORT=5432              # Porta do banco
POSTGRES_DB=proxies             # Nome do database
POSTGRES_USER=postgres          # Usuário do banco
POSTGRES_PASSWORD=postgres      # Senha (ALTERAR EM PRODUÇÃO)
```

#### Validação de Proxies

```env
PROXY_TIMEOUT=10                # Timeout em segundos para teste
VALIDATION_URL=http://httpbin.org/ip  # URL para validação
```

#### Scraping

```env
SCRAPING_DELAY=2.0              # Delay entre requisições (segundos)
MAX_RETRIES=3                   # Tentativas em caso de erro
```

#### Agendamento

```env
SCHEDULE_HOUR_START=2           # Hora inicial (UTC)
SCHEDULE_HOUR_END=4             # Hora final (UTC)
```

O serviço executará automaticamente uma vez ao dia em um horário aleatório entre `SCHEDULE_HOUR_START` e `SCHEDULE_HOUR_END`.

#### Logging

```env
LOG_LEVEL=INFO                  # Níveis: DEBUG, INFO, WARNING, ERROR
```

### Arquivo de URLs (proxies.txt)

O arquivo `root/proxy/proxies.txt` contém as URLs para scraping:

```txt
# Comentários começam com #
https://www.proxy-list.download/api/v1/get?type=http
https://api.proxyscrape.com/v2/?request=get&protocol=http

# Sites com Selenium (paginação)
https://www.freeproxy.world/?type=http&anonymity=4
https://free-proxy-list.net/
```

**Formato**:

- Uma URL por linha
- Linhas começando com `#` são ignoradas
- URLs vazias são ignoradas

## Uso

### Comandos Docker Compose

**Iniciar todos os serviços**:

```bash
docker-compose up -d
```

**Iniciar com pgAdmin (gerenciamento do banco)**:

```bash
docker-compose --profile admin up -d
```

**Ver logs em tempo real**:

```bash
docker-compose logs -f proxy-scraper
```

**Parar serviços**:

```bash
docker-compose down
```

**Parar e remover volumes (limpar banco)**:

```bash
docker-compose down -v
```

**Reconstruir imagens**:

```bash
docker-compose build --no-cache
docker-compose up -d
```

### Executar Scraping Imediato

Para executar o scraping imediatamente (sem esperar o agendamento):

```bash
docker-compose exec proxy-scraper python src/main.py --immediate
```

### Acessar pgAdmin (opcional)

Se iniciou com o profile `admin`:

1. Acesse: http://localhost:5050
2. Login: `admin@admin.com` / `admin` (configurável no .env)
3. Adicione servidor:
   - Host: `postgres`
   - Port: `5432`
   - Database: `proxies`
   - Username: seu `POSTGRES_USER`
   - Password: seu `POSTGRES_PASSWORD`

## Schema do Banco de Dados

### Tabela `proxies`

```sql
CREATE TABLE proxies (
    id SERIAL PRIMARY KEY,
    ip_address INET NOT NULL,
    port INTEGER NOT NULL CHECK (port > 0 AND port <= 65535),
    protocol VARCHAR(10) NOT NULL CHECK (protocol IN ('HTTP', 'HTTPS', 'SOCKS4', 'SOCKS5')),
    username VARCHAR(255),
    password VARCHAR(255),
    country_code CHAR(2),
    country_name VARCHAR(100),
    city VARCHAR(100),
    is_active BOOLEAN DEFAULT TRUE,
    is_anonymous BOOLEAN DEFAULT FALSE,
    response_time_ms INTEGER,
    last_checked_at TIMESTAMP WITH TIME ZONE,
    last_successful_at TIMESTAMP WITH TIME ZONE,
    failure_count INTEGER DEFAULT 0,
    success_count INTEGER DEFAULT 0,
    usage INTEGER DEFAULT 0,
    source VARCHAR(255),
    notes TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT unique_proxy UNIQUE (ip_address, port, protocol)
);
```

### Consultas Úteis

**Listar todos os proxies ativos e anônimos**:

```sql
SELECT ip_address, port, protocol, country_name, response_time_ms
FROM proxies
WHERE is_active = TRUE AND is_anonymous = TRUE
ORDER BY response_time_ms ASC;
```

**Estatísticas gerais**:

```sql
SELECT
    COUNT(*) as total,
    COUNT(*) FILTER (WHERE is_active = TRUE) as active,
    COUNT(*) FILTER (WHERE is_anonymous = TRUE) as anonymous,
    COUNT(DISTINCT country_code) as countries,
    AVG(response_time_ms) as avg_response_time
FROM proxies;
```

**Proxies por país**:

```sql
SELECT country_name, COUNT(*) as total
FROM proxies
WHERE is_active = TRUE AND is_anonymous = TRUE
GROUP BY country_name
ORDER BY total DESC;
```

**Proxies mais rápidos**:

```sql
SELECT ip_address, port, protocol, response_time_ms, country_name
FROM proxies
WHERE is_active = TRUE AND is_anonymous = TRUE
ORDER BY response_time_ms ASC
LIMIT 10;
```

## Funcionamento do Sistema

### Fluxo de Execução

1. **Agendamento**: Serviço aguarda horário programado (2h-4h UTC por padrão)
2. **Scraping**: Lê URLs do `proxies.txt` e processa uma por vez
3. **Parsing**: Extrai informações de proxy (IP, porta, protocolo)
4. **Deduplicação**: Remove duplicatas da lista scraped
5. **Validação**: Testa cada proxy para:
   - Conectividade (timeout de 10s)
   - Anonimato (verifica vazamento de IP real)
6. **Filtragem**: Mantém APENAS proxies anônimos
7. **Armazenamento**: Insere no PostgreSQL (ignora duplicatas)
8. **Estatísticas**: Exibe métricas do processamento

### Validação de Anonimato

O sistema verifica anonimato através de:

1. **Headers HTTP**: Detecta headers que revelam IP real:

   - `X-Forwarded-For`
   - `X-Real-IP`
   - `Via`
   - `Forwarded`

2. **Análise de Response**: Valida o IP retornado pela URL de teste

3. **Critério Conservador**: Em caso de dúvida, o proxy é marcado como não-anônimo

### Tipos de Scraper

**GenericHTMLScraper**:

- Para sites estáticos
- Parsing com BeautifulSoup
- Extrai de tabelas HTML ou texto
- Rápido e eficiente

**SeleniumScraper**:

- Para sites dinâmicos (JavaScript)
- Suporta paginação automática
- Sites como freeproxy.world
- Mais lento mas completo

## Monitoramento

### Logs

O sistema gera logs estruturados e coloridos:

```
2025-11-21 02:15:30 - INFO - Starting proxy scraping job
2025-11-21 02:15:31 - INFO - Scraped 150 proxies from sources
2025-11-21 02:15:45 - INFO - 45 proxies validated successfully
2025-11-21 02:15:46 - INFO - Inserted 38 new anonymous proxies
```

**Níveis de log**:

- **DEBUG**: Informações detalhadas de cada operação
- **INFO**: Progresso e estatísticas (padrão)
- **WARNING**: Problemas não-críticos
- **ERROR**: Erros que precisam atenção

### Health Check

O container possui health check integrado:

```bash
docker-compose ps
```

Verifica conectividade com o banco a cada 60 segundos.

### Métricas

Após cada execução, o sistema exibe:

- Total de proxies scraped
- Taxa de validação
- Proxies inseridos vs duplicados
- Estatísticas do banco
- Tempo de execução

## Troubleshooting

### Container não inicia

**Verificar logs**:

```bash
docker-compose logs proxy-scraper
```

**Problemas comuns**:

- Arquivo `proxies.txt` não existe
- Credenciais PostgreSQL incorretas
- PostgreSQL não está pronto (aguarde health check)

### Nenhum proxy é inserido

**Causas possíveis**:

1. Proxies não são anônimos (validação falha)
2. Proxies já existem no banco
3. Todos os proxies falharam na validação

**Verificar**:

```bash
# Ver logs detalhados
docker-compose logs proxy-scraper | grep -i "anonymous\|validated"

# Executar com nível DEBUG
# Edite .env: LOG_LEVEL=DEBUG
docker-compose restart proxy-scraper
```

### Selenium/Chrome não funciona

**Erro**: "Chrome binary not found"

**Solução**:

```bash
# Reconstruir imagem
docker-compose build --no-cache proxy-scraper
docker-compose up -d
```

### Problemas de conexão PostgreSQL

**Erro**: "Connection refused" ou "could not connect"

**Verificar**:

```bash
# Status do PostgreSQL
docker-compose ps postgres

# Logs do PostgreSQL
docker-compose logs postgres

# Testar conexão manual
docker-compose exec postgres psql -U postgres -d proxies -c "\dt"
```

### Performance lenta

**Otimizações**:

1. Ajuste `PROXY_TIMEOUT` para valor menor (padrão: 10s)
2. Reduza número de URLs em `proxies.txt`
3. Aumente workers de validação (edite `src/main.py`, `max_workers=20`)

## Segurança

### Recomendações para Produção

1. **Altere senhas padrão**:

```env
POSTGRES_PASSWORD=senha_forte_e_unica
PGADMIN_PASSWORD=outra_senha_forte
```

2. **Não exponha portas desnecessárias**:

   - Remova `ports` do serviço `postgres` no `docker-compose.yml`
   - Use apenas através de pgAdmin ou conexões internas

3. **Use volumes nomeados**:

   - Já configurado no `docker-compose.yml`
   - Dados persistem entre restarts

4. **Atualize regularmente**:

```bash
docker-compose pull
docker-compose build --no-cache
docker-compose up -d
```

5. **Firewall**:
   - Bloqueie acesso externo às portas do Docker
   - Use apenas localhost ou VPN

## Extensões e Customizações

### Adicionar novo scraper

Edite `src/scrapers.py`:

```python
class CustomScraper(ProxyScraper):
    def scrape(self) -> List[Dict[str, Any]]:
        # Sua lógica aqui
        proxies = []
        # ... scraping logic ...
        return proxies
```

### Modificar critérios de anonimato

Edite `src/validator.py`, método `_check_anonymity()`:

```python
def _check_anonymity(self, response, proxy_ip):
    # Customize validation logic
    pass
```

### Adicionar campos ao banco

1. Modifique `init-db.sql`
2. Atualize models em `src/database.py`
3. Recrie o banco:

```bash
docker-compose down -v
docker-compose up -d
```

### Integrar com API externa

Modifique `src/main.py` para exportar ou notificar serviços externos após scraping.

## Performance

### Benchmarks Típicos

Com configurações padrão:

- **Scraping**: 100-500 proxies em 2-5 minutos
- **Validação**: 20 proxies/segundo (max_workers=20)
- **Armazenamento**: < 1 segundo

### Otimizações

- Pool de conexões PostgreSQL (já implementado)
- Validação concorrente com ThreadPoolExecutor
- Cache de webdriver no Selenium
- Índices otimizados no banco

## Suporte e Contribuições

### Estrutura do Código

- **Modular**: Cada arquivo tem responsabilidade única
- **Type Hints**: Código totalmente tipado
- **Documentado**: Docstrings em todas as funções
- **Error Handling**: Try/catch em operações críticas
- **Logging**: Rastreamento completo de execução

### Desenvolvimento Local

```bash
# Criar virtualenv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

# Instalar dependências
pip install -r requirements.txt

# Executar localmente (requer PostgreSQL rodando)
export POSTGRES_HOST=localhost
python src/main.py --immediate
```

## Licença

Este projeto é fornecido como está, sem garantias. Use por sua conta e risco.

## Changelog

### v1.0.0 (2025-11-21)

- Implementação inicial completa
- Suporte a múltiplas fontes de proxy
- Validação de anonimato
- Agendamento automático
- Deploy com Docker Compose
- Documentação completa

---

**Criado com Claude Code** - Sistema production-ready de scraping de proxies anônimos.