gvm

README

Version Manager

Version manager allows you to manage and download the latest software versions for your applications from GitHub Releases.

Example use

Creating an instance of Version Manager

First set the archive location

dlPath, _ := ioutil.TempDir("", "")

Then set the options for the GitHub organization and the repository, the architecture and operating system are determined at runtime, you can override these values.

	o := Options{
		Organization: "nicholasjackson",
		Repo:         "fake-service",
		ReleasesPath: dlPath,
		//GOOS:         "linux",
		//GOARCH:       "x64",
	}

To determine the name of the asset you define a function, tools like GoReleaser will use formularic naming for assets added to a release. The asset name may be an archive, in this instance Version Manager will automatically unpack the archive.

	nf := func(goos, goarch string) string {
		baseName := "fake-service"

		switch goos {
		case "darwin":
			return fmt.Sprintf("%s-osx", baseName)
		case "linux":
			return fmt.Sprintf("%s-linux", baseName)
		case "windows":
			return fmt.Sprintf("%s.exe", baseName)
		}

		return ""
	}

	o.AssetNameFunc = nf

In the instance that the release asset is an archive you can define a second function to determine the name of the executable within the archive. In the instance that the asset is a simple binary you can set this to the same function as previously used.

	o.ExeNameFunc = nf

You can now create a new instance of Version Manager

  v := New(o)

Listing Releases on GitHub

To list available releases you can use the ListReleases method, this takes a single parameter of a Semantic Version constraint. For example, to list all the releases >= 1.2.3, < 2.0.0, you would specify a constraint of ^1.2.3. Version manager returns you a map of release name and asset download URL.

r, err := v.ListReleases("^1.2.3")
for version, url := range r {
  fmt.Println("Version:", version, "URL:", url)
}

Downloading the latest version matching the constraint

To download the latest version which matches the given constraint.

tag, url, err := v.GetLatestReleaseURL("~v0.12.0")
assert.NoError(t, err)

dl, err := v.DownloadRelease(tag, url)
assert.NoError(t, err)

Documentation

Index

• type Archive
• type MockVersions
  • func (m *MockVersions) DownloadRelease(tag, url string) (path string, err error)
  • func (m *MockVersions) GetInstalledVersion(constraint string) (tag string, path string, err error)
  • func (m *MockVersions) GetLatestReleaseURL(constraint string) (tag string, url string, err error)
  • func (m *MockVersions) InRange(version string, constraint string) (bool, error)
  • func (m *MockVersions) ListInstalledVersions(constraint string) (map[string]string, error)
  • func (m *MockVersions) ListReleases(constraint string) (map[string]string, error)
  • func (m *MockVersions) SortMapKeys(ma map[string]string, descending bool) []string
• type Options
• type Versions
  • func New(o Options) Versions
• type VersionsImpl
  • func (v *VersionsImpl) DownloadRelease(tag, url string) (filePath string, err error)
  • func (v *VersionsImpl) GetInstalledVersion(constraint string) (string, string, error)
  • func (v *VersionsImpl) GetLatestReleaseURL(constraint string) (string, string, error)
  • func (v *VersionsImpl) InRange(version string, constraint string) (bool, error)
  • func (v *VersionsImpl) ListInstalledVersions(constraint string) (map[string]string, error)
  • func (v *VersionsImpl) ListReleases(constraint string) (map[string]string, error)
  • func (v *VersionsImpl) SortMapKeys(m map[string]string, decending bool) []string

Types

type Archive

type Archive int

type MockVersions

type MockVersions struct {
	mock.Mock
}

func (*MockVersions) DownloadRelease

func (m *MockVersions) DownloadRelease(tag, url string) (path string, err error)

func (*MockVersions) GetInstalledVersion

func (m *MockVersions) GetInstalledVersion(constraint string) (tag string, path string, err error)

func (*MockVersions) GetLatestReleaseURL

func (m *MockVersions) GetLatestReleaseURL(constraint string) (tag string, url string, err error)

func (*MockVersions) InRange

func (m *MockVersions) InRange(version string, constraint string) (bool, error)

func (*MockVersions) ListInstalledVersions

func (m *MockVersions) ListInstalledVersions(constraint string) (map[string]string, error)

func (*MockVersions) ListReleases

func (m *MockVersions) ListReleases(constraint string) (map[string]string, error)

func (*MockVersions) SortMapKeys

func (m *MockVersions) SortMapKeys(ma map[string]string, descending bool) []string

type Options

type Options struct {
	Organization  string
	Repo          string
	GOOS          string // set to os default if blank
	GOARCH        string // set to os value if blank
	AssetNameFunc func(ver, goos, goarch string) string
	ExeNameFunc   func(ver, goos, goarch string) string
	ReleasesPath  string // location to store donwloaded releases
}

Options defines the options for Versions

type Versions

type Versions interface {
	// ListAvailable lists the currently available releases
	// returns a map of version tags with the asset URL
	// Optionally specify a semantic version contstraint to filter results
	// e.g. "~1.2.3", version is greater or equal to 1.2.3 and less than 1.3.0
	ListReleases(constraint string) (map[string]string, error)
	// GetLatestRelease returns the asset for the latest release given the constraint
	GetLatestReleaseURL(constraint string) (tag string, url string, err error)
	// Download and uncompress the release at the given url
	DownloadRelease(tag, url string) (path string, err error)
	// ListInstalledVersions lists versions which have been installed
	ListInstalledVersions(constraint string) (map[string]string, error)
	// GetInstalledVersion returns the version for the latests release given the constraint
	GetInstalledVersion(constraint string) (tag string, path string, err error)
	// SortMapKeys sorts the keys in the map and returns a sorted slice
	// keys must adhere to Semver
	SortMapKeys(map[string]string, bool) []string
	// InRange returns true when the version can be satisfied by the constraint
	// Returns an error if either the constraint or the version are not valid semantic versions
	InRange(version string, constraint string) (bool, error)
}

Versions defines the methods for a Go Version Manager implementation

func New

func New(o Options) Versions

New creates a new Versions for the given options

type VersionsImpl

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

VersionsImpl is the concrete implementation for the Versions interface

func (*VersionsImpl) DownloadRelease

func (v *VersionsImpl) DownloadRelease(tag, url string) (filePath string, err error)

DownloadRelease and uncompress the given release

func (*VersionsImpl) GetInstalledVersion

func (v *VersionsImpl) GetInstalledVersion(constraint string) (string, string, error)

func (*VersionsImpl) GetLatestReleaseURL

func (v *VersionsImpl) GetLatestReleaseURL(constraint string) (string, string, error)

GetLatestRelease returns the asset which has the latest semantic version matching the constraint

func (*VersionsImpl) InRange

func (v *VersionsImpl) InRange(version string, constraint string) (bool, error)

func (*VersionsImpl) ListInstalledVersions

func (v *VersionsImpl) ListInstalledVersions(constraint string) (map[string]string, error)

ListInstalledVersions lists the versions of the software which are installed int the archive folder

func (*VersionsImpl) ListReleases

func (v *VersionsImpl) ListReleases(constraint string) (map[string]string, error)

ListReleases returns a map of assets for releases which match the given semantic version and which contain assets matching the value returned from AssetNameFunc If no version is specified all versions with matching assets are returned Release tags which are not valid semantic versions are ignored

func (*VersionsImpl) SortMapKeys

func (v *VersionsImpl) SortMapKeys(m map[string]string, decending bool) []string