# Integração do Sistema de Proxies

Este documento descreve como o sistema de proxies foi integrado à API do YouTube.

## Visão Geral

O sistema de proxies foi implementado para melhorar a confiabilidade da API, usando proxies armazenados em um banco de dados PostgreSQL. Quando um proxy falha, ele é automaticamente removido e outro proxy é testado.

## Arquitetura

### Arquivos Criados

1. **database.py**: Módulo de conexão e operações com PostgreSQL
   - `get_db_connection()`: Cria conexão com o banco
   - `get_latest_proxy()`: Busca o melhor proxy disponível (baseado em métricas)
   - `delete_proxy(proxy_id)`: Marca um proxy como inativo e incrementa failure_count
   - `mark_proxy_success(proxy_id)`: Marca sucesso e incrementa success_count
   - `format_proxy_url(proxy)`: Formata proxy no padrão yt_dlp (com suporte a autenticação)

2. **proxy_manager.py**: Lógica de retry automático com proxies
   - `is_proxy_error(error_msg)`: Identifica se um erro é relacionado a proxy
   - `execute_with_proxy_retry()`: Executa operações com retry automático

### Estrutura da Tabela de Proxies

```sql
CREATE TABLE proxies (
    id SERIAL PRIMARY KEY,
    ip_address VARCHAR(255) NOT NULL,
    port INTEGER NOT NULL,
    protocol VARCHAR(10) NOT NULL DEFAULT 'http',
    username VARCHAR(255),                    -- Autenticação (opcional)
    password VARCHAR(255),                    -- Autenticação (opcional)
    country_code VARCHAR(10),                 -- Código do país (ex: US, BR)
    country_name VARCHAR(100),                -- Nome do país
    city VARCHAR(100),                        -- Cidade
    is_active BOOLEAN DEFAULT TRUE,           -- Proxy está ativo?
    is_anonymous BOOLEAN DEFAULT FALSE,       -- Proxy é anônimo?
    response_time_ms INTEGER,                 -- Tempo de resposta em ms
    last_checked_at TIMESTAMP,                -- Última verificação
    last_successful_at TIMESTAMP,             -- Último sucesso
    failure_count INTEGER DEFAULT 0,          -- Contador de falhas
    success_count INTEGER DEFAULT 0,          -- Contador de sucessos
    usage VARCHAR(50),                        -- Uso do proxy
    source VARCHAR(100),                      -- Fonte do proxy
    notes TEXT,                               -- Notas adicionais
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## Configuração

### 1. Variáveis de Ambiente

Crie um arquivo `.env` baseado no `.env.example`:

```bash
DB_HOST=seu_host_postgresql
DB_PORT=5432
DB_NAME=seu_banco
DB_USER=seu_usuario
DB_PASSWORD=sua_senha
```

### 2. Docker Compose

O `docker-compose.yml` já está configurado para carregar as variáveis de ambiente. Use:

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

## Como Funciona

### Fluxo de Execução

1. **Seleção Inteligente de Proxy**: A cada requisição, o sistema busca o melhor proxy disponível baseado em:
   - Proxies ativos (`is_active = TRUE`)
   - Último sucesso mais recente (`last_successful_at DESC`)
   - Menor tempo de resposta (`response_time_ms ASC`)
   - Maior taxa de sucesso (`success_count / (success_count + failure_count)`)
   - Mais recentemente adicionado (`created_at DESC`)

2. **Tentativa de Execução**: Tenta executar a operação usando o proxy selecionado
   - Suporta autenticação automática se o proxy tiver `username` e `password`
   - Formato: `protocol://username:password@ip_address:port`
   - **Timeout configurado**: 8 segundos para conexão com proxy

3. **Detecção de Erro**: Se houver erro relacionado a proxy (timeout, connection refused, etc.)

4. **Desativação do Proxy**: O proxy com problema é marcado como inativo
   - `is_active = FALSE`
   - `failure_count` incrementado
   - `last_checked_at` e `updated_at` atualizados
   - **Nota**: O proxy NÃO é deletado, apenas desativado

5. **Atualização de Sucesso**: Quando a operação é bem-sucedida
   - `success_count` incrementado
   - `last_successful_at` atualizado
   - `is_active = TRUE` (reativa o proxy se estava inativo)
   - `last_checked_at` e `updated_at` atualizados

6. **Retry**: Busca outro proxy ativo e tenta novamente

7. **Limite de Tentativas**: Máximo de 10 tentativas (configurável)

### Performance e Timeout

- **Socket Timeout**: 8 segundos por tentativa de proxy
- **Retry do yt_dlp**: Desabilitado (`retries: 0`)
- **Vantagem**: Ao detectar erro, troca IMEDIATAMENTE de proxy sem tentar novamente no mesmo
- **Comportamento**:
  - ❌ **ANTES**: Proxy ruim → tenta 3x no mesmo → 24 segundos perdidos → troca
  - ✅ **AGORA**: Proxy ruim → erro após 8s → remove → busca outro → 8 segundos
- **Tempo máximo de espera**: ~80 segundos (10 proxies × 8 segundos cada)
- **Nota**: Se precisar de timeout diferente, altere `socket_timeout` nas opções do yt_dlp

### Palavras-chave de Erro de Proxy

O sistema identifica erros de proxy por estas palavras-chave:
- proxy
- connection
- timeout
- timed out
- refused
- unreachable
- unable to connect
- network
- failed to connect
- connection reset
- read timed out
- http error 407 (proxy authentication)
- tunnel connection failed

