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 ¶
- Variables
- type ApplyResult
- type Asset
- type CacheEntry
- type CacheMetadata
- type Channel
- type Checker
- type Destination
- type DowngradePolicy
- type GitHubChecker
- type GitHubOptions
- type InstallKind
- type Installer
- type InstallerOptions
- type Platform
- type RateLimitError
- type Release
- type Repository
- type Request
- type StagedUpdate
- type Status
- type Store
- type Version
Constants ¶
This section is empty.
Variables ¶
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 ¶
ApplyResult reports whether an apply operation committed the replacement and where the prior executable remains when cleanup or rollback needs attention.
type CacheEntry ¶
type CacheEntry struct {
Metadata CacheMetadata
Releases []Release
}
CacheEntry is the complete caller-persisted discovery state.
type CacheMetadata ¶
CacheMetadata contains HTTP validators for a release collection.
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.
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 ¶
Platform identifies a Go operating system and architecture pair.
func CurrentPlatform ¶
func CurrentPlatform() Platform
CurrentPlatform returns the platform of the running binary.
type RateLimitError ¶
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 ¶
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 ¶
ParseVersion parses and normalizes a semantic version.
func (Version) Compare ¶
Compare returns -1, 0, or 1 when v is less than, equal to, or greater than other.
func (Version) MarshalJSON ¶
MarshalJSON serializes a Version as a JSON string.
func (Version) MarshalText ¶
MarshalText serializes a Version as normalized semantic-version text.
func (*Version) UnmarshalJSON ¶
UnmarshalJSON validates a JSON string as a semantic version.
func (*Version) UnmarshalText ¶
UnmarshalText validates semantic-version text.