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.

Composición de Configuración {#config-composition}

--config es repetible; los archivos se componen de izquierda a derecha usando el mismo esquema:

wippy run --config .wippy.yaml --config .wippy.local.yaml

• Los archivos posteriores sobrescriben los valores coincidentes y conservan todo lo demás.
• Cada archivo nombrado explícitamente debe existir. Sin --config, el .wippy.yaml por defecto es opcional.
• El primer archivo ancla el directorio usado para resolver rutas relativas.
• Los nombres de archivo no tienen significado reservado; nada aparte del archivo por defecto se descubre automáticamente.

La configuración se aplica en orden: composición de archivos, luego las selecciones de --profile, luego las sobrescrituras de --set. Para aplicaciones ejecutadas desde packs, los valores por defecto de runtime empaquetados se sitúan por debajo de todos estos (ver Publicar Valores por Defecto de Runtime).

Perfiles {#profiles}

Un archivo de configuración puede declarar overlays con nombre bajo profiles:. Cada cuerpo de perfil refleja las secciones normales de configuración; seleccionarlo con --profile <name> superpone esos valores sobre la configuración base fusionada:

version: "1.0"

vars:
  port: 8085

override:
  app:db:kind: db.sql.sqlite

disable:
  namespaces: ["legacy.**"]

profiles:
  pg:
    vars:
      port: 18085
    override:
      app:db:kind: db.sql.postgres
    disable:
      namespaces.add: ["experimental.**"]

wippy run --profile pg

• --profile es repetible; los perfiles se componen de izquierda a derecha, después de la composición de archivos y antes de --set. Un nombre desconocido es un error.
• Los valores se fusionan por hoja (el último en escribir gana). La propia sección profiles: se elimina de la configuración resuelta.
• La sección disable admite operaciones de lista dentro de perfiles — namespaces.add, namespaces.remove, entries.add, entries.remove — de modo que un perfil puede ajustar la lista base en lugar de reemplazarla.
• Las referencias ${name} se interpolan desde la sección vars: fusionada. Las referencias a variables de entorno del SO no están permitidas dentro de las vars de perfil; usa ${env:NAME} en la configuración base, resuelta al cargar el archivo.

wippy run, test y pack aceptan --profile; run list, install, update, lint y registry también lo aceptan para perfiles de workspace (junto con --set). Las aplicaciones pueden distribuir perfiles dentro de packs — ver Publicar Perfiles.

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.

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).

logmanager:
  propagate_downstream: true
  stream_to_events: false

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.

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.

security:
  strict_mode: false

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.

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

registry:
  history_type: postgres
  history_dsn: ${env:WIPPY_REGISTRY_HISTORY_DSN}
  history_schema: wippy_registry

Ver: Concepto de Registro, Módulo de Registro

Artifact

Raíz de salida para los artefactos de tiempo de build materializados.

artifact:
  materialization_root: build/wippy

Ver: Artefactos de tiempo de build

Workspace

Sustituciones de módulos locales, indexadas por org/module. Los valores son directorios; las rutas relativas se resuelven respecto al directorio del primer archivo --config, y null desactiva una sustitución heredada de una capa de configuración o perfil anterior.

workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: null

Las sustituciones nunca se escriben en wippy.lock. Ver Desarrollo local con sustituciones.

Relay

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

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.

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

Ver: Guía de Supervisión

Runtime de Lua

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

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

Ver: Visión General de Lua

Scheduler

Particionado de núcleos para el runtime WASM. Cuando está habilitado, se reservan reserved_cores CPUs para la ejecución WASM y el resto sirve al scheduler de actores; una división inválida (por ejemplo, más núcleos reservados que disponibles) se registra y se ignora.

scheduler:
  wasm_isolation:
    enabled: true
    reserved_cores: 2

Finder

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

finder:
  query_cache_size: 2000

OpenTelemetry

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

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

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

Ver: Guía de Observabilidad

Apagado

Comportamiento de apagado controlado.

shutdown:
  timeout: 60s

Métricas

Buffer interno de recolección de métricas.

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

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

Prometheus

Endpoint de métricas de Prometheus.

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

Expone el endpoint /metrics para el scraping de Prometheus, más /livez.

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

Membresía (gossip)

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

Se requiere un secreto de gossip. Establezca membership.secret_key o membership.secret_file (el archivo gana si se dan ambos); sin ninguno, el componente de cluster no arranca. El valor está codificado en base64.

Las cuatro claves de sondeo heredan los valores por defecto de red local de memberlist cuando no están definidas; auméntalas para enlaces de alta latencia (ej. probe_interval: 2s, probe_timeout: 500ms, suspicion_mult: 5).

Internodo (transporte)

Malla TCP que transporta el tráfico de relay y Raft entre nodos. Raft viaja por esta malla mediante request/reply internodo; no hay un puerto Raft separado.

advertise_addr/advertise_port publican un endpoint aditivo en los metadatos del nodo mientras el endpoint de enlace sigue anunciándose sin cambios, de modo que los clusters con versiones mixtas mantienen la conectividad durante una actualización progresiva.

La identidad internodo es obligatoria siempre que el clustering esté habilitado. identity_key e identity_key_file son mutuamente excluyentes y una de las dos debe estar presente; el valor decodifica (base64 estándar o crudo) a una semilla ed25519 de 32 bytes o a una clave privada ed25519 de 64 bytes. trusted_peer_keys asigna a cada nombre de nodo la clave pública ed25519 de 32 bytes de ese nodo, y debe contener una entrada para el cluster.name local cuyo valor coincida con la identidad local — de lo contrario el arranque falla. Ver la Guía de Cluster.

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).

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

cluster:
  enabled: true
  name: dev
  membership:
    secret_key: "d2lwcHktZG9jcy1nb3NzaXAtc2VjcmV0LTMyYnl0ZXM="
  internode:
    identity_key: "d2lwcHktZG9jcy1kZXYtbm9kZS1leGFtcGxlc2VlZCE="
    trusted_peer_keys:
      dev: "rNqImcjOzef28dzvma80mSrCW1px5LBAc5TbaYqAgm0="
  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. Cada nodo lleva el mismo mapa trusted_peer_keys y su propia clave privada:

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
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
  raft:
    bootstrap_expect: 3
    max_voters: 5

Cliente solo-gossip — se une al cluster para naming/mensajería pero nunca ejecuta Raft. Aún necesita su propia identidad y debe aparecer en el mapa de confianza de cada nodo:

cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/edge-7.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
      edge-7: "7lzP4jBAkC3P+0jq4vtMsC45571BlVXk3mSlOD/Z0SA="
  raft:
    role: client

LSP

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

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

Ver: Guía de LSP

Servicio de Red

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

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.

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

Módulos

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

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

Extensiones

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

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

Variables de Entorno

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