moz-cli-version-check 0.2.4

Version checking library for Mozilla CLI tools
Documentation

moz-cli-version-check

A lightweight version checking library for Mozilla CLI tools.

Features

  • Enabled by default: Checks for updates unless MOZTOOLS_UPDATE_CHECK=0 is set
  • Non-blocking: Runs in background thread, never delays program startup
  • Cached: Remote checks are throttled to at most once per interval per tool
  • Failure-aware: Failed or blocked remote checks are also throttled
  • Shared cache: All tools share ~/.mozbuild/tool-versions.json
  • Silent failures: Network errors don't affect program operation
  • Thread-safe: Safe for concurrent access

Usage

Add to your Cargo.toml:

[dependencies]
moz-cli-version-check = "0.2.4"

In your main.rs:

fn main() -> Result<()> {
    let version_checker = moz_cli_version_check::VersionChecker::new(
        "your-tool-name",
        env!("CARGO_PKG_VERSION"),
    );
    version_checker.check_async();

    let result = run();

    version_checker.print_warning();

    result
}

fn run() -> Result<()> {
    // Your actual program logic here
    Ok(())
}

To override the default interval in code:

use std::time::Duration;

fn main() -> Result<()> {
    let version_checker = moz_cli_version_check::VersionChecker::with_check_interval(
        "your-tool-name",
        env!("CARGO_PKG_VERSION"),
        Duration::from_secs(24 * 60 * 60),
    );
    version_checker.check_async();

    let result = run();

    version_checker.print_warning();

    result
}

How It Works

  1. At program startup, unless MOZTOOLS_UPDATE_CHECK=0 is set, spawn a background thread
  2. The thread checks the cache file (~/.mozbuild/tool-versions.json)
  3. If the cache is recent (< configured interval), use cached data
  4. Otherwise, query crates.io API: https://crates.io/api/v1/crates/<name>
  5. Record the attempt time even if the remote check fails or is blocked
  6. Update the cache with the latest version info when available
  7. At program exit, print a warning if a newer version is available

Warning Format

When a newer version is available, users see:

Note: A newer version of socorro-cli is available (0.2.0 > 0.1.0)
      Run: cargo binstall socorro-cli

Cache Format

The cache file at ~/.mozbuild/tool-versions.json contains:

{
  "socorro-cli": {
    "last_check": 1234567890,
    "latest": "0.2.0"
  },
  "treeherder-cli": {
    "last_check": 1234567890,
    "latest": "0.1.0"
  }
}

Testing

Version checking is enabled by default:

socorro-cli crash --help

To disable:

export MOZTOOLS_UPDATE_CHECK=0
socorro-cli crash --help

Configuration

  • Cache location: ~/.mozbuild/tool-versions.json
  • Default check interval: 24 hours
  • Env override: MOZTOOLS_UPDATE_CHECK_INTERVAL_SECONDS
  • Network timeout: 5 seconds
  • User-Agent: {tool-name}/version-check

Implementation Details

  • Uses reqwest with blocking client for HTTP requests
  • Uses serde_json for cache file serialization
  • Thread-safe via Arc<Mutex<Option<String>>>
  • Silently fails on any error (network, I/O, parsing)
  • Never blocks program execution

License

Licensed under either of:

at your option.