statusview

package
v0.2.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package statusview holds what `kubectl ptah schema` and `kubectl ptah migration` print the same way: the conditions the operator published, the ones a reader reads first, the decisions people made about a resource, and a list the reader was not allowed to read.

Nothing here decides anything about a resource. Every value comes from a field the operator or admission wrote, and the only judgments made are which of those fields a reader sees first.

Index

Constants

View Source
const DetailsHeading = "\nDetails, every status field this plugin's API version knows:\n"

DetailsHeading opens the part of a view --details adds, after everything the view prints without it. The status is decoded into the API types this plugin was built with, so a field a newer operator added is not among them.

View Source
const MaxDecisions = 5

MaxDecisions bounds how many approvals or acknowledgments one view prints. A resource collects one for every plan somebody approved, and a terminal is for the ones that explain where it stands now: the newest.

View Source
const TimeLayout = "2006-01-02T15:04:05Z"

TimeLayout is how every instant is printed: UTC, to the second.

Variables

View Source
var LabelWidth = leadingLabelWidth()

LabelWidth is the column the schema and migration views pad every "Label:" to, so that every value starts in the same column. A condition read first is labeled by its type, and the longest of those types is longer than any label the views print of their own.

Functions

func After added in v0.2.11

func After(at *metav1.Time) string

After is a time a record waits for, or nothing.

func Claimed added in v0.2.11

func Claimed(operationType string, attempt int32, startedAt metav1.Time) string

Claimed is the summary of an operation claim: its type, its attempt, and when it was claimed, where the claim records that.

func Clean

func Clean(text string) string

Clean makes free text safe to print on one terminal line.

A message, a reason or a user name reaches the screen from whoever wrote it: the operator, Ptah's report, an identity provider. A line break would split one row of a table into two that read as separate rows, and a control sequence or a bidirectional override can rewrite what the terminal shows. Line breaks and tabs become spaces; every other control character and every bidirectional control is printed as its escape, so a reader sees that it was there. Format characters -- zero-width spaces and joiners, a byte order mark, a soft hyphen -- are escaped too: they print as nothing, so a name that holds one reads exactly like a name that does not.

func Duration

func Duration(d time.Duration) string

Duration prints a length of time the way the plugin's help writes one: 5m rather than 5m0s, 1h rather than 1h0m0s, and 90s as 1m30s.

func FieldWriter

func FieldWriter(text *strings.Builder, indent string, width int) func(name, value string)

FieldWriter returns a function that writes "Label: value" lines, the label padded to width after indent, and skips a field with no value.

func JobLead added in v0.2.11

func JobLead(name string, uid types.UID, dispatchStarted, marksDispatch bool) string

JobLead says what an operation claim knows about its Job. The claim names the Job before it creates it, so a name alone is a reservation; the UID, recorded once the Job exists, is what confirms which Job it is.

marksDispatch says the claim records dispatchStarted before its one create, as every claim that holds the database realm does. Only such a claim is known not to have created a Job it has no mark for. A claim that does not mark can have created its Job and then failed the read that confirms it, or stopped between the create and the write that records the UID; the next pass adopts that Job by name.

func Label added in v0.2.11

func Label(name string) string

Label turns an API field name into the words a reader sees: jobUID is "Job UID", applyPodUIDs "Apply pod UIDs", dispatchNotAfter "Dispatch not after".

func MigrationLog added in v0.2.12

func MigrationLog(log operatorv1alpha1.MigrationLogStatus) string

MigrationLog says what a run's writes to schema_migrations_log came to: how many entries the database accepted, and, when it refused any, that the database's own record of the run is incomplete and which entries it lacks. The history and the status print the same words for the same record.

func ReadRequest added in v0.2.11

func ReadRequest(requested, answered string) string

ReadRequest says whether the read a person asked for with the read-request annotation has been answered: requested is the annotation as the resource holds it now, answered is status.lastReadRequest. The status records an answer as operatorv1alpha1.ReadRequestToken of the value, which is a digest for a value longer than MaxReadRequestLength, so the annotation is compared through the same token.

