config

Documentation

Overview

Package config implements VORTEX's CUE-based configuration engine (build plan M1.2).

The user edits a single vortex.cue file. At startup it is unified against the embedded master schema (config/schema.cue). If it violates any type or constraint, or declares an unknown field, loading fails with the offending file, line, and field path and the process exits 1 — config is always valid or rejected, never validated lazily at first use (Non-Negotiable Rule #3).

A loaded Config is exposed as plain typed Go structs. A Holder wraps the active *Config behind an atomic pointer so it can be read from many goroutines while SIGHUP-driven reloads swap it atomically (see reload.go).

Secrets never appear in config — only secret names (Rule #2).

Index

• Constants
• type Backend
• type Cluster
• type Config
  • func Load(path string) (*Config, error)
  • func (c *Config) Hash() string
• type HealthCheck
• type Holder
  • func NewHolder(cfg *Config) *Holder
  • func (h *Holder) Get() *Config
  • func (h *Holder) Store(cfg *Config)
• type LoadError
  • func (e *LoadError) Error() string
• type LoadErrors
  • func (es LoadErrors) Error() string
• type LogRotate
• type Manager
  • func NewManager(path string, log *slog.Logger) (*Manager, error)
  • func (m *Manager) Current() *Config
  • func (m *Manager) Holder() *Holder
  • func (m *Manager) RegisterReload(lc *lifecycle.Manager)
  • func (m *Manager) Reload() error
• type Observability
• type RateLimit
• type Route
• type Secrets
• type Security
• type Server
• type TLS

Constants

const DefaultPath = "vortex.cue"

DefaultPath is where VORTEX looks for the config file when none is specified.

Types

type Backend

type Backend struct {
	Host   string `json:"host"`
	Port   int    `json:"port"`
	Weight int    `json:"weight"`
}

Backend mirrors #Backend.

type Cluster

type Cluster struct {
	Name       string   `json:"name"`
	Nodes      []string `json:"nodes"`
	GossipPort int      `json:"gossip_port"`
	RaftPort   int      `json:"raft_port"`
}

Cluster mirrors #Cluster in schema.cue.

type Config

type Config struct {
	Cluster       Cluster       `json:"cluster"`
	TLS           TLS           `json:"tls"`
	Routes        []Route       `json:"routes"`
	Security      Security      `json:"security"`
	Secrets       Secrets       `json:"secrets"`
	Observability Observability `json:"observability"`
	Servers       []Server      `json:"servers,omitempty"`
	// contains filtered or unexported fields
}

Config is the fully-typed, validated configuration. It is produced by Load and is safe to treat as immutable; reloads create a new Config rather than mutating an existing one.

func Load

func Load(path string) (*Config, error)

Load reads and validates the config file at path, applies environment variable overrides, and returns a fully-typed *Config. On any validation problem it returns a LoadErrors describing each issue with file:line:field.

path may be "" to use DefaultPath.

func (*Config) Hash

func (c *Config) Hash() string

Hash returns the SHA-256 hex digest of this config's canonical encoding.

type HealthCheck

type HealthCheck struct {
	Path     string `json:"path"`
	Interval string `json:"interval"`
}

HealthCheck mirrors #HealthCheck.

type Holder

type Holder struct {
	// contains filtered or unexported fields
}

Holder is a thread-safe container for the active *Config. Many goroutines may call Get concurrently; Store atomically swaps in a new Config during reload.

func NewHolder

func NewHolder(cfg *Config) *Holder

NewHolder returns a Holder pre-loaded with cfg.

func (*Holder) Get

func (h *Holder) Get() *Config

Get returns the currently active config. Never nil once initialized.

func (*Holder) Store

func (h *Holder) Store(cfg *Config)

Store atomically replaces the active config.

type LoadError

type LoadError struct {
	Path    string // the config file the problem relates to
	Line    int    // 1-based line; 0 if unknown
	Column  int    // 1-based column; 0 if unknown
	Field   string // CUE field path, e.g. "cluster.name"; may be empty
	Message string // human-readable description
}

LoadError is a structured configuration error carrying, where available, the source file, line, column, and a human-readable message. Its Error() string is formatted for direct display to an operator.

func (*LoadError) Error

func (e *LoadError) Error() string

type LoadErrors

type LoadErrors []*LoadError

LoadErrors is a sorted collection of LoadError. Load returns this type so a caller can report every problem at once rather than one per run.

func (LoadErrors) Error

func (es LoadErrors) Error() string

type LogRotate

type LogRotate struct {
	Enabled    bool `json:"enabled"`
	MaxSizeMB  int  `json:"max_size_mb"`
	MaxAgeDays int  `json:"max_age_days"`
	MaxBackups int  `json:"max_backups"`
	Compress   bool `json:"compress"`
}

LogRotate mirrors #LogRotate.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns the live config Holder and the metadata needed to reload it. It bridges the config engine to pkg/lifecycle: on SIGHUP (or an explicit lifecycle reload) it re-reads and re-validates the config file, and on success atomically swaps the active config. On failure it logs and keeps the previous config — a bad reload never takes the process down (this is the M1.2 "never crash on reload" requirement).

func NewManager

func NewManager(path string, log *slog.Logger) (*Manager, error)

NewManager loads the config at path once (failing if it is invalid — startup must reject bad config per Rule #3) and returns a Manager wrapping it.

func (*Manager) Current

func (m *Manager) Current() *Config

Current returns the currently active config.

func (*Manager) Holder

func (m *Manager) Holder() *Holder

Holder returns the thread-safe holder for the active config, suitable for passing to subsystems that need to read config concurrently.

func (*Manager) RegisterReload

func (m *Manager) RegisterReload(lc *lifecycle.Manager)

RegisterReload wires this Manager's Reload into the lifecycle Manager so that SIGHUP (Unix) or a programmatic lifecycle reload triggers it. The hook swallows the error after logging so a bad reload is non-fatal.

func (*Manager) Reload

func (m *Manager) Reload() error

Reload re-reads and re-validates the config file. On success it swaps in the new config and returns nil; on failure it returns the error and leaves the active config untouched. It never panics.

type Observability

type Observability struct {
	MetricsPath   string    `json:"metrics_path"`
	Tracing       bool      `json:"tracing"`
	TraceEndpoint string    `json:"trace_endpoint"`
	LogLevel      string    `json:"log_level"`
	LogSink       string    `json:"log_sink"`
	LogFile       string    `json:"log_file"`
	LogSampling   bool      `json:"log_sampling"`
	LogRotate     LogRotate `json:"log_rotate"`
}

Observability mirrors #Observability.

type RateLimit

type RateLimit struct {
	RPM   int `json:"rpm"`
	Burst int `json:"burst"`
}

RateLimit mirrors #RateLimit.

type Route

type Route struct {
	Name        string       `json:"name"`
	Protocol    string       `json:"protocol"`
	Host        string       `json:"host,omitempty"`
	Listen      int          `json:"listen,omitempty"`
	Backends    []Backend    `json:"backends"`
	HealthCheck *HealthCheck `json:"health_check,omitempty"`
	RateLimit   *RateLimit   `json:"rate_limit,omitempty"`
	Timeout     string       `json:"timeout,omitempty"`
	MTLS        bool         `json:"mtls"`
	Plugins     []string     `json:"plugins"`
	NamespaceID string       `json:"namespace_id,omitempty"`
}

Route mirrors #Route. Pointer fields are optional in the schema.

type Secrets

type Secrets struct {
	Store     string   `json:"store"`
	Keys      []string `json:"keys"`
	InjectEnv bool     `json:"inject_env"`
}

Secrets mirrors #Secrets — names only, never values.

type Security

type Security struct {
	BlockTor    bool     `json:"block_tor"`
	BlockClouds bool     `json:"block_clouds"`
	IPAllowlist []string `json:"ip_allowlist"`
}

Security mirrors #Security.

type Server

type Server struct {
	Name     string `json:"name"`
	Host     string `json:"host"`
	Port     int    `json:"port"`
	User     string `json:"user"`
	KeyPath  string `json:"key_path,omitempty"`
	Password string `json:"password,omitempty"`
}

Server mirrors #Server in schema.cue: an SSH-reachable host for the DevOps agent (M16). Password/KeyPath are credentials — prefer KeyPath.

type TLS

type TLS struct {
	ACMEEmail  string `json:"acme_email"`
	Provider   string `json:"provider"`
	MinVersion string `json:"min_version"`
}

TLS mirrors #TLS.