update

Documentation

Overview

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

It is the "backend" for aw.Workflow's update API, and provides concrete updaters for GitHub and Gitea releases, and Alfred metadata.json files (as aw.Options). Updater implements aw.Updater and you can create a custom Updater to use with aw.Workflow/aw.Update() by passing a custom implementation of Source to NewUpdater().

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

Updater is also Alfred-version-aware, and ignores incompatible workflow version, e.g. workflow files with the extension ".alfred4workflow" are ignored when Updater is run in Alfred 3.

See ../_examples/update for one possible way to using the updater API.

Index

• Variables
• func GitHub(repo string) aw.Option
• func Gitea(repo string) aw.Option
• func Metadata(url string) aw.Option
• func SortSemVer(versions []SemVer)
• type Download
  • func (dl Download) AlfredVersion() SemVer
• 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) Gt(v2 SemVer) bool
  • func (v SemVer) Gte(v2 SemVer) bool
  • func (v SemVer) IsZero() 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 Source
• type Updater
  • func NewUpdater(src Source, currentVersion, cacheDir string) (*Updater, error)
  • func (u *Updater) CheckDue() bool
  • func (u *Updater) CheckForUpdate() error
  • func (u *Updater) Install() error
  • func (u *Updater) UpdateAvailable() bool

Examples

• GitHub
• Gitea
• Metadata

Variables

var (
	// UpdateInterval is how often to check for updates.
	UpdateInterval = 24 * time.Hour
	// HTTPTimeout is the timeout for establishing an HTTP(S) connection.
	HTTPTimeout = 60 * time.Second
)

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 Gitea

func Gitea(repo string) aw.Option

Gitea is a Workflow Option. It sets a Workflow Updater for the specified Gitea repo. Repo name should be the URL of the repo, e.g. "git.deanishe.net/deanishe/alfred-ssh".

Example

Configure Workflow to update from a Gitea repo.

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

Output:

true

func Metadata

func Metadata(url string) aw.Option

Metadata is a Workflow Option. It sets a Workflow Updater based on a `metadata.json` file exported from Alfred 4+.

URL is the location of the `metadata.json` file. Note: You *must* set `downloadurl` in the `metadata.json` file to the URL of your .alfredworkflow (or .alfred4workflow etc.) file.

Example

Configure Workflow to update from a remote `metadata.json` file.

// Set source repo using Gitea Option
wf := aw.New(Metadata("https://raw.githubusercontent.com/deanishe/alfred-ssh/master/metadata.json"))
// Is a check for a newer version due?
fmt.Println(wf.UpdateCheckDue())

Output:

true

func SortSemVer

func SortSemVer(versions []SemVer)

SortSemVer sorts a slice of SemVer structs.

Types

type Download

type Download struct {
	URL string // Where the workflow file can be downloaded from
	// Filename for downloaded file.
	// Must have extension .alfredworkflow or .alfredXworkflow where X is a number,
	// otherwise the Download will be ignored.
	Filename   string
	Version    SemVer // Semantic version no.
	Prerelease bool   // Whether this version is a pre-release
}

Download is an Alfred workflow available for download & installation. It is the primary update data structure, returned by all Sources.

func (Download) AlfredVersion

func (dl Download) AlfredVersion() SemVer

AlfredVersion returns minimum compatible version of Alfred based on file extension. For example, Workflow.alfred4workflow has version 4, while Workflow.alfred3workflow has version 3. The standard .alfredworkflow extension returns a zero version.

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) 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) IsZero

func (v SemVer) IsZero() bool

IsZero returns true if SemVer has no value.

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 Source

type Source interface {
	// Downloads returns all available workflow files.
	Downloads() ([]Download, error)
}

Source provides workflow files that can be downloaded. This is what concrete updaters (e.g. GitHub, Gitea) should implement. Source is called by the Updater after every updater interval.

type Updater

type Updater struct {
	Source         Source // Provides downloads
	CurrentVersion SemVer // Version of the installed workflow
	Prereleases    bool   // Include pre-releases when checking for updates

	// AlfredVersion is the version of the running Alfred application.
	// Read from $alfred_version environment variable.
	AlfredVersion SemVer

	// When the remote release list was last checked (and possibly cached)
	LastCheck time.Time
	// contains filtered or unexported fields
}

Updater checks for newer version of the workflow. Available versions are provided by a Source, such as the built-in GitHub source, which reads the releases in a GitHub repo. It is a concrete implementation of aw.Updater.

CheckForUpdate() retrieves the list of available downloads from the source and caches them. UpdateAvailable() reads the cache and returns true if there is a download with a higher version than the running workflow. Install() downloads the latest version and asks Alfred to install it.

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 NewUpdater

func NewUpdater(src Source, currentVersion, cacheDir string) (*Updater, error)

NewUpdater creates a new Updater for Source. `currentVersion` is the workflow's version number and `cacheDir` is a directory where the Updater can cache a list of available releases.

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.