applyledger

package
v0.42.0 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package applyledger records what one Apply actually did, unit by unit.

A rollout that half-succeeded used to reach the operator as a single error string, and a rollout that succeeded reached dashboards as a single green result. Neither said which module was running and which was not. The ledger is that missing per-unit truth: it names every runtime requirement the plan declared, what happened to it, why, whether retrying can help, and what to do next.

It is a projection, not an authority: the sealed Apply result and the durable journal remain the evidence. The ledger exists so an operator, an installer, and a dashboard can read the same account of the run.

Index

Constants

View Source 
const FileName = "outcomes.json"

FileName is the per-unit account stored beside a rollout run's events and summary, so the truth about a rollout survives the process that produced it.

View Source 
const SchemaVersion = "stackkit.apply-outcome-ledger/v1"

SchemaVersion identifies the machine-readable ledger.

Variables

This section is empty.

Functions

func Store 

func Store(runRoot string, ledger Ledger) (string, error)

Store writes a ledger beside the current rollout run's other durable evidence. Keeping the path and encoding here gives every producer and reader one storage contract.

Types

type Criticality 

type Criticality string

Criticality decides whether one unit's failure fails the whole Apply. It is declared by the kit authority, never inferred here. 

const (
	// CriticalityCore is the runtime the stack cannot exist without.
	CriticalityCore Criticality = "core"
	// CriticalityPlatform is the delivery machinery workloads depend on.
	CriticalityPlatform Criticality = "platform"
	// CriticalityWorkload is one user-facing application.
	CriticalityWorkload Criticality = "workload"
	// CriticalityAddon is an optional capability.
	CriticalityAddon Criticality = "addon"
)

func (Criticality) Critical 

func (c Criticality) Critical() bool

Critical reports whether a failure of this tier must fail the whole Apply.

type Failure 

type Failure struct {
	Class       string   `json:"class"`
	Code        string   `json:"code,omitempty"`
	Retryable   bool     `json:"retryable"`
	Transient   bool     `json:"transient"`
	Message     string   `json:"message,omitempty"`
	Remediation []string `json:"remediation,omitempty"`
	// RetryAfter is the RFC 3339 UTC time an external authority named for the
	// next attempt. A retry before it cannot succeed.
	RetryAfter string `json:"retryAfter,omitempty"`
}

Failure states why a unit did not apply, in terms a caller can act on.

type HealthOutcome 

type HealthOutcome struct {
	RequirementID string `json:"requirementId"`
	TargetRef     string `json:"targetRef,omitempty"`
	Status        string `json:"status"`
}

HealthOutcome is one health target's observed state.

type Ledger 

type Ledger struct {
	SchemaVersion string    `json:"schemaVersion"`
	Phase         string    `json:"phase"`
	PlanHash      string    `json:"planHash,omitempty"`
	OperationID   string    `json:"operationId,omitempty"`
	ObservedAt    time.Time `json:"observedAt"`
	Overall       Overall   `json:"overall"`
	Summary       Summary   `json:"summary"`
	Units         []Unit    `json:"units"`
	Next          *Next     `json:"next,omitempty"`
}

Ledger is the per-unit account of one Apply.

func Applied 

func Applied(requirements generationartifact.ApplyRequirements, planHash string, observedAt time.Time) Ledger

Applied returns the ledger for an Apply where every declared unit came up. It is built from the plan the sealed result verified, so a fully successful run reports the same shape as a partial one.

func Blocked 

func Blocked(requirements generationartifact.ApplyRequirements, planHash string, observedAt time.Time) Ledger

Blocked returns the ledger for an Apply that host admission refused. Nothing was mutated, so every declared unit is reported as never attempted.

func FromJournal 

func FromJournal(
	requirements generationartifact.ApplyRequirements,
	steps []StepOutcome,
	planHash, operationID, cause string,
	observedAt time.Time,
) Ledger

FromJournal builds the ledger for an Apply that stopped part-way, using the durable journal as the account of what each step did. Steps the journal never reached are reported skipped rather than failed: they were not attempted, and saying otherwise would send an operator after the wrong problem.

func Latest 

func Latest(workspace string) *Ledger

Latest returns the most recent per-unit account in a workspace, or nil when no run recorded one.

It lives here rather than in a caller because more than one surface has to answer the same question -- what did the last Apply actually do -- and two readers would eventually disagree about where the answer is kept.

type Next 

type Next struct {
	Resumable bool   `json:"resumable"`
	Command   string `json:"command,omitempty"`
}

Next tells the caller how to continue after an incomplete Apply.

type Outcome 

type Outcome string

Outcome is the closed per-unit vocabulary. 

const (
	// OutcomeApplied means the unit was applied and its health targets passed.
	OutcomeApplied Outcome = "applied"
	// OutcomeDegraded means the runtime applied but at least one health target
	// did not pass.
	OutcomeDegraded Outcome = "degraded"
	// OutcomeFailed means the unit did not apply.
	OutcomeFailed Outcome = "failed"
	// OutcomeSkipped means the unit was never attempted, because an earlier
	// critical failure stopped execution or a gate excluded it.
	OutcomeSkipped Outcome = "skipped"
	// OutcomeUnverified means the unit applied but its health could not be
	// observed. It is never reported as applied.
	OutcomeUnverified Outcome = "unverified"
)

type Overall 

type Overall string

Overall is the closed aggregate vocabulary for a whole Apply. 

const (
	// OverallApplied means every unit applied.
	OverallApplied Overall = "applied"
	// OverallCompletedDegraded means the core came up but at least one unit did
	// not. The rollout is usable and incomplete, and says so.
	OverallCompletedDegraded Overall = "completed_degraded"
	// OverallFailed means a unit the stack depends on did not apply.
	OverallFailed Overall = "failed"
	// OverallBlocked means host admission refused before anything was mutated.
	OverallBlocked Overall = "blocked"
)

type StepOutcome 

type StepOutcome struct {
	Step  runtimeapply.Step
	State runtimeapply.StepSnapshot
}

StepOutcome is one journaled child step, paired with its recorded state.

type Subject 

type Subject struct {
	WorkloadRef         string `json:"workloadRef,omitempty"`
	RequirementID       string `json:"requirementId"`
	InstanceRef         string `json:"instanceRef,omitempty"`
	RuntimeOwnerRef     string `json:"runtimeOwnerRef,omitempty"`
	ModuleRef           string `json:"moduleRef,omitempty"`
	SiteRef             string `json:"siteRef,omitempty"`
	NodeRef             string `json:"nodeRef,omitempty"`
	ExecutionChannelRef string `json:"executionChannelRef,omitempty"`
}

Subject identifies one unit using the same keys the verified Apply result already exposes, so a consumer can correlate a ledger row with applied workload identities without a second vocabulary.

type Summary 

type Summary struct {
	Applied    int `json:"applied"`
	Degraded   int `json:"degraded"`
	Failed     int `json:"failed"`
	Skipped    int `json:"skipped"`
	Unverified int `json:"unverified"`
}

Summary counts units per outcome so a caller can render a headline without walking the list.

type Unit 

type Unit struct {
	Ref          string          `json:"ref"`
	Kind         string          `json:"kind"`
	Subject      Subject         `json:"subject"`
	Criticality  Criticality     `json:"criticality"`
	Outcome      Outcome         `json:"outcome"`
	Failure      *Failure        `json:"failure,omitempty"`
	Health       []HealthOutcome `json:"health,omitempty"`
	StepID       string          `json:"stepId,omitempty"`
	JournalState string          `json:"journalState,omitempty"`
}

Unit is one runtime requirement and everything known about its fate.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.