# Voyager (central) + Agentes (opcionais)

Este ZIP adiciona uma arquitetura **distribuída e opcional** para o Voyager:

- **Central (ScrapperAPI)** continua capaz de fazer o scrape localmente.
- **Agentes (VoyagerAgent)** são *opcionais*: quando habilitados, eles pegam lotes de URLs do central via **gRPC** e devolvem o conteúdo.
- A coordenação é feita por **lease** no banco (PostgreSQL). Se um agente morrer, o lease expira e outro worker pode recuperar o item.

## Visão geral

- Banco: a tabela `queue` ganhou colunas `leased_by` e `lease_expires_at`, além de `attempts` e `last_error`.
- Central expõe um gRPC `AgentService` para:
  - `RegisterAgent` (registro + thumbprint do cert)
  - `Heartbeat`
  - `LeaseWork` (lote de URLs)
  - `SubmitResult` (conteúdo + status)
- Segurança: recomendado **mTLS** (TLS mútuo) no endpoint gRPC.

## Modos (Workers.Mode)

Em `ScrapperAPI/appsettings*.json`:

- `LocalOnly`: **somente** worker local.
- `Hybrid` (padrão): local + agentes ao mesmo tempo.
- `PreferAgents`: local só trabalha quando não há agentes ativos (por uma janela de graça).
- `PreferLocal`: (reservado) mantenha local sempre ativo.

## Como rodar (dev)

1) Rode o banco e aplique o script:

- `ScrapperAPI/Scripts/database.sql`

2) Rode o central:

- `dotnet run --project ScrapperAPI`

3) (Opcional) Rode um agente:

- ajuste `VoyagerAgent/appsettings.json` com `CentralGrpcAddress` e `SessionIds`
- `dotnet run --project VoyagerAgent`

> Em dev, você pode deixar `Workers:Agents:RequireMutualTls=false` para testar sem cert.

## Como habilitar mTLS (produção)

### 1) Gere uma CA local e certs (exemplo)

> Ajuste paths conforme seu ambiente.

```bash
# CA
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -subj "/CN=Voyager-CA" -out ca.crt

# Servidor (central)
openssl genrsa -out server.key 2048
openssl req -new -key server.key -subj "/CN=voyager-grpc" -out server.csr
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 825 -sha256

# Agente
openssl genrsa -out agent01.key 2048
openssl req -new -key agent01.key -subj "/CN=agent-01" -out agent01.csr
openssl x509 -req -in agent01.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out agent01.crt -days 825 -sha256

# PFX do agente
openssl pkcs12 -export -out agent-01.pfx -inkey agent01.key -in agent01.crt -certfile ca.crt
```

### 2) Configure o Kestrel do central

A forma mais comum é via `appsettings.Production.json` (exemplo):

```json
{
  "Kestrel": {
    "Endpoints": {
      "HttpsGrpc": {
        "Url": "https://0.0.0.0:7443",
        "Certificate": {
          "Path": "./certs/server.pfx",
          "Password": "change-me"
        }
      }
    }
  },
  "Workers": {
    "Agents": {
      "Enabled": true,
      "RequireMutualTls": true
    }
  }
}
```

> Observação: o código do gRPC **exige cert do cliente** quando `RequireMutualTls=true`.

### 3) Configure o agente

Em `VoyagerAgent/appsettings.json`:

- `ClientCertificatePath` -> `./certs/agent-01.pfx`
- `ClientCertificatePassword` -> senha do PFX
- `CentralGrpcAddress` -> https do central (porta 7443, por exemplo)

### 4) Registro do agente

Ao iniciar, o agente chama `RegisterAgent` e o central grava:
- `agent.id`
- `agent.cert_thumbprint`

Depois disso, os requests são validados pelo thumbprint.

## O que foi adicionado/alterado

- `queue`: lease + tentativas
- `agent`: tabela para registrar agentes (thumbprint)
- `IQueueRepository`: lease batch, renew, mark done/failed validando `leased_by`
- `ScrapperAPI`: gRPC `AgentServiceImpl`
- `VoyagerAgent`: Worker Service que faz lease + scrape + submit