application

type AppSetStatus struct {
	// Mode is how the set is sourced, as the deployment configured it —
	// "static", "git" or "path". It is a label passed in rather than something
	// the source infers about itself, so the bootstrap's own vocabulary is what
	// an operator sees reflected back.
	Mode string `json:"mode"`

	// Source is what the bootstrap was pointed at, for a human: the repository,
	// the revision it tracks and the file within it, or the directory and file
	// an external process keeps current. Mode alone cannot be checked against
	// anything, and "which branch is this controller following" is the first
	// question a set that does not look right raises — and the one thing nothing
	// in git can change (D-f of #47).
	Source string `json:"source,omitempty"`

	// Revision is the commit the running set was loaded from. Empty when the
	// set does not come from a repository.
	Revision string `json:"revision,omitempty"`

	// LoadedAt is when the running set last loaded successfully — not when it
	// was last checked. A load that changed nothing does not move it, so the
	// pair with Error answers "how old is what I am running".
	LoadedAt time.Time `json:"loadedAt"`

	// Error is why the last attempt failed: a load that was refused, or the
	// applications a diff could not apply. Cleared by the next attempt that
	// succeeds.
	Error string `json:"error,omitempty"`

	// Stale reports that the running set is a last-good one and a newer version
	// is being refused. It is the field a UI colours; Error is what it shows
	// beside it. An error with Stale false is one of two different problems: a
	// set that loaded but could not be fully applied, or — with Applications at
	// zero and LoadedAt unset — a controller that has never managed to load one,
	// which is the louder of the three.
	Stale bool `json:"stale"`

	// Orphaned names applications that left the set. Their loops are stopped and
	// their stacks are still deployed and no longer reconciled by anyone —
	// reported rather than removed, unless prune is enabled.
	//
	// This list is what the running loop watched leave, so a restart empties it.
	// That is a gap in the reporting and not in the cleanup: the owner stamps
	// the releases carry are the durable record, so a controller with prune
	// enabled still finds and removes an application that departed before it
	// started. With prune disabled a restart does forget, and the swarm is the
	// only place left that knows.
	Orphaned []string `json:"orphaned,omitempty"`

	// Pruned names applications whose resources this controller has deleted,
	// most recent last. Empty whenever prune is disabled, which is the default.
	//
	// It exists because a departed application otherwise leaves no trace at all
	// once prune has run: it is gone from the app set, gone from Orphaned, and
	// gone from the swarm. "Did it actually go, or did the controller never
	// notice" is then only answerable from the logs.
	//
	// Like Orphaned, in memory: a restart empties it. What it reports is this
	// process's own deletions, not an audit log.
	Pruned []string `json:"pruned,omitempty"`

	// PruneHeldBy names the applications that have not reconciled yet and are
	// therefore holding the sweep back. Empty whenever prune is disabled, and
	// on any controller whose applications have all planned at least once —
	// which after a settled startup is every controller.
	//
	// The sweep deletes what no application declares, so it cannot run while an
	// application has not said what it declares; it would read that silence as
	// a departure. Waiting is the safe half of that trade and this is the other
	// half: an operator who enabled prune and sees nothing being pruned has to
	// be able to find out which application is holding it, or the safety
	// measure is indistinguishable from a broken feature.
	PruneHeldBy []string `json:"pruneHeldBy,omitempty"`
}

type ChartSource struct {
	Release      string           `json:"release" yaml:"release"`
	Path         string           `json:"path,omitempty" yaml:"path,omitempty"` // chart directory within the repo
	Ref          string           `json:"ref,omitempty" yaml:"ref,omitempty"`   // repo/chart
	Version      string           `json:"version,omitempty" yaml:"version,omitempty"`
	Values       []string         `json:"values,omitempty" yaml:"values,omitempty"` // paths within the repo
	Repositories []RepositorySpec `json:"repositories,omitempty" yaml:"repositories,omitempty"`
}