func ReadRequested added in v0.2.11

func ReadRequested(requested, answered string) string

ReadRequested is the line that says whether the read a person asked for has been answered, or nothing where none was ever asked for.

func StatusFor added in v0.2.11

func StatusFor(observed, generation int64) string

StatusFor says which spec generation the status was written for.

func Summary

func Summary(condition Condition) string

Summary is one condition on one line: its status, its reason and its message, cleaned for a terminal.

func Time

func Time(instant metav1.Time) string

Time prints one instant the way every other line of the plugin does.

func WriteApproval

func WriteApproval(text *strings.Builder, approval Approval, none string)

WriteApproval writes one approval: who approved which plan when, which of the resource's plans that is, and every condition the controller wrote on it. none is what to say when there is no condition, which differs by family: the controller answers a schema approval as soon as it reads it, and writes nothing on a migration approval until its plan is dispatched or a read withdraws it.

func WriteDecisionConditions

func WriteDecisionConditions(text *strings.Builder, conditions []Condition, none string)

WriteDecisionConditions writes the conditions of one decision, or none when it has no condition.

func WriteEveryHeading added in v0.2.11

func WriteEveryHeading[T any](
	text *strings.Builder,
	title, resource string,
	decisions *Decisions[T],
	unreadable *Unreadable,
) bool

WriteEveryHeading writes the line that opens a list of every decision that names a resource, oldest first, the way WriteListHeading opens the newest few. It reports whether entries follow.

func WriteFields added in v0.2.11

func WriteFields(text *strings.Builder, indent string, record any)

WriteFields writes every field a status record holds, one line each, under indent, labeled with its API name in words. A details view prints a record whole this way, so a field the API gains is printed without this code or its caller changing, and the label is the name the API reference lists it under.

A field the record leaves at its zero value is not printed when its JSON tag says omitempty, because the stored object does not hold it. A nested record is a label line with its fields indented under it, and a list of records is one indented block per item, each opened by "-". Every value passes through Clean.

func WriteListHeading

func WriteListHeading[T any](
	text *strings.Builder,
	title, resource, every string,
	decisions *Decisions[T],
	unreadable *Unreadable,
) bool

WriteListHeading writes the line that opens a list of decisions: how many follow, that there are none, or why they could not be read. It reports whether entries follow.

title names the list, resource is the plural whose list the API server was asked for, and every is the command that prints every one of them that names this resource: the line names it when the list was cut. It names no `kubectl get`, which lists every decision in the namespace, whichever resource it names, and leaves the reader to tell them apart.

func WriteRecord added in v0.2.11

func WriteRecord(text *strings.Builder, label, summary, lead string, record any)

WriteRecord writes one status record a details view prints: a "Label:" line with what the record is in a few words, a sentence that says what it means where the record alone does not, and then every field it holds. A record with no summary and no field set is not written at all.

func WriteScalars added in v0.2.11

func WriteScalars(text *strings.Builder, indent string, record any)

WriteScalars writes the fields of record that are printed on one line, the way WriteFields does, and leaves out its nested records, lists and maps, which a details view prints as records of their own.

func WriteStatusScalars added in v0.2.11

func WriteStatusScalars(text *strings.Builder, summary string, status any, extra ...string)

WriteStatusScalars writes the status's own one-line fields as the first record of a details view: its generation, phase and times, with what the status was written for as the summary and extra lines after them.

func WriteTable

func WriteTable(text *strings.Builder, indent string, conditions []Condition, generation int64)

WriteTable writes conditions as an aligned table under a heading, one row each, the message last so a long one runs off the end of its own row rather than pushing the others apart.

generation is the resource's metadata.generation. A condition written for another generation says so after its message, because it may describe a spec that has since changed. Zero turns the note off.

func WriteWrapped added in v0.2.11

func WriteWrapped(text *strings.Builder, indent string, width int, paragraph string)

WriteWrapped writes one paragraph in lines of at most width columns, each after indent. A word longer than a line, such as a digest, takes a line of its own.

