Crate update_informer

Expand description

Overview

Update informer for CLI applications written in Rust. It checks for a new version on Crates.io, GitHub and PyPI.

Benefits

Support of Crates.io, GitHub and PyPI.
Ability to implement your own registry to check updates.
Configurable check frequency and request timeout.
Minimum dependencies - only directories, ureq, semver and serde.

Usage

By default, update-informer can only check on Crates.io. To enable support for other registries, use features:

[dependencies]
update-informer = { version = "0.5.0", default_features = false, features = ["github"] }

Available features:

Name	Default?
cargo	Yes
github	No
pypi	No

Crates.io

To check for a new version on Crates.io, use the UpdateInformer::check_version function. This function takes the project name and current version:

use update_informer::{registry, Check};

let informer = update_informer::new(registry::Crates, "crate_name", "0.1.0");
if let Some(version) = informer.check_version().ok().flatten() {
    println!("New version is available: {}", version);
}

Also, you can take the name and version of the project from Cargo using environment variables:

use update_informer::{registry, Check};

let name = env!("CARGO_PKG_NAME");
let version = env!("CARGO_PKG_VERSION");
update_informer::new(registry::Crates, name, version).check_version();

Interval

Note that the first check will start only after the interval has expired. By default, the interval is 24 hours, but you can change it:

use std::time::Duration;
use update_informer::{registry, Check};

const EVERY_HOUR: Duration = Duration::from_secs(60 * 60);

let informer = update_informer::new(registry::Crates, "crate_name", "0.1.0").interval(EVERY_HOUR);
informer.check_version(); // The check will start only after an hour

Cache file

By default, update-informer creates a file in the cache directory to avoid spam requests to the registry API.

In order not to cache requests, use a zero interval:

use std::time::Duration;
use update_informer::{registry, Check};

let informer = update_informer::new(registry::Crates, "crate_name", "0.1.0").interval(Duration::ZERO);
informer.check_version();

Request timeout

You can also change the request timeout. By default, it is 5 seconds:

use std::time::Duration;
use update_informer::{registry, Check};

const THIRTY_SECONDS: Duration = Duration::from_secs(30);

let informer = update_informer::new(registry::Crates, "crate_name", "0.1.0").timeout(THIRTY_SECONDS);
informer.check_version();

GitHub

To check for a new version on GitHub (note that the project name must contain the owner):

use update_informer::{registry, Check};

let informer = update_informer::new(registry::GitHub, "owner/repo", "0.1.0");
informer.check_version();

PyPi

To check for a new version on PyPI:

use update_informer::{registry, Check};

let informer = update_informer::new(registry::PyPI, "package_name", "0.1.0");
informer.check_version();

Implementing your own registry

You can implement your own registry to check updates. For example:

use std::time::Duration;
use update_informer::{registry, Check, Package, Registry, Result, Version};

struct YourOwnRegistry;

impl Registry for YourOwnRegistry {
    const NAME: &'static str = "your_own_registry";

    fn get_latest_version(pkg: &Package, _current_version: &Version, _timeout: Duration) -> Result<Option<String>> {
        let url = format!("https://your_own_registry.com/{}/latest-version", pkg);
        let result = ureq::get(&url).call()?.into_string()?;
        let version = result.trim().to_string();

        Ok(Some(version))
    }
}

let informer = update_informer::new(YourOwnRegistry, "package_name", "0.1.0");
informer.check_version();

Tests

In order not to check for updates in tests, you can use the FakeUpdateInformer::check_version function, which returns the desired version.

Example of usage in unit tests:

use update_informer::{registry, Check};

let name = "crate_name";
let version = "0.1.0";

#[cfg(not(test))]
let informer = update_informer::new(registry::Crates, name, version);

#[cfg(test)]
let informer = update_informer::fake(registry::Crates, name, version, "1.0.0");

if let Some(version) = informer.check_version().ok().flatten() {
    println!("New version is available: {}", version);
}

Integration tests

To use the FakeUpdateInformer::check_version function in integration tests, you must first add the feature flag to Cargo.toml:

[features]
stub_check_version = []

Then use this feature flag in your code and integration tests:

use update_informer::{registry, Check};

let name = "crate_name";
let version = "0.1.0";

#[cfg(not(feature = "stub_check_version"))]
let informer = update_informer::new(registry::Crates, name, version);

#[cfg(feature = "stub_check_version")]
let informer = update_informer::fake(Crates, name, version, "1.0.0");

informer.check_version();