Pular para o conteúdo principal

Testes da API de Auto-Discovery

Resultados dos testes para a API de Auto-Discovery que permite backends se registrarem dinamicamente.

Data do Teste: 2025-12-08 Porta da API: 8081

Endpoints da API​

EndpointMétodoDescrição
/healthGETHealth check com versão e contagem de backends
/api/v1/registerPOSTRegistrar um novo backend
/api/v1/heartbeat/:idPOSTAtualizar heartbeat do backend
/api/v1/backendsGETListar todos os backends registrados
/api/v1/backends/:idGETObter detalhes de um backend específico
/api/v1/backends/:idDELETEDesregistrar um backend

Resultados dos Testes​

1. Health Check​

Requisição:

curl -s http://34.246.117.138:8081/health

Resposta:

{
  "status": "ok",
  "version": "0.2.0",
  "registered_backends": 10
}

Status: OK

2. Registro de Backend​

Requisição:

curl -s -X POST http://34.246.117.138:8081/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pop-gru",
    "app": "gru.pop",
    "region": "sa",
    "ip": "10.50.1.1",
    "port": 80
  }'

Resposta:

{
  "id": "pop-gru",
  "registered": true,
  "message": "Backend registered successfully"
}

Todos os Registros:

IDAppRegiãoIPPortaResultado
pop-grugru.popsa10.50.1.180OK
pop-iadiad.popus10.50.2.180OK
pop-ordord.popus10.50.2.280OK
pop-laxlax.popus10.50.2.380OK
pop-lhrlhr.popeu10.50.3.180OK
pop-frafra.popeu10.50.3.280OK
pop-cdgcdg.popeu10.50.3.380OK
pop-nrtnrt.popap10.50.4.180OK
pop-sinsin.popap10.50.4.280OK
pop-sydsyd.popap10.50.4.380OK

Status: 10/10 registros bem-sucedidos

3. Listar Backends​

Requisição:

curl -s http://34.246.117.138:8081/api/v1/backends

Resposta:

{
  "backends": [
    {
      "id": "pop-gru",
      "app": "gru.pop",
      "region": "sa",
      "ip": "10.50.1.1",
      "port": 80,
      "healthy": true,
      "last_heartbeat_secs": 5,
      "registered_secs": 120
    },
    {
      "id": "pop-iad",
      "app": "iad.pop",
      "region": "us",
      "ip": "10.50.2.1",
      "port": 80,
      "healthy": true,
      "last_heartbeat_secs": 5,
      "registered_secs": 118
    }
    // ... mais backends
  ],
  "total": 10
}

Status: OK - Todos os 10 backends listados

4. Obter Backend Específico​

Requisição:

curl -s http://34.246.117.138:8081/api/v1/backends/pop-gru

Resposta:

{
  "id": "pop-gru",
  "app": "gru.pop",
  "region": "sa",
  "ip": "10.50.1.1",
  "port": 80,
  "healthy": true,
  "last_heartbeat_secs": 10,
  "registered_secs": 125
}

Status: OK

5. Atualização de Heartbeat​

Requisição:

curl -s -X POST http://34.246.117.138:8081/api/v1/heartbeat/pop-gru

Resposta:

{
  "id": "pop-gru",
  "status": "ok"
}

Status: OK - Heartbeat atualizado, last_heartbeat_secs resetado para 0

6. Desregistro de Backend​

Requisição:

curl -s -X DELETE http://34.246.117.138:8081/api/v1/backends/test-backend

Resposta:

{
  "deregistered": true,
  "id": "test-backend"
}

Status: OK

Schema do Payload de Registro​

Campos Obrigatórios​

CampoTipoDescriçãoExemplo
idstringIdentificador único do backend"pop-gru"
appstringNome da aplicação (usado para DNS)"gru.pop"
regionstringCódigo da região (sa, us, eu, ap)"sa"
ipstringEndereço IP do backend"10.50.1.1"
portnumberPorta do backend80

Campos Opcionais (com valores padrão)​

CampoTipoPadrãoDescrição
countrystringderivadoCódigo ISO do país
weightnumber2Peso no balanceamento de carga (1-10)
soft_limitnumber100Número confortável de conexões
hard_limitnumber150Máximo de conexões

Exemplo de Payload Completo​

{
  "id": "my-backend-1",
  "app": "myapp",
  "region": "eu",
  "country": "DE",
  "ip": "10.50.3.1",
  "port": 8080,
  "weight": 5,
  "soft_limit": 200,
  "hard_limit": 300
}

Gerenciamento de Saúde​

TTL do Heartbeat​

Backends são marcados como não saudáveis se não enviarem heartbeat dentro do período de TTL.

ConfiguraçãoPadrãoVariável de Ambiente
TTL do Heartbeat60 segundosEDGEPROXY_HEARTBEAT_TTL_SECS

Limpeza Automática​

  • Backends que perdem heartbeat são marcados healthy: false
  • Tarefa em background remove backends obsoletos periodicamente
  • Backends não saudáveis são excluídos do balanceamento de carga

Mantendo Backends Saudáveis​

# Loop de heartbeat simples (a cada 30 segundos)
while true; do
  curl -s -X POST http://hub:8081/api/v1/heartbeat/my-backend-1
  sleep 30
done

Integração com DNS​

Backends registrados via API podem ser resolvidos através do DNS:

# Registrar backend com nome do app
curl -X POST http://hub:8081/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"id":"my-eu-1","app":"myservice","region":"eu","ip":"10.50.3.1","port":8080}'

# Resolver via DNS
dig @hub -p 5353 myservice.internal +short
# Retorna: 10.50.3.1

Nota: Backends registrados via API são armazenados em memória (DashMap). Para resolução DNS, backends também devem estar no routing.db.

Respostas de Erro​

400 Bad Request​

{
  "error": "Missing required field: id"
}

404 Not Found​

{
  "error": "Backend not found",
  "id": "unknown-backend"
}

409 Conflict​

{
  "error": "Backend already exists",
  "id": "existing-backend"
}

Monitorando Backends Registrados​

Via API​

# Contar backends
curl -s http://hub:8081/api/v1/backends | jq '.total'

# Listar backends saudáveis
curl -s http://hub:8081/api/v1/backends | jq '.backends[] | select(.healthy==true) | .id'

# Encontrar backends por região
curl -s http://hub:8081/api/v1/backends | jq '.backends[] | select(.region=="eu")'

Via Logs​

# Observar eventos de registro
sudo journalctl -u edgeproxy -f | grep -i "register\|heartbeat"

Resumo dos Testes​

TesteResultado
Health CheckOK
Registro (10 backends)OK
Listar BackendsOK
Obter Backend EspecíficoOK
Atualização de HeartbeatOK
DesregistroOK

Total: Todos os testes da API passando