Documentation
¶
Index ¶
Constants ¶
const StatePath = ".stagefreight/pipeline.json"
StatePath is the workspace-relative path where pipeline state is persisted.
Variables ¶
This section is empty.
Functions ¶
func UpdateState ¶
UpdateState does read-modify-write. The caller mutates individual fields only — never rebuild nested structs wholesale to avoid clobbering prior state written by other subsystems.
func WriteState ¶
WriteState writes pipeline state atomically (tmp + fsync + rename). Normalizes Version to 1 on write.
Types ¶
type BuildState ¶
type BuildState struct {
ProducedImages bool `json:"produced_images"`
PublishedCount int `json:"published_count"`
ManifestPath string `json:"manifest_path,omitempty"`
}
BuildState holds build-specific domain metadata. Lifecycle tracking (attempted/completed/outcome) is in Subsystems.
type CIState ¶
type CIState struct {
Provider string `json:"provider"`
PipelineID string `json:"pipeline_id"`
Ref string `json:"ref,omitempty"`
Branch string `json:"branch,omitempty"`
Tag string `json:"tag,omitempty"`
SHA string `json:"sha"`
}
CIState captures the CI environment for this pipeline run.
func InitFromCI ¶
InitFromCI populates a CIState from a ci.CIContext.
type ExternalRetentionRecord ¶ added in v0.5.0
type ExternalRetentionRecord struct {
Registry string `json:"registry"`
Prefix string `json:"prefix"`
Total int `json:"total"`
Pruned int `json:"pruned"`
Kept int `json:"kept"`
Errors []string `json:"errors,omitempty"`
}
ExternalRetentionRecord records external cache retention results.
type LocalRetentionRecord ¶ added in v0.5.0
type LocalRetentionRecord struct {
Dir string `json:"dir"`
EntriesBefore int `json:"entries_before"`
Pruned int `json:"pruned"`
PrunedBytes int64 `json:"pruned_bytes"`
}
LocalRetentionRecord records local cache retention results.
type ReleaseState ¶
type ReleaseState struct {
Eligible bool `json:"eligible"`
}
ReleaseState holds release-specific domain metadata. Lifecycle tracking is in Subsystems.
type RetentionState ¶ added in v0.5.0
type RetentionState struct {
Local *LocalRetentionRecord `json:"local,omitempty"`
External *ExternalRetentionRecord `json:"external,omitempty"`
}
RetentionState records cache retention enforcement results. Authoritative — governance and diagnostics can inspect this.
type SecurityState ¶
type SecurityState struct{}
SecurityState holds security-specific domain metadata. Lifecycle tracking is in Subsystems.
type State ¶
type State struct {
Version int `json:"version"`
CI CIState `json:"ci"`
Build BuildState `json:"build"`
Security SecurityState `json:"security"`
Release ReleaseState `json:"release"`
Subsystems []SubsystemState `json:"subsystems,omitempty"`
Retention RetentionState `json:"retention,omitempty"`
}
State is the per-run ledger for the current pipeline workspace. Each subsystem records what it did; downstream stages read the ledger instead of probing files.
func ReadState ¶
ReadState reads pipeline state from the workspace. Returns a zero State (Version: 1) on missing file — missing state is normal when the first subsystem hasn't run yet. Only errors on I/O or parse failures for an existing file.
func (*State) GetSubsystem ¶ added in v0.5.0
func (st *State) GetSubsystem(name string) *SubsystemState
GetSubsystem returns the subsystem entry by name, or nil if not found.
func (*State) PipelineStatus ¶ added in v0.5.0
PipelineStatus derives the aggregate pipeline outcome from all subsystems. States: passing, warning, failing, unknown.
Resolution rules (platform-agnostic, policy-aware):
- Any required subsystem with outcome "failed" → failing
- Any non-required subsystem with outcome "failed" + allow_failure → warning
- Any subsystem with outcome "warning" → warning
- Nothing attempted → unknown
- Otherwise → passing
func (*State) RecordSubsystem ¶ added in v0.5.0
func (st *State) RecordSubsystem(s SubsystemState)
RecordSubsystem upserts a subsystem entry by name.
type SubsystemState ¶ added in v0.5.0
type SubsystemState struct {
Name string `json:"name"`
Attempted bool `json:"attempted"`
Completed bool `json:"completed"`
Skipped bool `json:"skipped"`
AllowFailure bool `json:"allow_failure"` // true = non-vital; failure produces warning, not fail
Required bool `json:"required"` // true = failure is a hard pipeline fail
Outcome string `json:"outcome"` // success | failed | skipped | warning | not_applicable | cancelled
Reason string `json:"reason,omitempty"`
}
SubsystemState is the generic lifecycle phase record. All subsystems register here regardless of mode. The resolver uses this list — never hardcoded field names.
Source Files