Module alfred_rs::updater

Helper for enabling Alfred workflows to upgrade themselves periodically (Alfred 3+)

Using this module, the workflow author can make Alfred check for latest releases (try_update_ready() or update_ready()) from a remote server within adjustable intervals (default is 24 hrs).

Additionally they can ask Alfred to download the new release to its cache folder for further action: download_latest().

For convenience, an associated method Updater::gh() is available to check for workflows hosted on github.com.

However, it’s possible to check with other servers as long as the Releaser trait is implemented for the desired remote service. See Updater::new() documentation if you are hosting your workflow on a non github.com service.

Notes:

• The github.com hosted repository should have release items following github’s process. This can be done by tagging a commit and then manually building a release where you attach/upload YourWorkflow.alfredworkflow to the release page. You can easily create YourWorkflow.alfredworkflow file by using the export feature of Alfred in its preferences window.

• The tag should follow all of the semantic versioning rules. The only exception to those rules is that you can prepend your semantic version tag with ASCII letter v: v0.3.1 or 0.3.1

Note to workflow authors

• Depending on network quality, checking if an update is available may take a long time. This module may spawn a worker thread so that the check does not block the main flow of your plugin. However given the limitations of Alfred’s plugin architecture, the worker thread cannot outlive your plugin’s executable. This means that you either have to wait/block for the worker thread, or if it is taking longer than a desirable time, you will have to abandon it. See the example for more details.
• Workflow authors should make sure that released workflow bundles have their version set in Alfred’s preferences window. However, this module provides set_version() to set the version during runtime.

Example

Create an updater for a workflow hosted on github.com/spamwax/alfred-pinboard-rs. By default, it will check for new releases every 24 hours. To change the interval, use set_interval() method.

extern crate alfred;

// This crate
extern crate alfred_rs;

use alfred::{Item, ItemBuilder, json};
use alfred_rs::Updater;

// Our workflow's main 'runner' function
fn run<'a>() -> Result<Vec<Item<'a>>> {
    let updater = Updater::gh("spamwax/alfred-pinboard-rs")?;

    // Start the process for getting latest release info
    updater.init().expect("cannot initialize updater");

    // We'll do some other work that's related to our workflow:
    do_some_other_stuff();
    let mut items: Vec<Item> = produce_items_for_user_to_see();

    // We can now check if update is ready using two methods:
    // 1- Block and wait until we receive results from worker thread
    //    It's a good practice to only wait for worker for a limited time so
    //    our workflow doesn't become unresponsive (not shown here)
    let update_status = updater.update_ready();

    // 2- Or without blocking, check if the worker thread sent the results.
    //    If the worker thread is still busy, we'll get an `Err`
    let update_status = updater.try_update_ready();

    if let Ok(is_ready) = update_status { // Comm. with worker was successful
        // Check for new update and add an item to 'items'
        if is_ready {
            let update_item = ItemBuilder::new(
                "New version is available!"
            ).into_item();
            // Add a new item to previous list of Items
            items.push(update_item);
        }
    } else {
        /* worker thread wasn't successful */
    }
    Ok(items)
}

fn main() {
    // Fetch the items and show them.
    if let Ok(ref items) = run() {
        json::write_items(io::stdout(), items);
    }
}

An issue with above example can be when user is on a poor network or server is unresponsive. In this case, the above snippet will try to call server every time workflow is invoked by Alfred until the operation succeeds.

Structs

GithubReleaser

Struct to handle checking and finding release files from github.com

Updater

Struct to check for & download the latest release of workflow from a remote server.

Constants

UPDATE_INTERVAL

Default update check interval duration (24 hrs). To change the interval use the set_interval() method.

Traits

Releaser

An interface for checking with remote servers to identify the latest release for an Alfred workflow.