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", = ["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 = 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); 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
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, menosservicos.ts). Tudo o que o crate tem, o pacote npm também tem. - 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.
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.