preflight

package
v0.8.19 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package preflight performs read-only readiness checks for Relayer. Reports deliberately contain no configuration path, command arguments, environment values, agent identifiers, names or raw dependency errors.

Every check is passive with one deliberate exception: when tmux is the effective backend, Options.TmuxProbe runs tmux inside a private socket to establish that it can actually serve a session. Nothing belonging to the user - configuration, audit journal, tmux server, agent process - is created, read or mutated.

Index

Constants

View Source 
const CurrentSchemaVersion = 1

Variables

View Source 
var ErrInvalidReport = errors.New("invalid preflight report")

ErrInvalidReport is deliberately static. A rejected report may contain caller-controlled paths, commands, environment values or raw errors, so the validation error must never echo the field which caused the rejection.

View Source 
var ErrNilContext = errors.New("preflight context is nil")

Functions

func ValidateReport 

func ValidateReport(report Report) error

ValidateReport verifies the complete display contract before a report may be rendered or cross a native/UI boundary. It accepts only reports produced by Check or FailureReport: every identifier, enum and displayed sentence belongs to a finite package-owned vocabulary.

Types

type AgentInfo 

type AgentInfo struct {
	Ordinal         int                       `json:"ordinal"`
	Source          AgentSource               `json:"source"`
	Command         CommandKind               `json:"command"`
	Installation    toolcatalog.InstallStatus `json:"installation"`
	Adapter         string                    `json:"adapter,omitempty"`
	AdapterMaturity adapters.Status           `json:"adapter_maturity,omitempty"`
	Backend         string                    `json:"backend,omitempty"`
}

AgentInfo uses a one-based ordinal in place of the configured agent ID or name. Executable names and resolved filesystem paths are also omitted.

type AgentSource 

type AgentSource string
const (
	AgentConfigured AgentSource = "configured"
	AgentDemo       AgentSource = "demo"
)

type AuditInfo 

type AuditInfo struct {
	Enabled       bool          `json:"enabled"`
	Mode          audit.Mode    `json:"mode"`
	Location      AuditLocation `json:"location"`
	MaxFileSizeMB int           `json:"max_file_size_mb"`
	MaxFiles      int           `json:"max_files"`
}

type AuditLocation 

type AuditLocation string
const (
	AuditLocationDisabled AuditLocation = "disabled"
	AuditLocationDefault  AuditLocation = "default"
	AuditLocationCustom   AuditLocation = "custom"
)

type CheckResult 

type CheckResult struct {
	ID          string      `json:"id"`
	Scope       Scope       `json:"scope"`
	Status      CheckStatus `json:"status"`
	Summary     string      `json:"summary"`
	Remediation string      `json:"remediation,omitempty"`
}

CheckResult contains only finite, static display text selected by the package.

type CheckStatus 

type CheckStatus string

CheckStatus is deliberately closed so presentation layers never need raw error strings to explain readiness. 

const (
	CheckPass    CheckStatus = "pass"
	CheckWarning CheckStatus = "warning"
	CheckBlock   CheckStatus = "block"
)

type CommandKind 

type CommandKind string
const (
	CommandDirect CommandKind = "direct"
	CommandShell  CommandKind = "shell"
)

type ConfigurationInfo 

type ConfigurationInfo struct {
	Version         int  `json:"version"`
	Legacy          bool `json:"legacy"`
	AgentCount      int  `json:"agent_count"`
	PolicyRuleCount int  `json:"policy_rule_count"`
}

type FailureKind 

type FailureKind string

FailureKind is a closed classification used by the application facade when it cannot construct an effective Input. The underlying error is never put into the report. 

const (
	FailureConfigMissing     FailureKind = "config_missing"
	FailureConfigInvalid     FailureKind = "config_invalid"
	FailureConfigUnreadable  FailureKind = "config_unreadable"
	FailureWorkingDirectory  FailureKind = "working_directory"
	FailureAgentResolution   FailureKind = "agent_resolution"
	FailurePolicyResolution  FailureKind = "policy_resolution"
	FailureAdapterResolution FailureKind = "adapter_resolution"
	FailurePreflightInternal FailureKind = "preflight_internal"
)

type Input 

type Input struct {
	Configuration config.Result
	Specs         []agent.Spec
	DemoAgents    bool
}

Input contains an already effective, validated runtime plan. Application facades remain responsible for applying the empty-agent demo fallback before calling Check.

