selfupdate

Documentation

Overview

Package selfupdate implements an opt-in, fail-safe self-update mechanism.

When enabled via the EnvAutoUpdate environment variable, the running binary checks GitHub for a newer release, downloads the asset matching the current OS/arch, verifies it, atomically replaces itself on disk, and re-executes the new binary with the original arguments.

The whole mechanism is best-effort: any failure (network, disk, permissions, version parsing, a corrupt download, ...) is logged and swallowed so the caller always falls back to running the current binary. The only observable effect of a failed update is a short delay and a log line.

Index

• Constants
• func Cleanup(ctx context.Context)
• func Enabled() bool
• func Run(ctx context.Context, stdin io.Reader, stderr io.Writer)
• type Updater
  • func New(currentVersion string) *Updater

Constants

const (
	// EnvAutoUpdate enables the self-update mechanism when set to a truthy
	// value ("1", "true", "yes", "on", case-insensitive).
	EnvAutoUpdate = "DOCKER_AGENT_AUTO_UPDATE"
)

Functions

func Cleanup

func Cleanup(ctx context.Context)

Cleanup removes the previous-binary backup after a successful re-exec. It is deliberately best-effort: cleanup failure must never block normal execution.

The backup path comes from an environment variable, so it is validated to look like a backup file produced by this package before being removed. This prevents an attacker-controlled environment from turning startup into an arbitrary file deletion.

func Enabled

func Enabled() bool

Enabled reports whether the self-update mechanism should run for this process. It is false when disabled by env, or when this process is already the re-executed child of a prior update (loop guard).

func Run

func Run(ctx context.Context, stdin io.Reader, stderr io.Writer)

Run attempts a self-update. It never returns an error: on success it re-executes the new binary (and does not return on Unix); on any failure or when already up to date it returns so the caller can continue with the current binary. Progress and failures are reported to stderr and slog.

When a newer release is available and the session is interactive, the user is prompted to confirm the upgrade; non-interactive sessions auto-confirm.

Types

type Updater

type Updater struct {
	CurrentVersion string
	Owner          string
	Repo           string

	APIBaseURL      string
	DownloadBaseURL string

	GOOS   string
	GOARCH string

	HTTPClient *http.Client
	// contains filtered or unexported fields
}

Updater performs a single best-effort self-update. The zero value is not usable; call New to get one wired with sensible defaults.

func New

func New(currentVersion string) *Updater

New returns an Updater configured for the docker-agent GitHub repository, targeting the current binary and platform.