update

Documentation

Overview

Package update implements VORTEX's self-update machinery: querying the GitHub releases API, downloading and verifying release archives, and atomically hot-swapping the running binary. It is split from the CLI command so the logic is testable without a terminal and reusable by future agents (e.g. the DevOps self-healing agents in M14). Stdlib only — no external HTTP client.

Index

• Variables
• func AssetName(goos, goarch string) string
• func AtomicReplace(newBin, targetPath string) error
• func Download(ctx context.Context, url, dest, expectedSHA256 string, progress func(n int64)) error
• func Extract(archive, destDir, filename string) (string, error)
• func FetchChecksums(ctx context.Context, release *Release) (map[string]string, error)
• func ParseChecksums(s string) map[string]string
• func Rollback(targetPath string) error
• func SetUserAgent(ua string)
• func VerifyChecksumsSignature(ctx context.Context, release *Release) error
• type Asset
  • func AssetForPlatform(release *Release, goos, goarch string) (*Asset, error)
  • func CurrentPlatformAsset(release *Release) (*Asset, error)
• type Release
  • func FetchLatestRelease(ctx context.Context, repo string) (*Release, error)
  • func FetchReleaseByTag(ctx context.Context, repo, tag string) (*Release, error)

Variables

var ErrBadSignature = errors.New("update: checksums signature verification failed")

ErrBadSignature is returned when the signature does not verify against the pinned public key — a strong signal of a tampered or forged release.

var ErrNoReleases = errors.New("no releases published yet")

ErrNoReleases is returned by FetchLatestRelease when the repository has no published releases yet (the GitHub API answers 404). It is informational rather than a failure — callers should treat it as "nothing to update to".

var ErrNoSignature = errors.New("update: release has no checksums.txt signature")

ErrNoSignature is returned when signature verification is requested but the release has no checksums.txt.sig asset.

var ReleaseSigningPublicKey = ""

ReleaseSigningPublicKey is the Ed25519 public key (base64, 32 bytes) that signs release checksums.txt files. It is empty until a signing key is provisioned (see scripts/sign.sh and the release workflow); when empty, signature verification is skipped and only the SHA-256 integrity check applies. Pinning the key in the binary is what makes the auto-update path authenticity-checked rather than merely integrity-checked (production audit H4): a compromised release that swaps both the binary and its checksum still cannot forge a valid signature without this key's secret half.

To enable: generate a key (scripts/sign.sh keygen), set this constant to the public key, and configure the release workflow to sign checksums.txt with the private key, publishing checksums.txt.sig alongside it.

Functions

func AssetName

func AssetName(goos, goarch string) string

AssetName returns the archive filename for a platform.

func AtomicReplace

func AtomicReplace(newBin, targetPath string) error

AtomicReplace replaces the binary at targetPath with newBin: the existing target is moved to targetPath+".bak", then newBin is copied into place with 0755 permissions. On any failure it restores the .bak. The caller is responsible for removing the .bak after verifying the new binary.

func Download

func Download(ctx context.Context, url, dest, expectedSHA256 string, progress func(n int64)) error

Download streams url to the file at dest, verifying its SHA-256 against expectedSHA256 (hex). progress, if non-nil, is called with the cumulative byte count roughly every 1MB. On a checksum mismatch or a cancelled context, the partial dest file is removed and an error is returned.

func Extract

func Extract(archive, destDir, filename string) (string, error)

Extract pulls the single entry named filename out of a .tar.gz or .zip archive into destDir, returning the path to the extracted file. The archive format is detected from the archive's extension. Entries whose path escapes destDir (zip-slip: containing ".." or absolute paths) are rejected.

func FetchChecksums

func FetchChecksums(ctx context.Context, release *Release) (map[string]string, error)

FetchChecksums downloads and parses the release's checksums.txt, returning a map of filename → SHA-256 hex.

func ParseChecksums

func ParseChecksums(s string) map[string]string

ParseChecksums turns "<hex> <filename>" lines into a filename→hash map.

func Rollback

func Rollback(targetPath string) error

Rollback restores targetPath+".bak" back to targetPath. It is idempotent: if no .bak exists it returns nil.

func SetUserAgent

func SetUserAgent(ua string)

SetUserAgent sets the User-Agent string sent to GitHub (e.g. the build version). Safe to call once at startup.

func VerifyChecksumsSignature

func VerifyChecksumsSignature(ctx context.Context, release *Release) error

VerifyChecksumsSignature downloads checksums.txt and checksums.txt.sig from the release and verifies the Ed25519 signature over the checksums bytes against the pinned ReleaseSigningPublicKey. It returns:

• nil if signing is disabled (no pinned key) — integrity-only mode, or if the signature verifies;
• ErrNoSignature if a key is pinned but the release has no .sig asset;
• ErrBadSignature if the signature does not verify.

Types

type Asset

type Asset struct {
	Name        string
	DownloadURL string
	Size        int64
}

Asset is a single downloadable file attached to a release.

func AssetForPlatform

func AssetForPlatform(release *Release, goos, goarch string) (*Asset, error)

AssetForPlatform returns the release archive Asset for the given platform. The naming follows GoReleaser's config: vortex_<goos>_<goarch>.tar.gz for linux/darwin and .zip for windows.

func CurrentPlatformAsset

func CurrentPlatformAsset(release *Release) (*Asset, error)

CurrentPlatformAsset is a convenience wrapper for the running platform.

type Release

type Release struct {
	Tag        string
	Assets     []Asset
	Body       string
	PreRelease bool
	Draft      bool
}

Release is a typed subset of a GitHub release.

func FetchLatestRelease

func FetchLatestRelease(ctx context.Context, repo string) (*Release, error)

FetchLatestRelease returns the latest published release for repo (e.g. "vortex-run/vortex"). It applies a 30s timeout derived from ctx.

func FetchReleaseByTag

func FetchReleaseByTag(ctx context.Context, repo, tag string) (*Release, error)

FetchReleaseByTag returns the published release with the given tag (e.g. "v0.2.0"). A 404 maps to ErrNoReleases, matching FetchLatestRelease.