type LstatFunc 

type LstatFunc func(string) (fs.FileInfo, error)

type Options 

type Options struct {
	Detector toolcatalog.Detector

	// TmuxProbe is the one check in this package that executes a program.
	// Discovering the tmux binary is not evidence that it can serve Relayer's
	// machine-readable protocol, and a report that cannot observe that failure
	// tells the operator the backend is healthy right before startup fails with
	// an opaque identity error.
	//
	// The probe is bounded and self-contained: one short-lived session on a
	// private socket inside a 0700 temporary directory, removed by name. It
	// never reads, attaches to, or mutates the user's tmux server, and never
	// calls kill-server. A nil probe uses tmuxbackend.Probe.
	TmuxProbe TmuxProbeFunc

	GOOS             string
	GOARCH           string
	Lstat            LstatFunc
	ReadDir          ReadDirFunc
	ResolveAuditPath ResolveAuditPathFunc
	OwnerCheck       OwnerCheckFunc
}

Options contains passive dependencies, plus the single deliberate exception described on TmuxProbe. Empty platform fields use the current runtime; a nil detector uses toolcatalog.DefaultDetector.

type OverallStatus 

type OverallStatus string

OverallStatus summarizes the strongest check status in a report. 

const (
	StatusReady   OverallStatus = "ready"
	StatusWarning OverallStatus = "warning"
	StatusBlocked OverallStatus = "blocked"
)

type OwnerCheckFunc 

type OwnerCheckFunc func(fs.FileInfo) OwnerStatus

type OwnerStatus 

type OwnerStatus string
const (
	OwnerCurrent OwnerStatus = "current"
	OwnerOther   OwnerStatus = "other"
	OwnerUnknown OwnerStatus = "unknown"
)

type PlatformInfo 

type PlatformInfo struct {
	OS        string `json:"os"`
	Arch      string `json:"arch"`
	Supported bool   `json:"supported"`
}

type ReadDirFunc 

type ReadDirFunc func(string) ([]fs.DirEntry, error)

type Report 

type Report struct {
	SchemaVersion int               `json:"schema_version"`
	Status        OverallStatus     `json:"status"`
	Platform      PlatformInfo      `json:"platform"`
	Configuration ConfigurationInfo `json:"configuration"`
	Audit         AuditInfo         `json:"audit"`
	Tools         []ToolInfo        `json:"tools"`
	Agents        []AgentInfo       `json:"agents"`
	Checks        []CheckResult     `json:"checks"`
}

Report is a versioned, display-safe snapshot shared by CLI and GUI.

func Check 

func Check(ctx context.Context, input Input, options Options) (Report, error)

Check passively validates one effective plan. It never opens an audit sink, constructs a terminal backend, starts a process or invokes an executable.

func FailureReport 

func FailureReport(kind FailureKind, options Options) Report

FailureReport builds a static, blocked report for facade failures that occur before an effective Input exists. Unknown kinds collapse to an internal failure and never become caller-controlled display text.

func (Report) Clone 

func (report Report) Clone() Report

Clone returns independent slice storage for presentation-layer caching.

func (Report) HasBlockers 

func (report Report) HasBlockers() bool

HasBlockers reports whether at least one check prevents safe startup.

func (Report) Ready 

func (report Report) Ready() bool

Ready reports whether no warning or blocker was found.

type ResolveAuditPathFunc 

type ResolveAuditPathFunc func(string) (string, error)

type Scope 

type Scope string

Scope groups checks without disclosing user-controlled identifiers. 

const (
	ScopeConfiguration Scope = "configuration"
	ScopePlatform      Scope = "platform"
	ScopePolicy        Scope = "policy"
	ScopeAudit         Scope = "audit"
	ScopeTool          Scope = "tool"
	ScopeAgent         Scope = "agent"
	ScopeAdapter       Scope = "adapter"
	ScopeBackend       Scope = "backend"
	ScopeTelemetry     Scope = "telemetry"
)

type TmuxProbeFunc 

type TmuxProbeFunc func(context.Context, string) error

TmuxProbeFunc reports whether a discovered tmux can actually run a session.

type ToolInfo 

type ToolInfo struct {
	ProfileID    toolcatalog.ProfileID     `json:"profile_id"`
	Installation toolcatalog.InstallStatus `json:"installation"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.