guise/update/
updater.rs

1//! [`UpdateConfig`] — the gpui-free engine — and [`Updater`], the app-level
2//! object the components and the poller are built from.
3//!
4//! The split is not decoration: the check and the install are blocking work that
5//! runs on gpui's background executor, which requires everything it captures to
6//! be `Send`. [`Updater`] carries `Rc` callbacks (notifications, a pre-restart
7//! hook) and so can never cross that boundary; [`UpdateConfig`] is the plain-data
8//! half that can, and it is what the background task actually gets a copy of.
9
10use std::rc::Rc;
11use std::time::Duration;
12
13use gpui::{App, SharedString};
14
15use super::{InstallKind, Relaunch, Release, UpdateCheck, UpdateSource, UpdateStage};
16
17/// How often to re-check while running (a conservative hourly cadence).
18pub const POLL: Duration = Duration::from_secs(60 * 60);
19
20/// Everything the blocking check and install need, and nothing that can't cross
21/// onto a background thread. Build one through [`Updater`] unless you are driving
22/// the mechanics yourself.
23#[derive(Clone, Debug, PartialEq, Eq)]
24pub struct UpdateConfig {
25  /// Display name, used in the prompt's copy ("Acme 1.2.3 is available").
26  pub(crate) app: String,
27  /// Filesystem-safe name, used for staging paths under `$TMPDIR`.
28  pub(crate) slug: String,
29  /// The running version, which every check compares against.
30  pub(crate) version: String,
31  /// Where releases are published.
32  pub(crate) source: UpdateSource,
33  /// Sent as `User-Agent` — GitHub's API rejects requests without one.
34  pub(crate) user_agent: String,
35  /// The macOS `codesign` requirement an update must satisfy.
36  pub(crate) requirement: Option<String>,
37  /// Refuse to install when the release publishes no SHA-256 to check the
38  /// download against.
39  pub(crate) require_checksum: bool,
40}
41
42impl UpdateConfig {
43  /// A config for `app` at `version`, checking `source`.
44  pub fn new(app: impl Into<String>, version: impl Into<String>, source: UpdateSource) -> Self {
45    let app = app.into();
46    let slug = slug(&app);
47    let user_agent = format!("{slug}-updater");
48    UpdateConfig {
49      app,
50      slug,
51      version: version.into(),
52      source,
53      user_agent,
54      requirement: None,
55      require_checksum: false,
56    }
57  }
58
59  /// The `codesign` requirement a macOS update must satisfy before it is
60  /// installed — **without** this, macOS installs refuse to run in place and
61  /// the prompt falls back to opening the download page.
62  ///
63  /// Pass the requirement text only; the `-R=` that `codesign` needs is added
64  /// here. Pin your team, not a certificate: team IDs survive certificate
65  /// renewals, so
66  ///
67  /// ```ignore
68  /// .codesign_requirement("anchor apple generic and certificate leaf[subject.OU] = XJDC46F35X")
69  /// ```
70  ///
71  /// keeps working when the signing cert rolls. The practical consequence is
72  /// that an ad-hoc signed build — what CI produces when the signing secrets
73  /// are absent — cannot self-update, and shouldn't be able to.
74  pub fn codesign_requirement(mut self, requirement: impl Into<String>) -> Self {
75    self.requirement = Some(requirement.into());
76    self
77  }
78
79  /// Refuse to install an update whose release publishes no SHA-256.
80  ///
81  /// A published digest is always checked when it exists. This turns a
82  /// *missing* one from a silent pass into a refusal, which is the setting
83  /// you want on Linux: the AppImage path has no signature to fall back on,
84  /// so without a digest the only thing vouching for the file that is about
85  /// to be renamed over the running binary is the feed that named it.
86  ///
87  /// Publish `<asset>.sha256` beside each artifact, or a `SHA256SUMS`
88  /// listing, and turn this on.
89  pub fn require_checksum(mut self, require: bool) -> Self {
90    self.require_checksum = require;
91    self
92  }
93
94  /// Whether a missing checksum blocks an install.
95  pub fn requires_checksum(&self) -> bool {
96    self.require_checksum
97  }
98
99  /// Check a downloaded file against the digest the release published for it.
100  ///
101  /// Absent a published digest this is a pass unless
102  /// [`require_checksum`](Self::require_checksum) is set — a release that
103  /// never shipped checksums shouldn't become uninstallable the day this
104  /// lands.
105  pub(crate) fn verify_checksum(
106    &self,
107    release: &Release,
108    asset: &super::ReleaseAsset,
109    file: &std::path::Path,
110  ) -> Result<(), String> {
111    let Some(published) = release.checksum_for(asset) else {
112      if self.require_checksum {
113        return Err(format!(
114          "this release publishes no SHA-256 for {} — refusing to install it",
115          asset.name
116        ));
117      }
118      return Ok(());
119    };
120    let body = super::fetch::bytes(&published.url, &self.user_agent)
121      .map_err(|e| format!("could not fetch the published checksum: {e}"))?;
122    let body = String::from_utf8_lossy(&body);
123    let expected = super::checksum::find(&body, &asset.name).ok_or_else(|| {
124      format!(
125        "{} does not record a SHA-256 for {}",
126        published.name, asset.name
127      )
128    })?;
129    let actual = super::checksum::of_file(file)?;
130    if !super::checksum::matches(&expected, &actual) {
131      return Err(format!(
132        "{} does not match its published SHA-256 — refusing to install it",
133        asset.name
134      ));
135    }
136    Ok(())
137  }
138
139  /// Override the `User-Agent` sent with every request.
140  pub fn user_agent(mut self, user_agent: impl Into<String>) -> Self {
141    self.user_agent = user_agent.into();
142    self
143  }
144
145  /// Override the filesystem-safe name used for staging paths.
146  pub fn slug(mut self, slug: impl Into<String>) -> Self {
147    self.slug = slug.into();
148    self
149  }
150
151  /// The app's display name.
152  pub fn app(&self) -> &str {
153    &self.app
154  }
155
156  /// The running version.
157  pub fn version(&self) -> &str {
158    &self.version
159  }
160
161  /// Where releases are published.
162  pub fn source(&self) -> &UpdateSource {
163    &self.source
164  }
165
166  /// How this copy was installed — see [`super::detect`].
167  pub fn install_kind(&self) -> InstallKind {
168    super::detect()
169  }
170
171  /// Fetch the latest release and classify it. **Blocking** (it spawns `curl`)
172  /// — run it on gpui's background executor, or let [`super::start`] and
173  /// [`super::check_now`] do that for you.
174  pub fn check(&self) -> Result<UpdateCheck, String> {
175    super::release::check(
176      &self.source,
177      &self.user_agent,
178      &self.version,
179      &self.install_kind(),
180    )
181  }
182
183  /// Download the release and rewrite this install in place, returning how to
184  /// relaunch. **Blocking** — run it off the UI thread. `on_stage` is called
185  /// from the calling thread as the install progresses, including once per
186  /// download sample.
187  pub fn install(
188    &self,
189    release: &Release,
190    kind: &InstallKind,
191    on_stage: &dyn Fn(UpdateStage),
192  ) -> Result<Relaunch, String> {
193    match kind {
194      InstallKind::MacApp(app) => super::mac::install(self, release, app, on_stage),
195      InstallKind::AppImage(path) => super::appimage::install(self, release, path, on_stage),
196      InstallKind::Unknown => Err("this install can't be updated in place".to_string()),
197    }
198  }
199
200  /// Whether this release can be installed in place — the question the prompt's
201  /// action button asks before it promises anything.
202  ///
203  /// All three halves matter. The install has to be one we can rewrite; the
204  /// release has to have published the asset to do it with (a release still
205  /// uploading its artifacts hasn't); and a macOS install needs a
206  /// [`codesign_requirement`](Self::codesign_requirement) to verify the payload
207  /// against. Any of them missing and the honest button is "Open Download".
208  pub fn can_install(&self, release: &Release, kind: &InstallKind) -> bool {
209    if !kind.is_in_place() || release.asset_for(kind).is_none() {
210      return false;
211    }
212    !matches!(kind, InstallKind::MacApp(_)) || self.requirement.is_some()
213  }
214}
215
216/// The app-level updater: an [`UpdateConfig`] plus the parts only the UI side
217/// needs — the poll cadence, the update window's title, and hooks for posting a
218/// notification and for saving state before the app restarts.
219///
220/// ```ignore
221/// let updater = Updater::github("Acme", env!("CARGO_PKG_VERSION"), "acme/acme")
222///     .codesign_requirement("anchor apple generic and certificate leaf[subject.OU] = XJDC46F35X")
223///     .before_restart(|cx| save_session(cx));
224/// guise::update::start(updater, cx);
225/// ```
226#[derive(Clone)]
227pub struct Updater {
228  config: UpdateConfig,
229  poll: Duration,
230  title: SharedString,
231  notify: Option<NotifyHook>,
232  before_restart: Option<RestartHook>,
233}
234
235/// The app's notification hook, called with `(title, body)`.
236type NotifyHook = Rc<dyn Fn(&str, &str)>;
237
238/// The app's hook for the moment before the restart.
239type RestartHook = Rc<dyn Fn(&mut App)>;
240
241impl Updater {
242  /// An updater for `app` at `version`, checking `source`.
243  pub fn new(app: impl Into<String>, version: impl Into<String>, source: UpdateSource) -> Self {
244    Updater::from_config(UpdateConfig::new(app, version, source))
245  }
246
247  /// An updater reading a GitHub repo's `releases/latest`, given `owner/repo`.
248  pub fn github(
249    app: impl Into<String>,
250    version: impl Into<String>,
251    repo: impl Into<String>,
252  ) -> Self {
253    Updater::new(app, version, UpdateSource::github(repo))
254  }
255
256  /// Wrap an existing [`UpdateConfig`].
257  pub fn from_config(config: UpdateConfig) -> Self {
258    Updater {
259      config,
260      poll: POLL,
261      title: "Software Update".into(),
262      notify: None,
263      before_restart: None,
264    }
265  }
266
267  /// See [`UpdateConfig::require_checksum`] — recommended for Linux installs,
268  /// which have no signature to fall back on.
269  pub fn require_checksum(mut self, require: bool) -> Self {
270    self.config = self.config.require_checksum(require);
271    self
272  }
273
274  /// See [`UpdateConfig::codesign_requirement`] — required for macOS installs.
275  pub fn codesign_requirement(mut self, requirement: impl Into<String>) -> Self {
276    self.config = self.config.codesign_requirement(requirement);
277    self
278  }
279
280  /// Override the `User-Agent` sent with every request.
281  pub fn user_agent(mut self, user_agent: impl Into<String>) -> Self {
282    self.config = self.config.user_agent(user_agent);
283    self
284  }
285
286  /// Override the filesystem-safe name used for staging paths.
287  pub fn slug(mut self, slug: impl Into<String>) -> Self {
288    self.config = self.config.slug(slug);
289    self
290  }
291
292  /// How often [`super::start`] re-checks while the app runs (default one hour).
293  pub fn poll_every(mut self, every: Duration) -> Self {
294    self.poll = every;
295    self
296  }
297
298  /// Title for the windows [`super::check_now`] opens (default
299  /// "Software Update", the platform convention).
300  pub fn window_title(mut self, title: impl Into<SharedString>) -> Self {
301    self.title = title.into();
302    self
303  }
304
305  /// Called with `(title, body)` when the install starts, finishes without a
306  /// window to restart into, or fails. guise never posts an OS notification
307  /// itself — that needs an app's own bundle identity and permission state.
308  pub fn on_notify(mut self, notify: impl Fn(&str, &str) + 'static) -> Self {
309    self.notify = Some(Rc::new(notify));
310    self
311  }
312
313  /// Called immediately before the app restarts into the new version — the
314  /// place to persist a session, since the restart never goes through the
315  /// normal quit path where an app would usually save.
316  pub fn before_restart(mut self, hook: impl Fn(&mut App) + 'static) -> Self {
317    self.before_restart = Some(Rc::new(hook));
318    self
319  }
320
321  /// The `Send` half, for the background check and install.
322  pub fn config(&self) -> &UpdateConfig {
323    &self.config
324  }
325
326  /// The app's display name.
327  pub fn app(&self) -> &str {
328    self.config.app()
329  }
330
331  /// The running version.
332  pub fn version(&self) -> &str {
333    self.config.version()
334  }
335
336  /// The re-check cadence.
337  pub fn poll(&self) -> Duration {
338    self.poll
339  }
340
341  /// The update window's title.
342  pub fn title(&self) -> &SharedString {
343    &self.title
344  }
345
346  /// Post a notification through the app's hook, if it installed one.
347  pub(crate) fn notify(&self, title: &str, body: &str) {
348    if let Some(notify) = &self.notify {
349      notify(title, body);
350    }
351  }
352
353  /// Run the pre-restart hook, if the app installed one.
354  pub(crate) fn run_before_restart(&self, cx: &mut App) {
355    if let Some(hook) = &self.before_restart {
356      hook(cx);
357    }
358  }
359}
360
361/// A filesystem-safe name derived from the app's display name: lowercase, with
362/// every run of anything else collapsed to a single `-`. Staging paths are built
363/// from this, so a name like "My App 2.0" must not arrive with spaces in it.
364fn slug(app: &str) -> String {
365  let mut out = String::with_capacity(app.len());
366  for ch in app.chars() {
367    if ch.is_ascii_alphanumeric() {
368      out.push(ch.to_ascii_lowercase());
369    } else if !out.ends_with('-') {
370      out.push('-');
371    }
372  }
373  let trimmed = out.trim_matches('-');
374  if trimmed.is_empty() {
375    "app".to_string()
376  } else {
377    trimmed.to_string()
378  }
379}
380
381#[cfg(test)]
382mod tests {
383  use super::*;
384  use crate::update::ReleaseAsset;
385  use std::path::PathBuf;
386
387  fn release(names: &[&str]) -> Release {
388    Release {
389      version: "9.9.9".to_string(),
390      url: "https://acme.dev/releases/9.9.9".to_string(),
391      assets: names
392        .iter()
393        .map(|name| ReleaseAsset {
394          name: name.to_string(),
395          url: format!("https://d/{name}"),
396          size: 1,
397        })
398        .collect(),
399    }
400  }
401
402  fn config() -> UpdateConfig {
403    UpdateConfig::new("Acme", "1.0.0", UpdateSource::github("acme/acme"))
404  }
405
406  #[test]
407  fn slugs_are_path_safe() {
408    assert_eq!(slug("Acme"), "acme");
409    assert_eq!(slug("My App 2.0"), "my-app-2-0");
410    assert_eq!(slug("  Spaced  "), "spaced");
411    assert_eq!(slug("../../etc"), "etc");
412    assert_eq!(slug("🚀"), "app");
413    assert_eq!(slug(""), "app");
414  }
415
416  #[test]
417  fn the_user_agent_defaults_to_the_slug() {
418    assert_eq!(config().user_agent, "acme-updater");
419    assert_eq!(
420      UpdateConfig::new("My App", "1", UpdateSource::github("a/b")).user_agent,
421      "my-app-updater"
422    );
423  }
424
425  /// A macOS install with no requirement configured has nothing to verify the
426  /// payload against, so it must not be offered as an in-place install.
427  #[test]
428  fn macos_needs_a_codesign_requirement_to_be_installable() {
429    let mac = InstallKind::MacApp(PathBuf::from("/Applications/Acme.app"));
430    let dmg = release(&["Acme.dmg"]);
431    assert!(!config().can_install(&dmg, &mac));
432    assert!(config()
433      .codesign_requirement("anchor apple generic")
434      .can_install(&dmg, &mac));
435  }
436
437  /// The AppImage path verifies by architecture match and size, not codesign,
438  /// so it needs no requirement.
439  #[test]
440  fn appimage_is_installable_without_a_requirement() {
441    let image = InstallKind::AppImage(PathBuf::from("/opt/Acme.AppImage"));
442    let asset = format!("Acme-9.9.9-{}.AppImage", std::env::consts::ARCH);
443    assert!(config().can_install(&release(&[&asset]), &image));
444  }
445
446  #[test]
447  fn a_release_without_our_asset_is_not_installable() {
448    let mac = InstallKind::MacApp(PathBuf::from("/Applications/Acme.app"));
449    let config = config().codesign_requirement("anchor apple generic");
450    assert!(!config.can_install(&release(&["Acme.AppImage"]), &mac));
451    assert!(!config.can_install(&release(&[]), &mac));
452  }
453
454  #[test]
455  fn unknown_installs_are_never_installable_in_place() {
456    let config = config().codesign_requirement("anchor apple generic");
457    let every_asset = release(&["Acme.dmg", "Acme.AppImage"]);
458    assert!(!config.can_install(&every_asset, &InstallKind::Unknown));
459    assert!(config
460      .install(&every_asset, &InstallKind::Unknown, &|_| {})
461      .is_err());
462  }
463
464  /// The Linux install path has no signature to fall back on, so a release
465  /// that publishes no digest must be refusable outright.
466  #[test]
467  fn require_checksum_refuses_a_release_with_no_digest() {
468    let release = crate::update::Release {
469      version: "9.9.9".to_string(),
470      url: String::new(),
471      assets: vec![crate::update::ReleaseAsset {
472        name: "Acme.AppImage".to_string(),
473        url: "https://d/a".to_string(),
474        size: 1,
475      }],
476    };
477    let asset = release.assets[0].clone();
478    let path = std::path::Path::new("/nonexistent/Acme.AppImage");
479
480    // Off by default: a project that never shipped checksums keeps working.
481    let lenient = config();
482    assert!(lenient.verify_checksum(&release, &asset, path).is_ok());
483
484    let strict = config().require_checksum(true);
485    assert!(strict.requires_checksum());
486    let err = strict
487      .verify_checksum(&release, &asset, path)
488      .expect_err("a missing digest must block the install");
489    assert!(err.contains("publishes no SHA-256"), "{err}");
490  }
491}
guise/update/updater.rs

guise/update/
updater.rs
