updater

package
v1.6.27 Latest Latest
Warning

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

 Go to latest Published: Nov 27, 2024 License: GPL-3.0 Imports: 32 Imported by: 0

Documentation

Overview

Package updater is an update registry that manages updates and versions.

Index

Constants

View Source 
const (
	// SignaturePolicyRequire fails on any error.
	SignaturePolicyRequire = iota

	// SignaturePolicyWarn only warns on errors.
	SignaturePolicyWarn

	// SignaturePolicyDisable only downloads signatures, but does not verify them.
	SignaturePolicyDisable
)

Signature Policies.

View Source 
const (
	StateReady       = "ready"       // Default idle state.
	StateChecking    = "checking"    // Downloading indexes.
	StateDownloading = "downloading" // Downloading updates.
	StateFetching    = "fetching"    // Fetching a single file.
)

Registry States.

View Source 
const MaxUnpackSize = 1000000000 // 1GB

MaxUnpackSize specifies the maximum size that will be unpacked.

Variables

View Source 
var (
	ErrNotFound                  = errors.New("the requested file could not be found")
	ErrNotAvailableLocally       = errors.New("the requested file is not available locally")
	ErrVerificationNotConfigured = errors.New("verification not configured for this resource")
)

Errors returned by the updater package.

View Source 
var (
	// ErrIndexChecksumMismatch is returned when an index does not match its
	// signed checksum.
	ErrIndexChecksumMismatch = errors.New("index checksum does mot match signature")

	// ErrIndexFromFuture is returned when an index is parsed with a
	// Published timestamp that lies in the future.
	ErrIndexFromFuture = errors.New("index is from the future")

	// ErrIndexIsOlder is returned when an index is parsed with an older
	// Published timestamp than the current Published timestamp.
	ErrIndexIsOlder = errors.New("index is older than the current one")

	// ErrIndexChannelMismatch is returned when an index is parsed with a
	// different channel that the expected one.
	ErrIndexChannelMismatch = errors.New("index does not match the expected channel")
)

Functions

func GetIdentifierAndVersion 

func GetIdentifierAndVersion(versionedPath string) (identifier, version string, ok bool)

GetIdentifierAndVersion splits the given file path into its identifier and version.

func GetVersionedPath 

func GetVersionedPath(identifier, version string) (versionedPath string)

GetVersionedPath combines the identifier and version and returns it as a file path.

func UnpackGZIP 

func UnpackGZIP(r io.Reader) (io.Reader, error)

UnpackGZIP unpacks a GZIP compressed reader r and returns a new reader. It's suitable to be used with registry.GetPackedFile.

Types

type File 

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

File represents a file from the update system.

func (*File) Blacklist 

func (file *File) Blacklist() error

Blacklist notifies the update system that this file is somehow broken, and should be ignored from now on, until restarted.

func (*File) EqualsVersion 

func (file *File) EqualsVersion(version string) bool

EqualsVersion normalizes the given version and checks equality with semver.

func (*File) Identifier 

func (file *File) Identifier() string

Identifier returns the identifier of the file.

func (*File) Path 

func (file *File) Path() string

Path returns the absolute filepath of the file.

func (*File) SemVer 

func (file *File) SemVer() *semver.Version

SemVer returns the semantic version of the file.

func (*File) SigningMetadata 

func (file *File) SigningMetadata() map[string]string

SigningMetadata returns the metadata to be included in signatures.

func (*File) Unpack 

func (file *File) Unpack(suffix string, unpacker Unpacker) (string, error)

Unpack returns the path to the unpacked version of file and unpacks it on demand using unpacker.

func (*File) UpgradeAvailable 

func (file *File) UpgradeAvailable() bool

UpgradeAvailable returns whether an upgrade is available for this file.

func (*File) Verify 

func (file *File) Verify() ([]*filesig.FileData, error)

Verify verifies the given file.

func (*File) Version 

func (file *File) Version() string

Version returns the version of the file.

func (*File) WaitForAvailableUpgrade 

func (file *File) WaitForAvailableUpgrade() <-chan struct{}

WaitForAvailableUpgrade blocks (selectable) until an upgrade for this file is available.

type Index 

type Index struct {
	// Path is the path to the index file
	// on the update server.
	Path string

	// Channel holds the release channel name of the index.
	// It must match the filename without extension.
	Channel string

	// PreRelease signifies that all versions of this index should be marked as
	// pre-releases, no matter if the versions actually have a pre-release tag or
	// not.
	PreRelease bool

	// AutoDownload specifies whether new versions should be automatically downloaded.
	AutoDownload bool

	// LastRelease holds the time of the last seen release of this index.
	LastRelease time.Time
}

Index describes an index file pulled by the updater.

