Referência de Configuração

Referência de Configuração

O Wippy é configurado via arquivos .wippy.yaml. Todas as opções têm padrões sensíveis.

Qualquer valor abaixo pode ser sobrescrito na inicialização com wippy run --set section.path=value (repetível, tem precedência sobre o arquivo). Para sobrescrever entradas individuais do registro em vez destas seções de configuração, use a seção override: ou -o — veja Sobrescrevendo Entradas.

Logger

Controla o encoder do logger zap. Flags do CLI (-v, -c, -s) sobrescrevem nível/saída; a única opção controlada por yaml é a codificação.

Campo	Tipo	Padrão	Descrição
encoding	string	console	Encoder: console (legível) ou json (estruturado)

logger:
  encoding: json

Gerenciador de Log

Controla o roteamento de logs do runtime. A saída do console é configurada via flags do CLI (-v, -c, -s).

Campo	Tipo	Padrão	Descrição
propagate_downstream	bool	true	Envia logs para saída console/arquivo
stream_to_events	bool	false	Publica logs no barramento de eventos para acesso programático
min_level	int	-1	Nível mínimo: -1=debug, 0=info, 1=warn, 2=error

logmanager:
  propagate_downstream: true
  stream_to_events: false
  min_level: 0

Veja: Módulo Logger

Profiler

Servidor HTTP pprof do Go para profiling de CPU/memória. Habilite com a flag -p ou configuração.

Campo	Tipo	Padrão	Descrição
enabled	bool	false	Inicia servidor do profiler
address	string	localhost:6060	Endereço de escuta
read_timeout	duration	15s	Timeout de leitura HTTP
write_timeout	duration	15s	Timeout de escrita HTTP
idle_timeout	duration	60s	Timeout de keep-alive

profiler:
  enabled: true
  address: "localhost:6060"

Acesse em http://localhost:6060/debug/pprof/

Segurança

Comportamento de segurança global. Políticas individuais são definidas como entradas security.policy.

Campo	Tipo	Padrão	Descrição
strict_mode	bool	false	Nega acesso quando contexto de segurança está incompleto

security:
  strict_mode: true

Veja: Sistema de Segurança, Módulo Security

Registro

Armazenamento de entradas e histórico de versões. O registro armazena todas as entradas de configuração.

Campo	Tipo	Padrão	Descrição
enable_history	bool	true	Rastreia versões de entradas
history_type	string	memory	Armazenamento: memory, sqlite, nil
history_path	string	.wippy/registry.db	Caminho do arquivo SQLite

registry:
  history_type: sqlite
  history_path: /var/lib/wippy/registry.db

Veja: Conceito de Registro, Módulo Registry

Relay

Roteamento de mensagens entre processos através de nós.

Campo	Tipo	Padrão	Descrição
node_name	string	local	Identificador para este nó de relay

relay:
  node_name: worker-1

Veja: Modelo de Processos

Supervisor

Gerenciamento de ciclo de vida de serviços. Controla a caixa de mensagens de controle interna do supervisor usada para despachar eventos de ciclo de vida.

Campo	Tipo	Padrão	Descrição
host.buffer_size	int	1024	Capacidade da caixa de mensagens de controle interna
host.worker_count	int	16	Workers despachantes concorrentes

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

Veja: Guia de Supervisão

Workers e filas por `process.host` são configurados na própria entrada (`workers`, `queue_size`, `local_queue_size`), não nesta seção global. Veja o tipo de entrada [Process Host](system/process-host.md).

Runtime Lua

Cache de VM Lua e avaliação de expressões.

Campo	Tipo	Padrão	Descrição
proto_cache_size	int	60000	Cache de protótipos compilados
main_cache_size	int	10000	Cache de chunks principais
cache.enabled	bool	false	Persistir cache de bytecode/typecheck compilado em disco
cache.dir	string	(diretório de cache do sistema)	Caminho do diretório de cache
cache.mode	string	read_write	Modo de cache: read_write, read_only, write_only
type_system.enabled	bool	false	Habilitar verificação estática de tipos
type_system.strict	bool	false	Tratar avisos de tipo como erros

lua:
  proto_cache_size: 60000
  cache:
    enabled: true
    dir: .cache/lua
  type_system:
    enabled: true

Veja: Visão Geral Lua

Finder

Cache de busca do registro. Usado internamente para consultas de entradas.

Campo	Tipo	Padrão	Descrição
query_cache_size	int	1000	Resultados de consulta em cache
regex_cache_size	int	100	Padrões regex compilados

finder:
  query_cache_size: 2000

OpenTelemetry

Tracing distribuído e exportação de métricas via OTLP.

