Conexão: ciclo de vida e verificação

A conexão WebSocket tem duração limitada, e conferir se ela ainda está viva é uma ação que você envia — o servidor não reporta isso por conta própria. Esta página reúne as duas coisas, porque a segunda existe por causa da primeira.

Ciclo de vida da conexão

A conexão não é permanente, e isso não é falha: são limites do serviço, e valem para todos os canais.

Limite	Valor	O que acontece
Duração máxima	2 horas	a conexão é encerrada, mesmo com tráfego
Ociosidade	10 minutos	sem nenhuma mensagem nos dois sentidos, a conexão é encerrada

Na prática, uma integração ativa reconecta a cada duas horas, aproximadamente.

Ao reconectar, assine os canais de novo

As subscrições vivem com a conexão e são descartadas quando ela cai. Reconectar não restaura o que estava assinado: sem um novo subscribe, a conexão fica aberta e não recebe nada.

É o modo de falha mais comum de quem integra pela primeira vez, e ele se parece com "o canal não funciona" em vez de "faltou um passo".

Verificando se a conexão está viva

Silêncio no canal tem dois significados, e eles são indistinguíveis de fora: nada aconteceu, ou a conexão caiu. Quando a conexão é encerrada normalmente o seu cliente recebe o evento de fechamento; mas há situações — queda de rede, NAT expirado, equipamento intermediário — em que o fechamento nunca chega, e o cliente segue achando que está ouvindo.

Envie getConnectionStatus para responder isso:

{ "action": "getConnectionStatus" }

Resposta:

{
  "action": "connectionStatus",
  "timestamp": 1788192000,
  "channels": ["watchorders"]
}

A resposta responde três perguntas de uma vez:

Campo	O que ele diz
a resposta chegar	a conexão está viva
timestamp	o horário do servidor, em epoch de segundos
channels	o que você está de fato recebendo

O channels é o que distingue "conectado" de "recebendo". Se ele vier vazio, a conexão está aberta mas nenhum canal está assinado — reenvie o subscribe.

Por que não se chama ping

O WebSocket já tem um ping: os control frames Ping e Pong definidos pela RFC 6455, que a sua biblioteca cliente troca com o servidor automaticamente, sem o seu código pedir. Eles continuam funcionando e não têm relação com esta ação.

getConnectionStatus é uma mensagem de aplicação, que você envia explicitamente e que devolve algo que os frames de protocolo não têm: a lista de canais assinados. Os dois convivem na mesma conexão — daí o nome diferente, para que "o ping voltou" nunca fique ambíguo entre um e outro.

Cadência sugerida: a cada 5 minutos. Fica confortavelmente abaixo do limite de ociosidade e mantém a conexão viva mesmo numa janela sem movimento. Se a resposta não voltar dentro de alguns segundos, trate como conexão perdida: feche, reconecte e assine os canais de novo.

O getConnectionStatus é opcional. Integração que não o utiliza continua funcionando exatamente como antes — o servidor nunca pergunta por conta própria, e nenhuma mensagem nova chega sem que você peça.