6 releases

0.1.4 Jan 30, 2024
0.1.3 Jan 30, 2024
0.1.1 Dec 27, 2023
0.0.0 Sep 4, 2023

#5 in #endpoints

Download history 9/week @ 2023-12-25 13/week @ 2024-01-29 5/week @ 2024-02-19 6/week @ 2024-02-26 11/week @ 2024-03-11 83/week @ 2024-04-01

94 downloads per month

Apache-2.0 OR MIT

73KB
1K SLoC

cargo-packager-updater

Updater for apps that was packaged by cargo-packager.

Checking for an update

you can check for an update using check_update function or construct a new Updater using UpdaterBuilder, both methods require the current version of the app and a Config that specifies the endpoints to request updates from and the public key of the update signature.

use cargo_packager_updater::{check_update, Config};

let config = Config {
  endpoints: vec!["http://myserver.com/updates"],
  pubkey: "<pubkey here>",
  ..Default::default()
};
if let Some(update) = check_update("0.1.0", config).expect("failed while checking for update") {
  update.download_and_install().expect("failed to download and install update");
} else {
  // there is no updates
}

Endpoints

Each endpoint optionally could have {{arch}}, {{target}} or {{current_version}} which will be detected and replaced with the appropriate value before making a request to the endpoint.

  • {{current_version}}: The version of the app that is requesting the update.
  • {{target}}: The operating system name (one of linux, windows or macos).
  • {{arch}}: The architecture of the machine (one of x86_64, i686, aarch64 or armv7).

for example:

 "https://releases.myapp.com/{{target}}/{{arch}}/{{current_version}}"

will turn into

 "https://releases.myapp.com/windows/x86_64/0.1.0"

if you need more data, you can set additional request headers UpdaterBuilder::header to your liking.

Endpoint Response

The updater expects the endpoint to respond with 2 possible reponses:

  1. 204 No Content in case there is no updates available.
  2. 200 OK and a JSON response that could be either a JSON representing all available platform updates or if using endpoints variables (see above) or a header to attach the current updater target, then it can just return information for the requested target.

The JSON response is expected to have these fields set:

  • version: must be a valid semver, with or without a leading v``, meaning that both 1.0.0andv1.0.0`are valid.
  • urlorplatforms.[target].url: must be a valid url to the update bundle.
  • signatureorplatforms.[target].signature: must be the content of the generated .sigfile. The signature may change each time you run build your app so make sure to always update it.
  • formatorplatforms.[target].format: must be one of app, appimage, nsisorwix.

[!NOTE] if using platforms object, each key is in the OS-ARCH format, where OS is one of linux, macos or windows, and ARCH is one of x86_64, aarch64, i686 or armv7, see the example below.

It can also contain these optional fields:

  • notes: Here you can add notes about the update, like release notes.
  • pub_date: must be formatted according to RFC 3339 if present.

Here is an example of the two expected JSON formats:

  • JSON for all platforms

    {
      "version": "v1.0.0",
      "notes": "Test version",
      "pub_date": "2020-06-22T19:25:57Z",
      "platforms": {
        "darwin-x86_64": {
          "signature": "Content of app.tar.gz.sig",
          "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-x86_64.app.tar.gz",
          "format": "app"
        },
        "darwin-aarch64": {
          "signature": "Content of app.tar.gz.sig",
          "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-aarch64.app.tar.gz",
          "format": "app"
        },
        "linux-x86_64": {
          "signature": "Content of app.AppImage.sig",
          "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-amd64.AppImage.tar.gz",
          "format": "appimage"
        },
        "windows-x86_64": {
          "signature": "Content of app-setup.exe.sig or app.msi.sig, depending on the chosen format",
          "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-x64-setup.nsis.zip",
          "format": "nsis or wix depending on the chosen format"
        }
      }
    }
    
  • JSON for one platform

    {
      "version": "0.2.0",
      "pub_date": "2020-09-18T12:29:53+01:00",
      "url": "https://mycompany.example.com/myapp/releases/myrelease.tar.gz",
      "signature": "Content of the relevant .sig file",
      "format": "app or nsis or wix or appimage depending on the release target and the chosen format",
      "notes": "These are some release notes"
    }
    

Update install mode on Windows

You can specify which install mode to use on Windows using WindowsConfig::install_mode which can be on of:

  • "Passive": There will be a small window with a progress bar. The update will be installed without requiring any user interaction. Generally recommended and the default mode.
  • "BasicUi": There will be a basic user interface shown which requires user interaction to finish the installation.
  • "Quiet": There will be no progress feedback to the user. With this mode the installer cannot request admin privileges by itself so it only works in user-wide installations or when your app itself already runs with admin privileges. Generally not recommended.

Licenses

MIT or MIT/Apache 2.0 where applicable.

Dependencies

~7–23MB
~363K SLoC