Campo	Tipo	Padrão	Descrição
enabled	bool	false	Habilita OTEL
endpoint	string	localhost:4318	Endpoint OTLP
protocol	string	http/protobuf	Protocolo: grpc, http/protobuf
service_name	string	wippy-runtime	Identificador do serviço
service_version	string		Tag de versão do serviço
insecure	bool	true	Permite conexão OTLP em texto plano
sample_rate	float	1.0	Amostragem de trace (0.0-1.0)
propagators	string[]	[tracecontext, baggage]	Propagadores de contexto
traces_enabled	bool	true	Exporta traces
metrics_enabled	bool	false	Exporta métricas
http.enabled	bool	true	Rastreia requisições HTTP
http.extract_headers	bool	true	Extrai contexto de trace dos cabeçalhos de entrada
http.inject_headers	bool	true	Injeta contexto de trace nos cabeçalhos de saída
process.enabled	bool	true	Rastreia ciclo de vida de processos
process.trace_lifecycle	bool	true	Emite spans para spawn/terminate
interceptor.enabled	bool	true	Rastreia chamadas de funções
interceptor.order	int	100	Prioridade do interceptor
queue.enabled	bool	true	Rastreia publicação/consumo de filas
temporal.enabled	bool	false	Rastreia workflows do Temporal

otel:
  enabled: true
  endpoint: "http://jaeger:4318"
  traces_enabled: true
  process:
    trace_lifecycle: true

Variáveis de ambiente OTEL padrão (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_TRACES_SAMPLER_ARG, OTEL_PROPAGATORS, OTEL_SDK_DISABLED) sobrescrevem os campos correspondentes.

Veja: Guia de Observabilidade

Shutdown

Comportamento de encerramento gracioso.

Campo	Tipo	Padrão	Descrição
timeout	duration	30s	Tempo máximo de espera para componentes pararem

shutdown:
  timeout: 60s

Métricas

Buffer de coleta de métricas internas.

Campo	Tipo	Padrão	Descrição
buffer.size	int	10000	Capacidade do buffer de métricas
interceptor.enabled	bool	false	Rastreia chamadas de funções automaticamente

metrics:
  buffer:
    size: 20000
  interceptor:
    enabled: true

Veja: Módulo Metrics, Guia de Observabilidade

Prometheus

Endpoint de métricas Prometheus.

Campo	Tipo	Padrão	Descrição
enabled	bool	false	Inicia servidor de métricas
address	string	localhost:9090	Endereço de escuta

prometheus:
  enabled: true
  address: "0.0.0.0:9090"

Expõe endpoint /metrics para scraping do Prometheus.

Veja: Guia de Observabilidade

Cluster

Clustering multi-nó: associação gossip mais um núcleo Raft de consenso limitado. Consulte o Guia de Cluster para a arquitetura e modelo operacional; esta seção é a referência de chaves de configuração.

Nível superior

Campo	Tipo	Padrão	Descrição
enabled	bool	false	Habilita clustering
name	string	hostname	Nome do nó; deve ser único no cluster
failure_domain	string		Label de zona/rack; anunciado via gossip para que voters se distribuam entre domínios

Associação (gossip)

Gossip SWIM via memberlist. Usado para descoberta de nós, detecção de falhas e disseminação de metadados.

Campo	Tipo	Padrão	Descrição
membership.bind_addr	string	0.0.0.0	Endereço de bind do gossip
membership.bind_port	int	7946	Porta de bind do gossip (TCP+UDP)
membership.advertise_addr	string		Endereço que os peers usam para alcançar este nó (NAT/k8s)
membership.join_addrs	string		Pares seed host:port separados por vírgula
membership.secret_key	string		Chave de criptografia gossip codificada em base64 (inline)
membership.secret_file	string		Caminho para arquivo contendo a chave de criptografia gossip

Internós (transporte)

Malha TCP que transporta o tráfego de relay e Raft entre nós. O Raft usa esta malha (multiplexado com yamux); não há porta Raft separada.

Campo	Tipo	Padrão	Descrição
internode.bind_addr	string	0.0.0.0	Endereço de bind da malha
internode.bind_port	int	0	Porta da malha (0 = auto: 7950-7959, depois efêmera)
internode.auto_port	bool	true	Descobrir a porta real no boot, fixá-la e anunciá-la via gossip

Raft (consenso)

Raft limitado. O estado do Raft é durável em disco por padrão, armazenado sob raft.data_dir (padrão ~/.wippy/store); um nó reiniciado ainda rejoina o quórum a partir dos peers. As entradas store.kv.raft replicam através dele. O bootstrap é conduzido por gossip (estilo bootstrap_expect do Consul/Nomad).

