update

Documentation

Overview

Package update implements `txco update check` and `txco upgrade`: it discovers the latest release from GitHub, compares versions, detects how the running binary was installed, and (for self-managed installs) downloads + verifies + atomically replaces the binary.

The package is pure with respect to the CLI surface — it takes the build version / install-method origin as plain strings so it never imports chassis/cli (which would be a cycle). The CLI layer (chassis/cli/ update_cmd.go) reads cli.Build and calls in.

Index

• func CanSelfUpdate(origin string) bool
• func OutdatedNotice(current string, p *Policy) string
• func SelfUpdate(ctx context.Context, userAgent string) (string, error)
• func UpgradeGuidance(m Method) string
• type Asset
• type Method
  • func Resolve(origin, exePath string) Method
  • func ResolveCurrent(origin string) Method
• type Policy
• type Release
  • func LatestRelease(ctx context.Context, userAgent string) (Release, error)
  • func (r Release) AssetURL(name string) string
• type Result
  • func Check(ctx context.Context, current, userAgent string) (Result, error)
• type ServerInfo
  • func FetchServerInfo(ctx context.Context, baseURL, userAgent string) (ServerInfo, error)

Functions

func CanSelfUpdate

func CanSelfUpdate(origin string) bool

CanSelfUpdate reports whether the running binary (build origin = cli.Build.InstallMethod) may replace itself in place.

func OutdatedNotice

func OutdatedNotice(current string, p *Policy) string

OutdatedNotice returns a human warning when `current` is older than the policy's minimum_supported (louder when Critical), or "" when in sync, when the policy is absent, or when current isn't valid semver. This is WARN-ONLY — it never signals "block".

func SelfUpdate

func SelfUpdate(ctx context.Context, userAgent string) (string, error)

SelfUpdate downloads the latest release asset for this OS/arch, verifies its SHA256 against the release's checksums.txt, extracts the binary, and atomically replaces the running executable (go-update rolls back on a failed swap). Returns the version it updated to (no leading v).

Callers must gate on the install-method policy (CanSelfUpdate) before calling — SelfUpdate itself does not re-check it.

func UpgradeGuidance

func UpgradeGuidance(m Method) string

UpgradeGuidance returns the human instruction for upgrading a binary that txco must NOT self-update. Returns "" for self-managed installs (the caller performs the in-place update instead).

Types

type Asset

type Asset struct {
	Name        string `json:"name"`
	DownloadURL string `json:"browser_download_url"`
}

Asset is one downloadable file attached to a release.

type Method

type Method struct {
	// Name is the effective method: "source" | "manual" | "homebrew" |
	// "unknown". ("manual" covers any self-managed release binary — a direct
	// download or the curl installer; they are byte-identical.)
	Name string
	// SelfUpdate reports whether txco may replace its own binary in place.
	SelfUpdate bool
}

Method is the resolved install method plus its self-update policy.

func Resolve

func Resolve(origin, exePath string) Method

Resolve maps the build origin (ldflag main.InstallMethod, mirrored to cli.Build.InstallMethod) plus the running executable's path to the effective install method.

The released binary is a single artifact per os/arch, shared by the curl/manual download AND Homebrew (the formula installs the prebuilt binary — no compile step), so the ldflag alone can't distinguish them: a "release" binary under a Homebrew prefix is brew-managed and must delegate; anywhere else it is self-managed. "source" (Makefile / unstamped dev builds) and anything unrecognized never self-update.

exePath should be the symlink-resolved path to the running binary; ResolveCurrent supplies it for the live process.

func ResolveCurrent

func ResolveCurrent(origin string) Method

ResolveCurrent resolves the install method for the running process: the build origin from cli.Build.InstallMethod plus the symlink-resolved path of the executable.

type Policy

type Policy struct {
	Latest           string `json:"latest"`
	MinimumSupported string `json:"minimum_supported"`
	Critical         bool   `json:"critical"`
}

Policy is the client-version policy a server advertises in its /healthz JSON. Empty fields mean "unset" (the server has no opinion).

type Release

type Release struct {
	TagName string  `json:"tag_name"`
	HTMLURL string  `json:"html_url"`
	Assets  []Asset `json:"assets"`
}

Release is the subset of a GitHub release we consume.

func LatestRelease

func LatestRelease(ctx context.Context, userAgent string) (Release, error)

LatestRelease fetches the latest non-prerelease release from GitHub. userAgent should carry the CLI version (e.g. "txco-cli/0.2.3"). The call is unauthenticated (GitHub allows 60 req/hr/IP — ample for occasional manual checks).

func (Release) AssetURL

func (r Release) AssetURL(name string) string

AssetURL returns the browser_download_url for the named asset, or "".

type Result

type Result struct {
	Current    string // running version, e.g. "0.2.3"
	Latest     string // latest release version, no leading v, e.g. "0.2.6"
	HTMLURL    string // release page URL
	Available  bool   // Latest is strictly newer than Current
	Comparable bool   // Current parsed as valid semver (false ⇒ dev/unset)
}

Result is the outcome of an update check.

func Check

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

Check fetches the latest release and compares it against the current version. userAgent should carry the CLI version (e.g. "txco-cli/0.2.3").

type ServerInfo

type ServerInfo struct {
	Status         string  `json:"status"`
	Version        string  `json:"version"`
	Commit         string  `json:"commit"`
	Chassis        string  `json:"chassis"`
	BuildTimestamp string  `json:"build_timestamp"`
	Client         *Policy `json:"client"`
}

ServerInfo is a chassis's self-reported build identity plus its client policy, read from <base>/healthz?format=json. It doubles as a "what's deployed?" surface (Version/Commit/Chassis).

func FetchServerInfo

func FetchServerInfo(ctx context.Context, baseURL, userAgent string) (ServerInfo, error)

FetchServerInfo GETs the JSON form of <baseURL>/healthz (the chassis admin base, e.g. https://admin.thanks.computer). Best-effort: callers treat any error as "no server policy / unreachable" and carry on.