reconciler

type AuditEvent struct {
	Action string
	AppID  string
	Detail map[string]any
}

type AuditWriter interface {
	Write(ctx context.Context, e audit.Event) error
}

type Auditor interface {
	Write(ctx context.Context, e AuditEvent) error
}

type AutoDeploy struct {
	Apps        *state.Apps
	Deployments *state.Deployments
	Checks      *state.AutoDeployChecks
	Resolver    RefResolver

	// Deployer starts a deploy as a person's would (approval.Service).
	Deployer Deployer

	// Audit records each auto-deploy, with the commit it moves from and to,
	// before anything is created (R-227, R-228).
	Audit AuditWriter

	Logger *zap.Logger

	// Concurrency is how many apps are checked at once. Eight when zero
	// [P]: each check is a `git ls-remote` against somebody's git host, and
	// in series a poll over a few thousand apps outlasted its own interval.
	Concurrency int

	// Policy is host policy as it is now. An app whose deploys need approval
	// does not auto-deploy (R-158); nil reads as no policy, so nothing is
	// skipped for it.
	Policy PolicyLoader
}

type BackupRunner interface {
	CreateForApp(ctx context.Context, id string, req backup.AppCreateRequest) (backup.Created, error)
	Discard(ctx context.Context, adapterRef, objectName string) error
}

type BuildCaches interface {
	Forget(ctx context.Context, builderRef, appID string) error
}

type Deployer interface {
	Deploy(ctx context.Context, p authz.Principal, app state.App, rev state.Revision, trigger string) (state.Deployment, error)
}

type Desired interface {
	SetDesiredState(ctx context.Context, appID, desired string) error
}

type Difference struct {
	Workload string
	Kind     string
	Detail   string
}

type Drift struct {
	// Reconcilable are differences the reconciler may correct. Every one of
	// them is a thing to create or start.
	Reconcilable []Difference

	// ReportOnly are differences it must not. Every one of them would mean
	// destroying or overwriting something a person may have put there.
	ReportOnly []Difference
}

type Environments interface {
	Environments(ctx context.Context, s *spec.AppSpec) (map[string]map[string]secret.Value, error)
}

type GC struct {
	Apps   *state.Apps
	Logger *zap.Logger

	// Registry resolves the adapters that hold a deleted app's bundle. Nil
	// disables teardown rather than failing: an install with no runtime
	// configured has nothing to tear down.
	Registry Registry

	// Auditor records teardowns. Destroying a bundle is destruction, and
	// R-227's rule does not have an exception for the janitor.
	Auditor Auditor

	// Backups gates reclaiming a deleted app's storage on a backup holding
	// its data. Nil disables that rather than failing. Taking and expiring
	// rolling backups is RollingBackups, a job of its own (issue #72).
	Backups *state.Backups

	// The security pass (R-315, R-316). All four are nil on an installation
	// with no scanner, where nothing is scored and the pass does nothing.
	Security      SecurityScores
	SecurityState SecurityState
	PolicyStore   PolicyStore
	Desired       Desired
	Notifier      OwnerNotifier

	// Clock is here so retention is testable without waiting a day.
	Clock clock.Clock

	// Interval overrides GCInterval. Zero means the default.
	//
	// Configurable for the same reason the retry backoff is: the acceptance
	// test for bundle teardown would otherwise have to wait an hour to watch a
	// janitor run. Nothing here is urgent, so a short interval is wasteful
	// rather than dangerous — which is why this one gets no startup warning.
	Interval time.Duration

	// TeardownNow starts a teardown pass between ticks. Deleting an app sends
	// on it, so the app's containers stop when it is deleted rather than at the
	// next pass — which was up to an hour later, while a force-deleted app kept
	// running and holding its share of the host (issue #55). Nil means ticks
	// only.
	//
	// Served by a loop of its own, so a delete is acted on while the rest of
	// a pass — a security pass over every app, reclaiming storage — is still
	// running, rather than after it (issue #72).
	TeardownNow <-chan struct{}

	// TeardownEvery is how often teardown runs when nothing asks: a delete
	// whose signal reached another replica, or one whose runtime was away.
	// Ten seconds when zero.
	TeardownEvery time.Duration

	// BuildCaches and DiscardUpload remove a deleted app's build cache and
	// uploaded source at teardown. Nil skips each.
	BuildCaches   BuildCaches
	DiscardUpload func(ctx context.Context, appID string) error

	// DiscardCredential removes a deleted app's registry credential (issue
	// #41). Apps soft-delete, so the row's cascade never fires; a credential
	// for an app nobody can deploy is a key kept for no one. Nil skips it.
	DiscardCredential func(ctx context.Context, appID string) error

	// RegistryImages deletes a deleted app's builds from the install's image
	// registry (issue #72 PR 5, R-224). Nil when the install has none. Best
	// effort: a failure is recorded on the teardown's audit event and does
	// not hold the teardown.
	RegistryImages RegistryImages
	// contains filtered or unexported fields
}

