hubdoctor

type Check struct {
	ID, Title string
	Run       func(ctx context.Context, add func(Finding))
	// Timeout bounds this check. Zero uses the run's CheckTimeout.
	Timeout time.Duration
	// Every, when set, is how often a live run makes this check at most, as
	// liveEvery says for the hub's own.
	Every time.Duration
}

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"`
	// AsOf is when the check was made, for a finding a live run carried over
	// from an earlier one (liveEvery); zero means now. Run never sets it.
	AsOf time.Time `json:"as_of,omitzero"`
}

type Live struct {
	// contains filtered or unexported fields
}

type LiveOptions struct {
	// Options are the checks' own. Smoke and ProbeNetworkPolicy are ignored:
	// a live run has no step that starts work.
	Options

	// CheckTimeout bounds each step. Zero uses DefaultCheckTimeout.
	CheckTimeout time.Duration

	// Extra steps run after the hub's own.
	Extra []Check

	// OnPanic, when set, is told of every step that panics — also one that
	// panics after its deadline, which no report will mention — with where.
	// It runs on the panicking step's goroutine.
	OnPanic func(step string, value any, stack []byte)

	// Generation names the configuration the run is made under. A step made
	// less often than reports are (liveEvery) is reused only by a run of the
	// same generation, so a changed configuration is diagnosed afresh.
	Generation string

	// Fresh asks for a run of everything recent enough not to be: a step
	// made less often than reports are is reused only if its last run is
	// under a minute old.
	Fresh bool
}

type LiveReport struct {
	Report
	Steps []StepResult `json:"steps"`
	// NotRun names what this diagnosis leaves to `cloop hub doctor`.
	NotRun []NotRun `json:"not_run"`
	// Elapsed is how long the run took.
	Elapsed time.Duration `json:"-"`
}

type NotRun struct {
	Check string `json:"check"`
	Flag  string `json:"flag"`
	Why   string `json:"why"`
}

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)

	// ClaudeHomesRoot overrides where the doctor's own process keeps
	// per-user Claude homes, for the leftover-homes check (Task 20422).
	// Empty is claudecodeauth.HomeRootPath, from this process's environment.
	ClaudeHomesRoot string

	// Self is what the hub being diagnosed knows about itself, when it is the
	// process diagnosing (Live, Task 20434). Nil is an operator's shell, which
	// knows the configuration and its own environment and has to ask the rest.
	Self *Self
}

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 Self struct {
	// SSO, StaticToken and TLS say how the hub's listener admits a request as
	// the process runs now: single sign-on in force, a static admin token
	// configured, TLS served. The exposure check judges from them instead of
	// asking the listener without a credential — which a hub with a static
	// token and no SSO counts as a failed sign-in, five of which lock the
	// asking address out.
	SSO, StaticToken, TLS bool

	// KMS returns the roots the hub resolved at startup, which every keyring
	// it opens uses, and whether it pinned any. The sealing-key checks use
	// them instead of resolving secrets.kms again, which would open a new KMS
	// client — for Vault, a new login and a new token — on every report.
	KMS func() (kms.Roots, bool)

	// Probe answers an executor's liveness from what the hub already knows:
	// what its supervisor last observed, or the hub member a device is
	// connected to. err nil is reachable; source says where the answer came
	// from. It replaces a probe of every executor on every member — leases a
	// Kubernetes credential, asks a device another member holds — per report.
	Probe func(ctx context.Context, ex executor.Executor) (source string, err error)
}

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

type StepOutcome string

type StepResult struct {
	ID         string      `json:"id"`
	Title      string      `json:"title"`
	Outcome    StepOutcome `json:"outcome"`
	DurationMS int64       `json:"duration_ms"`
	// Panic is the recovered value of a step that panicked, rendered.
	Panic string `json:"panic,omitempty"`
	// RanAt is when a reused step's findings were made.
	RanAt time.Time `json:"ran_at,omitzero"`
}