preflight

Documentation

Overview

Package preflight provides reusable non-mutating checks for validating a host and agent configuration before bootstrap.

Index

• type Checker
  • func Flatten(groups ...[]Checker) []Checker
• type Options
• type Report
  • func Run(ctx context.Context, checks []Checker, opts Options) Report
  • func (r Report) Err(failOnWarnings bool) error
  • func (r Report) HasErrors() bool
  • func (r Report) HasWarnings() bool
• type Result
  • func Error(name, target, message string, args ...any) Result
  • func OK(name, target, message string) Result
  • func Results(results ...Result) []Result
  • func ResultsError(name, target, message string, args ...any) []Result
  • func ResultsOK(name, target, message string) []Result
  • func ResultsWarning(name, target, message string, args ...any) []Result
  • func Warning(name, target, message string, args ...any) Result
• type Severity
• type Summary

Types

type Checker

type Checker interface {
	Name() string
	Check(ctx context.Context) []Result
}

Checker is a non-mutating preflight validation unit.

func Flatten

func Flatten(groups ...[]Checker) []Checker

Flatten returns one checker slice from ordered checker groups.

type Options

type Options struct {
	IgnoreErrors   []string
	FailOnWarnings bool
}

Options controls preflight result handling.

type Report

type Report struct {
	Status  string   `json:"status"`
	Checks  []Result `json:"checks"`
	Summary Summary  `json:"summary"`
}

Report is the complete preflight output for both text and JSON consumers.

func Run

func Run(ctx context.Context, checks []Checker, opts Options) Report

Run executes all checks, applies ignore rules, and returns a complete report.

func (Report) Err

func (r Report) Err(failOnWarnings bool) error

Err converts the report status into a command error.

func (Report) HasErrors

func (r Report) HasErrors() bool

HasErrors reports whether any fatal errors remain after ignore handling.

func (Report) HasWarnings

func (r Report) HasWarnings() bool

HasWarnings reports whether the report contains any warnings.

type Result

type Result struct {
	Name     string   `json:"name"`
	Target   string   `json:"target"`
	Severity Severity `json:"severity"`
	Message  string   `json:"message"`
	Ignored  bool     `json:"ignored"`
}

Result describes one preflight check outcome. Message and Target must not include raw configured values such as URLs, tokens, image references, or file contents.

func Error

func Error(name, target, message string, args ...any) Result

Error returns a fatal check result. When args are provided, message is formatted with fmt.Sprintf.

func OK

func OK(name, target, message string) Result

OK returns a successful check result.

func Results

func Results(results ...Result) []Result

Results returns a result slice for concise checker returns and test fixtures.

func ResultsError

func ResultsError(name, target, message string, args ...any) []Result

ResultsError returns a single fatal check result as a slice. When args are provided, message is formatted with fmt.Sprintf.

func ResultsOK

func ResultsOK(name, target, message string) []Result

ResultsOK returns a single successful check result as a slice.

func ResultsWarning

func ResultsWarning(name, target, message string, args ...any) []Result

ResultsWarning returns a single warning check result as a slice. When args are provided, message is formatted with fmt.Sprintf.

func Warning

func Warning(name, target, message string, args ...any) Result

Warning returns a warning check result. When args are provided, message is formatted with fmt.Sprintf.

type Severity

type Severity string

const (
	// SeverityOK indicates the check completed successfully.
	SeverityOK Severity = "ok"
	// SeverityWarning indicates the check found a condition that bootstrap can
	// usually remediate or that does not necessarily block bootstrap.
	SeverityWarning Severity = "warning"
	// SeverityError indicates the check found a fatal condition that should block
	// bootstrap unless explicitly ignored.
	SeverityError Severity = "error"
)

type Summary

type Summary struct {
	OK       int `json:"ok"`
	Warnings int `json:"warnings"`
	Errors   int `json:"errors"`
}

Summary contains aggregate result counts after ignore handling is applied.