06 — Heartbeat: a instalação avisa que está viva¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-10
Implementado em 2026-09-10; sai na próxima release. É a ponta de uma entrega que atravessa quatro repos — este, o integrador-server, o central-backend e o central-ui.
Escopo¶
Uma instalação que para — máquina desligada, jar travado, Java trocado, .properties quebrado —
ninguém via. O write-back simplesmente parava de chegar, e o sintoma aparecia horas ou dias
depois, relatado pelo cliente como "a integração parou". A casa também não sabia, sem acesso
remoto à máquina, qual versão roda em cada cliente nem quais fluxos estão ligados. E não há
cadastro de instalação: o cliente recebe o jar e começa a rodar, então o registro tinha de ser
automático.
O que foi construído¶
- Heartbeat na largada (
motivo=inicio): logo depois da trava de instância e antes de conectar ao PowerSync, para a instalação aparecer mesmo que a conexão falhe depois. Leva a versão do jar, os fluxos dezim.fluxos, o nome da máquina e o instante da largada. - Heartbeat periódico (
motivo=periodico) a cadaheartbeat.intervaloMinutos(60 por padrão), na mesma thread do laço. O primeiro conta a partir do heartbeat de início — não sai dobrado. - Nada a configurar no cliente: vai ao integrador-server do próprio cliente, no mesmo host e com
o mesmo token do write-back — nenhuma liberação nova de firewall. As chaves
heartbeat.*são opcionais;heartbeat.intervaloMinutos=0desliga tudo. - Nunca derruba o daemon: qualquer falha (rede, recusa, erro interno) vira WARN no log e só. Não vai ao GlitchTip: perder um heartbeat não importa, e quem enxerga o silêncio é o central.
- O
--debugnão manda heartbeat — sessão manual de homologação não é instalação.
O resto da cadeia mora nos outros repos: o integrador-server carimba de qual cliente é e repassa ao central; o central grava a instalação, conta as horas úteis sem sinal e, passadas 6, abre um alerta no GlitchTip; a aba Deploy do central-ui lista as instalações. O contrato do heartbeat é do integrador-server: heartbeat.md.
Decisões¶
| Decisão | Assunto |
|---|---|
| 0028 do central-backend | rota em dois saltos pelo integrador-server, horas úteis, alerta por cliente |