Types

type Approval

type Approval struct {
	Name      string      `json:"name"`
	CreatedAt metav1.Time `json:"createdAt"`
	// PlanRef and PlanFingerprint are the exact plan the approval names.
	PlanRef         operatorv1alpha1.ImmutableObjectReference `json:"planRef"`
	PlanFingerprint string                                    `json:"planFingerprint"`
	// CurrentPlan says the plan it names is the resource's current plan, by
	// name, UID and fingerprint. An approval of any other plan cannot
	// authorize anything, whatever its own conditions say.
	CurrentPlan bool `json:"currentPlan"`
	// AppliedPlan says the plan it names is the one the resource's last
	// confirmed apply ran, by name, UID and fingerprint: the approval that
	// apply consumed, once the plan is no longer current. A migration records
	// no applied plan, so it is false for a migration approval.
	AppliedPlan bool `json:"appliedPlan"`
	// Approver and ApprovedAt are what admission stamped from the
	// authenticated request.
	Approver   operatorv1alpha1.ApprovalIdentity `json:"approver"`
	ApprovedAt metav1.Time                       `json:"approvedAt"`
	Conditions []Condition                       `json:"conditions,omitempty"`
}

Approval is one approval of either family: the plan it names, the identity admission stamped on it, and what the controller answered.

type Condition

type Condition struct {
	Type    string `json:"type"`
	Status  string `json:"status"`
	Reason  string `json:"reason,omitempty"`
	Message string `json:"message,omitempty"`
	// ObservedGeneration is the spec generation the condition was written for.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// LastTransitionTime is when the status last changed, not when the
	// condition was last written: a message rewritten under the same status
	// keeps the older time.
	LastTransitionTime *metav1.Time `json:"lastTransitionTime,omitempty"`
}

Condition is one published condition, with the two fields that say when and for which spec it was written.

func Find

func Find(conditions []Condition, conditionType string) *Condition

Find returns the condition of a type, or nil when the status has none.

func FromConditions

func FromConditions(conditions []metav1.Condition) []Condition

FromConditions copies the conditions in the order the status holds them.

func Leading

func Leading(conditions []Condition) []Condition

Leading is what a reader reads before the full table: Ready, whatever its status, because the API documents its reason as the one to read first, and then every condition that is True and holds the resource.

It is a selection and not a verdict. Nothing is derived from a combination of conditions, and a condition not chosen here is still in the table.

type Decisions

type Decisions[T any] struct {
	// Total is how many name the resource. Items holds at most MaxDecisions
	// of them, so a Total above len(Items) is a list that was cut.
	Total int `json:"total"`
	Items []T `json:"items"`
}

Decisions is the newest decisions that name one resource, newest first.

func Every added in v0.2.11

func Every[T any](items []T, created func(T) metav1.Time, name func(T) string) *Decisions[T]

Every orders decisions oldest first, by the creation time the API server stamped and then by name, and keeps all of them: the order a history reads in, where the newest few are not the question.

func Newest

func Newest[T any](items []T, created func(T) metav1.Time, name func(T) string) *Decisions[T]

Newest orders decisions newest first, by the creation time the API server stamped and then by name, and keeps the first MaxDecisions.

type Unreadable

type Unreadable struct {
	// Forbidden says the API server refused the list for want of permission.
	// The plugin needs only get on the resource it reads, so a reader without
	// list on the decisions is an expected reader, not a failure.
	Forbidden bool `json:"forbidden"`
	// Message is the error the list returned: the API server's answer, or the
	// client's when no answer came.
	Message string `json:"message"`
}

Unreadable is why a list the view asked for could not be read. The view is still printed: what the resource itself says does not depend on it.

func UnreadableFrom

func UnreadableFrom(err error) *Unreadable

UnreadableFrom records why a list failed.

Directories

Path Synopsis
Package statusviewtest fills a status record for the tests that hold a details view to printing all of it.
Package statusviewtest fills a status record for the tests that hold a details view to printing all of it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL