checks

package
v0.14.0 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package checks verifies the environment proximo needs, one independently verifiable statement at a time, and collects the outcomes into one Report.

A Check reports; it never repairs, and it never elevates: everything proximo must read is readable unprivileged, and a check that needed a password would be describing a repair. Every failure therefore carries a Remedy — the cure where one exists, and otherwise the command whose own output names the cause.

Index

Constants

View Source
const (
	IDDocker       = "docker"
	IDPortHTTP     = "port-http"
	IDPortHTTPS    = "port-https"
	IDPortDNS      = "port-dns"
	IDCertutil     = "certutil"
	IDInstalled    = "installed"
	IDTrustSystem  = "trust-system"
	IDTrustNSS     = "trust-nss"
	IDStack        = "stack"
	IDStackVersion = "stack-version"
	IDStackImage   = "stack-image"
	IDDNSServer    = "dns-server"
	IDDNSResolver  = "dns-resolver"
	IDRoutes       = "routes"
	IDAgentSkill   = "agent-skill"
)

Check IDs. They are the vocabulary prerequisites are written in, so they are named rather than spelled out at each use.

Variables

This section is empty.

Functions

func DockerReachable

func DockerReachable(ctx context.Context) error

DockerReachable pings the Docker daemon. It is the one reading the rest of the CLI shares: every command that talks to Docker needs the same answer, and this way it is worded once.

Types

type Check

type Check struct {
	// ID is how other checks name this one as a prerequisite.
	ID string
	// Name is the statement itself, asserted in the positive, so that a pass
	// and a failure read as the same sentence with opposite marks.
	Name string
	// Doc is the anchor of the docs/troubleshooting.md section explaining this
	// failure. A test asserts the section exists: a documented failure with no
	// check, or a check with no explanation, is the drift this prevents.
	Doc string
	// Needs are the IDs of checks that must pass first. A prerequisite that
	// failed or was skipped skips this one instead of producing a second red
	// line for one cause.
	Needs []string
	// Run performs the verification. It must not mutate the host.
	Run func(ctx context.Context) Result
}

Check is one independently verifiable statement about the environment.

func All

func All(env Env) []Check

All is the registry: every check proximo knows how to make, in the order a developer should read them. One list, so the pre-install subset and the full report can never drift apart.

func PreInstall

func PreInstall(env Env) []Check

PreInstall is what `install` gates on: Preflight plus the one statement about a store `install` is about to write. It is not what `up` gates on, because `up` changes no host configuration and a machine that cannot install browser trust must still be allowed to start the stack.

func Preflight

func Preflight(env Env) []Check

Preflight is the subset that is meaningful before the host has been changed: what `install` and `up` share, so a developer learns that Docker is missing or that a stranger holds :443 before proximo touches anything.

type Env

type Env struct {
	// TLD is the domain proximo claims, and the suffix of the sentinel name the
	// DNS checks resolve.
	TLD string
	// CLIVersion is the version of this binary, compared against the stack's.
	CLIVersion string
	// CanonicalImage is the stack image this CLI pins itself to.
	CanonicalImage string

	// CAPath and ResolverPath are the two host artifacts that together mean
	// "installed": the CA on disk and the file pointing the TLD at proximo.
	CAPath       string
	ResolverPath string

	// ResolverRemedy and CertutilRemedy are OS-specific commands, resolved once
	// here so the registry stays free of platform branching.
	ResolverRemedy string
	CertutilRemedy string

	FileExists    func(path string) bool
	PortHeldBy    func(ctx context.Context, port int, proto string) (PortHolder, string)
	QueryLocal    func(ctx context.Context, name string) (string, error)
	SystemResolve func(ctx context.Context, name string) (string, error)
	SystemTrusted func(ctx context.Context) (bool, error)
	NSSTrusted    func(ctx context.Context) (found, total int, err error)
	// CertutilInstallable reports whether browser trust can be installed at
	// all — before `install` writes anything that would have to be undone.
	CertutilInstallable func() bool
	Docker              func(ctx context.Context) error
	Stack               func(ctx context.Context) (docker.StackInfo, error)
	Routes              func(ctx context.Context) ([]docker.Route, error)
	// AgentSkill reports every copy of the agent Skill proximo can see, so the
	// registry can tell a copy that is level with this binary from one that is
	// behind it and one it may not touch.
	AgentSkill func() ([]skill.Copy, error)
}

Env is everything the checks read the host through. Checks take their dependencies as parameters, the way the install host steps do, so the suite can build a machine with no resolver, a port held by a stranger, or no NSS store, without touching the host running the tests.

func DefaultEnv

func DefaultEnv(tld string) (Env, error)

DefaultEnv wires the checks to the real host. It fails only where proximo itself cannot run — an unsupported platform, or no home directory — since every other unknown is a check's answer to give, not an error to return.

type Outcome

type Outcome struct {
	Check  Check
	Result Result
}

Outcome is one Check and what it observed.

type PortHolder

type PortHolder string

PortHolder says who holds a host port. Three of the four outcomes are healthy, which is why the check asks who rather than whether.

const (
	// PortFree means nothing is listening.
	PortFree PortHolder = "free"
	// PortStack means a proximo stack container publishes it.
	PortStack PortHolder = "stack"
	// PortContainer means another container publishes it — nameable, so the
	// remedy can be a docker question.
	PortContainer PortHolder = "container"
	// PortProcess means no container publishes it, so a host process does.
	PortProcess PortHolder = "process"
)

type Report

type Report struct {
	Outcomes []Outcome
}

Report is one complete pass of Checks — passes, failures and skips together, which is what makes it a whole thing rather than a stream of errors.

func Run

func Run(ctx context.Context, list []Check) Report

Run performs each check in order, skipping any whose prerequisite did not pass and naming the prerequisite it waited on.

func (Report) Failures

func (r Report) Failures() []Outcome

Failures returns the outcomes that did not hold, in report order.

func (Report) OK

func (r Report) OK() bool

OK reports whether nothing failed. Skips are not failures: an unanswerable statement is not a broken one.

type Result

type Result struct {
	Status Status
	// Detail is what was observed, in the developer's terms. A passing check
	// says it too: a pass narrows the search as much as a failure does.
	Detail string
	// Remedy is the exact command the developer runs next. Required on Fail,
	// and meaningless otherwise.
	Remedy string
	// Doc names a troubleshooting section for this failure when it is not the
	// one the Check usually points at. One check can fail for causes that are
	// documented apart — a contested host is not a mislabelled container — and
	// sending a developer to the wrong section is worse than sending them to
	// none. Empty means the Check's own section.
	Doc string
}

Result is what one Check observed.

func Failed

func Failed(remedy, format string, a ...any) Result

Failed records a statement that did not hold, with the command that clears it (or, where nothing cures it, the command whose output names the cause).

func Passed

func Passed(format string, a ...any) Result

Passed records a statement that held, with what was observed.

func Skipped

func Skipped(format string, a ...any) Result

Skipped records a statement the environment could not answer, naming what it waited on.

func (Result) Explains

func (r Result) Explains(doc string) Result

Explains points a failure at a troubleshooting section other than its Check's own.

type Status

type Status string

Status is the outcome of one Check. There are exactly three. A fourth ("warn") would mean a failure proximo decided not to insist on, and that decision belongs to whoever reads the Report, not to proximo writing it.

const (
	// Pass is a statement that held.
	Pass Status = "pass"
	// Fail is a statement that did not hold. It always carries a Remedy.
	Fail Status = "fail"
	// Skip is a statement the environment could not answer — never one whose
	// answer was inconvenient. A skip names what it waited on.
	Skip Status = "skip"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL