Referencia de Configuración

Referencia de Configuración

Wippy se configura mediante archivos .wippy.yaml. Todas las opciones tienen valores por defecto razonables.

Cualquier valor a continuación puede sobrescribirse en el arranque con wippy run --set section.path=value (repetible, tiene prioridad sobre el archivo). Para sobrescribir entradas individuales del registro en lugar de estas secciones de configuración, usa la sección override: o -o — consulta Sobrescribir entradas.

Logger

Controla el codificador del logger zap. Los flags de CLI (-v, -c, -s) sobrescriben el nivel/salida; la única opción controlada por yaml es la codificación.

Campo	Tipo	Por defecto	Descripción
encoding	string	console	Codificador: console (humanizado) o json (estructurado)

logger:
  encoding: json

Gestor de Registros

Controla el enrutamiento de registros del runtime. La salida en consola se configura mediante flags de CLI (-v, -c, -s).

Campo	Tipo	Por defecto	Descripción
propagate_downstream	bool	true	Enviar registros a la salida de consola/archivo
stream_to_events	bool	false	Publicar registros al bus de eventos para acceso programático
min_level	int	-1	Nivel mínimo: -1=debug, 0=info, 1=warn, 2=error

logmanager:
  propagate_downstream: true
  stream_to_events: false
  min_level: 0

Ver: Módulo Logger

Profiler

Servidor HTTP de pprof de Go para perfilado de CPU/memoria. Habilitarlo con el flag -p o mediante configuración.

Campo	Tipo	Por defecto	Descripción
enabled	bool	false	Iniciar servidor de perfilado
address	string	localhost:6060	Dirección de escucha
read_timeout	duration	15s	Tiempo de espera de lectura HTTP
write_timeout	duration	15s	Tiempo de espera de escritura HTTP
idle_timeout	duration	60s	Tiempo de espera de keep-alive

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

Acceso en http://localhost:6060/debug/pprof/

Seguridad

Comportamiento de seguridad global. Las políticas individuales se definen como entradas security.policy.

Campo	Tipo	Por defecto	Descripción
strict_mode	bool	false	Denegar acceso cuando el contexto de seguridad está incompleto

security:
  strict_mode: true

Ver: Sistema de Seguridad, Módulo de Seguridad

Registro

Almacenamiento de entradas e historial de versiones. El registro almacena todas las entradas de configuración.

Campo	Tipo	Por defecto	Descripción
enable_history	bool	true	Rastrear versiones de entradas
history_type	string	memory	Almacenamiento: memory, sqlite, nil
history_path	string	.wippy/registry.db	Ruta del archivo SQLite

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

Ver: Concepto de Registro, Módulo de Registro

Relay

Enrutamiento de mensajes entre procesos a través de nodos.

Campo	Tipo	Por defecto	Descripción
node_name	string	local	Identificador de este nodo relay

relay:
  node_name: worker-1

Ver: Modelo de Procesos

Supervisor

Gestión del ciclo de vida de servicios. Controla el buzón de control interno del supervisor utilizado para despachar eventos de ciclo de vida.

Campo	Tipo	Por defecto	Descripción
host.buffer_size	int	1024	Capacidad del buzón de control interno
host.worker_count	int	16	Workers del despachador concurrentes

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

Ver: Guía de Supervisión

Los workers y colas por `process.host` se configuran en la propia entrada (`workers`, `queue_size`, `local_queue_size`), no en esta sección global. Ver el tipo de entrada [Process Host](system/process-host.md).

Runtime de Lua

Caché de la VM de Lua y evaluación de expresiones.

Campo	Tipo	Por defecto	Descripción
proto_cache_size	int	60000	Caché de prototipos compilados
main_cache_size	int	10000	Caché del chunk principal
cache.enabled	bool	false	Persistir caché de bytecode/verificación de tipos en disco
cache.dir	string	(directorio de caché del sistema)	Ruta del directorio de caché
cache.mode	string	read_write	Modo de caché: read_write, read_only, write_only
type_system.enabled	bool	false	Habilitar verificación estática de tipos
type_system.strict	bool	false	Tratar advertencias de tipos como errores

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

Ver: Visión General de Lua

Finder

Caché de búsqueda del registro. Usado internamente para búsquedas de entradas.

Campo	Tipo	Por defecto	Descripción
query_cache_size	int	1000	Resultados de consulta en caché
regex_cache_size	int	100	Patrones de regex compilados

finder:
  query_cache_size: 2000

OpenTelemetry

Exportación de trazas distribuidas y métricas via OTLP.

