Documentation
¶
Overview ¶
Package config is the machinery the binaries read their environment with (review-2026-10.md G4). It knows nothing about what is configured: each component declares the variables it needs on a struct of its own, and a binary composes those structs into one root and hands it to Load.
A variable is a tagged field:
Addr string `env:"BACKUPD_ADDR" doc:"..."`
Its default is whatever the field holds when Load is called, so a component declares its defaults in code, from its own constants, by providing a constructor for its struct. A nested struct is a section; its `section` tag is the heading in the reference. A section (or the root) that implements Validator is checked after parsing, and may normalise what it checks.
From the declarations the package parses the environment, refuses the unedited manifest's placeholders, renders the effective configuration with secrets redacted by type (Secret), and renders the environment reference the documentation publishes (Reference).
Supported field types: string, Secret, bool (exactly "true" or "false"), int (non-negative), and []string (comma-separated). A string field may restrict its values with a `values:"a,b"` tag (matched ignoring case).
Index ¶
Constants ¶
const PlaceholderMarker = "REPLACE_ME"
PlaceholderMarker is what the shipped manifests put where a deployer must fill something in.
Variables ¶
var ErrPlaceholder = errors.New("placeholder value")
ErrPlaceholder is returned when a variable still holds the manifest's placeholder.
Functions ¶
func Effective ¶
Effective is the configuration root holds, one attribute per variable, keyed by the variable's name in lower case, unset ones included so defaults are visible. Secrets show only whether they are set: the Secret type redacts itself, so this needs no list of names.
func Load ¶
Load fills root, a pointer to a struct, from environ ("NAME=value" entries, as os.Environ returns them) and validates it. Fields keep the value they hold for a variable that is unset or empty: that value is the default.
Every problem is reported in the one error, so one restart shows them all. The exception is an unreplaced placeholder, which is reported alone: every diagnosis after an unfinished manifest is of a symptom.
Types ¶
type Program ¶
type Program struct {
// Name is the binary.
Name string
// Intro is a paragraph of Markdown introducing it.
Intro string
// Config is the binary's configuration root, a pointer to a struct
// holding the defaults.
Config any
// Generator is the command that regenerates the page, named in its
// header.
Generator string
}
Program is one binary's configuration, as its reference presents it.
type Secret ¶
type Secret struct {
// contains filtered or unexported fields
}
Secret is a configuration value that must never be printed: a wrapping key, a password, a credential.
Redaction is a property of the type, not of a list of variable names: a field declared as Secret cannot reach a log line, an error message or a "%v" of the configuration, whatever its name and whoever adds it later. The value sits behind an unexported pointer so even the formatting paths that bypass String (a "%d", or reflection over unexported fields) see an address, never the text.
func (Secret) MarshalText ¶
MarshalText covers every encoder that honours encoding.TextMarshaler, encoding/json among them.
type Validator ¶
type Validator interface {
Validate() error
}
Validator is implemented by a section that checks what depends on more than one of its variables, or on a variable's meaning rather than its type. It is called on a pointer, so it may normalise the values it checks.
type Variable ¶
type Variable struct {
// Name is the environment variable.
Name string
// Section is the heading the variable is listed under.
Section string
// Type is what the variable accepts, in words ("boolean", "secret", ...).
Type string
// Default is the value an unset variable has, as it would be written in
// the environment; "" when there is none.
Default string
// Doc is the operator-facing description.
Doc string
// Secret reports whether the variable is declared as a Secret.
Secret bool
}
Variable describes one declared environment variable, for documentation and for tests that check a binary's declarations as a whole.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package configtest holds the checks every binary's configuration must pass, so each binary states them in one line rather than copying them.
|
Package configtest holds the checks every binary's configuration must pass, so each binary states them in one line rather than copying them. |