ops

type AuditEntry struct {
	At   metav1.Time `json:"at"`
	Kind AuditKind   `json:"kind"`
	// Namespace is which one this happened in. Carried on every entry because
	// an audit spanning namespaces has no other way to say, and a Gate name is
	// not unique across them.
	Namespace string `json:"namespace"`
	Gate      string `json:"gate"`
	Bundle    string `json:"bundle,omitempty"`
	// Digest is what actually shipped. The Bundle name is a label; this is the
	// content address, and it is the only field that answers "which bits".
	Digest string `json:"digest,omitempty"`
	// Actor is who caused it. Empty means nobody did — an automatic Gate acting
	// on its own, which is a meaningful answer rather than a missing one.
	Actor   string `json:"actor,omitempty"`
	Passage string `json:"passage,omitempty"`
	// Detail is why, for a refusal, in the words of whatever refused.
	Detail string `json:"detail,omitempty"`
	// Verified records whether a crossing's verification confirmed it worked,
	// which is a different question from whether it completed.
	Verified *bool `json:"verified,omitempty"`
	// Evidence links the entry to the compliance record: the Fides trail, the
	// verdict, and any blockers. This is what turns "it was promoted" into
	// "it was promoted, and here is what said it could be".
	Evidence *v1alpha1.EvidenceRef `json:"evidence,omitempty"`
}

type AuditKind string

type Blocker struct {
	// Kind is a stable code, so a caller can branch without parsing prose.
	Kind BlockerKind `json:"kind"`
	// Detail is the human-readable specifics.
	Detail string `json:"detail"`
	// Fix is what would unblock it, when there is a single obvious answer.
	Fix string `json:"fix,omitempty"`
}

type BlockerKind string

type Day struct {
	// Date is the day in YYYY-MM-DD, in UTC. A chart axis needs a stable label
	// and the server is the only place that knows what "today" means for the
	// data it just counted.
	Date string `json:"date"`
	// Crossed is how many Bundles entered a Gate that day.
	Crossed int `json:"crossed"`
	// Failed is how many Passages ended badly that day.
	//
	// Subject to Passage retention, unlike Crossed — a failure that has been
	// collected is no longer counted. Better than not drawing failures at all,
	// but it means the further back the chart goes the more it flatters.
	Failed int `json:"failed"`
}

type Evidence struct {
	Bundle    string `json:"bundle"`
	Namespace string `json:"namespace"`
	// Digest is the artifact all of this is about. Named explicitly because the
	// evidence belongs to the image, not to the Bundle that happens to pin it.
	Digest string `json:"digest,omitempty"`
	// Trail is the Fides trail this evidence lives on. Reported as the bare
	// identifier rather than a link: the portal is a single-page export with
	// no per-trail route to deep-link to, and a link that 404s is worse than
	// an id an auditor can paste.
	Trail string `json:"trail,omitempty"`
	// Gate is which Gate's Fides configuration was used to look this up, so a
	// reader can tell which environment's view they are seeing.
	Gate string `json:"gate,omitempty"`
	// Verdict is the change gate's answer, with its controls, attestation
	// counts, approvals and segregation-of-duties finding.
	Verdict *fides.ChangeVerdict `json:"verdict,omitempty"`
	// Change is the ITSM change request governing this crossing, when one has
	// been checked. Carried alongside the verdict rather than inside it: the
	// verdict is Fides' judgement of the evidence, and this is the ticket a
	// person opens when they disagree with it.
	Change *fides.ChangeRequest `json:"change,omitempty"`
	// ApprovedIn lists the approvals Hecate itself recorded, which is not the
	// same list as Fides' — a Gate that does not use Fides still has approvers,
	// and they belong in the answer to "who allowed it".
	ApprovedIn []v1alpha1.BundleApproval `json:"approvedIn,omitempty"`
	// Unavailable says why there is nothing to show, when there is nothing.
	// A panel that renders empty is indistinguishable from a clean bill of
	// health, and those are opposite answers.
	Unavailable string `json:"unavailable,omitempty"`
}

type Explanation struct {
	Gate      string `json:"gate"`
	Namespace string `json:"namespace"`
	State     State  `json:"state"`
	// Summary is one line, suitable on its own.
	Summary string `json:"summary"`
	// Blockers are the specific things standing in the way, most actionable
	// first. Empty when nothing is wrong.
	Blockers []Blocker `json:"blockers,omitempty"`
	// Current is the Bundle in the environment now, if any.
	Current string `json:"current,omitempty"`
	// Eligible names Bundles that could cross right now.
	Eligible []string `json:"eligible,omitempty"`
	// Waiting names Bundles that cannot, with the reason for each.
	Waiting []Waiting `json:"waiting,omitempty"`
	// Health is the Gate's own assessment of what it watches.
	Health v1alpha1.Health `json:"health,omitempty"`
	// Evidence is the change gate's verdict for the crossing in progress, when
	// there is one. Carried whole so a caller can show the risk score next to
	// the reasons rather than parsing them back out of a sentence.
	Evidence *v1alpha1.EvidenceRef `json:"evidence,omitempty"`
}