Campo	Tipo	Por defecto	Descripción
enabled	bool	false	Habilitar OTEL
endpoint	string	localhost:4318	Endpoint OTLP
protocol	string	http/protobuf	Protocolo: grpc, http/protobuf
service_name	string	wippy-runtime	Identificador del servicio
service_version	string		Etiqueta de versión del servicio
insecure	bool	true	Permitir conexión OTLP en texto plano
sample_rate	float	1.0	Muestreo de trazas (0.0-1.0)
propagators	string[]	[tracecontext, baggage]	Propagadores de contexto
traces_enabled	bool	true	Exportar trazas
metrics_enabled	bool	false	Exportar métricas
http.enabled	bool	true	Trazar solicitudes HTTP
http.extract_headers	bool	true	Extraer contexto de traza de cabeceras entrantes
http.inject_headers	bool	true	Inyectar contexto de traza en cabeceras salientes
process.enabled	bool	true	Trazar ciclo de vida de procesos
process.trace_lifecycle	bool	true	Emitir spans para spawn/terminate
interceptor.enabled	bool	true	Trazar llamadas a funciones
interceptor.order	int	100	Prioridad del interceptor
queue.enabled	bool	true	Trazar publicación/consumo de colas
temporal.enabled	bool	false	Trazar workflows de Temporal

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

Las variables de entorno estándar de OTEL (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_TRACES_SAMPLER_ARG, OTEL_PROPAGATORS, OTEL_SDK_DISABLED) sobrescriben los campos correspondientes.

Ver: Guía de Observabilidad

Apagado

Comportamiento de apagado controlado.

Campo	Tipo	Por defecto	Descripción
timeout	duration	30s	Tiempo máximo de espera para que los componentes se detengan

shutdown:
  timeout: 60s

Métricas

Buffer interno de recolección de métricas.

Campo	Tipo	Por defecto	Descripción
buffer.size	int	10000	Capacidad del buffer de métricas
interceptor.enabled	bool	false	Rastrear automáticamente llamadas a funciones

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

Ver: Módulo de Métricas, Guía de Observabilidad

Prometheus

Endpoint de métricas de Prometheus.

Campo	Tipo	Por defecto	Descripción
enabled	bool	false	Iniciar servidor de métricas
address	string	localhost:9090	Dirección de escucha

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

Expone el endpoint /metrics para el scraping de Prometheus.

Ver: Guía de Observabilidad

Cluster

Clustering multi-nodo: membresía por gossip más un núcleo de consenso Raft acotado. Ver la Guía de Cluster para la arquitectura y el modelo operativo; esta sección es la referencia de claves de configuración.

Nivel superior

Campo	Tipo	Por defecto	Descripción
enabled	bool	false	Habilitar clustering
name	string	hostname	Nombre del nodo; debe ser único en el cluster
failure_domain	string		Etiqueta de zona/rack; anunciada en gossip para que los votantes se distribuyan entre dominios

Membresía (gossip)

Gossip SWIM via memberlist. Usado para descubrimiento de nodos, detección de fallos y diseminación de metadatos.

Campo	Tipo	Por defecto	Descripción
membership.bind_addr	string	0.0.0.0	Dirección de enlace para gossip
membership.bind_port	int	7946	Puerto de enlace para gossip (TCP+UDP)
membership.advertise_addr	string		Dirección que los peers usan para llegar a este nodo (NAT/k8s)
membership.join_addrs	string		Pares de semilla host:port separados por coma
membership.secret_key	string		Clave de cifrado para gossip codificada en Base64 (en línea)
membership.secret_file	string		Ruta al archivo que contiene la clave de cifrado para gossip

Internodo (transporte)

Malla TCP que transporta el tráfico de relay y Raft entre nodos. Raft viaja por esta malla (multiplexada con yamux); no hay un puerto Raft separado.

Campo	Tipo	Por defecto	Descripción
internode.bind_addr	string	0.0.0.0	Dirección de enlace de la malla
internode.bind_port	int	0	Puerto de la malla (0 = automático: 7950-7959, luego efímero)
internode.auto_port	bool	true	Descubrir el puerto real en el arranque, fijarlo y anunciarlo en gossip

Raft (consenso)

Raft acotado. El estado de Raft es durable en disco por defecto, almacenado bajo raft.data_dir (por defecto ~/.wippy/store); un nodo reiniciado aún se une al quórum desde sus peers. Las entradas store.kv.raft se replican a través de él. El bootstrap es dirigido por gossip (estilo Consul/Nomad bootstrap_expect).

