engine

Documentation

Overview

Package engine defines the check contract and the runner. A Check produces Findings; the runner executes every registered check with a shared timeout and aggregates results. Output rendering lives in internal/output, so checks stay pure and testable.

Index

• func StackPath(basePath, stack string) string
• func Summarize(findings []Finding) map[Status]int
• func Validate(cfg *Config) []string
• type CertsConfig
• type Check
• type ChecksConfig
• type Config
  • func LoadConfig(path string) (*Config, error)
  • func LoadConfigStack(basePath, stack string) (*Config, error)
• type ConsulConfig
• type DNSConfig
• type DNSTarget
• type FilterOptions
• type Finding
  • func Filter(findings []Finding, o FilterOptions) []Finding
• type HAProxyConfig
• type HTTPConfig
• type HTTPTarget
• type NATSConfig
• type Options
• type PatroniConfig
• type PostgresConfig
• type PostgresTarget
• type Result
  • func Run(ctx context.Context, checks []Check, timeout time.Duration) Result
  • func RunWith(ctx context.Context, checks []Check, opts Options) Result
• type Status
  • func ParseStatus(s string) (Status, bool)
  • func Worst(findings []Finding) Status
• type StreamConfig
• type StreamTarget

Functions

func StackPath

func StackPath(basePath, stack string) string

StackPath derives the per-stack config path from the base path: "checkfleet.yml" + "prod" → "checkfleet.prod.yml".

func Summarize

func Summarize(findings []Finding) map[Status]int

Summarize counts findings per status.

func Validate

func Validate(cfg *Config) []string

Validate checks a loaded config for problems without running any check. It returns a list of human-readable issues; empty means the config is usable. It runs on the defaulted config, so threshold checks compare effective values.

Types

type CertsConfig

type CertsConfig struct {
	WarnDays int `yaml:"warn_days"`
	CritDays int `yaml:"crit_days"`
	// Default port for targets and inventory hosts without an explicit one.
	Port int `yaml:"port"`
	// Explicit host[:port] targets.
	Targets []string `yaml:"targets"`
	// Optional Ansible INI inventory: every host becomes a target on Port.
	AnsibleInventory string `yaml:"ansible_inventory"`
}

CertsConfig configures the TLS certificate expiry check.

type Check

type Check interface {
	Name() string
	Run(ctx context.Context) []Finding
}

Check is implemented by every module (certs, http, ...).

type ChecksConfig

type ChecksConfig struct {
	Certs    *CertsConfig    `yaml:"certs"`
	HTTP     *HTTPConfig     `yaml:"http"`
	NATS     *NATSConfig     `yaml:"nats"`
	HAProxy  *HAProxyConfig  `yaml:"haproxy"`
	Stream   *StreamConfig   `yaml:"stream"`
	Patroni  *PatroniConfig  `yaml:"patroni"`
	Consul   *ConsulConfig   `yaml:"consul"`
	Postgres *PostgresConfig `yaml:"postgres"`
	DNS      *DNSConfig      `yaml:"dns"`
}

type Config

type Config struct {
	TimeoutSeconds int          `yaml:"timeout_seconds"`
	Retries        int          `yaml:"retries"`          // retry checks with ERROR findings
	RetryBackoffMS int          `yaml:"retry_backoff_ms"` // base backoff (default 500 when retries>0)
	Checks         ChecksConfig `yaml:"checks"`
}

Config is the root of checkfleet.yml.

func LoadConfig

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

LoadConfig reads and validates checkfleet.yml, applying defaults.

func LoadConfigStack

func LoadConfigStack(basePath, stack string) (*Config, error)

LoadConfigStack loads a base config and overlays a per-stack file (checkfleet.<stack>.yml next to the base), applying defaults after the merge. A module present in the stack replaces the base's module wholesale.

type ConsulConfig

type ConsulConfig struct {
	// Consul HTTP API endpoints as host[:port]; Port applies when a target has
	// none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	Scheme  string   `yaml:"scheme"`
	// Optional Ansible INI inventory: every host becomes an API target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Optional expected number of raft peers; fewer than this is WARN.
	ExpectPeers int `yaml:"expect_peers"`
	// Optional ACL token, read from this env var (X-Consul-Token); never inline.
	TokenEnv string `yaml:"token_env"`
	// Optional KV keys that must exist; a missing key is BAD.
	KVKeys []string `yaml:"kv_keys"`
}