type FluxResource struct {
	Kind      string `json:"kind"`
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	// Suspended means Flux is not reconciling it.
	//
	// The reason this whole screen exists. A suspended resource is cluster
	// state that git will not restore, so it outlives the debugging session it
	// was created for — and every crossing afterwards appears to succeed while
	// changing nothing, because the step that would have applied it is not
	// running. It is the one Flux state that fails silently.
	Suspended bool `json:"suspended"`
	// Health is what pkg/flux makes of its conditions.
	Health v1alpha1.Health `json:"health"`
	// Detail is the Ready condition's message, or why it is not Ready.
	Detail string `json:"detail,omitempty"`
	// Revision is what Flux has actually applied.
	Revision string `json:"revision,omitempty"`
	// LastHandled is the reconcile request Flux has acted on, so a caller can
	// tell its own "reconcile now" landed rather than watching for any change.
	LastHandled string `json:"lastHandled,omitempty"`
	// Missing means the Gate names it and the cluster does not have it. Not an
	// error: a Gate committed before its Kustomization exists is ordinary, and
	// reporting it as absent beats reporting it as unhealthy.
	Missing bool `json:"missing"`
}

type GateSummary struct {
	Name string `json:"name"`
	// Health is the Gate's own report, or Unknown when it has none yet.
	Health v1alpha1.Health `json:"health"`
	// Issues is why the health is what it is. Carried here rather than left to
	// a click, because a board that shows a red dot and no reason sends
	// everyone to the same second page to find out.
	Issues []string `json:"issues,omitempty"`
	// Current is the Bundle in the Gate now.
	Current string `json:"current,omitempty"`
	// Eligible counts what could cross. The names are one page away; the count
	// is what decides whether to look.
	Eligible int `json:"eligible"`
	// Running is the Passage crossing this Gate now, if one is.
	Running string `json:"running,omitempty"`
	// Suspended means the Gate will not admit anything until it is resumed.
	// Reported prominently for the same reason a suspended Beacon is: a
	// suspended Gate looks exactly like a quiet one, and "nothing has shipped
	// all week" is usually this.
	Suspended bool `json:"suspended"`
}

type NamespaceOverview struct {
	Namespace string        `json:"namespace"`
	Gates     []GateSummary `json:"gates"`
}

type NotFoundError struct {
	Kind      string
	Namespace string
	Name      string
}

type Ops struct {
	Client client.Client
	// Now is the clock, injectable for tests and for judging promotion windows.
	Now func() metav1.Time
	// FidesServer is the default Fides server, used when a Gate names none of
	// its own. Approvals are recorded there so segregation of duties can be
	// evaluated over real identities.
	FidesServer string
	// DialFides is injectable so tests can point at a fake Fides. Nil is the
	// real client.
	DialFides func(fides.Config) (*fides.Client, error)
}

type Overview struct {
	// Namespaces holds one entry per namespace with Gates in it, ordered by
	// name so the page does not reshuffle between loads.
	Namespaces []NamespaceOverview `json:"namespaces"`
	// Totals is the whole picture in numbers.
	Totals Totals `json:"totals"`
	// Activity is what crossed and what failed, by day, oldest first.
	Activity []Day `json:"activity"`
}

type Preflight struct {
	Bundle string `json:"bundle"`
	// Compliant is whether the evidence gate would let it through.
	Compliant bool `json:"compliant"`
	// Missing is the attestation types the policies wanted and the trail does
	// not have, deduplicated across policies — one missing type failing four
	// policies is one thing to fix, not four.
	Missing []string `json:"missing,omitempty"`
	// Policies names the policies that are not satisfied. Carried alongside
	// Missing rather than instead of it, because they answer different
	// questions: which rule stopped this, and what has to exist for it not to.
	Policies []string `json:"policies,omitempty"`
	// Unknown says why there is no answer, when there is none. A Bundle whose
	// evidence could not be checked is not a Bundle that passed, and rendering
	// the two the same way is how a page starts lying.
	Unknown string `json:"unknown,omitempty"`
}

type RefusedError struct {
	Action string
	Reason string
}

type State string

type Totals struct {
	Gates       int `json:"gates"`
	Healthy     int `json:"healthy"`
	Progressing int `json:"progressing"`
	Degraded    int `json:"degraded"`
	Unknown     int `json:"unknown"`
	Suspended   int `json:"suspended"`
	// Eligible is how many Bundles could cross somewhere right now.
	Eligible int `json:"eligible"`
	// Running is how many Passages are in flight.
	Running int `json:"running"`
	// Failed is how many Passages ended badly and are still around to say so.
	// Retention collects Passages (D40), so this is "recently" by definition
	// rather than by a window this code picks.
	Failed int `json:"failed"`
}

type Waiting struct {
	Bundle string `json:"bundle"`
	Reason string `json:"reason"`
	// Kind is the same reason as a stable code, matching BlockerKind's values
	// where they overlap. Without it the approval queue would have to decide
	// what is waiting on a human by matching the prose, and rewording a message
	// would break a caller.
	Kind gate.Code `json:"kind,omitempty"`
}