updater

package
v0.0.0-...-c5434ca Latest Latest
Warning

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

Go to latest
Published: May 8, 2024 License: BSD-3-Clause, MIT Imports: 9 Imported by: 2

README

Updater

Build Status GoDoc

Warning: This isn't ready for non-Keybase libraries to use yet!

The goals of this library are to provide an updater that:

  • Is simple
  • Works on all our platforms (at least OS X, Windows, Linux)
  • Recovers from non-fatal errors
  • Every request or command execution should timeout (nothing blocks)
  • Can recover from failures in its environment
  • Can run as an unprivileged background service
  • Has minimal, vendored dependencies
  • Is well tested
  • Is secure
  • Reports failures and activity
  • Can notify the user of any non-transient failures

This updater library is used to support updating (in background and on-demand) for Keybase apps and services.

Packages

The main package is the updater core, there are other support packages:

  • command: Executes a command with a timeout
  • keybase: Keybase specific behavior for updates
  • osx: MacOS specific UI
  • process: Utilities to find and terminate Processes
  • saltpack: Verify updates with saltpack
  • service: Runs the updater as a background service
  • sources: Update sources for remote locations (like S3), or locally (for testing)
  • test: Test resources
  • util: Utilities for updating, such as digests, env, file, http, unzip, etc.
  • watchdog: Utility to monitor processes and restart them (like launchd), for use with updater service
  • windows: Windows specific UI
Development

This library should pass the gometalinter.

There is a pre-commit hook available:

pip install pre-commit
go get -u github.com/alecthomas/gometalinter
gometalinter --install --update
pre-commit install
pre-commit run -a

Documentation

Index

Constants

View Source
const DefaultTickDuration = time.Hour
View Source
const Version = "0.3.8"

Version is the updater version

Variables

This section is empty.

Functions

This section is empty.

Types

type Asset

type Asset struct {
	Name      string `json:"name"`
	URL       string `json:"url"`
	Digest    string `json:"digest"`
	Signature string `json:"signature"`
	LocalPath string `json:"localPath"`
}

Asset describes a downloadable file

type Config

type Config interface {
	GetUpdateAuto() (bool, bool)
	SetUpdateAuto(b bool) error
	GetUpdateAutoOverride() bool
	SetUpdateAutoOverride(bool) error
	GetInstallID() string
	SetInstallID(installID string) error
	IsLastUpdateCheckTimeRecent(d time.Duration) bool
	SetLastUpdateCheckTime()
	SetLastAppliedVersion(string) error
	GetLastAppliedVersion() string
}

Config defines configuration for the Updater

type Context

type Context interface {
	GetUpdateUI() UpdateUI
	UpdateOptions() UpdateOptions
	Verify(update Update) error
	BeforeUpdatePrompt(update Update, options UpdateOptions) error
	BeforeApply(update Update) error
	Apply(update Update, options UpdateOptions, tmpDir string) error
	AfterApply(update Update) error
	ReportError(err error, update *Update, options UpdateOptions)
	ReportAction(updatePromptResponse UpdatePromptResponse, update *Update, options UpdateOptions)
	ReportSuccess(update *Update, options UpdateOptions)
	AfterUpdateCheck(update *Update)
	GetAppStatePath() string
	IsCheckCommand() bool
	DeepClean()
}

Context defines options, UI and hooks for the updater. This is where you can define custom behavior specific to your apps.

type Error

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

Error is an update error with a type/category for reporting

func CancelErr

func CancelErr(err error) Error

CancelErr can be returned by lifecycle methods to abort an update

func NewError

func NewError(errorType ErrorType, err error) Error

NewError constructs an Error from a source error

func (Error) Error

func (e Error) Error() string

Error returns description for an UpdateError

func (Error) IsCancel

func (e Error) IsCancel() bool

IsCancel returns true if error was from a cancel

func (Error) IsGUIBusy

func (e Error) IsGUIBusy() bool

