awgo: github.com/deanishe/awgo/update Index | Examples | Files

package update

import "github.com/deanishe/awgo/update"

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

Examples

Package Files

doc.go gitea.go github.go metadata.go semver.go update.go

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
)

func GitHub Uses

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".

Configure Workflow to update from a GitHub repo.

Code:

// 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 Uses

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".

Configure Workflow to update from a Gitea repo.

Code:

// 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 Uses

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.

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

Code:

// 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 Uses

func SortSemVer(versions []SemVer)

SortSemVer sorts a slice of SemVer structs.

type Download Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (v SemVer) Eq(v2 SemVer) bool

Eq checks if v == v2

func (SemVer) Gt Uses

func (v SemVer) Gt(v2 SemVer) bool

Gt checks if v > v2

func (SemVer) Gte Uses

func (v SemVer) Gte(v2 SemVer) bool

Gte checks if v >= v2

func (SemVer) IsZero Uses

func (v SemVer) IsZero() bool

IsZero returns true if SemVer has no value.

func (SemVer) Lt Uses

func (v SemVer) Lt(v2 SemVer) bool

Lt checks if v < v2

func (SemVer) Lte Uses

func (v SemVer) Lte(v2 SemVer) bool

Lte checks if v <= v2

func (SemVer) Ne Uses

func (v SemVer) Ne(v2 SemVer) bool

Ne checks if v != v2

func (SemVer) String Uses

func (v SemVer) String() string

String returns a canonical semver string

type SemVers Uses

type SemVers []SemVer

SemVers implements sort.Interface for SemVer.

func (SemVers) Len Uses

func (vs SemVers) Len() int

Len implements sort.Interface

func (SemVers) Less Uses

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

Less implements sort.Interface

func (SemVers) Swap Uses

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

Swap implements sort.Interface

type Source Uses

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 Uses

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 Uses

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 Uses

func (u *Updater) CheckDue() bool

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

func (*Updater) CheckForUpdate Uses

func (u *Updater) CheckForUpdate() error

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

func (*Updater) Install Uses

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 Uses

func (u *Updater) UpdateAvailable() bool

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

Package update imports 19 packages (graph) and is imported by 6 packages. Updated 2020-05-21. Refresh now. Tools for package owners.