upgradehistory

package
v1.3.2 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package upgradehistory records every control plane version transition at boot, however the binary was replaced, and builds the links and context the Updates page shows for it.

Index

Constants

View Source
const (
	MethodInstallScript = "install.sh"
	MethodRollback      = "rollback"
	MethodSelfUpgrade   = "self-upgrade"
	MethodManual        = "manual"
	MethodPackage       = "package"
	MethodCI            = "ci"
)

Marker methods.

View Source
const (
	KindInstalled   = "installed"
	KindAdopted     = "adopted"
	KindUpgraded    = "upgraded"
	KindRolledBack  = "rolled_back"
	KindRebuilt     = "rebuilt"
	KindDevelopment = "development"
	KindChanged     = "changed"
)

Transition kinds.

View Source
const (
	InitiatorUnknown = "unknown"
	// HealthBooted: the version started and its migrations applied. Recording
	// happens right after, so this is the only health fact known at that time.
	HealthBooted = "booted"
)

Initiator and health values when nothing reported them.

View Source
const (
	AuditActionRecorded = "upgrade_history.recorded"
	AuditActionAcked    = "upgrade_history.acknowledged"
)

Audit action names, written into the audit log path as "<action>: detail".

View Source
const MarkerFile = "upgrade-context.json"

MarkerFile is the context file the installer and the host rollback command leave in the data dir for the next boot.

View Source
const MarkerMaxAge = 24 * time.Hour

MarkerMaxAge bounds how long an unconsumed marker is believed.

Variables

This section is empty.

Functions

func ChannelOf

func ChannelOf(v string) string

ChannelOf names the release channel a tag belongs to, "" for non-releases.

func Classify

func Classify(prev, cur string, hasPrev, markerRollback bool) string

Classify decides the kind of a transition from prev to cur. A marker method of rollback wins when the versions cannot be ordered.

func CleanNotes

func CleanNotes(body string) string

CleanNotes strips HTML comments from release notes, the same cleanup the Updates page applies before rendering.

func ClearMarker

func ClearMarker(dir string)

ClearMarker removes the marker, ignoring a missing one.

func IsDevelopment

func IsDevelopment(v string) bool

IsDevelopment reports whether v is a local or pseudo-version build.

func IsRelease

func IsRelease(v string) bool

IsRelease reports whether v looks like a published release tag such as v1.2.3 or v1.2.3-beta.4. Dev builds and pseudo-versions are not.

func WriteMarker

func WriteMarker(dir string, m Marker) error

WriteMarker stores m in dir, replacing any earlier one, with owner-only permissions.

Types

type Links struct {
	ReleaseURL string
	CompareURL string
}

Links are the public pages for a transition. Empty fields mean the version is not a published release, so no link is invented.

func BuildLinks(repoURL, from, to string) Links

BuildLinks derives release and compare URLs from the repository URL.

type Marker

type Marker struct {
	ToVersion  string    `json:"to_version"`
	Initiator  string    `json:"initiator"`
	Method     string    `json:"method"`
	Channel    string    `json:"channel,omitempty"`
	BackupName string    `json:"backup_name,omitempty"`
	Reason     string    `json:"reason,omitempty"`
	WrittenAt  time.Time `json:"written_at"`
}

Marker is who changed the binary and how. It never holds secrets.

func ConsumeMarker

func ConsumeMarker(dir, running string, now time.Time) (Marker, bool)

ConsumeMarker reads and deletes the marker when it describes a transition to running. A marker for another version is left in place (an old binary restarting must not eat it) unless it has outlived MarkerMaxAge. A malformed marker is deleted and reported as absent.

type NotesFetcher

type NotesFetcher func(ctx context.Context, tag string) (string, error)

NotesFetcher returns the release notes text for a tag. Errors are normal (offline, rate limited) and leave the snapshot unavailable.

func NewGitHubNotesFetcher

func NewGitHubNotesFetcher(repoSlug string) NotesFetcher

NewGitHubNotesFetcher fetches a tag's release body from the GitHub API for repoSlug ("owner/name"). It refuses redirects that leave api.github.com over https and caps the response size.

type Observed

type Observed struct {
	SchemaBefore int
	BackupName   string
}

Observed is what the migration step saw before this boot, when it ran.

type Recorder

type Recorder struct {
	Store   Store
	Notes   NotesFetcher
	DataDir string
	Version string
	Logger  *slog.Logger
	Now     func() time.Time
	// PriorData reports that the database existed before this feature, so a
	// first row is "adopted" rather than a fresh install.
	PriorData bool
}

Recorder compares the running version with the last recorded one and appends a history row when they differ.

func (*Recorder) Record

func (r *Recorder) Record(ctx context.Context, schemaAfter int, obs Observed) (store.UpgradeHistoryEntry, bool, error)

Record writes at most one row for this boot. It never fails the caller's boot: errors are returned for logging only. The notes snapshot is fetched on a goroutine and stored when it completes.

type Store

type Store interface {
	InsertUpgradeHistory(ctx context.Context, e store.UpgradeHistoryEntry) (store.UpgradeHistoryEntry, bool, error)
	LatestUpgradeHistory(ctx context.Context) (store.UpgradeHistoryEntry, bool, error)
	CompleteUpgradeNotes(ctx context.Context, id, notes, state string) error
	SaveAuditEntry(ctx context.Context, e store.AuditEntry) error
}

Store is the persistence Recorder needs; *store.DB satisfies it.

Jump to

Keyboard shortcuts

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