reconcile

type CredentialsFunc func(dir string, cfg *config.Config, execID string) (Identity, func(), error)

type Diagnostic struct {
	// ID is the executor ID, which is also the registry key.
	ID string `json:"id"`
	// Kind is the executor.Kind* the driver reports.
	Kind string `json:"kind"`
	// Status is the reconciliation outcome.
	Status Status `json:"status"`
	// Registered reports whether the executor ended up in the registry.
	// Degraded executors are registered; failed ones are not.
	Registered bool `json:"registered"`
	// Isolating reports whether this driver puts a boundary between the
	// workload and the control-plane host. It is what strict mode counts.
	Isolating bool `json:"isolating"`
	// Message is the one-line summary an operator reads first.
	Message string `json:"message"`
	// Remediation is the concrete next action. Empty only when Status is OK.
	Remediation string `json:"remediation,omitempty"`
	// Findings is the preflight checklist, when one was run.
	Findings []Finding `json:"findings,omitempty"`
	// CheckedAt is when this diagnostic was produced.
	CheckedAt time.Time `json:"checked_at"`
}

type ExecutorSweep struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	// Removed counts the objects collected. For Kubernetes that is Pods plus
	// the NetworkPolicies that governed them; for the container driver it is
	// sandbox containers.
	Removed int `json:"removed"`
	// Objects names what went, newest-format "namespace/name", capped so a
	// pathological sweep cannot put an unbounded slice into an HTTP response.
	Objects []string `json:"objects,omitempty"`
	// Error is the driver's failure, if the pass could not complete. A sweep
	// that failed is reported rather than hidden: an operator whose RBAC lost
	// the list verb should find out from the fleet panel, not from a namespace
	// slowly filling with Pods.
	Error string `json:"error,omitempty"`
}

type Finding struct {
	Name string `json:"name"`
	// Level is "ok", "warn" or "fail", matching both drivers' vocabulary.
	Level   string `json:"level"`
	Message string `json:"message"`
	Fix     string `json:"fix,omitempty"`
}

type Identity struct {
	// Cluster authenticates to the Kubernetes API server. Required.
	Cluster kubernetes.CredentialSource
	// Workspace leases the credential a private-repository fetch needs. nil is
	// legitimate and means "public repositories only": an in-cluster hub with
	// no sealing key can still schedule Pods, and the driver's preflight says
	// so rather than failing a deployment that never needed it.
	Workspace executor.WorkspaceCredentialSource
}

type NotReadyError struct {
	// Reason is the one-line cause.
	Reason string
	// Remediation is the concrete next action.
	Remediation string
	// Diagnostics are the failed or degraded drivers from the last
	// reconciliation, when there was one. Empty means nothing was even
	// configured — a materially different and more urgent situation than a
	// driver that tried and failed.
	Diagnostics []Diagnostic
}

