config

Documentation

Overview

Package config loads and validates aa-server-status's TOML configuration: a committed base file deep-merged with a gitignored local overlay for secrets. See design/aa-server-status.md §7 for the design.

Index

• Constants
• func Validate(cfg Config) error
• type Config
  • func Load(basePath, localPath string) (Config, error)
  • func (c Config) ServerByName(name string) (Server, bool)
• type Duration
  • func (d Duration) MarshalText() ([]byte, error)
  • func (d *Duration) UnmarshalText(text []byte) error
• type Health
  • func (h *Health) UnmarshalTOML(data any) error
• type Server
  • func (s Server) WebhookPort() (int, bool)
• type ServerType
• type Supervisor
• type Warm
  • func (w *Warm) UnmarshalTOML(data any) error

Constants

const (
	DefaultGracePeriod   = 5 * time.Second
	DefaultReadyTimeout  = 15 * time.Second
	DefaultPollInterval  = 500 * time.Millisecond
	DefaultHealthTimeout = 2 * time.Second
)

Default supervisor values, applied when the corresponding TOML key is absent from both the committed and local files.

Functions

func Validate

func Validate(cfg Config) error

Validate runs all structural checks on a fully merged config. Every failure here is a hard error — config problems abort the whole program at read time (design/aa-server-status.md §6.5).

Types

type Config

type Config struct {
	Supervisor Supervisor `toml:"supervisor"`
	Servers    []Server   `toml:"server"`
}

Config is the fully loaded, merged, and validated configuration.

func Load

func Load(basePath, localPath string) (Config, error)

Load reads the committed config at basePath, optionally deep-merges the local overlay at localPath if it exists, applies supervisor defaults, and validates the result. Any failure is a hard error — callers should treat a non-nil error as fatal (config errors abort the whole program).

func (Config) ServerByName

func (c Config) ServerByName(name string) (Server, bool)

ServerByName returns the [[server]] entry with the given name, and whether one was found. It lets a caller look up a named server without hand-rolling a loop over Config.Servers.

type Duration

type Duration struct {
	time.Duration
}

