Documentation
¶
Overview ¶
Package update provides shared logic for checking GitHub releases and determining whether the running build is older than the latest publicly available version.
The check distinguishes two version shapes:
- Semver builds (vX.Y.Z, with optional v prefix): compared numerically against the repo's latest stable release.
- SHA builds (any string carrying a commit hash — bare hex, git describe, the legacy main+SHA): compared against the origin/main HEAD via the GitHub commits-compare API.
Anything we can't classify (e.g. the literal "dev") is reported as State=DevBuild — current is unrecognized, latest release is shown for reference but no update is offered.
Index ¶
- Variables
- func AddGitHubAuth(req *http.Request)
- func FetchBranchHEAD(branch string) (string, error)
- func FetchInstallTarget(channel, currentVersion string) (string, error)
- func InferChannel(version string) string
- func SetRepo(repo string)
- func SpawnChecker(ctx context.Context, version string, store UpdateStore)
- type CompareResult
- type GitHubAsset
- type GitHubRelease
- type Kind
- type Result
- type State
- type UpdateStore
Constants ¶
This section is empty.
Variables ¶
var APIBase = "https://api.github.com/repos/cynkra/blockyard"
APIBase is the GitHub API root pointing at the configured repo (e.g. https://api.github.com/repos/cynkra/blockyard). It is a var so SetRepo can rewrite it from config and tests can point it at a local httptest server.
Functions ¶
func AddGitHubAuth ¶
AddGitHubAuth sets the Authorization header if GITHUB_TOKEN is set.
func FetchBranchHEAD ¶
FetchBranchHEAD returns the HEAD commit SHA of the named branch (typically "main"). Used by SHA-build update checks to know what the upstream is currently at.
func FetchInstallTarget ¶
FetchInstallTarget returns the version string the orchestrator should install on the given channel ("stable" or "main"). Returns "" when current already matches the channel's head, signalling "no update needed". The channel concept is preserved here (vs. the version-classifier used by CheckLatest) because operators pick which release stream to follow independently of how the running build is versioned.
func InferChannel ¶
InferChannel picks the default release channel for a build given its version string: "stable" when the version is a clean semver tag, "main" otherwise. Used by the CLI self-update flow when the caller doesn't pass --channel explicitly.
func SetRepo ¶
func SetRepo(repo string)
SetRepo points subsequent API calls at the given owner/repo (e.g. "cynkra/blockyard"). Called once at server startup from config so forks can self-host without recompiling.
func SpawnChecker ¶
func SpawnChecker(ctx context.Context, version string, store UpdateStore)
SpawnChecker periodically checks GitHub for a newer release and stores the result on store. Performs an initial check after one minute (so startup isn't slowed by network), then once every 24 hours. Blocks until ctx is cancelled.
Types ¶
type CompareResult ¶
type CompareResult struct {
Status string `json:"status"`
AheadBy int `json:"ahead_by"`
BehindBy int `json:"behind_by"`
}
CompareResult is the relevant subset of GitHub's compare-commits response. Status is one of "ahead", "behind", "identical", "diverged"; the counts describe head relative to base.
func CompareCommits ¶
func CompareCommits(base, head string) (*CompareResult, error)
CompareCommits asks GitHub how head relates to base. Returns (nil, nil) when the API responds 404 — typically because base isn't reachable on the remote (fork or unpushed branch).
type GitHubAsset ¶
type GitHubAsset struct {
Name string `json:"name"`
URL string `json:"url"` // API URL — use with Accept: application/octet-stream
}
GitHubAsset represents a downloadable artifact in a release.
type GitHubRelease ¶
type GitHubRelease struct {
TagName string `json:"tag_name"`
Name string `json:"name"`
Assets []GitHubAsset `json:"assets"`
}
GitHubRelease represents a GitHub release.
func FetchLatestStableRelease ¶
func FetchLatestStableRelease() (*GitHubRelease, error)
FetchLatestStableRelease fetches the latest tagged (non-prerelease) release.
func FetchRelease ¶
func FetchRelease(url string) (*GitHubRelease, error)
FetchRelease fetches a single release from the given GitHub API URL.
func FetchReleaseByTag ¶
func FetchReleaseByTag(tag string) (*GitHubRelease, error)
FetchReleaseByTag fetches a release by its Git tag name. Used by the orchestrator when applying a rolling update.
type Result ¶
type Result struct {
State State `json:"state"`
CurrentVersion string `json:"current_version"`
LatestVersion string `json:"latest_version,omitempty"`
Detail string `json:"detail,omitempty"`
}
Result is what consumers persist and render. LatestVersion is a display string (semver tag, short SHA, or empty when unknown); Detail carries human-readable extra context (e.g. "3 commits behind").
func CheckLatest ¶
CheckLatest classifies the current version and queries GitHub to produce a Result. Network errors are folded into the Result as State=NoRemote rather than returned, so callers can render the outcome without an extra error branch — the (error) return is reserved for unrecoverable bugs (none today).
func PerformCheck ¶
func PerformCheck(store UpdateStore) (*Result, error)
PerformCheck runs a single update check synchronously and writes the outcome to store. Always writes — even when the result is "up to date" or "dev build" — so the UI can display the most recent check time. Returns the result so a UI handler can render it directly.
type State ¶
type State string
State enumerates how the running build compares to the upstream version the check found.
const ( StateUnknown State = "unknown" // no check has run yet StateUpToDate State = "up_to_date" // matches latest release / origin/main HEAD StateUpdateAvailable State = "update_available" // older than latest release / behind origin/main StateAhead State = "ahead" // newer than latest release / ahead of origin/main StateDiverged State = "diverged" // SHA build that diverged from origin/main StateDevBuild State = "dev_build" // unparseable version string (e.g. "dev") StateNoRemote State = "no_remote" // GitHub unreachable or returned an error StateLocalNotFound State = "local_not_found" // SHA known but origin/main doesn't have it )
type UpdateStore ¶
UpdateStore is the interface a long-lived caller (the server) implements to receive check results. Satisfied by server.Server.
Source Files