termo_core 0.1.10

Todos os clientes da Termotubos num crate só: um módulo por serviço e cada rota da API como uma função de uma linha, com o endereço resolvido pelo ambiente atual.
Documentation

TermoCore

Todos os clientes da Termotubos num crate só, o termo_core. Cada serviço é um módulo (termo_core::bucket, termo_core::auth...) e cada rota da API do serviço é uma função de uma linha, gerada a partir do openapi.json dele.

termo_core = "=0.1.5"                                          # todos os serviços
termo_core = { version = "=0.1.5", features = ["webhook_postgres"] } # + fila de saída de eventos

Fixe sempre a versão exata (=). O workflow publica cada mudança de contrato do sandbox subindo só o último número, inclusive quando a mudança quebra código. Para atualizar, troque a versão de propósito e confira se compila.

let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let usuario = termo_core::auth::buscar_pelo_id_usuario(&credencial_de_acesso, id).await?;
let pagina = termo_core::auth::buscar_paginador_usuario(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPaginadorUsuario { pagina: Some(1), ..Default::default() },
)
.await?;

Token do aplicativo (conversa entre back-ends)

let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_aplicativo().await?;
let resposta = termo_core::bucket::/* rota de sistema */(&credencial_de_acesso, /* ... */).await?;

token_do_aplicativo() troca o SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH por um JWT curto em POST {TermoAuth}/token_de_app ({ "segredo" } → { token, expira_em, app }). O token fica em cache no processo e só é pedido de novo quando falta menos de 60 s para expira_em; não há tarefa em background. Sem a variável, devolve ErroAoChamarServico::FalhaAoMontarRequisicao dizendo para defini-la. Token de aplicativo só vale nas APIs de sistema (gateway do TermoAI, API de arquivos do TermoBucket, publicação no TermoWebhook); as rotas de painel continuam só para pessoas.

O nome da função é a ação seguida do recurso (operationId usuarioBuscarPeloId com a tag usuario vira buscar_pelo_id_usuario). Rotas públicas não pedem credencial. Todo erro vem como ErroAoChamarServico, com o status e o campo erro da resposta.

Configuração: a variável AMBIENTE

AMBIENTE Para onde cada serviço aponta
LOCALHOST o servidor local (http://localhost:51xx1) ou o sandbox, escolhido por serviço
SANDBOX https://sandbox-api-<serviço>.termotubos.com.br
PRODUCTION https://api-<serviço>.termotubos.com.br

A tabela fica em termo_core/base/servicos.rs. No LOCALHOST, o TermoAI usa o endereço do sandbox (EnderecoNoLocalhost::MesmoEnderecoDoSandbox), então não é preciso levantar a IA na máquina. Sem AMBIENTE ou com um valor inválido, o processo para com uma mensagem clara: nunca cai em PRODUCTION por engano.

A única outra variável lida é SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH, o segredo do app gerado no TermoAuth (PATCH /app/{id} com gerar_segredo: true), guardado no secret do GitHub Actions e gravado no .env pelo deploy. Ela só é exigida por quem fala como aplicativo (veja abaixo).

Para apontar um serviço para outro endereço só num processo (ex.: teste): termo_core::substituir_endereco_do_servico_neste_processo(&termo_core::servicos::TERMO_AUTH, "http://...").

Serviços

Módulo Serviço
termo_core::ai TermoAI
termo_core::auth TermoAuth
termo_core::bucket TermoBucket
termo_core::intranet TermoIntranetAPI
termo_core::leads TermoLeads
termo_core::mcp TermoMCP
termo_core::portal TermoPortal
termo_core::quality TermoQuality
termo_core::sell TermoSell
termo_core::status TermoStatus
termo_core::studio TermoStudio
termo_core::support TermoSupport
termo_core::tracing TermoTracing
termo_core::webhook TermoWebhook
termo_core::wms TermoWMS

Cada módulo também é uma feature, todas ligadas por padrão (todos_os_servicos). Quem quiser compilar menos usa default-features = false, features = ["auth", "bucket"]. O webhook tem ainda webhook_publicar, webhook_receber e webhook_postgres (veja abaixo).

Eventos do TermoWebhook

Os contratos dos eventos são gerados dos esquemas cadastrados no hub, lidos de GET /esquemas.json do TermoWebhook (o TermoCore não acessa o banco de nenhum serviço). Cada aplicativo dono vira um módulo:

use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV1;

// Ao subir, uma vez (feature webhook_postgres):
termo_core::webhook::iniciar_envio_automatico_dos_eventos_guardados(&pool, termo_core::webhook::ConfiguracaoDoHub::carregar_do_ambiente_atual()).await?;

// No model, dentro da transação que já grava a mudança:
termo_core::webhook::guardar_evento_para_publicar_na_mesma_transacao(&mut *transacao, id.to_string(), ColaboradorCriadoV1 { /* ... */ }).await?;

// Na rota que recebe as entregas (feature webhook_receber):
let evento = termo_core::webhook::receber_evento_conferido_do_hub::<ColaboradorCriadoV1>(&cabecalhos, &corpo).await?;

O endereço do hub vem do AMBIENTE. A publicação manda Authorization: Bearer <token do aplicativo> (token_do_aplicativo()), então quem publica só informa SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH; o hub reconhece o app pelo sub do token. Sem a variável, ConfiguracaoDoHub::carregar_do_ambiente_atual() devolve None e os eventos só são impressos no terminal. Quem recebe entregas informa TERMOWEBHOOK_APLICATIVO_ID.

Como o código é gerado

cargo run -p gerador                # sincronizar + gerar
cargo run -p gerador -- sincronizar # baixa o openapi.json de cada serviço e o /esquemas.json do TermoWebhook (do SANDBOX) para openapi/
cargo run -p gerador -- gerar       # gera termo_core/<serviço>/rotas.rs e tipos.rs, e termo_core/webhook/eventos/contratos.rs
  • openapi/ fica no git: toda mudança de API aparece no diff.
  • rotas.rs, tipos.rs e eventos/contratos.rs nunca são editados à mão. Código feito à mão fica em outros arquivos do módulo (como publicar.rs e receber.rs do webhook).
  • Serviço novo: adicione a constante em termo_core/base/servicos.rs e em TODOS_OS_SERVICOS, a feature e o pub mod no termo_core, e rode o gerador. Ele cria o mod.rs do módulo novo.

Publicação

O workflow publicar-termo-core.yml roda a cada push na production, manualmente ou por repository_dispatch (contratos_atualizados). Ele sincroniza, gera, testa, faz commit dos contratos que mudaram e publica o termo_core no crates.io quando o código mudou, subindo o último número da versão. Usa o segredo CARGO_REGISTRY_TOKEN.