Pular para conteúdo

0029 — cliente_id do heartbeat derivado do fqdn

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-20 · Decidido em: 2026-09-18

Contexto

A decisão 0026 fixou que CLIENTE_ID não tem fallback: o CLIENTE é nome de exibição (Maxsul, Sul Plata Trading do Brasil) e nunca passaria na regra do central (^[a-z0-9-]{1,50}$), então derivar dele esconderia a misconfiguração atrás de um erro de validação. A consequência aceita foi: env vazia → 503 heartbeat_desligado + ERROR a cada batida.

O custo apareceu na operação. Em 2026-09-18, 5 das 6 instâncias estavam sem CLIENTE_ID — o heartbeat de cada uma respondia 503 e logava ERROR de hora em hora, e a correção foi cadastrar a env na mão nas cinco. Isso fecha o buraco daquele dia, não a classe de erro: a env é cadastrada à mão por instância, então o próximo cliente novo nasce quebrado do mesmo jeito. O erro só aparece depois que o integrador-client do cliente já está instalado e batendo.

Existe uma fonte confiável que ninguém precisa cadastrar: toda instância tem COOLIFY_FQDN, e ele é int.<slug>.xadm.biz, onde <slug> é exatamente o cliente_id do central (conferido nas seis).

Decisão

  • CLIENTE_ID explícito sempre vence. O derivado é só fallback — nada muda onde a env existe.
  • Faltando CLIENTE_ID, o cliente_id é o 1º label do COOLIFY_FQDN, e só quando o fqdn casa int.<slug>.xadm.biz. Qualquer outro formato deixa o cliente_id vazio e o heartbeat segue em 503 heartbeat_desligado: melhor desligado do que carimbar o central com o cliente errado.
  • O fqdn da perna native não casa, de propósito. Ela é int-native.<cli>.xadm.biz (decisão 0028); lá o CLIENTE_ID explícito é copiado da perna jar e vence pela regra acima. Derivar dali carimbaria um cliente que não existe.
  • CLIENTE continua fora, pelo motivo original da 0026 — esta decisão não o reabilita.
  • A resolução mora no código (HeartbeatController), não no YAML: default aninhado em ${...} não funciona no Micronaut, que casa o primeiro } e transforma o resto em lixo (engenharia/java-micronaut, Armadilhas). Mesmo padrão do sascar.slug, resolvido no MensageriaEnfileirador.
  • O boot diz de onde saiu o cliente_id — env explícita, derivado do fqdn, ou nenhuma fonte.

Alternativas preteridas

  • Deixar como estava (sem fallback). Mantém a 0026 intacta, mas aceita que todo cliente novo nasça com heartbeat em 503 + ERROR até alguém lembrar da env.
  • Fallback para CLIENTE. Já preterido na 0026 e continua preterido: é nome de exibição.
  • Derivar sem conferir o formato. Um fqdn de outro formato viraria um cliente_id inventado, e o central passaria a receber heartbeat carimbado com cliente errado — pior que o 503.
  • Recusar o boot sem cliente_id. Inverteria a 0026 sem necessidade: as instâncias sem integrador-client ficam legitimamente sem as envs do heartbeat, e nenhum heartbeat chega nelas.

Consequências

  • Instância nova nasce com heartbeat funcionando; cadastrar CLIENTE_ID deixa de ser passo obrigatório e vira override.
  • A perna native exige CLIENTE_ID explícito na env — está na lista do que se copia da perna jar ao criar o recurso native.
  • O 503 continua existindo para o caso sem nenhuma fonte, e o runbook de incidentes comuns segue válido.
  • Config e precedência: application-config.