Campo	Tipo	Por defecto	Descripción
raft.data_dir	string	~/.wippy/store	Directorio para el estado de Raft durable en disco y los snapshots durables de CRDT (bajo <data_dir>/_sys/). Sin disco solo cuando no se resuelve ninguna ruta (sin directorio home y ninguna establecida)
raft.enabled	bool	true	Ejecutar un nodo Raft; false convierte este nodo en un cliente solo-gossip
raft.role	string	server	server ejecuta un nodo Raft; client es solo-gossip
raft.eligible	bool	true	Si este nodo puede ser seleccionado como votante
raft.priority	int	100	Prioridad de selección de votante (valor menor es preferido)
raft.bootstrap_expect	int	1	Tamaño inicial del quórum: 0=unirse a uno existente, 1=nodo único, N=esperar N peers elegibles para formar quórum
raft.max_voters	int	5	Límite de votantes (debe ser impar); los nodos elegibles adicionales se convierten en standbys
raft.max_standbys	int	4	Miembros no votantes mantenidos en espera para promoción; los nodos más allá de voters+standbys no son miembros Raft
raft.reconcile_debounce	duration	2s	Ventana de consolidación tras un evento de gossip antes de que se ejecute el reconciliador de votantes
raft.reconcile_timeout	duration	2s	Límite por pasada de reconciliación
raft.heartbeat_timeout	duration	3s	Tiempo de espera inactivo del seguidor antes de iniciar una elección
raft.election_timeout	duration	3s	Tiempo de espera de elección del candidato (limitado a >= heartbeat)
raft.commit_timeout	duration	500ms	Cadencia de heartbeat del líder inactivo
raft.snapshot_threshold	uint64	8192	Entradas de log desde el último snapshot antes de crear uno nuevo
raft.snapshot_interval	duration	2m	Intervalo de verificación de snapshots
raft.snapshot_retain	int	3	Snapshots retenidos
raft.trailing_logs	uint64	10240	Entradas de log retenidas tras un snapshot
raft.max_append_entries	int	16	Máximo de entradas por RPC AppendEntries
raft.leader_probe_interval	duration	3s	Cadencia de sonda de alcanzabilidad del líder del registro global
raft.leader_probe_grace	int	3	Fallos consecutivos de sonda antes de declarar al líder inalcanzable

Nodo único (desarrollo) — clustering activado, se bootstrapea inmediatamente:

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

Cluster de votación de tres nodos — cada nodo lista los otros como semillas y espera a los tres 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 solo-gossip — se une al cluster para naming/mensajería pero nunca ejecuta Raft:

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

LSP

Servidor del Protocolo de Servidor de Lenguaje para integraciones con editores.

Campo	Tipo	Por defecto	Descripción
enabled	bool	false	Habilitar el servidor TCP
address	string	:7777	Dirección de escucha TCP
http_enabled	bool	false	Habilitar el transporte HTTP
http_address	string	:7778	Dirección de escucha HTTP
http_path	string	/lsp	Ruta del endpoint HTTP
http_allow_origin	string	*	Origen permitido por CORS
max_message_bytes	int	8388608	Tamaño máximo de mensaje entrante

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

Ver: Guía de LSP

Servicio de Red

Gestor de red superpuesta (drivers SOCKS5, I2P, Tailscale).

Campo	Tipo	Por defecto	Descripción
state_dir	string	.wippy/net	Directorio de almacenamiento del estado del driver
default_network	string		ID de red por defecto aplicado cuando las entradas omiten network

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

Ver: Redes Superpuestas

Despachador HTTP

Ajuste del pool de clientes HTTP compartido utilizado por funciones despachadas HTTP y solicitudes salientes.

Campo	Tipo	Por defecto	Descripción
dispatcher.http.timeout	duration	0 (ninguno)	Tiempo de espera por solicitud
dispatcher.http.max_idle_conns	int	0 (stdlib)	Máximo de conexiones inactivas en todos los hosts
dispatcher.http.max_idle_per_host	int	0 (stdlib)	Máximo de conexiones inactivas por host
dispatcher.http.idle_conn_timeout	duration	0 (stdlib)	Tiempo de espera de conexión inactiva
dispatcher.http.max_clients	int	0 (ilimitado)	Máximo de clientes distintos en el pool

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

Módulos

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

Campo	Tipo	Por defecto	Descripción
registry_url	string	https://hub.wippy.ai	Endpoint del registro

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

Extensiones

Extensiones de plugin nativo de Go cargadas al inicio (solo Unix).

Campo	Tipo	Por defecto	Descripción
enabled	bool	true	Cargar extensiones
paths	string[]		Rutas de archivos de plugin (relativas al directorio de configuración)

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

Variables de Entorno

Variable	Descripción
GOMEMLIMIT	Límite de memoria (sobrescribe el flag --memory-limit)

Ver También

• Referencia de CLI - Opciones de línea de comandos
• Guía de Cluster - Arquitectura y operaciones de clustering
• Tipos de Entrada - Todos los tipos de entrada
• Guía de Observabilidad - Registro, métricas, trazas