type Options struct {
	// Registry receives the executors. nil means executor.DefaultRegistry.
	Registry *executor.Registry

	// SkipPreflight registers without probing. Preflight costs container
	// runtime calls and Kubernetes API round-trips, which is the right price
	// for a long-running hub and the wrong one for a short CLI command that
	// will never dispatch a workload.
	SkipPreflight bool

	// PreflightTimeout bounds each driver's probe. Zero uses
	// DefaultPreflightTimeout. A cluster that cannot answer in this long is
	// one the operator needs told about, not one worth waiting for.
	PreflightTimeout time.Duration

	// ReconcileOrphans asks for the full restart sweep: orphaned Pods and
	// orphaned containers from the drivers, stale `running` session rows, and
	// leaked task worktrees. It costs API calls and runtime round-trips, so
	// only the entry points a control plane actually restarts as should ask
	// for it.
	//
	// It was Kubernetes-only until Task 20191, which is why the name says
	// "orphans" rather than "restart". The three additions all answer the
	// same question — "what did the process I am replacing leave behind?" —
	// and splitting them across four flags would only create combinations
	// with no operator meaning. See startup.go.
	ReconcileOrphans bool

	// HandleStore persists driver handle identity so a control plane that
	// restarts reattaches to workloads that are still running instead of
	// losing them (Task 20191).
	//
	// Nil means "open dir's state database", which is what a real deployment
	// wants and what makes ReconcileOrphans able to tell a workload this hub
	// dispatched from an orphan. Set DisableHandleStore to opt out entirely.
	HandleStore executor.HandleStore

	// DisableHandleStore suppresses handle persistence. Tests reconciling
	// into a private registry set it so a pass over a temp directory does not
	// create a state database as a side effect.
	//
	// It is a separate bool rather than a nil HandleStore because nil already
	// means "use the default", the same shape Publish needed and for the same
	// reason: the zero value has to be the production behaviour.
	DisableHandleStore bool

	// WorktreeMinAge bounds the leaked-worktree sweep. Zero uses
	// worktree.DefaultMinAge. It is the single most safety-critical knob in
	// the sweep — see pruneWorktrees.
	WorktreeMinAge time.Duration

	// SweepInterval is how often the orphan sweep repeats after startup. Zero
	// uses DefaultSweepInterval; negative disables it entirely.
	//
	// Negative-means-off rather than zero-means-off because zero is what an
	// unset field is, and the default has to be the behaviour a deployment
	// that never heard of this option should get. An operator turning it off
	// says so explicitly; see ExecutorsConfig.OrphanSweepIntervalMinutes,
	// where the operator-facing 0 is translated to a negative here.
	//
	// Only honoured alongside ReconcileOrphans: the sweep is the same work,
	// and an entry point that does not want it at startup does not want it
	// every fifteen minutes either. See periodic.go.
	SweepInterval time.Duration

	// KubernetesCredentials overrides how the Kubernetes driver's identity is
	// obtained. nil uses BrokerCredentials, which reads the secret broker out
	// of dir's state database. Tests and embedders that already hold a
	// credential source inject it here.
	KubernetesCredentials CredentialsFunc

	// WrapWorkspaceSource decorates the credential source a driver is given,
	// per executor. nil means no decoration.
	//
	// It exists so the hub can interpose the git interception proxy
	// (pkg/executor/gitproxycreds) without this package learning about it:
	// reconciliation decides *which* executors exist and what authenticates
	// them, while whether a sandbox reaches the forge directly or through a
	// proxy is a property of the deployment. A nil source stays nil — there is
	// nothing to route when no credential is leased in the first place.
	WrapWorkspaceSource func(execID string, src executor.WorkspaceCredentialSource) executor.WorkspaceCredentialSource

	// Logf receives one line per diagnostic. nil logs to stderr; supply a
	// no-op to silence a pass entirely.
	Logf func(format string, args ...any)

	// QuietWhenHealthy logs only problems. A CLI invocation wants this — a
	// line reading "executor container: ready" on every `cloop status` is
	// noise, and a caller that prefixes its output with "warning:" would
	// otherwise emit "warning: ... ready". A long-running server wants the
	// healthy lines, because "which executors did this hub come up with" is
	// the first question asked of a startup log.
	QuietWhenHealthy bool

	// Publish records the report where LastReport and Ready can see it.
	// Defaults to true; tests reconciling into a private registry set it
	// false so they do not disturb process-global state.
	//
	// It is a pointer so the zero value can mean "yes" while still letting a
	// caller say "no" explicitly.
	Publish *bool

	// ControlPlaneDir is the hub's own directory, handed to the drivers that
	// bind or fork in a project's directory so each refuses one that contains
	// it (Task 20418, projectconfine.Backstop). Empty — a CLI command
	// reconciling for itself — checks nothing there; the hub always sets it.
	ControlPlaneDir string

	// SweepGate, when set, is asked before the startup sweep (periodic false)
	// and before each periodic orphan sweep (periodic true); a pass it refuses
	// is skipped. Nil runs every pass, which is right for a control plane
	// served by one process.
	//
	// For one served by several (Task 20354): the startup sweep closes
	// session rows whose workload this process cannot see and prunes the
	// worktrees of tasks not among them — both true of every live peer's work
	// — so it may only run while no peer is serving. The periodic orphan sweep
	// spares peers' workloads by itself (see executor.TrackedElsewhere) and is
	// gated to one process only so that it is not done N times.
	SweepGate func(periodic bool) bool
}

type Report struct {
	// Dir is the directory whose config was reconciled.
	Dir string `json:"dir"`
	// Diagnostics is one entry per configured driver, ordered by ID.
	Diagnostics []Diagnostic `json:"diagnostics"`
	// StrictMode is the host-execution policy in force when the pass ran.
	StrictMode bool `json:"strict_mode"`
	// ReconciledAt is when the pass completed.
	ReconciledAt time.Time `json:"reconciled_at"`
}

type Status string

type SweepReport struct {
	At        time.Time       `json:"at"`
	Removed   int             `json:"removed"`
	Executors []ExecutorSweep `json:"executors,omitempty"`
}