Ir para o conteúdo

Visão geral do cliente

param-manager é a biblioteca Python que consome a API. Está publicada no PyPI na versão 0.6.0 e é instalada dentro da sua aplicação.

from param_manager import ParamManager

pm = ParamManager.get_instance()
timeout = pm.get_param('MEU_APP', 'TIMEOUT_HTTP')

O que ela resolve

Ler configuração de um serviço remoto cria uma dependência nova no caminho crítico da sua aplicação. A biblioteca existe para que essa dependência degrade em vez de falhar:

  • Cache em dois níveis, para que a maioria das leituras nem toque na rede.
  • Circuit breaker, para parar de bater num servidor que está doente.
  • Cópia local em TinyDB, que responde quando a API não responde.
  • Decifragem transparente dos parâmetros sensíveis.

O preço disso é que o valor que você lê pode estar velho. Quanto, é você quem decide — ver Cache e modo offline.

Como uma leitura é resolvida

A cadeia abaixo é percorrida até algum degrau responder. A ordem não é acidental: cada degrau custa mais que o anterior, e o último existe para que a ausência da API seja degradação, e não falha.

flowchart TD
    accTitle: Resolução de um get_param no cliente
    accDescr: A leitura tenta primeiro o cache do parâmetro, depois o cache global do app, depois verifica o circuit breaker, e só então vai à rede. Cada verificação que dá positivo devolve o valor por um caminho próprio; a falha da rede arma o breaker e cai no TinyDB local.

    A["ParamManager<br/>multiton por instance_name"] --> D1{"cache do parâmetro<br/>ainda válido?"}

    D1 -- sim --> R1["retorna do cache do parâmetro"]
    D1 -- não --> D2{"cache global do app<br/>ainda válido?"}

    D2 -- sim --> R2["promove ao cache do parâmetro<br/>e retorna o valor"]
    D2 -- não --> D3{"breaker em cooldown?<br/>erro recente da API"}

    D3 -- sim --> R3["TinyDB local — modo offline<br/>params_&lt;instance&gt;.json"]
    D3 -- não --> B["GET /parameters/apps/.../params/...<br/>requests · timeout · verify_ssl<br/>headers de auth opcionais"]

    B --> D4{"resposta 200 OK?"}

    D4 -- não --> R4["404, timeout, conexão ou 5xx<br/>arma o breaker e chama<br/>_handle_api_error: TinyDB ou None"]
    D4 -- sim --> R5["é envelope? descriptografa<br/>AES-GCM + CHAVE_CUSTODIA_APP<br/>grava cache e TinyDB, retorna"]

A escrita não tem nada disso. Ela sempre vai à rede, sempre com token, e nunca consulta o cache:

flowchart LR
    accTitle: Caminho de escrita no cliente
    accDescr: As quatro operações de escrita ignoram o cache e o TinyDB, exigem token e vão direto à API.

    W["create_app · upsert_params<br/>delete_param · delete_app"] --> T["_auth_headers<br/>token obrigatório"]
    T --> API["API"]
    W -. nunca consulta .-x CACHE["cache · TinyDB"]

O detalhamento de cada degrau — validade do cache, o que arma e o que desarma o breaker, e o que acontece em cada modo de falha — está em Cache e modo offline.

Multiton, não singleton

ParamManager não é um singleton. É um multiton: uma instância por instance_name, guardadas num dicionário de classe protegido por lock.

producao = ParamManager.get_instance(instance_name='producao')
homolog  = ParamManager.get_instance(instance_name='homolog')

As duas têm URL, credencial, cache e arquivo local independentes.

A documentação antiga da biblioteca diz 'Singleton'

O README do param-manager e páginas antigas do site dele afirmam que a classe implementa o padrão Singleton, com __instance e cache de uma hora. Isso descreve uma versão que não existe mais. O que vale é o que está aqui.

__init__ retorna cedo quando a instância já foi inicializada, então construir ParamManager(instance_name='x') duas vezes devolve o mesmo objeto sem refazer nada.

A superfície pública

O pacote exporta exatamente dois nomes:

from param_manager import ParamManager, ParamNaoEncontradoError

Leitura

Método Devolve
get_param(app_name, param_name, save_cache=True) O valor, já decifrado
get_all_params(app_name) Mapa de nome para valor

Escrita

Método Observação
create_app(name, description=None) Espera 201 do servidor
upsert_params(app_name, param_name, *, value, param_type, ...) Um parâmetro por chamada
delete_param(app_name, param_name)
delete_app(app_name)

Escrita sempre vai à rede, sempre com token, e nunca consulta cache.

Cache

Método Observação
clear_cache(app_name=None, param_name=None) Sem argumento, limpa tudo
get_cache_info() Estado dos caches, validade e marcas de erro

Métodos que a documentação antiga promete e não existem

update_param(...) e get_param_schema(...) aparecem no tutorial do site do param-manager. Nenhum dos dois existe. Para alterar um valor, use upsert_params.

Versões de Python

requires-python = ">=3.10", sem teto. Uma biblioteca pura não tem como saber que vai quebrar numa versão que ainda não existe, e o teto antigo, <=3.14, recusava até o 3.14.1.

O piso subiu de 3.8 para 3.10 por segurança, não por sintaxe: python-dotenv==1.2.2 corrige a PYSEC-2026-2270 e não é publicado abaixo de 3.10. Em 3.9 o teto alcançável ainda é vulnerável; em 3.8, pior. Baixar o piso significa voltar a distribuir a falha.