Campo	Tipo	Padrão	Descrição
raft.data_dir	string	~/.wippy/store	Diretório para o estado durável do Raft em disco e snapshots duráveis do CRDT (sob <data_dir>/_sys/). Sem disco apenas quando nenhum caminho é resolvido (sem diretório home e nenhum definido)
raft.enabled	bool	true	Executa um nó Raft; false torna este um cliente apenas gossip
raft.role	string	server	server executa um nó Raft; client é apenas gossip
raft.eligible	bool	true	Se este nó pode ser selecionado como voter
raft.priority	int	100	Prioridade de seleção de voter (menor é preferido)
raft.bootstrap_expect	int	1	Tamanho inicial do quórum: 0=apenas se juntar a um existente, 1=nó único, N=aguardar N peers elegíveis antes de formar quórum
raft.max_voters	int	5	Teto de voters (deve ser ímpar); nós elegíveis extras tornam-se standbys
raft.max_standbys	int	4	Membros não-votantes mantidos prontos para promoção; nós além de voters+standbys não são membros Raft
raft.reconcile_debounce	duration	2s	Janela de coalescência após um evento gossip antes do reconciliador de voters executar
raft.reconcile_timeout	duration	2s	Limite por passagem de reconciliação
raft.heartbeat_timeout	duration	3s	Tempo de espera ocioso do follower antes de iniciar uma eleição
raft.election_timeout	duration	3s	Timeout de eleição do candidato (limitado a >= heartbeat)
raft.commit_timeout	duration	500ms	Cadência de heartbeat do leader ocioso
raft.snapshot_threshold	uint64	8192	Entradas de log desde o último snapshot antes de criar um novo
raft.snapshot_interval	duration	2m	Intervalo de verificação de snapshot
raft.snapshot_retain	int	3	Snapshots retidos
raft.trailing_logs	uint64	10240	Entradas de log retidas após um snapshot
raft.max_append_entries	int	16	Máximo de entradas por RPC AppendEntries
raft.leader_probe_interval	duration	3s	Cadência de sondagem de alcançabilidade do leader do registro global
raft.leader_probe_grace	int	3	Falhas consecutivas de sondagem antes de declarar o leader inacessível

Nó único (desenvolvimento) — clustering ativo, bootstrap imediato:

cluster:
  enabled: true
  name: dev
  raft:
    bootstrap_expect: 1

Cluster de três voters — cada nó lista os outros como seeds e aguarda os três antes de formar quórum:

cluster:
  enabled: true
  name: node-1
  failure_domain: us-east-1a
  membership:
    bind_port: 7946
    join_addrs: "node-2:7946,node-3:7946"
    secret_file: /etc/wippy/cluster.key
  raft:
    bootstrap_expect: 3
    max_voters: 5

Cliente apenas gossip — junta-se ao cluster para nomeação/mensagens mas nunca executa Raft:

cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
  raft:
    role: client

LSP

Servidor do Language Server Protocol para integrações com editores.

Campo	Tipo	Padrão	Descrição
enabled	bool	false	Habilitar o servidor TCP
address	string	:7777	Endereço de escuta TCP
http_enabled	bool	false	Habilitar o transporte HTTP
http_address	string	:7778	Endereço de escuta HTTP
http_path	string	/lsp	Caminho do endpoint HTTP
http_allow_origin	string	*	Origem permitida por CORS
max_message_bytes	int	8388608	Tamanho máximo de mensagem recebida

lsp:
  enabled: true
  address: ":7777"
  http_enabled: true

Veja: Guia do LSP

Serviço de Rede

Gerenciador de redes overlay (drivers SOCKS5, I2P, Tailscale).

Campo	Tipo	Padrão	Descrição
state_dir	string	.wippy/net	Diretório de armazenamento do estado do driver
default_network	string		ID de rede padrão aplicado quando entradas omitem network

network_service:
  state_dir: /var/lib/wippy/net
  default_network: app:tailscale

Veja: Overlays de Rede

Dispatcher HTTP

Ajuste para o pool de clientes HTTP compartilhado usado por funções despachadas via HTTP e requisições de saída.

Campo	Tipo	Padrão	Descrição
dispatcher.http.timeout	duration	0 (nenhum)	Timeout por requisição
dispatcher.http.max_idle_conns	int	0 (stdlib)	Máximo de conexões ociosas em todos os hosts
dispatcher.http.max_idle_per_host	int	0 (stdlib)	Máximo de conexões ociosas por host
dispatcher.http.idle_conn_timeout	duration	0 (stdlib)	Timeout de conexão ociosa
dispatcher.http.max_clients	int	0 (ilimitado)	Máximo de clientes distintos em pool

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

Módulos

Cliente do registro de módulos usado por wippy install/update.

Campo	Tipo	Padrão	Descrição
registry_url	string	https://hub.wippy.ai	Endpoint do registro

modules:
  registry_url: https://internal-registry.example.com

Extensões

Extensões nativas de plugin Go carregadas no boot (somente Unix).

Campo	Tipo	Padrão	Descrição
enabled	bool	true	Carregar extensões
paths	string[]		Caminhos dos arquivos de plugin (relativos ao diretório de configuração)

extensions:
  enabled: true
  paths:
    - ./extensions/myplugin.so

Variáveis de Ambiente

Variável	Descrição
GOMEMLIMIT	Limite de memória (sobrescreve flag --memory-limit)

Veja Também

• Referência do CLI - Opções de linha de comando
• Guia de Cluster - Arquitetura e operações de clustering
• Tipos de Entradas - Todos os tipos de entradas
• Guia de Observabilidade - Logging, métricas, tracing