Documentation
¶
Overview ¶
Package selfupdate implements `dockercmd --self-upgrade`: download the latest GitHub release asset for this OS/arch, verify its SHA-256 and atomically replace the running executable.
Self-update executes downloaded code, so the checksum check is mandatory: the binary is only swapped in once its SHA-256 matches the digest GitHub records for the asset. The download lands in the target directory (same filesystem) so the final swap is an atomic rename.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrPolicyRefused = errors.New("update refused by policy")
ErrPolicyRefused is returned by ApplyChecked when the release actually resolved by this call fails the caller's allow predicate (e.g. a granularity ceiling). The predicate is evaluated against the SAME fetch that would be installed, not an earlier/cached one, so a release published between an earlier check and this call can never slip past the gate.
var ErrUpToDate = errors.New("already up to date")
ErrUpToDate is returned by Apply when the running version is already current.
Functions ¶
Types ¶
type ErrNotWritable ¶ added in v1.7.0
ErrNotWritable is returned when the executable's directory can't be written to — surfaced before any download happens (see preflightWritable). The CLI path (Run, called from `--self-upgrade`) can offer to re-exec elevated when it sees this; the in-app path (Apply, behind the web UI's "Update & restart") has no terminal to prompt on and just reports it — that surface needs the permission granted at install time instead (see ReadWritePaths in deploy/dockercmd.service, added in v1.6.2).
func (*ErrNotWritable) Error ¶ added in v1.7.0
func (e *ErrNotWritable) Error() string
func (*ErrNotWritable) Unwrap ¶ added in v1.7.0
func (e *ErrNotWritable) Unwrap() error
type Result ¶ added in v1.5.0
type Result struct {
From string `json:"from"` // version before the upgrade
To string `json:"to"` // version now staged on disk
Asset string `json:"asset"` // release asset that was installed
SHA256 string `json:"sha256"` // verified checksum of the new binary
}
Result describes a completed upgrade.
func Apply ¶ added in v1.5.0
Apply downloads, verifies and installs the latest release, returning a Result describing the upgrade. It is the programmatic (in-app) entry point and writes no progress output. ErrUpToDate is returned when nothing newer exists.
func ApplyChecked ¶ added in v1.7.0
func ApplyChecked(ctx context.Context, current string, allowed func(latestTag string) bool) (Result, error)
ApplyChecked is Apply, but the resolved release's tag must also pass allowed before anything is installed — checked against the exact release this call is about to install, never a value resolved by an earlier, possibly-stale call (e.g. a cached "update available" status). This closes a TOCTOU gap a caller enforcing a policy (like a version-granularity ceiling) would otherwise have: checking that policy against yesterday's cached status and then calling plain Apply lets whatever is latest AT INSTALL TIME through unchecked, which can be a newer release than the one the check saw. Returns ErrPolicyRefused, without downloading anything, when allowed(tag) is false.