selfupdate

package
v1.7.2 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
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.

View Source
var ErrUpToDate = errors.New("already up to date")

ErrUpToDate is returned by Apply when the running version is already current.

Functions

func Run

func Run(ctx context.Context, current string, w io.Writer, checkOnly bool) error

Run checks for a newer release and, unless checkOnly is set, downloads and installs it. Progress is written to w; it is a no-op (with a message) when the running version is already current. This is the CLI (`--self-upgrade`) entry.

Types

type ErrNotWritable added in v1.7.0

type ErrNotWritable struct {
	Dir string
	Err error
}

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

func Apply(ctx context.Context, current string) (Result, error)

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.

Jump to

Keyboard shortcuts

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