type IndexFile 

type IndexFile struct {
	Channel   string
	Published time.Time

	Releases map[string]string
}

IndexFile represents an index file.

func ParseIndexFile 

func ParseIndexFile(indexData []byte, channel string, lastIndexRelease time.Time) (*IndexFile, error)

ParseIndexFile parses an index file and checks if it is valid.

type RegistryState 

type RegistryState struct {
	sync.Mutex

	// ID holds the ID of the state the registry is currently in.
	ID string

	// Details holds further information about the current state.
	Details any

	// Updates holds generic information about the current status of pending
	// and recently downloaded updates.
	Updates UpdateState
	// contains filtered or unexported fields
}

RegistryState describes the registry state.

func (*RegistryState) EndOperation 

func (s *RegistryState) EndOperation()

EndOperation ends an operation.

func (*RegistryState) ReportDownloads 

func (s *RegistryState) ReportDownloads(downloaded []string, failed error)

ReportDownloads reports downloaded updates to the registry state.

func (*RegistryState) ReportUpdateCheck 

func (s *RegistryState) ReportUpdateCheck(pendingDownload []string, failed error)

ReportUpdateCheck reports an update check to the registry state.

func (*RegistryState) StartOperation 

func (s *RegistryState) StartOperation(id string) bool

StartOperation starts an operation.

func (*RegistryState) UpdateOperationDetails 

func (s *RegistryState) UpdateOperationDetails(details any)

UpdateOperationDetails updates the details of an operation. The supplied struct should be a copy and must not be changed after calling this function.

type Resource 

type Resource struct {
	sync.Mutex

	// Identifier is the unique identifier for that resource.
	// It forms a file path using a forward-slash as the
	// path separator.
	Identifier string

	// Versions holds all available resource versions.
	Versions []*ResourceVersion

	// ActiveVersion is the last version of the resource
	// that someone requested using GetFile().
	ActiveVersion *ResourceVersion

	// SelectedVersion is newest, selectable version of
	// that resource that is available. A version
	// is selectable if it's not blacklisted by the user.
	// Note that it's not guaranteed that the selected version
	// is available locally. In that case, GetFile will attempt
	// to download the latest version from the updates servers
	// specified in the resource registry.
	SelectedVersion *ResourceVersion

	// VerificationOptions holds the verification options for this resource.
	VerificationOptions *VerificationOptions

	// Index holds a reference to the index this resource was last defined in.
	// Will be nil if resource was only found on disk.
	Index *Index
	// contains filtered or unexported fields
}

Resource represents a resource (via an identifier) and multiple file versions.

func (*Resource) AddVersion 

func (res *Resource) AddVersion(version string, available, currentRelease, preRelease bool) error

AddVersion adds a resource version to a resource.

func (*Resource) AnyVersionAvailable 

func (res *Resource) AnyVersionAvailable() bool

AnyVersionAvailable returns true if any version of res is locally available.

func (*Resource) Blacklist 

func (res *Resource) Blacklist(version string) error

Blacklist blacklists the specified version and selects a new version.

func (*Resource) Export 

func (res *Resource) Export() *Resource

Export makes a copy of the resource with only the exposed information. Attributes are copied and safe to access. Any ResourceVersion must not be modified.

func (*Resource) GetFile 

func (res *Resource) GetFile() *File

GetFile returns the selected version as a *File.

func (*Resource) Len 

func (res *Resource) Len() int

Len is the number of elements in the collection. It implements sort.Interface for ResourceVersion.

func (*Resource) Less 

func (res *Resource) Less(i, j int) bool

Less reports whether the element with index i should sort before the element with index j. It implements sort.Interface for ResourceVersions.

func (*Resource) Purge 

func (res *Resource) Purge(keepExtra int)

Purge deletes old updates, retaining a certain amount, specified by the keep parameter. Purge will always keep at least 2 versions so specifying a smaller keep value will have no effect.

func (*Resource) Swap 

func (res *Resource) Swap(i, j int)

Swap swaps the elements with indexes i and j. It implements sort.Interface for ResourceVersions.

func (*Resource) UnpackArchive 

func (res *Resource) UnpackArchive() error

UnpackArchive unpacks the archive the resource refers to. The contents are unpacked into a directory with the same name as the file, excluding the suffix. If the destination folder already exists, it is assumed that the contents have already been correctly unpacked.

type ResourceRegistry 