IsGUIBusy returns true if the UI was active

func (Error) TypeString

func (e Error) TypeString() string

TypeString returns a unique short string to denote the error type

type ErrorType

type ErrorType string

ErrorType is a unique short string denoting the error category

const (
	// UnknownError is for if we had an unknown error
	UnknownError ErrorType = "unknown"
	// CancelError is for if we canceled
	CancelError ErrorType = "cancel"
	// ConfigError is for errors reading/saving config
	ConfigError ErrorType = "config"
	// ConfigError is for when the GUI is active
	GUIBusyError ErrorType = "guiBusy"
)
const (
	// FindError is an error trying to find the update
	FindError ErrorType = "find"
	// PromptError is an UI prompt error
	PromptError ErrorType = "prompt"
	// DownloadError is an error trying to download the update
	DownloadError ErrorType = "download"
	// ApplyError is an error applying the update
	ApplyError ErrorType = "apply"
	// VerifyError is an error verifing the update (signature or digest)
	VerifyError ErrorType = "verify"
)

Errors corresponding to each stage in the update process

func (ErrorType) String

func (t ErrorType) String() string

type Log

type Log interface {
	Debug(...interface{})
	Info(...interface{})
	Debugf(s string, args ...interface{})
	Infof(s string, args ...interface{})
	Warningf(s string, args ...interface{})
	Errorf(s string, args ...interface{})
}

Log is the logging interface for this package

type Property

type Property struct {
	Name  string `codec:"name" json:"name"`
	Value string `codec:"value" json:"value"`
}

Property is a generic key value pair for custom properties

type Update

type Update struct {
	Version     string     `json:"version"`
	Name        string     `json:"name"`
	Description string     `json:"description"`
	InstallID   string     `json:"installId"`
	RequestID   string     `json:"requestId"`
	Type        UpdateType `json:"type"`
	PublishedAt int64      `json:"publishedAt"`
	Props       []Property `codec:"props" json:"props,omitempty"`
	Asset       *Asset     `json:"asset,omitempty"`
	NeedUpdate  bool       `json:"needUpdate"`
}

Update defines an update to apply

type UpdateAction

type UpdateAction string

UpdateAction is the update action requested by the user

const (
	// UpdateActionApply means the user accepted and to perform update
	UpdateActionApply UpdateAction = "apply"
	// UpdateActionAuto means that auto update is set and to perform update
	UpdateActionAuto UpdateAction = "auto"
	// UpdateActionSnooze snoozes an update
	UpdateActionSnooze UpdateAction = "snooze"
	// UpdateActionCancel cancels an update
	UpdateActionCancel UpdateAction = "cancel"
	// UpdateActionError means an error occurred
	UpdateActionError UpdateAction = "error"
	// UpdateActionContinue means no update action was available and the update should continue
	UpdateActionContinue UpdateAction = "continue"
	// UpdateActionUIBusy means the UI was busy and the update should be attempted later
	UpdateActionUIBusy UpdateAction = "uiBusy"
)

func (UpdateAction) String

func (u UpdateAction) String() string

String is a unique string label for the action

type UpdateChecker

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

UpdateChecker runs updates checks every check duration

func NewUpdateChecker

func NewUpdateChecker(updater *Updater, ctx Context, tickDuration time.Duration, log Log) UpdateChecker

NewUpdateChecker creates an update checker

func (*UpdateChecker) Check

func (u *UpdateChecker) Check()

Check checks for an update.

func (UpdateChecker) Count

func (u UpdateChecker) Count() int

Count is number of times the check has been called

func (*UpdateChecker) Start

func (u *UpdateChecker) Start() bool

Start starts the update checker. Returns false if we are already running.

func (*UpdateChecker) Stop

func (u *UpdateChecker) Stop()

Stop stops the update checker

type UpdateOptions