type Compat struct {
	Status   CompatState `json:"status"`
	Required string      `json:"required,omitempty"`
	Engine   string      `json:"engine,omitempty"`
	Reason   string      `json:"reason,omitempty"`
}

type CompatState string

type ControllerStatus struct {
	AppSet       AppSetStatus `json:"appSet"`
	Applications int          `json:"applications"`
}

type Destination struct {
	Swarm string `json:"swarm,omitempty" yaml:"swarm,omitempty"`
}

type DriftDetection string

type Duration time.Duration

type Health struct {
	State    HealthState   `json:"state"`
	Message  string        `json:"message,omitempty"`
	Services ServiceCounts `json:"services"`
}

type HealthState string

type History struct {
	Releases []ReleaseHistory `json:"releases"`
}

type ReleaseDiff struct {
	Release string     `json:"release"`
	Action  SyncAction `json:"action"`
	Diff    string     `json:"diff"`
}

type ReleaseHistory struct {
	Name      string     `json:"name"`
	Revisions []Revision `json:"revisions"`
}

type ReleaseStatus struct {
	Name     string          `json:"name"`
	Chart    string          `json:"chart"`
	Version  string          `json:"version"`
	Revision int             `json:"revision"` // charts revision number; 0 when never installed
	Action   SyncAction      `json:"action"`
	Sync     SyncState       `json:"sync"`
	Health   Health          `json:"health"`
	Services []ServiceStatus `json:"services,omitempty"`
	Compat   *Compat         `json:"compat,omitempty"`
}

type RepositorySpec struct {
	Name string `json:"name" yaml:"name"`
	URL  string `json:"url" yaml:"url"`
}

type Revision struct {
	Revision int    `json:"revision"`
	Chart    string `json:"chart"`
	Version  string `json:"version"`
	// Status is the engine's derived status: the highest revision keeps its
	// stored status and every lower deployed one reads "superseded".
	Status string `json:"status"`
	// Created is RFC3339, as the engine recorded it.
	Created string `json:"created,omitempty"`
	// Owner is the stamp naming what produced the revision, empty when
	// unclaimed. A history view showing a revision this controller did not
	// install is telling the operator something worth knowing.
	Owner string `json:"owner,omitempty"`
}

type ServiceCounts struct {
	Healthy int `json:"healthy"`
	Total   int `json:"total"`
}

type ServiceStatus struct {
	Name        string      `json:"name"`
	Mode        string      `json:"mode"`
	Running     int         `json:"running"`
	Desired     int         `json:"desired"`
	Completed   int         `json:"completed,omitempty"`
	Health      HealthState `json:"health"`
	UpdateState string      `json:"updateState,omitempty"` // "" means never updated, not finished
	Message     string      `json:"message,omitempty"`
}

type Source struct {
	RepoURL  string `json:"repoURL" yaml:"repoURL"`
	Revision string `json:"revision" yaml:"revision"` // branch, tag or SHA, as written

	ReleaseFile string       `json:"releaseFile,omitempty" yaml:"releaseFile,omitempty"` // path within the repo
	Chart       *ChartSource `json:"chart,omitempty" yaml:"chart,omitempty"`
}

type Spec struct {
	Name   string `json:"name" yaml:"name"`
	Source Source `json:"source" yaml:"source"`

	// RegistryAuth names a Docker secret holding a docker config.json
	// ({"auths":{...}}). The controller uses only this application's secret to
	// authenticate the pulls its images need, so one application cannot pull
	// another's private images even though both credentials are mounted in the
	// same controller. Empty means the application's images are public.
	//
	// It is a secret name, not a path: the controller reads it from the default
	// mount /run/secrets/<name>, so the secret must be mounted there — the
	// short form `secrets: [<name>]` in stack.yml does exactly that.
	RegistryAuth string `json:"registryAuth,omitempty" yaml:"registryAuth,omitempty"`

	Destination    Destination    `json:"destination" yaml:"destination"`
	SyncPolicy     SyncPolicy     `json:"syncPolicy" yaml:"syncPolicy"`
	DriftDetection DriftDetection `json:"driftDetection" yaml:"driftDetection"`
}

