selfupdate

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2020 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

go-selfupdate detects the information of the latest release via GitHub Releases API and checks the current version. If newer version than itself is detected, it downloads released binary from GitHub and replaces itself.

- Automatically detects the latest version of released binary on GitHub

- Retrieve the proper binary for the OS and arch where the binary is running

- Update the binary with rollback support on failure

- Tested on Linux, macOS and Windows

- Many archive and compression formats are supported (zip, gzip, xzip, bzip2, tar)

There are some naming rules. Please read following links.

Naming Rules of Released Binaries:

https://github.com/creativeprojects/go-selfupdate#naming-rules-of-released-binaries

Naming Rules of Git Tags:

https://github.com/creativeprojects/go-selfupdate#naming-rules-of-versions-git-tags

This package is hosted on GitHub:

https://github.com/creativeprojects/go-selfupdate

Small CLI tools as wrapper of this library are available also:

https://github.com/creativeprojects/go-selfupdate/cmd/detect-latest-release
https://github.com/creativeprojects/go-selfupdate/cmd/go-get-release

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecompressCommand

func DecompressCommand(src io.Reader, url, cmd, os, arch string) (io.Reader, error)

DecompressCommand decompresses the given source. Archive and compression format is automatically detected from 'url' parameter, which represents the URL of asset. This returns a reader for the decompressed command given by 'cmd'. '.zip', '.tar.gz', '.tar.xz', '.tgz', '.gz', '.bz2' and '.xz' are supported.

func SetLogger

func SetLogger(logger Logger)

SetLogger redirects all logs to the logger defined in parameter. By default logs are not sent anywhere.

Example
// you can plug-in any logger providing the 2 methods Print and Printf
// the default log.Logger satisfies the interface
logger := stdlog.New(os.Stdout, "selfupdate ", 0)
SetLogger(logger)

func UpdateTo

func UpdateTo(assetURL, cmdPath string) error

UpdateTo downloads an executable from assetURL and replaces the current binary with the downloaded one. This function is low-level API to update the binary. Because it does not use GitHub API and downloads asset directly from the URL via HTTP, this function is not available to update a release for private repositories. cmdPath is a file path to command executable.

Types

type Config

type Config struct {
	// APIToken represents GitHub API token. If it's not empty, it will be used for authentication of GitHub API
	APIToken string
	// EnterpriseBaseURL is a base URL of GitHub API. If you want to use this library with GitHub Enterprise,
	// please set "https://{your-organization-address}/api/v3/" to this field.
	EnterpriseBaseURL string
	// EnterpriseUploadURL is a URL to upload stuffs to GitHub Enterprise instance. This is often the same as an API base URL.
	// So if this field is not set and EnterpriseBaseURL is set, EnterpriseBaseURL is also set to this field.
	EnterpriseUploadURL string
	// Validator represents types which enable additional validation of downloaded release.
	Validator Validator
	// Filters are regexp used to filter on specific assets for releases with multiple assets.
	// An asset is selected if it matches any of those, in addition to the regular tag, os, arch, extensions.
	// Please make sure that your filter(s) uniquely match an asset.
	Filters []string
	// Context used by the http client (default to context.Background)
	Context context.Context
	// OS is set to the value of runtime.GOOS by default, but you can force another value here
	OS string
	// Arch is set to the value of runtime.GOARCH by default, but you can force another value here
	Arch string
	// Arm 32bits version. Valid values are 0 (unknown), 5, 6 or 7. Default is detected value (if any)
	Arm uint8
}

Config represents the configuration of self-update.

type ECDSAValidator

type ECDSAValidator struct {
	PublicKey *ecdsa.PublicKey
}

ECDSAValidator specifies a ECDSA validator for additional file validation before updating.

func (*ECDSAValidator) Suffix

func (v *ECDSAValidator) Suffix() string

Suffix returns the suffix for ECDSA validation.

func (*ECDSAValidator) Validate

func (v *ECDSAValidator) Validate(input, signature []byte) error

Validate checks the ECDSA signature the release against the signature contained in an additional asset file. additional asset file.

type Logger

type Logger interface {
	// Print calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
	Print(v ...interface{})
	// Printf calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
	Printf(format string, v ...interface{})
}

Logger interface. Compatible with standard log.Logger

type Release

type Release struct {
	// AssetURL is a URL to the uploaded file for the release
	AssetURL string
	// AssetSize represents the size of asset in bytes
	AssetByteSize int
	// AssetID is the ID of the asset on GitHub
	AssetID int64
	// ValidationAssetID is the ID of additional validaton asset on GitHub
	ValidationAssetID int64
	// URL is a URL to release page for browsing
	URL string
	// ReleaseNotes is a release notes of the release
	ReleaseNotes string
	// Name represents a name of the release
	Name string
	// PublishedAt is the time when the release was published
	PublishedAt *time.Time
	// RepoOwner is the owner of the repository of the release
	RepoOwner string
	// RepoName is the name of the repository of the release
	RepoName string
	// OS this release is for
	OS string
	// Arch this release is for
	Arch string
	// Arm 32bits version (if any). Valid values are 0 (unknown), 5, 6 or 7
	Arm uint8
	// contains filtered or unexported fields
}

