releaseupdate

package
v0.2.52 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: 0

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