Help us shape the future of Go! Take the 2026 Go Developer Survey

releaseupdate

package
v0.2.56 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 29, 2026 License: MIT Imports: 31 Imported by: 3

Documentation

Overview

Package releaseupdate discovers and applies verified releases for binaries that a caller explicitly identifies as directly owned.

Discovery is read-only with respect to an installation. It projects GitHub releases into provider-neutral types, applies stable or beta channel policy, selects a named GoReleaser-compatible OS/architecture asset, and persists HTTP validators and release metadata only through a caller-supplied Store.

Direct updates require a pinned publisher certificate, a signed checksum manifest, and a matching artifact checksum. Downloads and decompression are bounded before a verified executable can be staged. Apply uses a private, no-replace filesystem transaction with rollback.

Callers retain ownership of check cadence, cache persistence, install-source detection, user consent and rendering, package-manager and application-bundle behavior, daemon supervision, restart/readiness policy, and telemetry. In particular, this package never infers mutation authority from the running executable path and never stops or restarts a service.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrReleaseNotFound     = errors.New("release not found")
	ErrAssetNotFound       = errors.New("release asset not found")
	ErrCacheMiss           = errors.New("conditional response has no cached releases")
	ErrRateLimited         = errors.New("release source rate limited")
	ErrInvalidRelease      = errors.New("invalid release metadata")
	ErrUnsupportedChannel  = errors.New("unsupported release channel")
	ErrUnsupportedPlatform = errors.New("unsupported release platform")
	ErrInstallNotOwned     = errors.New("installation is not directly owned")
	ErrInvalidDestination  = errors.New("invalid update destination")
	ErrDownloadLimit       = errors.New("download exceeds configured limit")
	ErrUnsafeArchive       = errors.New("archive contains an unsafe path")
	ErrAuthenticity        = errors.New("publisher authenticity verification failed")
	ErrChecksum            = errors.New("artifact checksum verification failed")
	ErrUpdateNotAvailable  = errors.New("release is not an authorized update")
	ErrApplyCleanup        = errors.New("replacement committed with cleanup remaining")
	ErrStagedUpdateUsed    = errors.New("staged update has already been used")
)

Functions

This section is empty.

Types

type ApplyResult

type ApplyResult struct {
	Applied      bool
	PreviousPath string
	CleanupPath  string
}

ApplyResult reports whether an apply operation committed the replacement and where the prior executable remains when cleanup or rollback needs attention.

type Asset

type Asset struct {
	ID          int64
	Name        string
	DownloadURL string
	Size        int64
	Platform    Platform
}

Asset describes an immutable release artifact.

type CacheEntry

type CacheEntry struct {
	Metadata CacheMetadata
	Releases []Release
}

CacheEntry is the complete caller-persisted discovery state.

type CacheMetadata

type CacheMetadata struct {
	ETag         string
	LastModified string
	ValidatedAt  time.Time
}

CacheMetadata contains HTTP validators for a release collection.

type Channel

type Channel string

Channel controls whether prereleases are eligible.

const (
	ChannelStable Channel = "stable"
	ChannelBeta   Channel = "beta"
)

type Checker

type Checker interface {
	Check(context.Context, Request) (Status, error)
}

Checker discovers releases without mutating an installation.

type Destination

type Destination struct {
	Path             string
	StagingDirectory string
	InstallKind      InstallKind
}

Destination grants mutation authority for one explicitly named installation.

type DowngradePolicy

type DowngradePolicy string

DowngradePolicy controls whether a lower latest release is actionable.

const (
	DowngradeDisallow DowngradePolicy = "disallow"
	DowngradeAllow    DowngradePolicy = "allow"
)

type GitHubChecker

type GitHubChecker struct {
	// contains filtered or unexported fields
}

GitHubChecker discovers releases through GitHub's releases API.

func NewGitHubChecker

func NewGitHubChecker(options GitHubOptions) (*GitHubChecker, error)

NewGitHubChecker constructs a GitHub release checker.

func (*GitHubChecker) Check

func (c *GitHubChecker) Check(ctx context.Context, request Request) (Status, error)

Check performs release discovery and never mutates an installation.

type GitHubOptions

type GitHubOptions struct {
	HTTPClient       *http.Client
	APIBaseURL       string
	Token            string
	UserAgent        string
	Store            Store
	MaxResponseBytes int64
}

GitHubOptions configures release discovery. Store is required; Token is optional and is never included in returned errors.

type InstallKind

type InstallKind string

InstallKind reports which system owns an installation.