type Holds interface {
	Held(ctx context.Context, appID string) (state.Hold, error)
	// HostHeld is what holds every app on host, a name the runtime gave
	// (api.ObservedBundle.Host): whether it is lost or fenced.
	HostHeld(ctx context.Context, host string) (state.Hold, error)
}

type Inputs struct {
	// ExpectedDigests is what each workload ran, by name. A workload with no
	// entry is not checked: unknown is not drift.
	//
	// Per workload because an app's parts can be built separately. One digest
	// compared against every workload made every service but one look wrong
	// forever, and "correcting" that replaced them with the primary's image.
	ExpectedDigests map[string]string

	// ExpectedDigest is the image the last successful deployment ran, which is
	// the primary workload's. Kept for the single-image case and for the
	// report text; the per-workload map decides.
	ExpectedDigest string

	// AppliedEnvHash and CurrentEnvHash stand in for environment observation
	// (R-193). Either being empty means the comparison cannot be made, and an
	// unanswerable question is not drift.
	AppliedEnvHash string
	CurrentEnvHash string

	// VolumesThatHeldData is the difference between a volume Pando may recreate
	// and one it must only report.
	VolumesThatHeldData map[string]bool

	RouteExpected bool
	RoutePresent  bool
}

type Notifier interface {
	Notify(ctx context.Context, n api.Notification) error
}

type OwnerNotifier interface {
	Notify(ctx context.Context, userID, appID, subject, body string)
}

type PolicyLoader interface {
	Load(ctx context.Context) (policy.Document, error)
}

type PolicyStore interface {
	Document(ctx context.Context) (policy.Document, error)
}

type Reconciler struct {
	Apps       *state.Apps
	Reconciles *state.Reconciles
	Secrets    *state.Secrets

	// Services adds provisioned services to what should be running (R-131).
	// Nil on an install with no provisioner, where every app's shape is already
	// complete.
	Services ServiceShapes

	// Environments supplies what each workload runs with when a correction
	// is applied (R-148). Nil applies the shape as it is, which is complete
	// only for an app whose workloads take no environment.
	Environments Environments

	Volumes  *state.Volumes
	Registry Registry
	Auditor  Auditor
	Notifier Notifier
	Logger   *zap.Logger
	Clock    clock.Clock

	// BuiltImageAuth is the install registry's credential for an image Pando
	// pushed there, nil for any other (issue #72, PR 5). A workload restored
	// on a runtime that pulls needs it for the pull, as the deploy did. Nil
	// means no install registry. Nil too for an image s names: the
	// credential is for the app's own builds (R-025).
	BuiltImageAuth func(ctx context.Context, s *spec.AppSpec, ref string) *api.RegistryAuth

	// Backoff, FailureThreshold and FailureWindow override R-149 and R-150's
	// defaults. Zero values mean the defaults, so a caller that does not care
	// sets nothing.
	//
	// Configurable because the acceptance test for R-151 — a crash-looping app
	// reaches failed and stays there — has to wait out the real schedule, and
	// at the production numbers that is forty minutes of a forty-three minute
	// suite. The test is asserting the state machine, not the durations, and it
	// was paying for the durations.
	//
	// The state machine is what stays under test either way: compressing the
	// schedule changes how long each step waits and nothing about which step
	// comes next.
	Backoff          []time.Duration
	FailureThreshold int
	FailureWindow    time.Duration

	// MinRevisit is how recently visited an app may be and still be left
	// for a later pass (DefaultMinRevisit in production). Zero visits every
	// app on every pass, which is what a test calling Tick in a row wants.
	MinRevisit time.Duration

	// LeaseDuration overrides DefaultLeaseDuration. Zero means the default.
	LeaseDuration time.Duration

	// SettledRevisit is how long an app found as it should be is left before
	// it is looked at again, when its runtime reports events (O-52, events.go).
	// Zero means DefaultSettledRevisit.
	SettledRevisit time.Duration

	// Runtimes names the runtime adapters whose events Run follows (O-52).
	// Asked again on every tick, so a runtime added in the console is
	// followed without a restart. Nil follows none, and every app is visited
	// on every pass, as before events.
	Runtimes func() []string

	// Holds keeps the reconciler off an app whose host is lost or fenced, or
	// whose standby is being promoted (holds.go). Nil holds nothing, as on
	// an install with one host.
	Holds Holds

	// Hosts counts the cluster's hosts (hosts.Service.Count). While it is
	// one, nothing can hold an app — no other host to be lost, fenced or
	// promoted to — and Holds is not consulted (holds.go). Nil consults Holds
	// whenever it is set.
	Hosts func(ctx context.Context) (int, error)

	// LocalFenced reports whether this replica's own host is fenced (R-421).
	// While it is, Tick does nothing: a host cut off from most of the
	// cluster starts nothing. Nil is never.
	LocalFenced func() bool

	// ProxyUpstream is where routes point. Every route points at Pando's proxy
	// and never at a workload (R-023) — the reconciler re-ensuring a route must
	// not be the one place that forgets.
	ProxyUpstream string
	// contains filtered or unexported fields
}

