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
• 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 Finding
• type HAProxyConfig
• type HTTPConfig
• type HTTPTarget
• type NATSConfig
• type PatroniConfig
• type PostgresConfig
• type PostgresTarget
• type Result
  • func Run(ctx context.Context, checks []Check, timeout time.Duration) Result
• type Status
  • 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.

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

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 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 sequentially, each bounded by timeout. Findings are sorted by severity (worst first), then check, then target.

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