type Status struct {
	Sync       Sync            `json:"sync"`
	Health     Health          `json:"health"`
	Releases   []ReleaseStatus `json:"releases,omitempty"`
	Error      string          `json:"error,omitempty"` // last reconcile error; not a failed sync
	ObservedAt time.Time       `json:"observedAt"`
}

type Sync struct {
	State    SyncState   `json:"state"`
	Revision string      `json:"revision,omitempty"` // resolved SHA, never a branch name
	Summary  SyncSummary `json:"summary"`
	LastSync *SyncResult `json:"lastSync,omitempty"`
}

type SyncAction string

type SyncPolicy struct {
	Automated  bool     `json:"automated" yaml:"automated"`
	Interval   Duration `json:"interval,omitempty" yaml:"interval,omitempty"`
	Wait       bool     `json:"wait,omitempty" yaml:"wait,omitempty"`
	Timeout    Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	HistoryMax int      `json:"historyMax,omitempty" yaml:"historyMax,omitempty"`

	// Prune deletes the resources of a release this application used to declare
	// and no longer does. Off by default: reporting an orphan is safe and
	// deleting one is not, so it is a deliberate choice per application.
	//
	// It governs only this application's own releases — those carrying its
	// owner stamp. A release another application or the command line installed
	// is unmanaged here and is never touched, whatever this says.
	//
	// Not to be confused with HistoryMax, which prunes an individual release's
	// revision history rather than the release itself. Two senses of the word,
	// one of which is the chart engine's; see the prune package.
	Prune bool `json:"prune,omitempty" yaml:"prune,omitempty"`

	// PruneVolumes extends Prune to the named volumes of what it deletes, and
	// means nothing without it — a config declaring one and not the other is
	// refused rather than half-obeyed.
	//
	// Separate from Prune because it is the one irreversible part. Everything
	// else prune removes can be recreated from git on the next reconcile; the
	// data in a volume cannot be recreated from anything.
	PruneVolumes bool `json:"pruneVolumes,omitempty" yaml:"pruneVolumes,omitempty"`

	// PruneFirst deletes before installing, instead of after.
	//
	// The default order applies and then prunes, so a failed apply leaves the
	// old release running rather than nothing at all. The cost is that a
	// renamed release briefly coexists with the name it replaced: the new name
	// is an install and the old one an orphan, and between the two steps both
	// are deployed.
	//
	// For a workload where two instances running at once is worse than none —
	// a blockchain validator that would double-sign and be slashed, a job
	// runner that must not process a queue twice — that trade is the wrong way
	// round. This inverts it: the departing release is deleted before its
	// replacement is installed, so they never overlap, and a failed apply
	// leaves a gap instead.
	//
	// It bounds the overlap this controller creates deliberately; it is not a
	// distributed lock. Nothing here can prevent two instances during a network
	// partition or a node recovering with stale state, so a workload that
	// cannot tolerate that at all needs an external guard — a remote signer
	// with an anti-slashing record, or a lease.
	//
	// Means nothing without Prune, and is refused rather than ignored.
	PruneFirst bool `json:"pruneFirst,omitempty" yaml:"pruneFirst,omitempty"`
}

type SyncResult struct {
	Revision   string    `json:"revision"`
	StartedAt  time.Time `json:"startedAt"`
	FinishedAt time.Time `json:"finishedAt"`
	Succeeded  bool      `json:"succeeded"`
	Error      string    `json:"error,omitempty"`
}

type SyncState string

type SyncSummary struct {
	Install   int `json:"install"`
	Upgrade   int `json:"upgrade"`
	Unchanged int `json:"unchanged"`
}

type View struct {
	Spec   Spec   `json:"spec"`
	Status Status `json:"status"`
}