TermoCore
Todos os clientes da Termotubos num pacote só, o termo_core, em Rust (crates.io, em packages/rust) e em TypeScript (npm, em packages/typescript, para frontend e backend). 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, com o mesmo nome nas duas linguagens. O uso em TypeScript está no README do pacote npm.
= "=0.1.5" # todos os serviços
= { = "=0.1.5", = ["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 = token_do_usuario_logado;
let usuario = buscar_pelo_id_usuario.await?;
let pagina = buscar_paginador_usuario
.await?;
Token do aplicativo (conversa entre back-ends)
let credencial_de_acesso = token_do_aplicativo.await?;
let resposta = /* rota de sistema */.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 packages/rust/base/servicos.rs (o gerador copia para packages/typescript/base/servicos.ts). 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 ColaboradorCriadoV1;
// Ao subir, uma vez (feature webhook_postgres):
iniciar_envio_automatico_dos_eventos_guardados.await?;
// No model, dentro da transação que já grava a mudança:
guardar_evento_para_publicar_na_mesma_transacao.await?;
// Na rota que recebe as entregas (feature webhook_receber):
let evento = .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 não informa nada a mais: o destino assinado pelo hub é o id do app no TermoAuth (app do token de aplicativo, identificador_do_aplicativo()), o mesmo id do aplicativo no hub. Sem o segredo do app, a entrega responde 503 e o hub reenvia.
Como o código é gerado
gerador/
leitura_do_openapi.rs lê rotas, parâmetros, corpo, resposta e o catálogo de eventos (comum às duas linguagens)
rust/ escreve packages/rust/<serviço>/{rotas,tipos}.rs e webhook/eventos/contratos.rs
typescript/ escreve packages/typescript/<serviço>/{rotas,tipos,index}.ts, base/servicos.ts, index.ts e webhook/eventos/
packages/
rust/ crate termo_core (crates.io)
typescript/ pacote termo_core (npm)
openapi/fica no git: toda mudança de API aparece no diff.- O código gerado nunca é editado à mão. Código feito à mão fica em outros arquivos (como
publicar.rsereceber.rsdowebhookno Rust, e a pastabase/do TypeScript, menosservicos.ts). - Serviço novo: adicione a constante em
packages/rust/base/servicos.rse emTODOS_OS_SERVICOS, a feature e opub modnotermo_core, e rode o gerador. Ele cria omod.rsdo módulo novo e o módulo TypeScript inteiro.
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 (segredo CARGO_REGISTRY_TOKEN) e no npm (segredo NPM_TOKEN), cada um só quando o código dele mudou, subindo o último número da versão de cada pacote.