update

Documentation

Index

• Variables
• func Compare(a, b string) int
• func IsPrerelease(tag string) bool
• type Install
• type Outcome
  • func Apply(ctx context.Context, currentVer, tag, execPath, goos, goarch string, ...) (Outcome, error)
• type Plan
  • func Preflight(execPath string, env func(string) string) Plan
• type Progress
• type Release
  • func FetchLatest(ctx context.Context, currentVer string) (Release, error)
• type Result
  • func Check(ctx context.Context, currentVer string, force bool) (*Result, error)
• type Stage
  • func (s Stage) String() string

Variables

var ErrRateLimit = errors.New("update: rate limited")

ErrRateLimit indicates a 403 or 429 response (rate-limited or blocked).

var ErrUpstream = errors.New("update: upstream error")

ErrUpstream indicates a non-2xx response from the GitHub API.

Functions

func Compare

func Compare(a, b string) int

Compare returns -1 if a < b, 0 if a == b, +1 if a > b. Strips leading "v". Treats git-describe form (vX.Y.Z-N-gSHA) as vX.Y.Z. Returns 0 for malformed input (treat as equal; caller filters with IsPrerelease).

func IsPrerelease

func IsPrerelease(tag string) bool

IsPrerelease reports whether a release tag should be excluded from stable upgrade comparisons. The API's Prerelease/Draft fields are the primary signal; this function is a belt-and-suspenders tag-name heuristic for any gaps.

Types

type Install

type Install int

Install classifies how the running binary was installed.

const (
	InstallSelfManaged Install = iota // install.sh, manual, scoop/choco (writable)
	InstallHomebrew                   // under a Homebrew prefix / Cellar
	InstallGo                         // under GOBIN or GOPATH/bin
)

type Outcome

type Outcome struct {
	From string
	To   string
}

Outcome reports the version transition an Apply performed.

func Apply

func Apply(ctx context.Context, currentVer, tag, execPath, goos, goarch string, reportFn func(Progress)) (Outcome, error)

Apply downloads the release identified by tag, verifies its checksum, extracts the platform binary, and atomically swaps it over execPath. tag MUST come from a live Check(force=true) Result (never the on-disk cache) so a poisoned cache cannot redirect the download. execPath must be the resolved path of the running binary; its directory is where the temp download, extraction, and atomic rename all happen, so the rename stays same-filesystem.

Integrity rests on TLS + the published sha256 checksums — not signatures; this detects corruption and truncation, not a compromised release host.

reportFn, if non-nil, is called with a Progress as each stage begins (checksums → downloading → verifying → installing) and repeatedly during the archive download with byte counts; it is purely observational and never affects control flow. Pass nil to stay silent.

type Plan

type Plan struct {
	Managed     bool   // installed by a package manager (Homebrew / go install)
	Instruction string // channel-correct upgrade command, set when Managed
	Writable    bool   // install dir is writable (meaningful only when !Managed)
	Dir         string // install directory (the atomic-replace target dir)
}

Plan tells the CLI whether and how a self-update may proceed for the running binary, keeping all install-path heuristics inside this package.

func Preflight

func Preflight(execPath string, env func(string) string) Plan

Preflight classifies the binary at execPath and probes its directory's writability. env is the environment lookup (pass os.Getenv in production). A managed install short-circuits before the writability probe — there is nothing to write, the user must use their package manager.

type Progress

type Progress struct {
	Stage       Stage
	Done, Total int64
}

Progress reports how far an Apply run has advanced. Stage is always meaningful. Done and Total are only populated during StageDownloading, and Total is 0 when the server sent no Content-Length — render such a run as indeterminate rather than computing a ratio.

type Release

type Release struct {
	TagName     string    `json:"tag_name"`
	HTMLURL     string    `json:"html_url"`
	Name        string    `json:"name"`
	Draft       bool      `json:"draft"`
	Prerelease  bool      `json:"prerelease"`
	PublishedAt time.Time `json:"published_at"`
}

Release is the subset of the GitHub Releases API response used for update checks.

func FetchLatest

func FetchLatest(ctx context.Context, currentVer string) (Release, error)

FetchLatest queries the GitHub Releases API and returns the latest release. The HTTP client enforces a 1.5s total timeout with explicit dial and TLS sub-timeouts so degraded networks don't hang the caller.

type Result

type Result struct {
	SchemaVersion    int       `json:"schema_version"`
	Current          string    `json:"current"`
	Latest           string    `json:"latest"`
	UpgradeAvailable bool      `json:"upgrade_available"`
	ReleaseURL       string    `json:"release_url"`
	CheckedAt        time.Time `json:"checked_at"`
}

Result holds the outcome of an update check. It is cached to disk between runs.

func Check

func Check(ctx context.Context, currentVer string, force bool) (*Result, error)

Check returns the update status for currentVer. Returns (nil, nil) when currentVer is a dev/pseudo-version — no check is performed. When force=true the 24h cache is bypassed and a fresh fetch is made. On any network or parse error the caller receives a non-nil error; silent-degrade is the caller's responsibility (both the opportunistic startup check and the `--check-update` command treat errors as no-op).

type Stage

type Stage int

Stage identifies a phase of an Apply run, reported to an optional progress callback so a CLI front-end can show the user what is happening during the otherwise-silent download/verify/swap. Reporting is observational only — it never alters control flow or error handling.

const (
	// StageChecksums is reported just before the release checksums.txt is
	// fetched. This work always happened; it simply was not reported before.
	StageChecksums Stage = iota
	// StageDownloading is reported just before the release archive is fetched,
	// then repeatedly as bytes arrive.
	StageDownloading
	// StageVerifying is reported just before the SHA-256 integrity check.
	StageVerifying
	// StageInstalling is reported just before the binary is extracted and
	// swapped. From this point the run is no longer safely cancellable: the
	// remaining work is the atomic rename that the updater's safety rests on.
	StageInstalling
)

func (Stage) String

func (s Stage) String() string

String returns the lowercase human label for a stage.