Checklist de testes de broker MQTT: 25 verificações antes da produção

Antes que um broker MQTT receba dispositivos reais, passe por este checklist de testes de broker MQTT: 25 verificações concretas, cada uma com um comando e o resultado esperado. Ele cobre conectividade, TLS, autenticação, ACLs, semântica de mensagens, resiliência e capacidade, as áreas onde os incidentes de produção realmente começam.

Todos os exemplos usam os clientes de linha de comando do Mosquitto (mosquitto_pub, mosquitto_sub) e broker.connectmq.com. Troque host, portas e credenciais pelos do seu broker. Salvo indicação em contrário, os clientes falam MQTT 3.1.1; adicione -V mqttv5 para testar o comportamento do MQTT 5.

export HOST=broker.connectmq.com
export T=testmqtt/checklist-$RANDOM     # prefixo de topic único para esta execução
export AUTH="-u $MQTT_USER -P $MQTT_PASS"
export TLS="-p 8883 --capath /etc/ssl/certs"

Conectividade (verificações 1–5)

1. O DNS resolve para o endereço esperado. dig +short $HOST retorna os IPs que você espera, de dentro de todas as redes que seus clientes usam (escritório, VPC na nuvem, APN celular).

2. Todas as portas dos listeners estão acessíveis. Espere succeeded (ou open) para cada porta que você pretende expor, e falha para as que não:

for p in 1883 8883 8083 8084; do nc -zv -w 3 $HOST $p; done

3. Um cliente recebe um CONNACK. mosquitto_pub -h $HOST -t $T/ping -m hi -d imprime Client … received CONNACK (0). Qualquer outra coisa, ou um travamento, indica problema de firewall, proxy ou listener.

4. O endpoint WebSocket faz o upgrade. Navegadores precisam da porta 8084 com o path /mqtt. O handshake deve responder HTTP/1.1 101 Switching Protocols:

curl -si --http1.1 -m 5 https://$HOST:8084/mqtt \
  -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Protocol: mqtt" \
  -H "Sec-WebSocket-Key: $(openssl rand -base64 16)" | head -1

Depois conecte pelo cliente MQTT online para confirmar que um navegador real também funciona.

5. O tempo de conexão está dentro do orçamento. time mosquitto_pub -h $HOST $TLS $AUTH -t $T/ping -m hi via TLS a partir da região dos seus dispositivos. Defina um orçamento (por exemplo, 1–2 segundos em rede celular) e reprove a verificação acima dele.

TLS e autenticação (verificações 6–11)

6. A cadeia de certificados e o hostname são validados. Espere Verify return code: 0 (ok) e uma data de expiração a meses de distância:

openssl s_client -connect $HOST:8883 -servername $HOST -verify_return_error </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -enddate

Uma falha aqui é o que os dispositivos depois reportam como certificate verify failed. Testar uma conexão TLS MQTT cobre cada variante.

7. Texto puro está desativado onde deveria. Se os clientes de produção devem usar TLS, a porta 1883 do seu broker de produção deve recusar conexões (a verificação 2 deve falhar para 1883).

8. Clientes anônimos são rejeitados. Sem credenciais, espere Connection error: Connection Refused: not authorised.

mosquitto_pub -h $HOST $TLS -t $T/anon -m x

9. Senhas erradas são rejeitadas. Com uma senha incorreta, espere Connection Refused: bad user name or password. (no MQTT 5: reason code 0x86). Consulte qualquer outro código com a ferramenta de reason codes MQTT.

mosquitto_pub -h $HOST $TLS -u "$MQTT_USER" -P wrong-password -t $T/auth -m x

10. As ACLs bloqueiam topics de terceiros. Entre como usuário de um dispositivo e publique fora do namespace dele. No MQTT 3.1.1 o broker descarta a mensagem silenciosamente, então confirme com um subscriber privilegiado que nada chega. No MQTT 5 com QoS 1, o PUBACK traz a recusa: a saída de debug mostra RC:135 (0x87 Not authorized):

mosquitto_pub -h $HOST $TLS $AUTH -V mqttv5 -q 1 -d -t other-tenant/secret -m x

11. Usuários de dispositivos não conseguem assinar #. mosquitto_sub -h $HOST $TLS $AUTH -t '#' -C 1 -W 5 deve imprimir All subscription requests were denied. Veja como testar permissões ACL no MQTT para um teste completo da matriz de ACL.

Semântica de mensagens (verificações 12–18)

12. O ciclo publish/subscribe funciona. Assine, publique um token único e receba-o dentro de um timeout. O script de smoke test de um minuto faz exatamente isso, com código de saída de sucesso ou falha.