Duration wraps time.Duration so it can be decoded from a TOML string like "5s" or "500ms" (time.ParseDuration syntax) via the toml.Unmarshaler interface (BurntSushi/toml's UnmarshalText hook).

func (Duration) MarshalText

func (d Duration) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler for round-tripping.

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler, which BurntSushi/toml uses to decode TOML strings into non-string Go types.

type Health

type Health struct {
	Host string `toml:"host"`
	Port int    `toml:"port"`
	Path string `toml:"path"`
}

Health describes a server's health-check endpoint.

func (*Health) UnmarshalTOML

func (h *Health) UnmarshalTOML(data any) error

UnmarshalTOML implements toml.Unmarshaler, accepting either the existing table form (`health = { host = "...", port = ..., path = "..." }`) or a shorthand string form (`health = "GET /spend?prefix=SOP"`), where host and port default to the server's own (internal/health.ResolveSpec). Only GET is accepted in the string form — the health package's probe is a mandatory GET with no method fallback (design/aa-server-status.md §6.1), so the method name is documentation, not a configurable verb.

type Server

type Server struct {
	Name    string     `toml:"name"`
	Type    ServerType `toml:"type"`
	Enabled bool       `toml:"enabled"`
	Host    string     `toml:"host"`

	// mlx / python launch port.
	Port int `toml:"port"`

	// source / exec self-listened ports.
	Listens []int `toml:"listens"`

	// mlx
	Model string `toml:"model"`

	// python
	Venv     string   `toml:"venv"`
	Entry    string   `toml:"entry"`
	Packages []string `toml:"packages"`

	// source
	Build  string `toml:"build"`
	Binary string `toml:"binary"`

	// optional, any server type: sets the child's working directory
	// (exec.Cmd.Dir) at launch, and anchors a relative Venv/Entry/Binary to
	// itself instead of to aa-server-status's own launch cwd. A leading "~/" is
	// expanded against the user's home directory; otherwise, when relative,
	// Dir resolves against aa-server-status's own launch cwd (it is not
	// config-file-relative — only the supervisor's base_dir is). Unset Dir
	// leaves the child's working directory as today.
	//
	// For source servers, Dir is reused from its pre-existing build-time
	// role (injected as `go -C <dir>`) — the same field now also sets the
	// post-build launch's cmd.Dir. The build's own output is still always
	// rewritten to a temp path and copied into Binary (internal/lifecycle's
	// buildToTemp/replaceBinary), so Binary resolution during the build step
	// itself is unaffected by this launch-time role.
	Dir string `toml:"dir"`

	// exec
	Command string   `toml:"command"`
	Args    []string `toml:"args"`

	Health Health `toml:"health"`

	// Warm is an optional request fired once after launch and before the
	// health gate opens. Empty Path (the zero value) means "no warm-up" --
	// the health poll starts immediately, as it always has.
	Warm Warm `toml:"warm"`

	Env map[string]string `toml:"env"`

	// Per-server overrides of the supervisor defaults. Zero value means
	// "use the supervisor value."
	GracePeriod  Duration `toml:"grace_period"`
	ReadyTimeout Duration `toml:"ready_timeout"`
}

Server is one [[server]] entry — the schema is a union of all four server-type shapes; Validate enforces per-type required fields.

func (Server) WebhookPort

func (s Server) WebhookPort() (int, bool)

WebhookPort resolves a server's webhook/streams port and whether one is declared. By the convention already documented in aa-server-status.toml (e.g. "listens = [9730, 9740] # twilio-cli↔HTTP + Twilio"), a server's primary listen is Listens[0] and its webhook/streams port is Listens[1]; servers declaring fewer than two listens have no webhook port.

type ServerType

type ServerType string

ServerType is the launch strategy for a [[server]] entry.

const (
	TypeMLX    ServerType = "mlx"
	TypePython ServerType = "python"
	TypeExec   ServerType = "exec"
	TypeSource ServerType = "source"
)

type Supervisor

type Supervisor struct {
	LogDir        string   `toml:"log_dir"`
	LockFile      string   `toml:"lock_file"`
	GracePeriod   Duration `toml:"grace_period"`
	ReadyTimeout  Duration `toml:"ready_timeout"`
	PollInterval  Duration `toml:"poll_interval"`
	HealthTimeout Duration `toml:"health_timeout"`

	// BaseDir anchors relative LogDir/LockFile values to something other
	// than the supervisor's own launch cwd. When set and itself relative,
	// BaseDir resolves against the directory containing the --config file
	// (never against process cwd) — see design/aa-server-status.md §7.
	BaseDir string `toml:"base_dir"`
}

Supervisor holds the system-wide settings from the [supervisor] table.

type Warm

type Warm struct {
	Host   string
	Port   int
	Method string
	Path   string
	Body   string
}

Warm is an optional request aa-server-status sends once after launching a server, before it starts polling the health gate. It exists for servers whose health endpoint answers before the server can actually do any work: mlx-serve's `/v1/models` lists what is on disk and 200s in milliseconds, while the model itself is only loaded on demand — so without a warm-up the supervisor reports a 30GB model "up" seconds before it can serve anything, and the first real request eats the whole load.

A 2xx is the only thing aa-server-status looks at; the response body is discarded. Only once it arrives does the health poll begin.

Unlike Health's probe, the method is a real choice (a warm-up is usually a POST carrying a body), so it is honored rather than being documentation.

func (*Warm) UnmarshalTOML

func (w *Warm) UnmarshalTOML(data any) error

UnmarshalTOML implements toml.Unmarshaler for the string form `warm = "POST /path <body>"`, extending Health's `"METHOD /path"` shorthand with everything after the path taken verbatim as the request body:

warm = 'POST /v1/chat/completions {"model":"m","messages":[],"max_tokens":1}'

The body is deliberately an opaque string. aa-server-status neither parses nor validates it — it is whatever that server wants to be asked, and modelling each server's request schema in TOML would buy nothing when the only thing that matters is the status code. Host and port default to the server's own (internal/health.ResolveWarmSpec).