config

package
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 2, 2026 License: MIT Imports: 7 Imported by: 0

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

View Source
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.

Variables

This section is empty.

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(path string) (Config, error)

Load reads the config at path, 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).

One file, one path. There was once a second, gitignored ".local.toml" deep- merged on top of this one; AATK-33 removed it. It had been silently dropping any [server.prompt] declared only in the overlay since prompts were introduced, and nobody noticed — which was the clearest evidence available that nothing depended on it. Per-machine and secret values come from the environment the supervisor inherits and passes to its children, not from a second config file.

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"`

	// Exec is argv, never a shell line — the supervisor runs the program
	// directly, exactly as lifecycle.ExecCommand does for an exec server. An
	// argument containing a space therefore survives as one argument.
	Exec []string `toml:"exec"`

	// Source, when declared, means Exec names a program built from source —
	// the source-exec form (design/aa-server-status.md §6.1, AATK-41) —
	// rather than a path assumed to already exist. It exists for the case
	// AATK-36's exec form meets: a probe program a consuming project builds
	// from its own source, which nothing in the fleet otherwise builds. Only
	// meaningful alongside Exec; Validate rejects it declared with the HTTP
	// form, since there is no program to build for a GET.
	Source SourceExec `toml:"source"`
}

Health describes a server's readiness check, in one of the two forms design/aa-server-status.md §6.1 defines: the HTTP form (Host/Port/Path), a GET whose 2xx answer means serving, or the exec form (Exec), a command whose exit 0 means ready. §6.1 carries the rationale for the second — in short, nothing that speaks its own wire protocol can supply a path truthfully.

Exactly one form may be declared; Validate rejects both zero and two.

func (Health) Declared added in v0.3.0

func (h Health) Declared() bool

Declared reports whether the server declares a readiness check at all, and IsExec reports which form it is. Between them they are the only place either question is answered: every call site asks here rather than inspecting a particular form's field, so adding a third form later cannot leave a site silently checking the wrong one.

func (Health) IsExec added in v0.3.0

func (h Health) IsExec() bool

IsExec reports whether the check is the command form. See Declared.

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 `health = { exec = ["pg_isready", "-p", "5432"] }`) 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 HTTP probe has no method fallback (design/aa-server-status.md §6.1), so the method name is documentation, not a configurable verb. There is deliberately no string shorthand for the exec form: splitting a command line on spaces would break the argv property the Exec field documents.

type PromptSpec added in v0.3.0

type PromptSpec struct {
	Question string   `toml:"question"`
	YesArgs  []string `toml:"yes_args"`
	NoArgs   []string `toml:"no_args"`

	// YesEnv and NoEnv are merged into the server's Env when their branch is
	// chosen, overriding a static Env entry of the same key and leaving every
	// other key alone.
	//
	// Env exists because the args half only covers choices a server takes on
	// its command line; much of what a child reads comes from its environment,
	// and a question whose answer cannot reach that is a question the operator
	// has to remember to act on twice. Unlike args, Env reaches every server
	// type, so a prompt declaring only env is valid on any of them — see
	// validatePrompt.
	YesEnv map[string]string `toml:"yes_env"`
	NoEnv  map[string]string `toml:"no_env"`
}

Server is one [[server]] entry — the schema is a union of all four server-type shapes; Validate enforces per-type required fields. PromptSpec makes a server's launch arguments and environment an interactive choice instead of a config line the operator has to remember to hand-edit between runs. When present, bringing the server up asks Question, appends YesArgs or NoArgs to whatever args its type already resolves, and merges YesEnv or NoEnv into its Env.

Declaring only one branch is legal: the omitted branch simply contributes nothing, which is the natural way to express "add this flag, or launch normally".

type Server

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

	// Prompt, when set, makes this server ask a y/n question before it
	// launches and append the chosen branch's args. Only server types whose
	// launch path actually reads Args (exec, source) may declare one —
	// Validate rejects the rest rather than letting the answer be silently
	// discarded.
	Prompt *PromptSpec `toml:"prompt"`

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

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

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

	// mlx, optional: a Gemma-4-style assistant drafter checkpoint path for
	// speculative decoding (mlx-serve's --drafter DIR|none — see
	// https://github.com/ddalcu/mlx-serve). Empty (the zero value) means
	// "no drafter" — MLXCommand appends no --drafter flag, the launch
	// invocation is unchanged from before this field existed. mlx-serve's
	// model-agnostic PLD speculative decoding runs regardless of this
	// field (it's on by default, unrelated to --drafter).
	Drafter string `toml:"drafter"`

	// 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"`

	// Detached marks a server whose launched process is expected to exit
	// after starting an external service (e.g. docker compose up -d). The
	// supervisor skips PID-tree port observation and instead verifies that
	// the declared ports are listening on the host, regardless of which
	// process holds them. Teardown re-runs the command with TeardownArgs
	// instead of signaling a PID.
	Detached     bool     `toml:"detached"`
	TeardownArgs []string `toml:"teardown_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"`
}

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 SourceExec added in v0.3.0

type SourceExec struct {
	Build  string `toml:"build"`
	Binary string `toml:"binary"`
}

SourceExec declares that an executable is built from source before it is used — "this source, built when stale, then run" (design/aa-server-status.md §6.1) — rather than assumed to already exist on disk. It carries the same build+output-path shape as a TypeSource server's own Build/Binary pair (a full `go build -o <path> ...` command plus the resulting binary's path): building this executable is the same operation as building a TypeSource server's own binary, so internal/lifecycle reuses that machinery (buildToTemp, ProbeStaleness, PerformBuild) rather than restating a second build path.

Binary duplicates Health.Exec[0] in the same sense Build's own "-o <path>" duplicates it — exactly the redundancy the existing TypeSource Build/Binary pair already carries (§5), kept here for the same reason: Validate can then reject the two paths drifting apart (health.exec[0] must equal Binary) instead of silently building one artifact and probing another.

func (SourceExec) Declared added in v0.3.0

func (se SourceExec) Declared() bool

Declared reports whether se names a source-exec build at all. Build and Binary are required together once either is set — see config/validate.go's validateSourceExec.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL