Documentation
¶
Overview ¶
Package config reads and validates knell's environment configuration. All environment reads live here; the rest of the app receives the parsed Config. Malformed required values fail startup with a clear error rather than falling back: a dead-man watcher silently running with the wrong beats or webhook is worse than one that refuses to start.
Index ¶
Constants ¶
const MaxBeatIDLen = 64
MaxBeatIDLen is the longest beat id beatIDPattern admits: the pattern is built from it (1 leading character + MaxBeatIDLen-1), so the bound lives in one place. Exported because a notifier has to render an id of this length inside a bounded message.
const MaxRequestHeaderBytes = maxTokenLength + headerOverheadAllowance
MaxRequestHeaderBytes is the request-header cap the composition root applies to the HTTP server, derived from the token bound so the two cannot drift: a token checkBeatToken accepted always fits, with headerOverheadAllowance to spare. Exported for main.go the same way MaxBeatIDLen is exported for the notifier — the bound is owned where the rule that produces it lives. net/http's own default is 1 MiB, which lets one unauthenticated caller make this process read a megabyte of header per connection.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Beat ¶
Beat is one watched heartbeat: an id senders ping and the silence deadline after which the beat is declared missing.
type Config ¶
type Config struct {
// AllowedHosts is the exact-match Host allowlist webapi applies. A nil or
// inactive policy accepts every Host (the documented default).
AllowedHosts *webhttp.HostPolicy
// TrustedProxies is the reverse-proxy CIDR set X-Forwarded-For is honored
// for. Empty (the default) keeps webhttp's spoof-proof behaviour: the
// access line's client_ip is the socket peer.
TrustedProxies []*net.IPNet
WebhookURL string
// WebhookSource is the channel DISCORD_WEBHOOK_URL arrived through, as envx
// names it: SourceFile for the _FILE companion, SourceEnv for the plain
// variable. It is carried here because it is the one non-secret FACT about
// the credential worth publishing at startup (see LogValue) — a webhook
// supplied through the plain variable sits in the process environment and in
// `docker inspect` output. Load is how consumers obtain a Config, and every
// successful Load assigns the source loadWebhook returned, so this field is
// always populated on the Config the app logs.
WebhookSource envx.SecretSource
Node string
ListenAddr string
BeatToken string
// BeatTokenSource is the channel BEAT_TOKEN arrived through, carried for the
// same reason WebhookSource is: it is the one non-secret FACT about the
// credential worth publishing at startup (see LogValue). A bearer token
// supplied through the plain variable sits in the process environment and in
// `docker inspect` output, where the _FILE channel keeps it out, and
// warnPlainVarIgnored reports the channel only when BOTH variables are set —
// so without this the plain-only case, which is the one with the
// consequence, is silent. Load is how consumers obtain a Config, and every
// successful Load assigns the source loadBeatToken returned, so this field
// is always populated on the Config the app logs.
BeatTokenSource envx.SecretSource
Beats []Beat
LogLevel slog.Level
}
Config is the fully parsed runtime configuration.
func Load ¶
func Load(maxNodeNameBytes int, hostPolicyOpts ...webhttp.HostAllowlistOption) (Config, error)
Load reads the environment and returns the validated configuration. BEATS, DISCORD_WEBHOOK_URL and BEAT_TOKEN are required; everything else has a default.
maxNodeNameBytes is the NODE_NAME cap this package ENFORCES; the bound itself is owned by the package that renders the notices it is measured over (internal/notify's MaxNodeNameBytes), and the composition root passes it in — the same mediation main already performs when it translates a config.Beat into a watch.Beat. Taking it as a parameter keeps the environment boundary free of any dependency on the Discord transport.
hostPolicyOpts are the serving-side ALLOWED_HOSTS policy options the composition root supplies (internal/webapi's HostPolicyOptions): the loopback exemption and the 403 envelope are HTTP response shape, so they are authored where the refusal is counted, and this package keeps only the ALLOWED_HOSTS grammar and its startup refusal. Taken as a parameter for the reason maxNodeNameBytes is: it keeps the environment boundary free of any dependency on knell's own transport and exposition packages.
func (Config) LogValue ¶ added in v1.1.0
LogValue implements slog.LogValuer so a Config can never publish its own secrets. DISCORD_WEBHOOK_URL's path IS the Discord credential and BeatToken is the required /beat/{id} gate, so NEITHER is rendered: each is reported by its SOURCE only, never by its value, and neither gets a presence attr (the webhook and the token are both required, so presence reports no state). Logging a Config (or a *Config, whose method set includes this value receiver) stays leak-free even from a call site that logs the whole struct rather than the attributes this method itself chooses -- which is what main.go's logConfig publishes today, by spreading this value's group.
The VALUE receiver is the load-bearing part: a *Config method set would leave the bare Config that Load returns (and run() holds) outside slog.LogValuer, so a slog call that logged the whole struct would reflection-render both secrets.