upgrade

Documentation

Overview

Package upgrade implements approval-gated upgrades of derived repositories.

An upgrade recomposes the files setup owns — the nested tools go.mod and go.sum, the engine shim, and the two workflows — against the current profile and a new engine release. The root go.mod is generated module output and is never overwritten. Files whose composed content already matches what is on disk are left alone; files that differ are written atomically; and everything else in the repository is preserved untouched.

The approval gate is the same hash-based mechanism setup uses: an upgrade is planned, rendered as a manifest, and applied only when the operator passes the manifest hash back. This ensures that an operator reviews every change, including workflow permission changes, before the repository is modified.

An upgrade refuses to run on a repository that is not a setup-produced derived repository, that has uncommitted changes, that would downgrade the engine, or that contains setup-owned paths the operator has added outside of setup.

Index

• Constants
• Variables
• type Action
• type Engine
• type Options
• type PolicyError
  • func (e *PolicyError) Error() string
  • func (e *PolicyError) Unwrap() error
• type Report
  • func (r Report) JSON() ([]byte, error)
• type Result
  • func Apply(ctx context.Context, opts Options, approve string) (*Result, error)
  • func Plan(ctx context.Context, opts Options) (*Result, error)
  • func (r *Result) Summary() string
• type Totals

Constants

const (
	ActionUpdate = "update"
	ActionCreate = "create"
)

The kinds of change an upgrade manifest records.

Variables

var (
	// ErrDirty means the work tree has uncommitted changes.
	ErrDirty = errors.New("work tree is dirty")
	// ErrNotDerived means the repository is not a setup-produced derived
	// repository.
	ErrNotDerived = errors.New("not a derived repository")
	// ErrUnknownOverwrite means a file that would be written exists but was not
	// produced by setup.
	ErrUnknownOverwrite = errors.New("refusing to overwrite an unrecognised file")
	// ErrApproval means the approval hash does not match the current plan.
	ErrApproval = errors.New("approval does not match the current manifest")
	// ErrUnsafePath means an owned path is not a regular file (it may be a
	// symbolic link, device, or directory where a regular file is expected).
	ErrUnsafePath = errors.New("owned path is not a regular file")
	// ErrDowngrade means the target engine version is older than the current.
	ErrDowngrade = errors.New("refusing to downgrade the engine")
)

Sentinel errors the upgrade package returns.

Types

type Action

type Action struct {
	Path     string `json:"path"`
	Kind     string `json:"kind"`
	Digest   string `json:"digest"`
	Previous string `json:"previous,omitempty"`
	Bytes    int    `json:"bytes"`
}

Action is one file write.

type Engine

type Engine struct {
	From string `json:"from"`
	To   string `json:"to"`
}

Engine describes the engine release being upgraded.

type Options

type Options struct {
	// Root is the absolute path to the derived repository.
	Root string
	// Config is the validated profile the repository carries.
	Config *config.Config
	// EngineVersion is the target engine release, such as tools/v1.5.0 or
	// v1.5.0.
	EngineVersion string
	// EngineMod is the go.mod of the target engine release.
	EngineMod []byte
	// EngineSum is the verified go.sum content for the nested tools module.
	EngineSum []byte
	// MigratedProfile is the migrated soapbox.yaml content. When non-nil the
	// upgrade manifest includes the profile so the approval hash binds the
	// profile change.
	MigratedProfile []byte
	// ProfilePath is the repo-relative path to the profile file, such as
	// "soapbox.yaml". Used as the derived-repository marker and as the
	// destination when MigratedProfile is written.
	ProfilePath string
	// Git drives the repository.
	Git *gitcli.Runner
}

Options carries the inputs for an upgrade.

type PolicyError

type PolicyError struct{ Err error }

PolicyError reports that the upgrade ran and the answer is no.

func (*PolicyError) Error

func (e *PolicyError) Error() string

func (*PolicyError) Unwrap

func (e *PolicyError) Unwrap() error

type Report

type Report struct {
	Schema  int      `json:"schema"`
	Engine  Engine   `json:"engine"`
	Actions []Action `json:"actions"`
	Kept    []string `json:"kept"`
	Totals  Totals   `json:"totals"`
	Notices []string `json:"notices"`
	Hash    string   `json:"hash"`
}

Report is the upgrade manifest.

func (Report) JSON

func (r Report) JSON() ([]byte, error)

JSON renders the manifest canonically.

type Result

type Result struct {
	// Report is the upgrade manifest.
	Report Report
	// Applied is true when the manifest was written.
	Applied bool
	// Partial is true when apply failed after at least one path may have
	// changed.
	Partial bool
}

Result is the outcome of a plan or apply.

func Apply

func Apply(ctx context.Context, opts Options, approve string) (*Result, error)

Apply writes the approved upgrade manifest into the repository.

func Plan

func Plan(ctx context.Context, opts Options) (*Result, error)

Plan computes what an upgrade would write without changing anything.

func (*Result) Summary

func (r *Result) Summary() string

Summary renders the manifest for a person.

type Totals

type Totals struct {
	Update    int `json:"update"`
	Create    int `json:"create"`
	Unchanged int `json:"unchanged"`
}

Totals count the manifest by kind.