### Erros NÃO Tratados como Proxy

Estes erros NÃO resultam em troca de proxy (são erros legítimos do vídeo):
- "requested format is not available" - Formato solicitado não existe
- "video unavailable" - Vídeo indisponível/removido
- "private video" - Vídeo privado
- "age restricted" - Vídeo com restrição de idade

Quando esses erros ocorrem, o sistema **não** descarta o proxy e retorna o erro imediatamente.

### Endpoints Integrados

Todos os endpoints que usam yt_dlp foram integrados:

1. **GET /get-video-metadata**: Obtém metadados de vídeos
2. **GET /download-video**: Download de vídeos
3. **GET /search**: Busca de vídeos
4. **GET /list-formats**: Lista formatos disponíveis

### Tratamento de Erros

- **ProxyError (503)**: Todos os proxies falharam ou não há proxies disponíveis
- **Exception (500)**: Erros não relacionados a proxy

## Alimentando o Banco de Proxies

Para adicionar proxies ao banco, você pode usar o serviço de scraper de proxies que já foi criado.

### Exemplos de Inserção Manual

**Proxies sem autenticação:**
```sql
INSERT INTO proxies (ip_address, port, protocol, is_active, is_anonymous, country_code)
VALUES
    ('123.456.789.10', 8080, 'http', TRUE, FALSE, 'US'),
    ('98.765.432.10', 3128, 'https', TRUE, TRUE, 'BR'),
    ('45.67.89.100', 1080, 'socks5', TRUE, TRUE, 'DE');
```

**Proxies com autenticação:**
```sql
INSERT INTO proxies (ip_address, port, protocol, username, password, is_active)
VALUES
    ('premium-proxy.example.com', 8080, 'http', 'user123', 'pass456', TRUE),
    ('secure-proxy.example.com', 3128, 'https', 'myuser', 'mypass', TRUE);
```

### Integração com Scraper

Quando o serviço de scraper adicionar novos proxies, deve incluir:
- `ip_address`, `port`, `protocol` (obrigatórios)
- `country_code`, `country_name`, `city` (se disponível)
- `is_anonymous` (se detectado)
- `response_time_ms` (tempo de resposta inicial)
- `source` (fonte do scraper)
- `is_active = TRUE` por padrão

## Monitoramento

O sistema imprime logs úteis no console:

```
Tentativa 1: Usando proxy http://41.65.160.173:8080 (ID: 42)
Erro na tentativa 1: Connection to 41.65.160.173 timed out
Erro identificado como erro de proxy. Removendo proxy ID 42
Proxy 42 desativado: True

Tentativa 2: Usando proxy http://98.765.432.10:3128 (ID: 43)
Operação concluída com sucesso na tentativa 2
Proxy (id 43) marcado como sucesso
```

**Importante**: Não haverá mais mensagens como "Retrying (1/3)..." porque desabilitamos o retry interno do yt_dlp. Cada erro resulta em troca imediata de proxy.

## Vantagens

1. **Alta Disponibilidade**: Se um proxy falhar, outro é usado automaticamente
2. **Seleção Inteligente**: Proxies são escolhidos baseado em performance e histórico
3. **Auto-recuperação**: Proxies são desativados quando falham, mas podem ser reativados em sucesso futuro
4. **Métricas Automáticas**: Sistema rastreia sucesso/falha e tempo de resposta automaticamente
5. **Suporte a Autenticação**: Proxies com username/password são suportados automaticamente
6. **Sem Intervenção Manual**: O sistema gerencia proxies de forma autônoma
7. **Preservação de Dados**: Proxies não são deletados, apenas desativados
8. **Fácil Integração**: Novo serviço de scraper pode adicionar proxies facilmente

## Monitoramento e Análise

### Queries Úteis

**Ver estatísticas de proxies:**
```sql
SELECT
    COUNT(*) as total,
    COUNT(*) FILTER (WHERE is_active = TRUE) as ativos,
    COUNT(*) FILTER (WHERE is_active = FALSE) as inativos,
    AVG(response_time_ms) as tempo_resposta_medio,
    SUM(success_count) as total_sucessos,
    SUM(failure_count) as total_falhas
FROM proxies;
```

**Ver top 10 melhores proxies:**
```sql
SELECT
    ip_address, port, protocol,
    success_count, failure_count,
    ROUND((success_count::FLOAT / NULLIF(success_count + failure_count, 0) * 100), 2) as taxa_sucesso,
    response_time_ms,
    last_successful_at
FROM proxies
WHERE is_active = TRUE
ORDER BY
    last_successful_at DESC NULLS LAST,
    response_time_ms ASC NULLS LAST
LIMIT 10;
```

**Reativar proxies desativados há mais de 24h (útil para retry):**
```sql
UPDATE proxies
SET is_active = TRUE, updated_at = NOW()
WHERE is_active = FALSE
  AND updated_at < NOW() - INTERVAL '24 hours';
```

## Próximos Passos Sugeridos

1. ✅ Integrar com o serviço de scraper de proxies
2. ✅ Implementar métricas de sucesso/falha por proxy (CONCLUÍDO)
3. ✅ Implementar sistema de priorização de proxies (CONCLUÍDO)
4. Criar endpoint de administração para visualizar estatísticas de proxies
5. Implementar job periódico para reativar proxies após período de cooldown
6. Adicionar alertas quando número de proxies ativos cair abaixo de threshold