Sistema de Ambiente

Gerencia variáveis de ambiente através de backends de armazenamento configuráveis.

Visão Geral

O sistema de ambiente separa armazenamento de acesso:

  • Armazenamentos - Onde valores são armazenados (SO, arquivos, memória)
  • Variáveis - Referências nomeadas a valores em armazenamentos

Variáveis podem ser referenciadas por:

  • Nome público - O valor do campo variable (deve ser único no sistema)
  • ID de entrada - Referência completa namespace:name

Se você não quer que uma variável seja publicamente acessível pelo nome, omita o campo variable.

Tipos de Entradas

Tipo Descrição
env.storage.memory Armazenamento chave-valor em memória
env.storage.file Armazenamento baseado em arquivo (formato .env)
env.storage.os Acesso somente leitura ao ambiente do SO
env.storage.static Armazenamento estático somente leitura de chave-valor
env.storage.router Encadeia múltiplos armazenamentos
env.variable Variável nomeada referenciando um armazenamento

Backends de Armazenamento

Armazenamento em Memória

Armazenamento volátil em memória.

- name: runtime_env
  kind: env.storage.memory

Armazenamento em Arquivo

Armazenamento persistente usando formato de arquivo .env (KEY=VALUE com comentários #).

- name: app_config
  kind: env.storage.file
  file_path: /etc/app/config.env
  auto_create: true
  file_mode: 0600
  dir_mode: 0700
Propriedade Tipo Padrão Descrição
file_path string obrigatório Caminho para arquivo .env
auto_create boolean false Cria arquivo se ausente
file_mode integer 0644 Permissões do arquivo
dir_mode integer 0755 Permissões do diretório

Armazenamento do SO

Acesso somente leitura a variáveis de ambiente do sistema operacional.

- name: os_env
  kind: env.storage.os

Sempre somente leitura. Operações de escrita retornam PERMISSION_DENIED.

Armazenamento Estático

Armazenamento somente leitura com valores definidos diretamente na configuração. Os valores são incorporados na entrada e não podem ser alterados em tempo de execução. Útil para constantes de configuração públicas que acompanham um módulo ou pacote.

- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    PUBLIC_WS_HOST: "wss://api.example.com/ws"
    APP_ENV: "production"
Propriedade Tipo Descrição
values map Pares chave-valor (string para string)

Sempre somente leitura. Operações de escrita retornam PERMISSION_DENIED.

Armazenamento Router

Encadeia múltiplos armazenamentos. Leituras buscam em ordem até encontrar. Escritas vão para o primeiro armazenamento apenas.

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Principal (escreve aqui)
    - app.config:file      # Fallback
    - app.config:os        # Fallback
Propriedade Tipo Descrição
storages array Lista ordenada de referências de armazenamento

Variáveis

Variáveis fornecem acesso nomeado a valores de armazenamento.

- name: DATABASE_URL
  kind: env.variable
  variable: DATABASE_URL
  storage: app.config:file
  default: postgres://localhost/app
  read_only: false
Propriedade Tipo Descrição
variable string Nome público da variável (opcional, deve ser único)
storage string Referência de armazenamento (namespace:name)
default string Valor padrão se não encontrado
read_only boolean Previne modificações

Nomenclatura de Variáveis

Nomes de variáveis devem conter apenas: a-z, A-Z, 0-9, _

Padrões de Acesso

# Variável pública - acessível pelo nome "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Variável privada - acessível apenas pelo ID "app.config:internal_key"
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

Erros

Condição Tipo Retentável
Variável não encontrada errors.NOT_FOUND não
Armazenamento não encontrado errors.NOT_FOUND não
Variável é somente leitura errors.PERMISSION_DENIED não
Armazenamento é somente leitura errors.PERMISSION_DENIED não
Nome de variável inválido errors.INVALID não

Acesso em Tempo de Execução

Veja Também