type ResourceRegistry struct {
	sync.RWMutex

	Name string

	UpdateURLs       []string
	UserAgent        string
	MandatoryUpdates []string
	AutoUnpack       []string

	// Verification holds a map of VerificationOptions assigned to their
	// applicable identifier path prefix.
	// Use an empty string to denote the default.
	// Use empty options to disable verification for a path prefix.
	Verification map[string]*VerificationOptions

	// UsePreReleases signifies that pre-releases should be used when selecting a
	// version. Even if false, a pre-release version will still be used if it is
	// defined as the current version by an index.
	UsePreReleases bool

	// DevMode specifies if a local 0.0.0 version should be always chosen, when available.
	DevMode bool

	// Online specifies if resources may be downloaded if not available locally.
	Online bool

	// StateNotifyFunc may be set to receive any changes to the registry state.
	// The specified function may lock the state, but may not block or take a
	// lot of time.
	StateNotifyFunc func(*RegistryState)
	// contains filtered or unexported fields
}

ResourceRegistry is a registry for managing update resources.

func (*ResourceRegistry) AddIndex 

func (reg *ResourceRegistry) AddIndex(idx Index)

AddIndex adds a new index to the resource registry. The order is important, as indexes added later will override the current release from earlier indexes.

func (*ResourceRegistry) AddResource 

func (reg *ResourceRegistry) AddResource(identifier, version string, index *Index, available, currentRelease, preRelease bool) error

AddResource adds a resource to the registry. Does _not_ select new version.

func (*ResourceRegistry) AddResources 

func (reg *ResourceRegistry) AddResources(versions map[string]string, index *Index, available, currentRelease, preRelease bool) error

AddResources adds resources to the registry. Errors are logged, the last one is returned. Despite errors, non-failing resources are still added. Does _not_ select new versions.

func (*ResourceRegistry) Cleanup 

func (reg *ResourceRegistry) Cleanup() error

Cleanup removes temporary files. 

func (reg *ResourceRegistry) CreateSymlinks(symlinkRoot *utils.DirStructure) error

CreateSymlinks creates a directory structure with unversioned symlinks to the given updates list.

func (*ResourceRegistry) DownloadUpdates 

func (reg *ResourceRegistry) DownloadUpdates(ctx context.Context, includeManual bool) error

DownloadUpdates checks if updates are available and downloads updates of used components.

func (*ResourceRegistry) Export 

func (reg *ResourceRegistry) Export() map[string]*Resource

Export exports the list of resources.

func (*ResourceRegistry) GetFile 

func (reg *ResourceRegistry) GetFile(identifier string) (*File, error)

GetFile returns the selected (mostly newest) file with the given identifier or an error, if it fails.

func (*ResourceRegistry) GetPendingDownloads 

func (reg *ResourceRegistry) GetPendingDownloads(manual, auto bool) (resources, sigs []*ResourceVersion)

GetPendingDownloads returns the list of pending downloads. If manual is set, indexes with AutoDownload=false will be checked. If auto is set, indexes with AutoDownload=true will be checked.

func (*ResourceRegistry) GetSelectedVersions 

func (reg *ResourceRegistry) GetSelectedVersions() (versions map[string]string)

GetSelectedVersions returns a list of the currently selected versions.

func (*ResourceRegistry) GetState 

func (reg *ResourceRegistry) GetState() RegistryState

GetState returns the current registry state. The returned data must not be modified.

func (*ResourceRegistry) GetVerificationOptions 

func (reg *ResourceRegistry) GetVerificationOptions(identifier string) *VerificationOptions

GetVerificationOptions returns the verification options for the given identifier.

func (*ResourceRegistry) GetVersion 

func (reg *ResourceRegistry) GetVersion(identifier string) (*ResourceVersion, error)

GetVersion returns the selected version of the given identifier. The returned resource version may not be modified.

func (*ResourceRegistry) Initialize 

func (reg *ResourceRegistry) Initialize(storageDir *utils.DirStructure) error

Initialize initializes a raw registry struct and makes it ready for usage.

func (*ResourceRegistry) LoadIndexes 

func (reg *ResourceRegistry) LoadIndexes(ctx context.Context) error

LoadIndexes loads the current release indexes from disk or will fetch a new version if not available and the registry is marked as online.

func (*ResourceRegistry) PreInitUpdateState 

func (reg *ResourceRegistry) PreInitUpdateState(s UpdateState) error

PreInitUpdateState sets the initial update state of the registry before initialization.

func (*ResourceRegistry) Purge 

func (reg *ResourceRegistry) Purge(keep int)

Purge deletes old updates, retaining a certain amount, specified by the keep parameter. Will at least keep 2 updates per resource.

func (*ResourceRegistry) ResetIndexes 

func (reg *ResourceRegistry) ResetIndexes()

ResetIndexes removes all indexes from the registry.

func (*ResourceRegistry) ResetResources 

func (reg *ResourceRegistry) ResetResources()

ResetResources removes all resources from the registry.

func (*ResourceRegistry) ScanStorage 

