Visão geral¶
O problema¶
Configuração espalhada em arquivo .env por máquina tem três defeitos que só
aparecem quando o sistema cresce: ninguém sabe qual é o valor corrente em
produção, mudar um valor exige um deploy, e senha em texto puro acaba em backup,
em log e no histórico do git.
Centralizar num serviço resolve os três — e cria um quarto: agora a aplicação não sobe se o serviço de configuração estiver fora. O Param Manager é desenhado em torno dessa troca. O cliente nunca depende de a API estar de pé no instante da leitura.
Os dois artefatos¶
fast-param-manager |
param-manager |
|
|---|---|---|
| O que é | API HTTP | Biblioteca Python |
| Onde roda | Servidor, em contêiner | Dentro da sua aplicação |
| Distribuição | Imagem / deploy próprio | PyPI — pip install param-manager |
| Guarda o quê | MongoDB | TinyDB local, como cópia de sobrevivência |
| Versão | 2.1.0 |
0.6.0 |
Eles são versionados e liberados de forma independente. Não existe deploy atômico dos dois: sempre há uma janela em que um cliente antigo conversa com um servidor novo. Essa é a restrição que mais molda o desenho do produto, e ela tem página própria — Compatibilidade.
Há também um aplicativo de desktop, que não é um terceiro artefato: ele vem
dentro do próprio param-manager, como extra (pip install "param-manager[front]",
Python 3.11 a 3.13), e fala com a API só através da biblioteca.
O que a API faz¶
- Guarda parâmetros agrupados por aplicação. Uma aplicação é um documento no Mongo; os parâmetros são um mapa dentro dele.
- Valida o tipo de cada valor. São quinze tipos, de
stringausers, cada um com um validador próprio — inclusive regex compilável, data em formato fixo e referência a outro parâmetro que precisa existir. - Cifra o que é sensível. Os tipos
secret,usereusersnunca são gravados em claro. - Decide quem escreve o quê. Administrador faz tudo; usuário comum só
altera o campo
valuede parâmetros marcados como editáveis. - Conta a própria operação. Todo controller, service e repository abre um span do OpenTelemetry e grava métricas.
O que o cliente faz¶
- Resolve um parâmetro pela cadeia mais barata primeiro: cache do parâmetro, cache da aplicação, e só então a rede.
- Para de bater num servidor doente. Erro de rede ou HTTP arma um circuit breaker com janela configurável.
- Sobrevive à API fora do ar. Todo parâmetro lido com sucesso é gravado num TinyDB local, que vira a fonte quando a rede falha.
- Decifra os segredos com a chave de custódia da aplicação, sem que o chamador precise saber que havia criptografia no caminho.
- Isola instâncias.
ParamManageré um multiton: uma instância por nome, cada uma com sua configuração, seu cache e seu arquivo local.
O que o produto deliberadamente não faz¶
Vale saber o que não procurar aqui:
- Não negocia versão de cliente. O servidor não sabe com quem está falando e não muda de comportamento por causa disso.
- Não distribui mudança em tempo real. Não há push, websocket nem invalidação remota de cache. Um valor alterado chega ao cliente quando o cache dele expira.
- Não protege leitura por padrão. De fábrica, ler parâmetro é anônimo. Isso é configurável em runtime, e a página de autenticação explica por que o default é esse e como sair dele com segurança.
- Não versiona o valor de um parâmetro. Existe um contador de versão por aplicação, usado para detectar escrita concorrente — não é histórico, e não dá para voltar atrás.