Crate gpui_updater_core

Expand description

Blocking cross-platform self-update, hosted on GitHub Releases, static JSON manifests, or Sparkle appcasts. This core has no GPUI dependencies.

GPUI ships no updater of its own, and Zed’s auto_update is GPL-licensed and wired to Zed’s private update server. This crate is an independent, MIT/Apache implementation of the same idea: a small state machine that checks a release source, downloads the platform artifact, verifies it, and swaps it into place.

§Layers

UpdateSource — where releases come from. GitHubSource, StaticManifestSource, and AppcastSource are built in.
UpdateEngine — the blocking pipeline: check → download (with SHA-256, minisign, and Sparkle-compatible Ed25519 verification) → install.
install / verify — the platform install strategies and integrity checks, usable on their own.
UpdateDriver — the contract for handing the whole flow to an external updater instead of the engine; gpui-updater-sparkle implements it with Sparkle on macOS.
delta (behind the delta feature) — binary delta updates: create a per-file bsdiff delta in release CI, and let the engine rebuild the new version from the installed one, falling back to the full download on any problem.
UpdateStatus — backend-independent state used by the separate gpui-updater (official GPUI) and gpui-updater-pre adapters, whichever backend (engine or driver) they run.

§Guides

Topic	Page
Choosing a source, the static manifest format, appcasts, proxies and request headers	`source`
Verification and trust: transport, the checks, policies, key rotation, signed manifests	`verify`
Install strategies, the install location check, installs a package manager owns, platform notes	`install`
Delta updates: enabling, generating, publishing, measurements (feature `delta`)	delta module
Error kinds and what to show the user	`ErrorKind`
Status values for a user interface	`UpdateStatus`

For a GPUI app, start with the gpui-updater or gpui-updater-pre crate, which wraps the engine in an observable entity.

§Example (blocking engine)

use gpui_updater_core::{EngineConfig, GitHubSource, UpdateEngine};
use semver::Version;

let source = GitHubSource::new("AprilNEA", "OpenLogi")
    .asset_contains("macos")
    .asset_contains(".dmg")
    .with_checksums("SHA256SUMS")
    .with_minisig();

let engine = UpdateEngine::new(
    source,
    EngineConfig::new(Version::parse(env!("CARGO_PKG_VERSION")).unwrap())
        .minisign_public_key("RWQ…"),
);

if let Some(release) = engine.check()? {
    let artifact = engine.download(&release, |done, total| {
        if let Some(total) = total {
            eprintln!("{done}/{total}");
        }
    })?;
    engine.install(&artifact)?;
}

Re-exports§

pub use driver::DriverEvent;
pub use driver::DriverEvents;
pub use driver::UpdateDriver;
pub use install::InstallOptions;
pub use install::Installed;
pub use install::MsiUi;
pub use install::Ownership;
pub use install::OwnershipHints;
pub use install::PackageManager;
pub use install::current_install_root;
pub use source::AppcastSource;
pub use source::AppcastVersion;
pub use source::FallbackSource;
pub use source::GitHubSource;
pub use source::StaticManifestSource;
pub use source::UpdateSource;

Modules§

deltadelta: Binary delta updates in the files-bsdiff-v1 format.
driver: The contract for handing the whole update flow to an external updater.
install: Replacing the installed application with a freshly downloaded artifact.
manifest: The static JSON release manifest, as one set of types for both sides.
source: Where to look for releases.
verify: Integrity and authenticity checks for downloaded artifacts. The functions here are the checks the engine runs on every download. They are public so that release tooling can run the same checks. This page describes the whole trust model of UpdateEngine.

Structs§

Artifact: A downloaded update that passed the engine’s checks, ready for UpdateEngine::install.
Asset: A downloadable file attached to a release.
CancelToken: Asks a running UpdateEngine::download_cancellable to stop.
DeltaAsset: A binary delta that upgrades one specific installed version to another.
EngineConfig: Configuration for an UpdateEngine.
HttpOptions: HTTP settings for an update source or for the engine’s downloads: extra request headers and the proxy.
Release: The latest applicable release resolved for the running platform.
UpdateEngine: Blocking update orchestrator: check → download → verify → install.
UpdateError: A failed update operation, as the user interface sees it: what kind of failure it was and the message describing it.
Version: Re-exported so consumers can build an EngineConfig without depending on semver directly (e.g. Version::parse(env!("CARGO_PKG_VERSION"))). SemVer version as defined by https://semver.org.

Enums§

BundleVersion: Whether the app bundle of an update must declare the release’s version (macOS).
CodeSigning: Which code signature an update must carry: the app bundle’s on macOS, the .exe or .msi Authenticode signature on Windows. Linux has no platform code signature, so nothing is checked there.
Error: Errors produced while checking for, downloading, verifying, or installing an update.
ErrorKind: The broad class of an Error, stable enough to drive user interface decisions: which message to show, and whether retrying can help.
UpdateStatus: Observable state of an update operation.
Verification: How strictly UpdateEngine enforces integrity and authenticity checks on a release.
VersionBinding: Whether a signature must name the version it was made for.

Constants§

DEFAULT_MAX_DELTA_HOPS: Longest chain of deltas the engine downloads by default.
DEFAULT_MAX_DOWNLOAD_SIZE: Largest download the engine accepts by default: 4 GiB, twice what GitHub Releases allows for a single asset.
DELTA_FORMAT_FILES_BSDIFF_V1: Format identifier of the deltas produced by the delta feature’s delta::create: per-file bsdiff patches against the installed tree.

Functions§

parse_tag: Parse a release tag such as v1.2.3 or 1.2.3 into a Version.
parse_version_lenient: Parse a version the way feeds that are not strictly semver publish it.

Type Aliases§

Result: Convenience alias for results returned by this crate.