func (reg *ResourceRegistry) ScanStorage(root string) error

ScanStorage scans root within the storage dir and adds found resources to the registry. If an error occurred, it is logged and the last error is returned. Everything that was found despite errors is added to the registry anyway. Leave root empty to scan the full storage dir.

func (*ResourceRegistry) SelectVersions 

func (reg *ResourceRegistry) SelectVersions()

SelectVersions selects new resource versions depending on the current registry state.

func (*ResourceRegistry) SetDevMode 

func (reg *ResourceRegistry) SetDevMode(on bool)

SetDevMode sets the development mode flag.

func (*ResourceRegistry) SetUsePreReleases 

func (reg *ResourceRegistry) SetUsePreReleases(yes bool)

SetUsePreReleases sets the UsePreReleases flag.

func (*ResourceRegistry) StorageDir 

func (reg *ResourceRegistry) StorageDir() *utils.DirStructure

StorageDir returns the main storage dir of the resource registry.

func (*ResourceRegistry) TmpDir 

func (reg *ResourceRegistry) TmpDir() *utils.DirStructure

TmpDir returns the temporary working dir of the resource registry.

func (*ResourceRegistry) UnpackResources 

func (reg *ResourceRegistry) UnpackResources() error

UnpackResources unpacks all resources defined in the AutoUnpack list.

func (*ResourceRegistry) UpdateIndexes 

func (reg *ResourceRegistry) UpdateIndexes(ctx context.Context) error

UpdateIndexes downloads all indexes. An error is only returned when all indexes fail to update.

type ResourceVersion 

type ResourceVersion struct {

	// VersionNumber is the string representation of the resource
	// version.
	VersionNumber string

	// Available indicates if this version is available locally.
	Available bool

	// SigAvailable indicates if the signature of this version is available locally.
	SigAvailable bool

	// CurrentRelease indicates that this is the current release that should be
	// selected, if possible.
	CurrentRelease bool

	// PreRelease indicates that this version is pre-release.
	PreRelease bool

	// Blacklisted may be set to true if this version should
	// be skipped and not used. This is useful if the version
	// is known to be broken.
	Blacklisted bool
	// contains filtered or unexported fields
}

ResourceVersion represents a single version of a resource.

func (*ResourceVersion) EqualsVersion 

func (rv *ResourceVersion) EqualsVersion(version string) bool

EqualsVersion normalizes the given version and checks equality with semver.

func (*ResourceVersion) GetFile 

func (rv *ResourceVersion) GetFile() *File

GetFile returns the version as a *File. It locks the resource for doing so.

func (*ResourceVersion) SemVer 

func (rv *ResourceVersion) SemVer() *semver.Version

SemVer returns the semantic version of the resource.

func (*ResourceVersion) SigningMetadata 

func (rv *ResourceVersion) SigningMetadata() map[string]string

SigningMetadata returns the metadata to be included in signatures.

func (*ResourceVersion) String 

func (rv *ResourceVersion) String() string

type SignaturePolicy 

type SignaturePolicy uint8

SignaturePolicy defines behavior in case of errors.

type StateDownloadingDetails 

type StateDownloadingDetails struct {
	// Resources holds the resource IDs that are being downloaded.
	Resources []string

	// FinishedUpTo holds the index of Resources that is currently being
	// downloaded. Previous resources have finished downloading.
	FinishedUpTo int
}

StateDownloadingDetails holds details of the downloading state.

type Unpacker 

type Unpacker func(io.Reader) (io.Reader, error)

Unpacker describes the function that is passed to File.Unpack. It receives a reader to the compressed/packed file and should return a reader that provides unpacked file contents. If the returned reader implements io.Closer it's close method is invoked when an error or io.EOF is returned from Read().

type UpdateState 

type UpdateState struct {
	// LastCheckAt holds the time of the last update check.
	LastCheckAt *time.Time
	// LastCheckError holds the error of the last check.
	LastCheckError error
	// PendingDownload holds the resources that are pending download.
	PendingDownload []string

	// LastDownloadAt holds the time when resources were downloaded the last time.
	LastDownloadAt *time.Time
	// LastDownloadError holds the error of the last download.
	LastDownloadError error
	// LastDownload holds the resources that we downloaded the last time updates
	// were downloaded.
	LastDownload []string

	// LastSuccessAt holds the time of the last successful update (check).
	LastSuccessAt *time.Time
}

UpdateState holds generic information about the current status of pending and recently downloaded updates.

type VerificationOptions 

type VerificationOptions struct {
	TrustStore     jess.TrustStore
	DownloadPolicy SignaturePolicy
	DiskLoadPolicy SignaturePolicy
}

VerificationOptions holds options for verification of files.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.