termo_core 0.1.66

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 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.

termo_core = "=0.1.5"                                          # todos os serviços
termo_core = { version = "=0.1.5", features = ["segredo_de_app"] }   # + busca automática do segredo do app

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); 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://...").

Toda requisição tem tempo limite de 30 s. Para um serviço que demora mais (ex.: gerar imagem no gateway do TermoAI), o processo troca o limite ao subir: termo_core::definir_tempo_limite_do_servico_neste_processo(&termo_core::servicos::TERMO_AI, Duration::from_secs(300)). No TypeScript é o mesmo, em milissegundos (definir_tempo_limite_do_servico_neste_processo(servicos.TERMO_AI, 300_000)), e cada chamada ainda aceita tempo_limite_em_milissegundos.

Serviços

Módulo Serviço
termo_core::agenda TermoAgenda
termo_core::ai TermoAI
termo_core::auth TermoAuth
termo_core::bucket TermoBucket
termo_core::flow TermoFlow
termo_core::intranet TermoIntranetAPI
termo_core::leads TermoLeads
termo_core::mcp TermoMCP
termo_core::meet TermoMeet
termo_core::miro TermoBoard
termo_core::portal TermoPortal
termo_core::quality TermoQuality
termo_core::status TermoStatus
termo_core::studio TermoStudio
termo_core::support TermoSupport
termo_core::talk TermoTalk
termo_core::tracing TermoTracing
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"]. A feature segredo_de_app liga a busca automática do segredo do app no TermoAuth.

Como o código é gerado

cargo run -p gerador                # sincronizar + gerar
cargo run -p gerador -- sincronizar # baixa o openapi.json de cada serviço (do SANDBOX) para openapi/
cargo run -p gerador -- gerar       # gera packages/rust e packages/typescript a partir de openapi/
gerador/
  leitura_do_openapi.rs   lê rotas, parâmetros, corpo e resposta (comum às duas linguagens)
  rust/                   escreve packages/rust/<serviço>/{rotas,tipos}.rs
  typescript/             escreve packages/typescript/<serviço>/{rotas,tipos,index}.ts, base/servicos.ts e index.ts
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 a pasta base/ do Rust e a do TypeScript, menos servicos.ts). Tudo o que o crate tem, o pacote npm também tem.
  • Serviço novo: adicione a constante em packages/rust/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 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.

Ao terminar com sucesso, o release-termo-core.yml cria uma GitHub Release crate-<versão>-npm-<versão> com as versões publicadas, que serve de gatilho para outras rotinas. Se nenhuma versão mudou, nenhuma release nova é criada.