type RefResolver interface {
	Resolve(ctx context.Context, src spec.Source, ad spec.AutoDeploy) (source.Tracked, error)
}

type Registry interface {
	Runtime(ref string) (api.RuntimeAdapter, bool)
	Routing(ref string) (api.RoutingAdapter, bool)
}

type RegistryImages interface {
	DeleteApp(ctx context.Context, appID string) error
}

type RollingBackups struct {
	Apps         *state.Apps
	Backups      *state.Backups
	Backup       BackupRunner
	BundleSource *state.BundleSource
	Auditor      Auditor
	Logger       *zap.Logger
	Clock        clock.Clock

	// Every is how often to look for apps due a backup. Five minutes when
	// zero [P]: a backup is due once a day, so this is how late one can be.
	Every time.Duration

	// Concurrency is how many backups run at once. Two when zero [P]: a
	// backup copies a volume, and the disk it reads is the one the apps use.
	Concurrency int

	// RetryAfter is how long after an attempt that was skipped or failed the
	// app is tried again. An hour when zero, which is what the attempt's
	// remedy tells a person ("within the hour").
	RetryAfter time.Duration

	// Batch is the most apps one pass takes. 200 when zero.
	Batch int
}

type RouteSync struct {
	Apps interface {
		LiveApps(ctx context.Context, f planner.InventoryFilter) ([]planner.InventoryApp, error)
	}
	Registry Registry

	// ProxyUpstream is where every route points: this host's Pando.
	ProxyUpstream string

	// ControlHosts counts the hosts holding the control role
	// (hosts.Service.ControlCount). With one, every edge is that host's and
	// its routes are the reconciler's alone, so the pass is skipped, however
	// many app hosts there are. Nil runs it always.
	ControlHosts func(ctx context.Context) (int, error)

	// Exclusive runs pass unless another replica on this host is running
	// one (state.Cluster.OnePerHost), and reports whether it ran: every
	// replica of a host writes to one edge, so one pass at a time is enough.
	// Nil runs it always.
	Exclusive func(ctx context.Context, pass func(context.Context)) (bool, error)

	Interval time.Duration
	Clock    clock.Clock
	Logger   *zap.Logger
	// contains filtered or unexported fields
}

type SecurityScores interface {
	Configured() (string, bool)
	Place(ctx context.Context, scores map[string]security.Scores) (map[string]security.Placed, error)
}

type SecurityState interface {
	LiveSecurityState(ctx context.Context, t state.SecurityThreshold) ([]state.SecurityState, error)
	MarkInsecure(ctx context.Context, appID string, at time.Time) error
	ClearInsecure(ctx context.Context, appID string) error
	SetStoppedForSecurity(ctx context.Context, appID string, stopped bool) error
}

type ServiceShapes interface {
	ServiceShapes(ctx context.Context, s *spec.AppSpec) (api.BundlePlan, error)
}