const (
	InstallKindUnknown           InstallKind = "unknown"
	InstallKindDirect            InstallKind = "direct"
	InstallKindHomebrew          InstallKind = "homebrew"
	InstallKindTauri             InstallKind = "tauri"
	InstallKindApplicationBundle InstallKind = "application-bundle"
	InstallKindManaged           InstallKind = "managed"
)

type Installer

type Installer interface {
	StageAndVerify(context.Context, Status, Destination) (*StagedUpdate, error)
}

Installer prepares an authorized, verified direct-binary update from a discovery Status.

func NewInstaller

func NewInstaller(options InstallerOptions) (Installer, error)

NewInstaller constructs a fail-closed direct-binary installer.

type InstallerOptions

type InstallerOptions struct {
	HTTPClient              *http.Client
	Token                   string
	PublisherCertificatePEM []byte
	ChecksumsAssetName      string
	SignatureAssetName      string
	AllowedDownloadHosts    []string
	MaxArtifactBytes        int64
	MaxMetadataBytes        int64
	MaxExecutableBytes      int64
	MaxArchiveBytes         int64
}

InstallerOptions pins release authenticity and download boundaries.

type Platform

type Platform struct {
	OS   string
	Arch string
}

Platform identifies a Go operating system and architecture pair.

func CurrentPlatform

func CurrentPlatform() Platform

CurrentPlatform returns the platform of the running binary.

type RateLimitError

type RateLimitError struct {
	RetryAt time.Time
}

RateLimitError reports when cached data was returned because GitHub refused a fresh request.

func (*RateLimitError) Error

func (e *RateLimitError) Error() string

func (*RateLimitError) Unwrap

func (e *RateLimitError) Unwrap() error

type Release

type Release struct {
	ID          int64
	Version     Version
	Name        string
	URL         string
	PublishedAt time.Time
	Prerelease  bool
	Draft       bool
	Asset       Asset
	Assets      []Asset
}

Release is provider-neutral release metadata. Asset is the platform-selected artifact; Assets contains the complete published asset set needed for verification.

type Repository

type Repository struct {
	Owner string
	Name  string
}

Repository identifies a provider repository.

type Request

type Request struct {
	Repository   Repository
	Current      Version
	Channel      Channel
	Platform     Platform
	ArtifactName string
	InstallKind  InstallKind
	Downgrade    DowngradePolicy
}

Request describes one read-only discovery operation.

type StagedUpdate

type StagedUpdate struct {
	// contains filtered or unexported fields
}

StagedUpdate is a verified, single-use replacement.

func (*StagedUpdate) Apply

func (s *StagedUpdate) Apply(ctx context.Context) (ApplyResult, error)

Apply atomically replaces the authorized direct binary.

func (*StagedUpdate) Destination

func (s *StagedUpdate) Destination() string

Destination returns the explicitly authorized replacement path.

func (*StagedUpdate) Discard

func (s *StagedUpdate) Discard() error

Discard removes a staged update without touching the destination.

func (*StagedUpdate) Path

func (s *StagedUpdate) Path() string

Path returns the non-executable staged file path.

type Status

type Status struct {
	Current     Version
	Latest      Version
	Available   bool
	Channel     Channel
	Downgrade   DowngradePolicy
	Release     Release
	InstallKind InstallKind
	CheckedAt   time.Time
	FromCache   bool
	Stale       bool
}

Status is a caller-renderable discovery result.

type Store

type Store interface {
	Load(context.Context, string) (CacheEntry, bool, error)
	Save(context.Context, string, CacheEntry) error
}

Store persists release metadata without prescribing filesystem state.

type Version

type Version struct {
	// contains filtered or unexported fields
}

Version is a validated semantic version.

func ParseVersion

func ParseVersion(value string) (Version, error)

ParseVersion parses and normalizes a semantic version.

func (Version) Compare

func (v Version) Compare(other Version) int

Compare returns -1, 0, or 1 when v is less than, equal to, or greater than other.

func (Version) MarshalJSON

func (v Version) MarshalJSON() ([]byte, error)

MarshalJSON serializes a Version as a JSON string.

func (Version) MarshalText

func (v Version) MarshalText() ([]byte, error)

MarshalText serializes a Version as normalized semantic-version text.

func (Version) String

func (v Version) String() string

String returns the normalized semantic version without a leading "v".

func (*Version) UnmarshalJSON

func (v *Version) UnmarshalJSON(data []byte) error

UnmarshalJSON validates a JSON string as a semantic version.

func (*Version) UnmarshalText

func (v *Version) UnmarshalText(text []byte) error

UnmarshalText validates semantic-version text.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL