update

Documentation

Overview

Package update implements an API for fetching updates to workflows from remote servers.

The Updater/Releaser API provides the ability to check for newer versions of your workflow. Support for updating from GitHub releases is built in. See GitHub example.

You can use your own backend by implementing the Releaser interface.

The only hard requirement is support for (mostly) semantic version numbers. See SemVer documentation and http://semver.org for details.

This package is the "backend". You should set an Updater on an aw.Workflow struct (using e.g. the GitHub aw.Option) and use the Workflow methods CheckForUpdate(), UpdateAvailable() and InstallUpdate() to interact with the Updater.

See ../examples/update for one possible way to use this API.

Index

• Constants
• Variables
• func GitHub(repo string) aw.Option
• func SortReleases(releases []*Release)
• func SortSemVer(versions []SemVer)
• type GitHubReleaser
  • func (gh *GitHubReleaser) Releases() ([]*Release, error)
• type Release
• type Releaser
• type Releases
  • func (r Releases) Len() int
  • func (r Releases) Less(i, j int) bool
  • func (r Releases) Swap(i, j int)
• type SemVer
  • func NewSemVer(s string) (SemVer, error)
  • func (v SemVer) Compare(v2 SemVer) int
  • func (v SemVer) EQ(v2 SemVer) bool
  • func (v SemVer) Equals(v2 SemVer) bool
  • func (v SemVer) GT(v2 SemVer) bool
  • func (v SemVer) GTE(v2 SemVer) bool
  • func (v SemVer) LT(v2 SemVer) bool
  • func (v SemVer) LTE(v2 SemVer) bool
  • func (v SemVer) NE(v2 SemVer) bool
  • func (v SemVer) String() string
• type SemVers
  • func (vs SemVers) Len() int
  • func (vs SemVers) Less(i, j int) bool
  • func (vs SemVers) Swap(i, j int)
• type Updater
  • func New(v Versioned, r Releaser) (*Updater, error)
  • func (u *Updater) CheckDue() bool
  • func (u *Updater) CheckForUpdate() error
  • func (u *Updater) Install() error
  • func (u *Updater) UpdateAvailable() bool
  • func (u *Updater) UpdateInterval(interval time.Duration)
• type Versioned

Examples

• GitHub

Constants

const DefaultUpdateInterval = time.Duration(24 * time.Hour)

DefaultUpdateInterval is how often to check for updates.

Variables

var HTTPTimeout = (60 * time.Second)

HTTPTimeout is the timeout for establishing an HTTP(S) connection.

Functions

func GitHub

func GitHub(repo string) aw.Option

GitHub is a Workflow Option. It sets a Workflow Updater for the specified GitHub repo. Repo name should be of the form "username/repo", e.g. "deanishe/alfred-ssh".

Example

Configure Workflow to update from a GitHub repo.

// Set source repo using GitHub Option
wf := aw.New(GitHub("deanishe/alfred-ssh"))
// Is a check for a newer version due?
fmt.Println(wf.UpdateCheckDue())

Output:

true

func SortReleases

func SortReleases(releases []*Release)

SortReleases sorts a slice of Releases, lowest to highest version number.

func SortSemVer

func SortSemVer(versions []SemVer)

SortSemVer sorts a slice of SemVer structs.

Types

type GitHubReleaser

type GitHubReleaser struct {
	Repo string // Repo name in form username/repo
	// contains filtered or unexported fields
}

GitHubReleaser updates from a GitHub repo's releases. Repo should be in the form "username/reponame", e.g. "deanishe/alfred-ssh". Releases are marked as pre-releases based on the "This is a pre-release" checkbox on the website, *not* the version number/tag.

func (*GitHubReleaser) Releases

func (gh *GitHubReleaser) Releases() ([]*Release, error)

Releases implements Releaser. Returns a slice of available releases that contain an .alfredworkflow file.

type Release

type Release struct {
	Filename   string   // Filename of workflow file
	URL        *url.URL // URL of the .alfredworkflow (or .alfred3workflow) file
	Prerelease bool     // Whether this release is a pre-release
	Version    SemVer   // The version number of the release
}

Release is the metadata of a release. Each Releaser must return one or more Release structs. If one has a higher version number than the workflow's current version, it will be considered an update.

type Releaser

type Releaser interface {
	Releases() ([]*Release, error)
}

Releaser is what concrete updaters should implement. The Updater should call the Releaser after every update interval to check if an update is available.

type Releases

type Releases []*Release

Releases is a slice of Releases that implements sort.Interface

func (Releases) Len

func (r Releases) Len() int

Len implements sort.Interface

func (Releases) Less

func (r Releases) Less(i, j int) bool

Less implements sort.Interface

func (Releases) Swap

func (r Releases) Swap(i, j int)

Swap implements sort.Interface

type SemVer

type SemVer struct {
	Major      uint64 // Increment for breaking changes.
	Minor      uint64 // Increment for added/deprecated functionality.
	Patch      uint64 // Increment for bugfixes.
	Build      string // Build metadata (ignored in comparisons)
	Prerelease string // Pre-release version (treated as string)
}

SemVer is a (mostly) semantic version number.

Unlike the semver standard:

• Minor and patch versions are not required, e.g. "v1" and "v1.0" are valid.
• Version string may be prefixed with "v", e.g. "v1" or "v3.0.1-beta". The "v" prefix is stripped, so "v1" == "1.0.0".
• Dots and integers are ignored in pre-release identifiers: they are compared purely alphanumerically, e.g. "v1-beta.11 < "v1-beta.2". Use "v1-beta.02" instead.

func NewSemVer

func NewSemVer(s string) (SemVer, error)

NewSemVer creates a new SemVer. An error is returned if the version string is not valid. See the SemVer struct documentation for deviations from the semver standard.

func (SemVer) Compare

func (v SemVer) Compare(v2 SemVer) int

Compare compares two Versions. Returns:

-1 if v < v2
 0 if v == v2
 1 if v > v2

func (SemVer) EQ

func (v SemVer) EQ(v2 SemVer) bool

EQ checks if v == v2

func (SemVer) Equals

func (v SemVer) Equals(v2 SemVer) bool

Equals checks if v == v2

func (SemVer) GT

func (v SemVer) GT(v2 SemVer) bool

GT checks if v > v2

func (SemVer) GTE

func (v SemVer) GTE(v2 SemVer) bool

GTE checks if v >= v2

func (SemVer) LT

func (v SemVer) LT(v2 SemVer) bool

LT checks if v < v2

func (SemVer) LTE

func (v SemVer) LTE(v2 SemVer) bool

LTE checks if v <= v2

func (SemVer) NE

func (v SemVer) NE(v2 SemVer) bool

NE checks if v != v2

func (SemVer) String

func (v SemVer) String() string

String returns a canonical semver string

type SemVers

type SemVers []SemVer

SemVers implements sort.Interface for SemVer.

func (SemVers) Len

func (vs SemVers) Len() int

Len implements sort.Interface

func (SemVers) Less

func (vs SemVers) Less(i, j int) bool

Less implements sort.Interface

func (SemVers) Swap

func (vs SemVers) Swap(i, j int)

Swap implements sort.Interface

type Updater

type Updater struct {
	CurrentVersion SemVer    // Version of the installed workflow
	LastCheck      time.Time // When the remote release list was last checked
	Prereleases    bool      // Include pre-releases when checking for updates
	Releaser       Releaser  // Provides available versions
	// contains filtered or unexported fields
}

Updater checks for newer version of the workflow. Available versions are provided by a Releaser, such as the built-in GitHub releaser, which reads the releases in a GitHub repo.

CheckForUpdate() retrieves the list of available releases from the releaser and caches them. UpdateAvailable() reads the cache. Install() downloads the latest version and asks Alfred to install it.

LastCheck and available releases are cached.

Because downloading releases is slow and workflows need to run fast, you should not run CheckForUpdate() in a Script Filter.

If an Updater is set on a Workflow struct, a magic action will be set for updates, so you can just add an Item that autocompletes to the update magic argument ("workflow:update" by default), and AwGo will check for an update and install it if available.

See ../examples/update for a full example implementation of updates.

func New

func New(v Versioned, r Releaser) (*Updater, error)

New creates a new Updater for Versioned and Releaser.

CurrentVersion is set to the workflow's version by calling Version(). If you've created your own Workflow struct and subsequently called wf.SetVersion(), you'll also need to set CurrentVersion manually.

LastCheck is loaded from the cache, and UpdateInterval is set to DefaultUpdateInterval.

func (*Updater) CheckDue

func (u *Updater) CheckDue() bool

CheckDue returns true if the time since the last check is greater than Updater.UpdateInterval.

func (*Updater) CheckForUpdate

func (u *Updater) CheckForUpdate() error

CheckForUpdate fetches the list of releases from remote (via Releaser) and caches it locally.

func (*Updater) Install

func (u *Updater) Install() error

Install downloads and installs the latest available version. After the workflow file is downloaded, Install calls Alfred to install the update.

func (*Updater) UpdateAvailable

func (u *Updater) UpdateAvailable() bool

UpdateAvailable returns true if an update is available. Retrieves the list of releases from the cache written by CheckForUpdate.

func (*Updater) UpdateInterval

func (u *Updater) UpdateInterval(interval time.Duration)

UpdateInterval sets the interval between checks for new versions.

type Versioned

type Versioned interface {
	Version() string  // Returns a semantic version string
	CacheDir() string // Path to directory to store cache files
}

Versioned has a semantic version number (for comparing to releases) and a cache directory (for saving information about available versions and time of last update check).

aw.Workflow implements this interface.