13. QoS 1 é confirmado. mosquitto_pub -h $HOST -q 1 -d -t $T/qos -m x mostra received PUBACK. Com -q 2, espere PUBREC e PUBCOMP.

14. Mensagens retidas são armazenadas e apagadas.

mosquitto_pub -h $HOST -t $T/retained -m on -r -q 1
mosquitto_sub -h $HOST -t $T/retained -C 1 -W 5 -v   # imprime o valor retido
mosquitto_pub -h $HOST -t $T/retained -r -n          # payload retido vazio apaga a mensagem
mosquitto_sub -h $HOST -t $T/retained -C 1 -W 5 -v   # timeout: nada retido

15. O Last Will é publicado em uma desconexão não limpa.

mosquitto_sub -h $HOST -t $T/status -v &
mosquitto_sub -h $HOST -i lwt-check -k 5 -t $T/none \
  --will-topic $T/status --will-payload offline &
sleep 2; kill -9 $!                                   # falha simulada

O primeiro subscriber imprime …/status offline. Um DISCONNECT limpo não deve dispará-lo.

16. Sessões persistentes enfileiram mensagens offline. Conecte com um client ID fixo e -c (clean session desligado), pare o cliente, publique com QoS 1 e reconecte com o mesmo comando: a mensagem enfileirada chega.

mosquitto_sub -h $HOST -i queue-check -c -q 1 -t $T/queue -W 3   # cria a sessão
mosquitto_pub -h $HOST -q 1 -t $T/queue -m while-offline
mosquitto_sub -h $HOST -i queue-check -c -q 1 -t $T/queue -C 1 -W 5

17. Client IDs duplicados se comportam como esperado. Inicie dois clientes com o mesmo -i; o broker desconecta o primeiro. Garanta que cada dispositivo gere um ID único (o gerador de client ID ajuda), ou você verá loops infinitos de reconexão.

18. O tamanho máximo de mensagem é conhecido. Publique um payload logo acima da sua maior mensagem real e confirme o comportamento do broker. Testando payloads MQTT grandes traz um script de varredura de tamanhos.

Resiliência (verificações 19–22)

19. Os clientes reconectam após reiniciar o broker. Em staging, reinicie o broker (docker restart mosquitto ou systemctl restart mosquitto) e confirme que todo tipo de cliente reconecta, assina de novo e volta a publicar sem ação manual.

20. Conexões mortas são detectadas. Descarte silenciosamente o tráfego para o broker (sudo iptables -A OUTPUT -p tcp --dport 8883 -j DROP) e verifique se o cliente percebe em cerca de 1,5 × o intervalo de keep-alive; depois remova a regra. Chaos testing com MQTT mostra como automatizar isso com tc netem e Toxiproxy.

21. As reconexões usam backoff com jitter. Após um reinício, as tentativas de conexão devem se espalhar ao longo de alguns segundos em vez de chegar em um único pico. Confira os logs do cliente ou o gráfico de taxa de conexões do broker.

22. O failover funciona, se você roda um cluster. Pare um nó e confirme que os clientes migram para outro, que as sessões sobrevivem conforme o projeto e que nenhum estado retido se perde.

Capacidade e operação (verificações 23–25)

23. O broker aguenta 2× o pico esperado. Rode um teste de carga com seu tamanho de payload, QoS e estrutura de topics reais (veja teste de carga de broker MQTT) e registre a latência p99 e a taxa de erros.

24. As métricas estão visíveis. Clientes conectados, taxas de mensagens e mensagens descartadas aparecem em um dashboard. No Mosquitto (onde permitido): mosquitto_sub -h $HOST $AUTH -t '$SYS/broker/clients/connected' -C 1 -v.

25. Os alertas disparam de verdade. Provoque um de propósito: pare um cliente de teste que deveria estar sempre online, ou aponte uma verificação para um certificado perto de expirar, e confirme que o alerta chega a uma pessoa.

Transformando o checklist em script

Comece automatizando as verificações rápidas e rode-as no CI e após cada mudança no broker; mantenha as lentas no checklist de release.

Rode as verificações 3, 12 e 14 no navegador

Um broker que passa nestas 25 verificações provou o que importa no primeiro dia: os clientes chegam até ele com segurança, só os clientes certos entram, as mensagens se comportam como projetado e as falhas se recuperam sozinhas. Guarde os comandos no seu repositório e rode-os de novo sempre que o broker, a configuração dele ou os certificados mudarem.

Perguntas frequentes