Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mgrachev/update-informer

Update informer for CLI applications written in Rust 🦀
https://github.com/mgrachev/update-informer

contributor-friendly contributors-welcome hacktoberfest rust rust-lang rust-library update-checker update-notifier

Last synced: 24 days ago
JSON representation

Update informer for CLI applications written in Rust 🦀

Host: GitHub
URL: https://github.com/mgrachev/update-informer
Owner: mgrachev
License: mit
Created: 2021-12-08T15:31:45.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2024-03-24T17:00:05.000Z (about 2 months ago)
Last Synced: 2024-04-13T21:08:46.375Z (about 1 month ago)
Topics: contributor-friendly, contributors-welcome, hacktoberfest, rust, rust-lang, rust-library, update-checker, update-notifier
Language: Rust
Homepage:
Size: 363 KB
Stars: 205
Watchers: 5
Forks: 7
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Lists

awesome-rust - mgrachev/update-informer - informer](https://crates.io/crates/update-informer)] — Update informer for CLI applications. It checks for a new version on Crates.io and GitHub [![build badge](https://github.com/mgrachev/update-informer/workflows/CI/badge.svg)](https://github.com/mgrachev/update-informer/actions) (Libraries / Command-line)
awesome-stars - mgrachev/update-informer - Update informer for CLI applications written in Rust 🦀 (Rust)
awesome-rust-cn - mgrachev/update-informer - informer](https://crates.io/crates/update-informer)] (库 Libraries / 命令行 Command-line)

README

        # Update-informer

[ci-badge]: https://github.com/mgrachev/update-informer/workflows/CI/badge.svg

[ci-url]: https://github.com/mgrachev/update-informer/actions

[crates-badge]: https://img.shields.io/crates/v/update-informer

[crates-url]: https://crates.io/crates/update-informer

[docs-badge]: https://img.shields.io/docsrs/update-informer

[docs-url]: https://docs.rs/update-informer

[codecov-badge]: https://codecov.io/gh/mgrachev/update-informer/branch/main/graph/badge.svg?token=A4XD1DGFGJ

[codecov-url]: https://codecov.io/gh/mgrachev/update-informer

[downloads-badge]: https://img.shields.io/crates/d/update-informer

[directories]: https://github.com/dirs-dev/directories-rs

[ureq]: https://github.com/algesten/ureq

[semver]: https://github.com/dtolnay/semver

[serde]: https://github.com/serde-rs/serde

[GitHub CLI application]: https://github.com/cli/cli/blob/trunk/internal/update/update.go

[npm]: https://github.com/npm/cli/blob/latest/lib/utils/update-notifier.js

[JavaScript library]: https://github.com/yeoman/update-notifier

[MIT]: https://choosealicense.com/licenses/mit

[git-cliff]: https://github.com/orhun/git-cliff

[dotenv-linter]: https://github.com/dotenv-linter/dotenv-linter

[update-informer]: https://evrone.com/update-informer?utm_source=github&utm_campaign=update-informer

[Evrone]: https://evrone.com/?utm_source=github&utm_campaign=update-informer

[turbo]: https://github.com/vercel/turbo

[fselect]: https://github.com/jhspetersson/fselect

[reqwest]: https://github.com/seanmonstar/reqwest

[isahc]: https://github.com/sagebind/isahc

[here]: https://github.com/mgrachev/update-informer/tree/main/examples

[![CI][ci-badge]][ci-url]

[![Version][crates-badge]][crates-url]

[![Docs.rs][docs-badge]][docs-url]

[![Codecov][codecov-badge]][codecov-url]

[![Downloads][downloads-badge]][crates-url]



Update informer for CLI applications written in Rust 🦀

It checks for a new version on Crates.io, GitHub, Npm and PyPI 🚀

## Benefits

- Support of **Crates.io**, **GitHub**, **Npm** and **PyPI**.

- Configurable [check frequency](#interval) and [request timeout](#request-timeout).

- [Caching](#caching) the results of checking updates.

- Ability to implement your own [registry](#implementing-your-own-registry) or [http client](#using-your-own-http-client).

- **Minimum dependencies** - only [directories], [semver], [serde] and an HTTP client ([ureq] or [reqwest]).

## Idea

The idea is actually not new. This feature has long been present in the [GitHub CLI application] and [npm].


There is also a popular [JavaScript library].

## Usage

Add `update-informer` to `Cargo.toml`:

```toml

[dependencies]

update-informer = "1.1"

```

By default, `update-informer` can only check on Crates.io and uses [ureq] as a default HTTP client.

To enable support for other registries or change the HTTP client, use `features`:

```toml

[dependencies]

update-informer = { version = "1.1", default-features = false, features = ["github", "reqwest", "native-tls"] }

```

Available features:

| Name       | Type                | Default? |

| ---------- | ------------------- | -------- |

| crates     | Registry            | Yes      |

| github     | Registry            | No       |

| npm        | Registry            | No       |

| pypi       | Registry            | No       |

| [ureq]     | HTTP client         | Yes      |

| [reqwest]  | HTTP client         | No       |

| rustls-tls | HTTP client feature | Yes      |

| native-tls | HTTP client feature | No       |

## Checking for a new version

To check for a new version, use the `UpdateInformer::check_version` function.


This function takes the project name and current version as well as registry:

```rust

use update_informer::{registry, Check};

let name = env!("CARGO_PKG_NAME");

let version = env!("CARGO_PKG_VERSION");

let informer = update_informer::new(registry::Crates, name, version);

if let Some(version) = informer.check_version().ok().flatten()  {

    println!("New version is available: {}", version);

}

```

More examples you can find [here].

## 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:

```rust

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

```

## Caching

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:

```rust

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**:

```rust

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();

```

## Implementing your own registry

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

```rust

use update_informer::{http_client::{GenericHttpClient, HttpClient}, registry, Check, Package, Registry, Result};

#[derive(serde::Deserialize)]

struct Response {

    version: String,

}

struct YourOwnRegistry;

impl Registry for YourOwnRegistry {

    const NAME: &'static str = "your_own_registry";

    fn get_latest_version(http_client: GenericHttpClient, pkg: &Package) -> Result> {

        let url = "https://turbo.build/api/binaries/version";

        let resp = http_client.get::(&url)?;

        Ok(Some(resp.version))

    }

}

let informer = update_informer::new(YourOwnRegistry, "turbo", "0.1.0");

informer.check_version();

```

## Using your own HTTP client

You can use your own HTTP client to check updates. For example, [isahc]:

```rust

use isahc::ReadResponseExt;

use std::time::Duration;

use serde::de::DeserializeOwned;

use update_informer::{http_client::{HeaderMap, HttpClient}, registry, Check};

struct YourOwnHttpClient;

impl HttpClient for YourOwnHttpClient {

    fn get(

        url: &str,

        _timeout: Duration,

        _headers: HeaderMap,

    ) -> update_informer::Result {

        let json = isahc::get(url)?.json()?;

        Ok(json)

    }

}

let informer = update_informer::new(registry::Crates, "crate_name", "0.1.0").http_client(YourOwnHttpClient);

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:

```rust

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`:

```toml

[features]

stub_check_version = []

```

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

```rust

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();

```

## Users

- [git-cliff]

- [dotenv-linter]

- [turbo]

- [fselect]

## MSRV

Minimum Supported Rust Version: 1.56.1

## Sponsors

[update-informer] is created & supported by [Evrone]

## License

[MIT]