ConsulConfig configures the Consul cluster health check.

type DNSConfig

type DNSConfig struct {
	// Resolvers to query as host[:port] (default port 53). Empty → the system
	// resolvers from /etc/resolv.conf.
	Resolvers []string `yaml:"resolvers"`
	// WARN when any answer's TTL is below this many seconds. 0 disables.
	MinTTLSeconds uint32      `yaml:"min_ttl_seconds"`
	Targets       []DNSTarget `yaml:"targets"`
}

DNSConfig configures the DNS resolution health check.

type DNSTarget

type DNSTarget struct {
	// Domain name to resolve.
	Name string `yaml:"name"`
	// Record type: A, AAAA, CNAME, TXT, NS, SOA. Default A.
	Type string `yaml:"type"`
	// Optional expected value set; a different answer is BAD (drift). For SOA
	// this is compared against the serial.
	Expect []string `yaml:"expect"`
}

type FilterOptions

type FilterOptions struct {
	Only        map[string]bool // check names to keep; empty = all
	MinSeverity Status          // keep findings at or above this severity; "" = all
	TargetGlob  string          // path.Match glob on the target; "" = all
}

FilterOptions narrows a set of findings for output.

type Finding

type Finding struct {
	Check   string `json:"check"`
	Target  string `json:"target"`
	Status  Status `json:"status"`
	Message string `json:"message"`
}

Finding is one observation about one target.

func Filter

func Filter(findings []Finding, o FilterOptions) []Finding

Filter returns the findings that pass every set criterion, preserving order.

type HAProxyConfig

type HAProxyConfig struct {
	// Stats endpoints as host[:port]; Port applies when a target has none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	// Scheme (http/https) and path of the CSV stats export.
	Scheme string `yaml:"scheme"`
	Path   string `yaml:"path"`
	// Optional Ansible INI inventory: every host becomes a stats target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Optional WARN when a server/backend session usage reaches this percent
	// of its limit (scur/slim). 0 disables the check.
	SessionWarnPct int `yaml:"session_warn_pct"`
	// Optional HTTP basic auth. The password is read from the named env var —
	// never store it in the config file.
	AuthUser    string `yaml:"auth_user"`
	AuthPassEnv string `yaml:"auth_pass_env"`
}

HAProxyConfig configures the HAProxy backend/server health check.

type HTTPConfig

type HTTPConfig struct {
	Targets []HTTPTarget `yaml:"targets"`
}

HTTPConfig configures the HTTP probe check.

type HTTPTarget

type HTTPTarget struct {
	URL          string `yaml:"url"`
	ExpectStatus int    `yaml:"expect_status"`
	MaxLatencyMS int    `yaml:"max_latency_ms"`
	ExpectBody   string `yaml:"expect_body"`
}

type NATSConfig

type NATSConfig struct {
	// Monitoring endpoints as host[:port]; Port applies when a target has none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	// Optional Ansible INI inventory: every host becomes a monitoring target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Scheme for the monitoring endpoint (http or https). Default http.
	Scheme string `yaml:"scheme"`
	// Optional expected meta-leader (server_name); a mismatch is WARN.
	ExpectMetaLeader string `yaml:"expect_meta_leader"`
	// Optional expected peer set (server_name); unexpected peers are ghosts
	// (WARN), missing expected peers are BAD.
	ExpectPeers []string `yaml:"expect_peers"`
	// Raft peer lag thresholds (entries). WARN/BAD when a peer is at or above.
	LagWarn int `yaml:"lag_warn"`
	LagCrit int `yaml:"lag_crit"`
}

NATSConfig configures the NATS JetStream cluster health check.

type Options

type Options struct {
	Timeout time.Duration // per-check (and per-attempt) deadline
	Retries int           // extra attempts for a check that produced ERROR findings
	Backoff time.Duration // base backoff between attempts (doubles each retry)
}

Run executes the checks sequentially, each bounded by timeout. Findings are sorted by severity (worst first), then check, then target. Options tunes a run.