Release represents a release asset for current OS and arch.

func DetectLatest

func DetectLatest(slug string) (*Release, bool, error)

DetectLatest detects the latest release of the slug (owner/repo). This function is a shortcut version of updater.DetectLatest.

func DetectVersion

func DetectVersion(slug string, version string) (*Release, bool, error)

DetectVersion detects the given release of the slug (owner/repo) from its version.

func UpdateCommand

func UpdateCommand(cmdPath string, current *semver.Version, slug string) (*Release, error)

UpdateCommand updates a given command binary to the latest version. This function is a shortcut version of updater.UpdateCommand.

func UpdateSelf

func UpdateSelf(current *semver.Version, slug string) (*Release, error)

UpdateSelf updates the running executable itself to the latest version. This function is a shortcut version of updater.UpdateSelf.

func (Release) Equal

func (r Release) Equal(other string) bool

Equal tests if two versions are equal to each other.

func (Release) GreaterOrEqual added in v0.2.0

func (r Release) GreaterOrEqual(other string) bool

GreaterOrEqual tests if one version is greater than or equal to another one.

func (Release) GreaterThan

func (r Release) GreaterThan(other string) bool

GreaterThan tests if one version is greater than another one.

func (Release) LessOrEqual added in v0.2.0

func (r Release) LessOrEqual(other string) bool

LessOrEqual tests if one version is less than or equal to another one.

func (Release) LessThan

func (r Release) LessThan(other string) bool

LessThan tests if one version is less than another one.

func (Release) Version

func (r Release) Version() string

Version is the version string of the release

type SHAValidator

type SHAValidator struct {
}

SHAValidator specifies a SHA256 validator for additional file validation before updating.

func (*SHAValidator) Suffix

func (v *SHAValidator) Suffix() string

Suffix returns the suffix for SHA256 validation.

func (*SHAValidator) Validate

func (v *SHAValidator) Validate(release, asset []byte) error

Validate checks the SHA256 sum of the release against the contents of an additional asset file.

type Updater

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

Updater is responsible for managing the context of self-update. It contains GitHub client and its context.

func DefaultUpdater

func DefaultUpdater() *Updater

DefaultUpdater creates a new updater instance with default configuration. It initializes GitHub API client with default API base URL. If you set your API token to $GITHUB_TOKEN, the client will use it.

func NewUpdater

func NewUpdater(config Config) (*Updater, error)

NewUpdater creates a new updater instance. It initializes GitHub API client. If you set your API token to $GITHUB_TOKEN, the client will use it.

func (*Updater) DetectLatest

func (up *Updater) DetectLatest(slug string) (release *Release, found bool, err error)

DetectLatest tries to get the latest version of the repository on GitHub. 'slug' means 'owner/name' formatted string. It fetches releases information from GitHub API and find out the latest release with matching the tag names and asset names. Drafts and pre-releases are ignored. Assets would be suffixed by the OS name and the arch name such as 'foo_linux_amd64' where 'foo' is a command name. '-' can also be used as a separator. File can be compressed with zip, gzip, zxip, bzip2, tar&gzip or tar&zxip. So the asset can have a file extension for the corresponding compression format such as '.zip'. On Windows, '.exe' also can be contained such as 'foo_windows_amd64.exe.zip'.

func (*Updater) DetectVersion

func (up *Updater) DetectVersion(slug string, version string) (release *Release, found bool, err error)

DetectVersion tries to get the given version of the repository on Github. `slug` means `owner/name` formatted string. And version indicates the required version.

func (*Updater) UpdateCommand

func (up *Updater) UpdateCommand(cmdPath string, current *semver.Version, slug string) (*Release, error)

UpdateCommand updates a given command binary to the latest version. 'slug' represents 'owner/name' repository on GitHub and 'current' means the current version.

func (*Updater) UpdateSelf

func (up *Updater) UpdateSelf(current *semver.Version, slug string) (*Release, error)

UpdateSelf updates the running executable itself to the latest version. 'slug' represents 'owner/name' repository on GitHub and 'current' means the current version.

func (*Updater) UpdateTo

func (up *Updater) UpdateTo(rel *Release, cmdPath string) error

UpdateTo downloads an executable from GitHub Releases API and replace current binary with the downloaded one. It downloads a release asset via GitHub Releases API so this function is available for update releases on private repository. If a redirect occurs, it fallbacks into directly downloading from the redirect URL.

type Validator

type Validator interface {
	// Validate validates release bytes against an additional asset bytes.
	// See SHAValidator or ECDSAValidator for more information.
	Validate(release, asset []byte) error
	// Suffix describes the additional file ending which is used for finding the
	// additional asset.
	Suffix() string
}

Validator represents an interface which enables additional validation of releases.

Jump to

Keyboard shortcuts

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