Documentation
¶
Overview ¶
Package plan is the upgrade step model shared by `nself update --plan|--yes` and `nself update stack` (cap:cli.update-plan, P7-LIVE-10; P7-PLUG-31 runs the same step list, PLUG D10).
Purpose: say, deterministically and without touching anything, which pins of a project (the CLI, the CLI-owned images, the installed plugins) differ from what the CLI image lock, the plugin registry and the latest CLI release offer, and in which order an upgrade applies them. Inputs: the project Lock (internal/lock) and the Candidates the caller resolved from its sources. Outputs: a Plan (the pin diff plus the ordered steps), a human table, and the Lock with image pins moved (ApplyImagePins). Constraints: pure. No network, no disk, no process. A source that could not be reached is the caller's error; a pin the source no longer offers is a Pin row with Resolvable=false and a Reason, never an omitted row and never a silent default (Constitution section 4.1).
Index ¶
Constants ¶
const ( ReasonNoImage = "not in the CLI image lock" ReasonNoPlugin = "not in the plugin registry" )
Reasons used for rows the sources cannot answer.
const ( KindCLI = "cli" KindImage = "image" KindPlugin = "plugin" )
Pin kinds.
const ( StepBackup = "backup" StepImages = "images" StepPlugins = "plugins" StepBuild = "build" StepStart = "start" StepMigrate = "migrate" StepReadiness = "readiness" StepHealth = "health" StepCLI = "cli" )
Step names, in execution order.
const ( StepKindLocal = "local" StepKindStack = "stack" StepKindSelf = "self" )
Step kinds say who runs a step. "local" steps change files of the project and run in `update --yes`; "stack" steps need a running stack and belong to `update stack`; "self" replaces the CLI binary and always runs last.
Variables ¶
This section is empty.
Functions ¶
func ApplyImagePins ¶
ApplyImagePins returns a copy of l with every resolvable image pin moved to its offered reference. A service that was tag-only becomes digest-pinned.
Types ¶
type Candidate ¶
type Candidate struct {
// Value is the offered image reference, plugin version or CLI version.
Value string
// Reason is set when the source cannot offer the pin (for example it
// answered 404); Value is then ignored.
Reason string
// Note is carried to the Pin of a resolvable image candidate.
Note string
}
Candidate is what a source offers for one pin.
type Candidates ¶
type Candidates struct {
// CLICurrent is the running CLI version; CLI is the latest release.
CLICurrent string
CLI Candidate
Images map[string]Candidate
Plugins map[string]Candidate
}
Candidates is everything the sources offered. A key missing from Images or Plugins means the source does not know the pin.
type Pin ¶
type Pin struct {
Kind string `json:"kind"` // cli | image | plugin
Name string `json:"name"` // "nself" for the CLI, the lock key for images and plugins
From string `json:"from"` // the current pin or version
To string `json:"to"` // the offered one; empty when unresolvable
// Resolvable is false when the source no longer offers the pin or answered
// that it does not exist; Reason then says why.
Resolvable bool `json:"resolvable"`
Reason string `json:"reason,omitempty"`
// Note is a caution about a resolvable pin (for example a stateful recreate);
// it never makes the pin unresolvable.
Note string `json:"note,omitempty"`
}
Pin is one difference between the project lock and what is on offer.
type Step ¶
type Step struct {
Name string `json:"name"`
Kind string `json:"kind"` // local | stack | self
Pins []Pin `json:"pins"` // the pins this step applies (empty for most)
Command string `json:"command"` // the nself command that performs it
}
Step is one stage of an upgrade.
func DefaultSteps ¶
DefaultSteps returns the ordered step list with each pin attached to the step that applies it. Only resolvable pins are attached: an unresolvable one is reported in Plan.Pins and never applied.
Source Files