Ir para o conteúdo

Visão geral da API

fast-param-manager é o servidor do produto: uma API FastAPI sobre MongoDB, com autenticação delegada ao Keycloak e instrumentação OpenTelemetry de ponta a ponta.

Responsabilidades

Faz Não faz
Guarda parâmetros agrupados por aplicação Não notifica ninguém quando um valor muda
Valida o valor contra o tipo declarado Não converte tipo automaticamente
Cifra secret, user e users Não guarda histórico de valores
Autoriza escrita por papel Não protege leitura por padrão
Emite spans e métricas de toda operação Não negocia versão de cliente

Superfície pública

Três grupos de rotas, com regimes de acesso diferentes:

Prefixo Para que serve Quem entra
/auth Emissão e renovação de token, dados do usuário Aberto para emitir, autenticado para userinfo
/parameters O CRUD de aplicações e parâmetros Varia por rota — ver Endpoints
/admin Configuração em runtime Só administrador

O detalhe rota a rota, com corpo de requisição e de resposta, está em Endpoints.

Modelo de dados

Uma aplicação é um documento; os parâmetros são um mapa dentro dele. Cada parâmetro carrega o valor mais os metadados que governam a validação:

{
  "value": "postgres://...",
  "description": "String de conexão do banco de relatórios",
  "type": "secret",
  "user_editable": false,
  "min_length": 0,
  "max_length": 30,
  "min_value": 0,
  "max_value": 1000000,
  "referenced_params": null
}

Os defaults dos limites surpreendem

max_length vale 30 por padrão e min_value vale 0. Isso significa que uma string de 40 caracteres é rejeitada e que um número negativo é rejeitado — em ambos os casos sem ninguém ter configurado nada. Os limites são detalhados em Tipos de parâmetro.

Na leitura, cada parâmetro volta enriquecido com auditoria: created_at, created_by, updated_at e updated_by.

Como uma requisição atravessa a API

O servidor é estritamente em camadas, e a regra que sustenta tudo é uma só: o controller nunca toca no banco.

flowchart TD
    accTitle: Caminho de uma requisição na API
    accDescr: A requisição entra pelo middleware que valida o token do Keycloak, desce por controllers, services e repositories, e termina no MongoDB. Keycloak, crypto_utils e OpenTelemetry ficam ao lado, ligados à camada que os usa.

    C["Cliente HTTP<br/>param-manager · curl · frontend"]

    subgraph servidor["fast-param-manager"]
        direction TB
        M["middlewares/keycloak_auth<br/>valida JWT RS256 via PyJWKClient<br/>get_current_user · require_admin"]
        K["controllers/ — routers FastAPI<br/>wiring por Depends<br/>get_read_user resolve READ_AUTH_MODE<br/>off · warn · enforce"]
        S["services/ — regras de negócio<br/>AppService · RuntimeConfigService<br/>_validate_permission · _encrypt_value"]
        R["repositories/ — acesso ao Mongo<br/>AppRepository · RuntimeConfigRepository<br/>compare-and-swap por params_version"]
    end

    D[("MongoDB<br/>singleton aberto e fechado no lifespan")]
    KC["Keycloak — externo<br/>emite e assina o token<br/>/auth/token · /refresh · /userinfo"]
    CR["security/crypto_utils<br/>PBKDF2 100k + AES-GCM<br/>salt · master_key · crypto_data"]
    OT["OpenTelemetry<br/>span por operação<br/>+ métricas"]

    C --> M
    M --> K
    K --> S
    S --> R
    R --> D

    M -. JWKS .-> KC
    S -. secret/user/users .-> CR
    K -. span .-> OT
    S -. span .-> OT
    R -. span .-> OT

Cada camada tem uma responsabilidade que as outras não têm licença para assumir: toda regra de negócio está em services/, todo acesso a dados em repositories/, e o controller apenas traduz HTTP em chamada de negócio. O detalhamento de cada camada, com o contrato de teste que a injeção por Depends cria, está em Arquitetura.

O portão de acesso de cada rota — leitura, token ou admin — está na tabela de Endpoints.

Versões que não batem

Um aviso honesto para quem for empacotar ou liberar: hoje existem três declarações de versão que discordam entre si no repositório do servidor.

Onde Valor
pyproject.toml 0.1.0
CHANGELOG.md 2.0.0
API_VERSION e service.version nos traces 2.0.0

Além disso, o CHANGELOG.md foi escrito à mão num formato que não corresponde ao title_format configurado, e o towncrier nunca rodou neste projeto. Rodar towncrier build sem resolver isso antes produz um changelog corrompido.