Pular para conteúdo

0024 — Adotar a lib xadm-comum-web

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-08-05 · Decidido em: 2026-08-05

Contexto

A infra web transversal do app — corpo de erro RFC 7807 (ProblemDetail + UnifiedErrorResponseProcessor, decisão 0021), as exceções HTTP base (BadRequest/Conflict/NotFound/Forbidden), o HealthController, o SentryInitializer (Bugsink) e o VersaoInfo (/info + log de startup) — vivia em comum/ e era cópia byte-a-byte da mesma stack em ≥3 apps X-Adm. Cada cópia é mais um lugar para corrigir e mais uma chance de divergir. O conjunto foi extraído para a lib canônica br.com.xadm:xadm-comum-web (ADR 0019 do xadm-commons; o vantroba foi a variante-fonte). As cópias locais em comum/ divergiam do canônico comum.web. Gêmeo da decisão 0023 (motor de auth), que deixou o AuthExceptionHandler local com re-extração adiada para cá.

Decisão

Depender de xadm-comum-web:0.1.0 (Forgejo Packages da org xadm, leitura anônima — mesma fonte da decisão 0015 e da 0023) e deletar as 9 cópias locais: ProblemDetail, UnifiedErrorResponseProcessor, BadRequestException, ConflictException, NotFoundException, ForbiddenException, HealthController, SentryInitializer, VersaoInfo. Migrar os consumidores (~22 fontes) para br.com.xadm.comum.web e repointar o seguranca/AuthExceptionHandler para o ProblemDetail da lib (fecha o adiamento da 0023).

Fica local só o que é do app: comum/util (ChecksumSha256, DataConverter, AnosVeiculoParser — utilitário, não infra web), comum/exception/StorageIndisponivelException (503, domínio XLS — estende HttpStatusException, sem dep nas classes movidas), comum/config (typed config do app) e comum/notificacao (Telegram do app). Nenhum pacote local é renomeado.

Consequências

  • Uma fonte só do formato de erro / health / Sentry / versão; um bump de lib corrige todos os apps.
  • Paridade provada contra o artefato 0.1.0 publicado, sem alterar asserção: TransporteControllerTest (RFC-7807 code+status, /health) e AuthExceptionHandlerTest (usa ProblemDetail) verdes com -PdockerTests (plataforma real, @MicronautTest).
  • O teste-espelho do motor SentryInitializerTest local foi deletado: chamava configurar()/parseTracesSampleRate() package-private, que não compilam com a classe noutro pacote — a fonte da verdade dele é o xadm-comum-web, que traz o seu próprio.
  • Os beans da lib registram sozinhos: o UnifiedErrorResponseProcessor (@Replaces do Hateoas + @Singleton), o HealthController (@Controller) e o VersaoInfo (InfoSource) vêm com as bean definitions Micronaut compiladas no jar (senão a DI não os descobriria). Não recriar o processor local — o @Replaces vem da lib.
  • A geração por-app do version.properties continua (a VersaoInfo.versaoAtual() da lib o lê do classpath); o sentry-logback já presente cobre o compileOnly do SDK Sentry que a lib declara.
  • Corpo funcionalmente equivalente ao local; o javadoc foi generalizado na lib (removidas refs app-específicas) — não é byte-idêntico, mas o comportamento HTTP é o mesmo do pré-adoção.

Alternativas consideradas

  • Manter as cópias locais: sem acoplamento à lib, mas N lugares para corrigir o mesmo formato de erro/health e N chances de divergirem. Descartado — é o risco que motivou a extração.
  • Recriar o UnifiedErrorResponseProcessor local (só depender dos tipos): duplicaria o @Replaces e o ponto único de render de erro. Descartado — o processor vem da lib.
  • Adotar já nos outros 3 apps / mover util e StorageIndisponivelException junto: fora de escopo; util não é infra web e a StorageIndisponivelException é domínio XLS (503) deste app.