hubdoctor

type Finding struct {
	Check       string         `json:"check"`
	Title       string         `json:"title"`
	Severity    Severity       `json:"severity"`
	Message     string         `json:"message"`
	Remediation string         `json:"remediation,omitempty"`
	Details     map[string]any `json:"details,omitempty"`
}

type Options struct {
	// Offline skips every check that would make a network request: OIDC
	// discovery, the JWKS fetch, registry reachability, and executor health
	// probes that dial. Those checks report a warning saying they were
	// skipped rather than silently vanishing.
	Offline bool

	// Timeout bounds each individual network probe. Zero uses
	// DefaultProbeTimeout.
	Timeout time.Duration

	// HTTPClient overrides the client used for probes. Tests inject one
	// pointed at an httptest server; production leaves it nil so the system
	// trust store (and SSL_CERT_DIR, which the compose stack sets) applies.
	HTTPClient *http.Client

	// Now overrides the clock, so certificate-expiry findings are testable
	// without generating a certificate per case.
	Now func() time.Time

	// LookPath overrides executable lookup, for the cosign check. Tests
	// substitute it; nil means exec.LookPath.
	LookPath func(string) (string, error)

	// DialContext overrides the dialer used by the advertised-address
	// reachability probes. Tests substitute one so a case can produce a
	// refusal or a resolution failure without depending on what the machine
	// running the suite can reach; nil means a plain net.Dialer.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)

	// ProbeNetworkPolicy runs the NetworkPolicy enforcement experiment against
	// the configured Kubernetes executors.
	//
	// Opt-in because it is the only check here that *writes to the operator's
	// cluster*: two throwaway Pods and a default-deny policy, removed on every
	// exit path. A diagnostic that mutated infrastructure by default would be
	// one nobody could safely run against production. See netpol.go.
	ProbeNetworkPolicy bool

	// ProbeExecutorID narrows a probe to one executor. Empty probes all of
	// them, which on the usual single-cluster hub is the same thing.
	//
	// Shared by --probe-network-policy and --smoke because it means the same
	// thing to both ("restrict this to one executor") and because an operator
	// should not have to remember two spellings of --executor.
	ProbeExecutorID string

	// Smoke runs the dispatch smoke test: a trivial hermetic workload sent
	// through the same primitives a real task takes. See smoke.go.
	//
	// Opt-in for the same reason ProbeNetworkPolicy is — it starts a real
	// workload and mints a real, if throwaway, credential — though it is far
	// cheaper and safe against production.
	Smoke bool

	// SmokeTimeout bounds one executor's smoke run. Zero uses
	// DefaultSmokeTimeout. Not Timeout, which bounds a single HTTP request
	// and is nowhere near long enough to start a container.
	SmokeTimeout time.Duration

	// SmokeLeaseDir is the directory the smoke stages its throwaway
	// credential file under, for a driver that reads it from the hub's
	// filesystem. Empty takes the tmpfs a real lease uses (/dev/shm, else
	// $TMPDIR). Tests point it somewhere private: the default is shared by
	// every hub and every test binary on the machine, so what a test found
	// there afterwards could be anybody's.
	SmokeLeaseDir string

	// ProbeImage overrides the busybox image the probe Pods run, for a cluster
	// that mirrors its own registry or enforces an image policy.
	ProbeImage string

	// ProbeTimeout bounds one probe. Zero uses
	// DefaultNetworkPolicyProbeTimeout — deliberately not Timeout, which bounds
	// a single HTTP request and is far too short for scheduling three Pods.
	ProbeTimeout time.Duration

	// ProbeLogf narrates the probe's steps. `cloop hub doctor` wires it to the
	// terminal, because the alternative is a command that prints nothing for
	// three minutes and looks hung.
	ProbeLogf func(format string, args ...any)

	// DiskProbe overrides how the free-space check measures the hub's state
	// volume (Task 20381). Tests substitute one so a volume can sit below its
	// floor without anything filling a disk; nil means diskusage.Volumes.
	DiskProbe func(paths ...string) ([]diskusage.Volume, error)

	// Port is the port of the hub being diagnosed (`cloop hub doctor
	// --port`). The exposure check looks for that hub's listener on it and
	// asks it whether it requires sign-in; zero judges the configuration
	// alone (Task 20393).
	Port int

	// Listeners overrides how the exposure check reads the sockets listening
	// on a port. Tests substitute one so a hub can appear to listen on every
	// interface without one binding there; nil reads the kernel's socket
	// tables (listeners.go).
	Listeners func(port int) ([]netip.AddrPort, error)

	// GlobalBudget overrides how the host-wide spend caps are read, which
	// budget.Enforce reads from the running user's config directory. Tests
	// substitute one so a machine's own caps cannot decide them; nil means
	// globalbudget.Load.
	GlobalBudget func() (globalbudget.GlobalBudgetConfig, error)
}

type Report struct {
	// Dir is the control plane's working directory (where .cloop lives).
	Dir string `json:"dir"`
	// CheckedAt is when the run started.
	CheckedAt time.Time `json:"checked_at"`
	// StrictMode reports executors.allow_host_process=false — recorded
	// because it changes what several findings mean.
	StrictMode bool `json:"strict_mode"`
	// Offline reports that network probes were skipped.
	Offline bool `json:"offline"`
	// Findings, in the order the checks produced them.
	Findings []Finding `json:"findings"`

	// SmokeRan reports that --smoke was asked for and the check ran, whether
	// or not it found anything to dispatch to. It is what lets SmokeExitCode
	// tell "no executor to smoke" from "smoke was never requested", which are
	// the same empty Smoke array but opposite answers for a readiness gate.
	SmokeRan bool `json:"smoke_ran,omitempty"`
	// Smoke carries the per-stage dispatch results, one entry per executor.
	// Empty unless Options.Smoke was set.
	Smoke []SmokeResult `json:"smoke,omitempty"`
}

type Severity string

type SmokeResult struct {
	ExecutorID string `json:"executor_id"`
	Kind       string `json:"kind,omitempty"`
	Isolation  string `json:"isolation,omitempty"`
	// Stages in smokeStageOrder.
	Stages []StageResult `json:"stages"`
	// FirstFailure is the stage that broke, or "" when none did. It is the
	// single most useful field in the report: the stages after a failure are
	// consequences, and an operator reading a wall of red needs to know which
	// line to act on.
	FirstFailure SmokeStage `json:"first_failure,omitempty"`
	// Leaked names resources cleanup could not remove. Non-empty is an
	// operator action item, not a warning.
	Leaked     []string `json:"leaked,omitempty"`
	DurationMS int64    `json:"duration_ms"`
}

type SmokeStage string

type StageOutcome string

type StageResult struct {
	Stage   SmokeStage   `json:"stage"`
	Outcome StageOutcome `json:"outcome"`
	Message string       `json:"message"`
	// Remediation names the fix. Required for anything that is not a pass,
	// for the same reason Finding.Remediation is.
	Remediation string         `json:"remediation,omitempty"`
	DurationMS  int64          `json:"duration_ms,omitempty"`
	Details     map[string]any `json:"details,omitempty"`
}