type UpdateOptions struct {
	// Version is the current version of the app
	Version string `json:"version"`
	// Platform is the os type (darwin, darwin-arm64, windows, linux)
	Platform string `json:"platform"`
	// DestinationPath is where to apply the update to
	DestinationPath string `json:"destinationPath"`
	// URL can override where the updater looks
	URL string `json:"URL"`
	// Channel is an alternative channel to get updates from (test, prerelease)
	Channel string `json:"channel"`
	// Env is an environment or run mode (prod, staging, devel)
	Env string `json:"env"`
	// Arch is an architecure description (x64, i386, arm)
	Arch string `json:"arch"`
	// Force is whether to apply the update, even if older or same version
	Force bool `json:"force"`
	// OSVersion is the version of the OS
	OSVersion string `json:"osVersion"`
	// UpdaterVersion is the version of the updater service
	UpdaterVersion string `json:"updaterVersion"`
	// IgnoreSnooze tells the server to send update despite we have snoozed
	// recently or not.
	IgnoreSnooze bool `json:"ignoreSnooze"`
}

UpdateOptions are options used to find an update

type UpdatePromptOptions

type UpdatePromptOptions struct {
	AutoUpdate bool   `json:"autoUpdate"`
	OutPath    string `json:"outPath"` // Used for windows instead of stdout
}

UpdatePromptOptions are the options for UpdatePrompt

type UpdatePromptResponse

type UpdatePromptResponse struct {
	Action         UpdateAction `json:"action"`
	AutoUpdate     bool         `json:"autoUpdate"`
	SnoozeDuration int          `json:"snooze_duration"`
}

UpdatePromptResponse is the result for UpdatePrompt

type UpdateSource

type UpdateSource interface {
	// Description is a short description about the update source
	Description() string
	// FindUpdate finds an update given options
	FindUpdate(options UpdateOptions) (*Update, error)
}

UpdateSource defines where the updater can find updates

type UpdateType

type UpdateType int

UpdateType is the update type. This is an int type for compatibility.

const (
	// UpdateTypeNormal is a normal update
	UpdateTypeNormal UpdateType = 0
	// UpdateTypeBugFix is a bugfix update
	UpdateTypeBugFix UpdateType = 1
	// UpdateTypeCritical is a critical update
	UpdateTypeCritical UpdateType = 2
)

type UpdateUI

type UpdateUI interface {
	// UpdatePrompt prompts for an update
	UpdatePrompt(Update, UpdateOptions, UpdatePromptOptions) (*UpdatePromptResponse, error)
}

UpdateUI is a UI interface

type Updater

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

Updater knows how to find and apply updates

func NewUpdater

func NewUpdater(source UpdateSource, config Config, log Log) *Updater

NewUpdater constructs an Updater

func (*Updater) ApplyDownloaded

func (u *Updater) ApplyDownloaded(ctx Context) (bool, error)

func (*Updater) CheckAndDownload

func (u *Updater) CheckAndDownload(ctx Context) (updateAvailable, updateWasDownloaded bool, err error)

func (*Updater) Cleanup

func (u *Updater) Cleanup(tmpDir string)

Cleanup removes temporary files from this update

func (*Updater) CleanupPreviousUpdates

func (u *Updater) CleanupPreviousUpdates() (err error)

CleanupPreviousUpdates removes temporary files from previous updates.

func (*Updater) FindDownloadedAsset

func (u *Updater) FindDownloadedAsset(assetName string) (matchingAssetPath string, err error)

Inspect previously downloaded updates to avoid redownloading

func (*Updater) NeedUpdate

func (u *Updater) NeedUpdate(ctx Context) (upToDate bool, err error)

NeedUpdate returns true if we are out-of-date.

func (*Updater) SetTickDuration

func (u *Updater) SetTickDuration(dur time.Duration)

func (*Updater) Update

func (u *Updater) Update(ctx Context) (*Update, error)

Update checks, downloads and performs an update

Directories

Path Synopsis
windows

Jump to

Keyboard shortcuts

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