5 releases (breaking)

Uses new Rust 2021

0.5.0 Mar 24, 2022
0.4.0 Feb 21, 2022
0.3.0 Feb 19, 2022
0.2.0 Jan 5, 2022
0.1.0 Dec 30, 2021

#40 in Command-line interface

Download history 759/week @ 2022-06-08 866/week @ 2022-06-15 978/week @ 2022-06-22 551/week @ 2022-06-29 751/week @ 2022-07-06 1061/week @ 2022-07-13 761/week @ 2022-07-20 995/week @ 2022-07-27 852/week @ 2022-08-03 988/week @ 2022-08-10 1141/week @ 2022-08-17 482/week @ 2022-08-24 1556/week @ 2022-08-31 3358/week @ 2022-09-07 3320/week @ 2022-09-14 2764/week @ 2022-09-21

11,158 downloads per month
Used in 16 crates (14 directly)

MIT license

49KB
818 lines

Update-informer CI Crates.io docs.rs codecov

update-informer

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.

The idea is actually not new, as GitHub has been doing for a long time in its CLI application.
There is also a popular JavaScript library.

Update-informer is created & supported by Evrone.

Usage

Add update-informer to Cargo.toml:

[dependencies]
update-informer = "0.5.0"

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 as well as check interval:

use update_informer::{registry, Check};

let informer = update_informer::new(registry::Crates, "crate_name", "0.1.0");
if let Ok(Some(version)) = informer.check_version() {
    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};

struct YourOwnRegistry;

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

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

        Ok(Some(version))
    }
}

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

Example

A real example of using update_informer with colored crate.
use colored::*;
use update_informer::{registry, Check};

fn main() {
    let pkg_name = env!("CARGO_PKG_NAME");
    let current_version = env!("CARGO_PKG_VERSION");

    let informer = update_informer::new(registry::Crates, pkg_name, current_version);
    if let Ok(Some(version)) = informer.check_version() {
        let msg = format!(
            "A new release of {pkg_name} is available: v{current_version} -> {new_version}",
            pkg_name = pkg_name.italic().cyan(),
            current_version = current_version,
            new_version = version.to_string().green()
        );

        let release_url = format!(
            "https://github.com/{pkg_name}/{pkg_name}/releases/tag/{version}",
            pkg_name = pkg_name,
            version = version
        )
            .yellow();

        println!("\n{msg}\n{url}", msg = msg, url = release_url);
    }
}

The result will look like: example

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 Ok(Some(version)) = informer.check_version() {
    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(registry::Crates, name, version, "1.0.0");

informer.check_version();

Sponsors

Sponsored by Evrone

License

MIT

Dependencies

~2.7–4MB
~105K SLoC