type PatroniConfig

type PatroniConfig struct {
	// Patroni REST API endpoints as host[:port]; Port applies when a target
	// has none.
	Targets []string `yaml:"targets"`
	Port    int      `yaml:"port"`
	Scheme  string   `yaml:"scheme"`
	// Optional Ansible INI inventory: every host becomes an API target.
	AnsibleInventory string `yaml:"ansible_inventory"`
	// Replica lag thresholds in bytes (WARN/BAD).
	LagWarnBytes int64 `yaml:"lag_warn_bytes"`
	LagCritBytes int64 `yaml:"lag_crit_bytes"`
}

PatroniConfig configures the Patroni cluster health check.

type PostgresConfig

type PostgresConfig struct {
	Targets []PostgresTarget `yaml:"targets"`
	// Replica lag thresholds in bytes (WARN/BAD).
	LagWarnBytes int64 `yaml:"lag_warn_bytes"`
	LagCritBytes int64 `yaml:"lag_crit_bytes"`
	// WARN when connections reach this percent of max_connections.
	ConnWarnPct int `yaml:"conn_warn_pct"`
	// Transaction-id age thresholds (WARN/BAD) for wraparound risk.
	WraparoundWarnAge int64 `yaml:"wraparound_warn_age"`
	WraparoundCritAge int64 `yaml:"wraparound_crit_age"`
	// Retained-WAL thresholds for inactive replication slots (WARN/BAD).
	SlotWarnBytes int64 `yaml:"slot_warn_bytes"`
	SlotCritBytes int64 `yaml:"slot_crit_bytes"`
}

PostgresConfig configures the PostgreSQL health check (read-only SQL).

type PostgresTarget

type PostgresTarget struct {
	// Display label; defaults to the DSN host.
	Name string `yaml:"name"`
	// libpq DSN or URL, WITHOUT the password.
	DSN string `yaml:"dsn"`
	// Password read from this env var (never store it in the config).
	PasswordEnv string `yaml:"password_env"`
}

type Result

type Result struct {
	Findings []Finding     `json:"findings"`
	Started  time.Time     `json:"started"`
	Duration time.Duration `json:"duration_ns"`
}

Result aggregates the findings of a run.

func Run

func Run(ctx context.Context, checks []Check, timeout time.Duration) Result

Run executes the checks with only a timeout (no retries).

func RunWith

func RunWith(ctx context.Context, checks []Check, opts Options) Result

RunWith executes the checks concurrently under opts. Results are collected per-check by index and flattened in check order, so the output is deterministic regardless of completion order (the stable sort below then orders by severity). Checks whose result contains an ERROR finding are retried up to opts.Retries times with exponential backoff.

type Status

type Status string

Status of a single finding. Severity order: OK < WARN < BAD < ERROR.

const (
	OK    Status = "OK"
	WARN  Status = "WARN"
	BAD   Status = "BAD"
	ERROR Status = "ERROR" // the check itself could not run against the target
)

func ParseStatus

func ParseStatus(s string) (Status, bool)

ParseStatus maps a case-insensitive name to a Status ("" input → ("", true)).

func Worst

func Worst(findings []Finding) Status

Worst returns the most severe status present (OK for an empty list).

type StreamConfig

type StreamConfig struct {
	Targets []StreamTarget `yaml:"targets"`
}

StreamConfig configures the HLS/DASH stream health check.

type StreamTarget

type StreamTarget struct {
	// Manifest URL: an HLS .m3u8 (master or media) or a DASH .mpd.
	URL string `yaml:"url"`
	// Optional display label; defaults to the URL.
	Name string `yaml:"name"`
	// Expected minimum ladder size (variants/representations). 0 disables.
	MinVariants int `yaml:"min_variants"`
	// Expect a live stream: check live-edge freshness and warn if it's VOD.
	Live bool `yaml:"live"`
	// Live-edge age thresholds in seconds (WARN/BAD). Applied when Live is set.
	MaxAgeWarnSeconds int `yaml:"max_age_warn_seconds"`
	MaxAgeCritSeconds int `yaml:"max_age_crit_seconds"`
}