guise/update/

prompt.rs

//! `UpdatePrompt` — the "an update is available" panel (gpui entity).
//!
//! A state machine with exactly one action in flight. Once an install starts it
//! reports every stage it moves through, and it stays put until it either
//! restarts the app or fails with the reason on screen — never a button whose
//! only feedback is a notification you might not see.
//!
//! ```ignore
//! let prompt = cx.new(|cx| UpdatePrompt::new(updater, release, cx));
//! cx.subscribe(&prompt, |_this, _prompt, event: &UpdatePromptEvent, _cx| {
//!     if let UpdatePromptEvent::Failed(why) = event { /* log it */ }
//! })
//! .detach();
//! ```
//!
//! [`super::open`] wraps one in its own window; rendered directly it is an
//! ordinary panel, so it can live in a modal or a settings pane instead.

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;

use gpui::prelude::*;
use gpui::{
  div, px, App, Context, EventEmitter, FocusHandle, Focusable, FontWeight, IntoElement,
  KeyDownEvent, MouseButton, SharedString, Window, WindowControlArea,
};

use super::{InstallKind, Relaunch, Release, UpdateStage, Updater};
use crate::devtools::Probed;
use crate::theme::{theme, ColorName, Size};
use crate::{Alert, Button, Progress, Variant};

/// Height of the strip that drags the window, and the padding that clears a
/// transparent titlebar. A platform metric, not a themed one.
const TITLEBAR: f32 = 34.0;

/// How often the foreground task drains installer progress into the view.
const PROGRESS_TICK: Duration = Duration::from_millis(80);

/// Emitted as the prompt works.
#[derive(Debug, Clone)]
pub enum UpdatePromptEvent {
  /// The user accepted and the install began.
  Started,
  /// The installer moved to a new stage.
  Stage(UpdateStage),
  /// The new version is on disk. Carries how to relaunch into it; the prompt
  /// restarts the app itself unless [`UpdatePrompt::auto_restart`] is off.
  Installed(Relaunch),
  /// The install failed, with the reason already on screen and the action
  /// button offering to retry.
  Failed(String),
  /// The user is done with the prompt — "Later", Escape, or the download page
  /// having opened for an install that can't be rewritten. Whoever owns the
  /// window closes it; the prompt never closes a window it doesn't own.
  Dismissed,
}

/// Where the prompt is in its one-shot lifecycle. Only `Idle` and `Failed`
/// accept the action, which is what keeps the action button from starting a
/// second install over the first.
enum Phase {
  Idle,
  Working(UpdateStage),
  Failed(String),
}

/// Set while an install is in flight, anywhere in the process.
///
/// `Phase::Working` only serializes installs within a single prompt, and there
/// can be more than one: a manual "Check for Updates…" opens a prompt
/// unconditionally. Two installs would race two downloads over the same staging
/// path, two `hdiutil attach` calls on the same mountpoint, and two rsyncs into
/// the live bundle — each one's unmount tearing down the other's mount mid-copy.
#[derive(Default)]
struct Installing(bool);
impl gpui::Global for Installing {}

/// Whether an update is installing right now. Worth checking before offering a
/// "Check for Updates…" menu item that would open a second prompt.
pub fn is_installing(cx: &App) -> bool {
  cx.try_global::<Installing>().is_some_and(|i| i.0)
}

fn set_installing(active: bool, cx: &mut App) {
  cx.set_global(Installing(active));
}

/// How far along the bar each stage sits, as the percentage [`Progress`] wants
/// (0..=100, *not* a 0..1 fraction). The download dominates the wall clock, so it
/// owns most of the bar and the later stages are checkpoints past it.
fn percent(stage: &UpdateStage) -> f32 {
  match stage {
    UpdateStage::Downloading { done, total } if *total > 0 => {
      85.0 * (*done as f32 / *total as f32).clamp(0.0, 1.0)
    }
    // Total unknown: hold at the start rather than pretending to advance.
    UpdateStage::Downloading { .. } => 0.0,
    UpdateStage::Preparing => 88.0,
    UpdateStage::Installing => 94.0,
    UpdateStage::Verifying => 98.0,
  }
}

/// Whether an install is in flight in this prompt, and so whether the action
/// button and Escape are inert. Free of the view so it can be tested directly.
fn busy(phase: &Phase) -> bool {
  matches!(phase, Phase::Working(_))
}

/// The action button's label for a given phase. `installable` is false when this
/// install can't be rewritten, or when the release hasn't published the asset to
/// do it with — either way the button must not promise an install.
fn action_label(phase: &Phase, installable: bool) -> &'static str {
  match phase {
    Phase::Working(_) => "Updating…",
    Phase::Failed(_) => "Try Again",
    Phase::Idle if installable => "Update & Restart",
    Phase::Idle => "Open Download",
  }
}

/// `Downloading` renders its byte counts; the rest are just their label.
fn detail(stage: &UpdateStage) -> String {
  match stage {
    UpdateStage::Downloading { done, total } if *total > 0 => {
      format!("{} of {}", megabytes(*done), megabytes(*total))
    }
    _ => String::new(),
  }
}

/// Decimal megabytes, matching what a release page and the OS file browser report
/// for the same file. Dividing by 1 MiB instead would render an 87.4 MB download
/// as "83.3 MB" and read as a stalled or wrong transfer.
fn megabytes(bytes: u64) -> String {
  format!("{:.1} MB", bytes as f64 / 1_000_000.0)
}

/// The update prompt: what is available, what will happen, and one action.
pub struct UpdatePrompt {
  updater: Updater,
  release: Release,
  kind: InstallKind,
  /// Whether this release can be rewritten into this install — see
  /// [`super::UpdateConfig::can_install`]. Resolved once at construction so the
  /// button's promise can't drift from what the installer will do.
  installable: bool,
  phase: Phase,
  auto_restart: bool,
  window_root: bool,
  focus: FocusHandle,
}

impl UpdatePrompt {
  /// A prompt offering `release`.
  pub fn new(updater: Updater, release: Release, cx: &mut Context<Self>) -> Self {
    let kind = updater.config().install_kind();
    let installable = updater.config().can_install(&release, &kind);
    UpdatePrompt {
      updater,
      release,
      kind,
      installable,
      phase: Phase::Idle,
      auto_restart: true,
      window_root: false,
      focus: cx.focus_handle(),
    }
  }

  /// Whether a successful install restarts the app itself (default `true`).
  /// Turn it off to handle [`UpdatePromptEvent::Installed`] yourself — the
  /// prompt then stays in its installing state, since only the host knows what
  /// comes next.
  pub fn auto_restart(mut self, auto_restart: bool) -> Self {
    self.auto_restart = auto_restart;
    self
  }

  /// Whether this prompt is the root view of its own update window: draws the
  /// titlebar drag strip and pads for a transparent titlebar. [`super::open`]
  /// sets it; leave it off when embedding the prompt in a window of your own.
  pub fn window_root(mut self, window_root: bool) -> Self {
    self.window_root = window_root;
    self
  }

  /// The release being offered.
  pub fn release(&self) -> &Release {
    &self.release
  }

  /// Whether an install is in flight in this prompt.
  pub fn busy(&self) -> bool {
    busy(&self.phase)
  }

  /// The stage the installer is on, if one is running.
  pub fn stage(&self) -> Option<&UpdateStage> {
    match &self.phase {
      Phase::Working(stage) => Some(stage),
      _ => None,
    }
  }

  /// Why the last attempt failed, if it did.
  pub fn error(&self) -> Option<&str> {
    match &self.phase {
      Phase::Failed(reason) => Some(reason),
      _ => None,
    }
  }

  /// Take the action the button offers: install in place and restart, or — when
  /// this install can't be rewritten — open the release page and dismiss.
  pub fn accept(&mut self, cx: &mut Context<Self>) {
    // `busy` covers this prompt; the global covers a second prompt whose
    // install is already running.
    if self.busy() || is_installing(cx) {
      return;
    }
    if self.installable {
      self.phase = Phase::Working(UpdateStage::Downloading { done: 0, total: 0 });
      set_installing(true, cx);
      cx.emit(UpdatePromptEvent::Started);
      cx.notify();
      self.install(cx);
    } else {
      cx.open_url(&self.release.url);
      cx.emit(UpdatePromptEvent::Dismissed);
    }
  }

  /// Give up on the prompt (the "Later" button and Escape). Inert while an
  /// install is running, so the progress can't be dismissed out from under
  /// itself.
  pub fn dismiss(&mut self, cx: &mut Context<Self>) {
    if self.busy() {
      return;
    }
    cx.emit(UpdatePromptEvent::Dismissed);
  }

  /// Show a stage without running the installer — for a host driving its own
  /// install, and for previewing the states.
  pub fn set_stage(&mut self, stage: UpdateStage, cx: &mut Context<Self>) {
    self.phase = Phase::Working(stage);
    cx.notify();
  }

  /// Show a failure without running the installer. The action button becomes
  /// "Try Again".
  pub fn set_failed(&mut self, reason: impl Into<String>, cx: &mut Context<Self>) {
    self.phase = Phase::Failed(reason.into());
    cx.notify();
  }

  /// Return to the offer, whatever state the prompt was in.
  pub fn reset(&mut self, cx: &mut Context<Self>) {
    self.phase = Phase::Idle;
    cx.notify();
  }

  /// Download and install off the UI thread, then relaunch into it.
  ///
  /// The installer reports its stages from a background thread, and gpui's
  /// background executor only carries `Send` work — so progress crosses back
  /// through a shared cell that a foreground task drains into the view.
  /// Without that, the window shows nothing at all until the whole install
  /// resolves.
  fn install(&mut self, cx: &mut Context<Self>) {
    self.updater.notify(
      self.updater.app(),
      &format!(
        "Downloading {} {}…",
        self.updater.app(),
        self.release.version
      ),
    );
    let updater = self.updater.clone();
    let config = self.updater.config().clone();
    let release = self.release.clone();
    let kind = self.kind.clone();
    let executor = cx.background_executor().clone();
    let latest: Arc<Mutex<Option<UpdateStage>>> = Arc::new(Mutex::new(None));
    // The installer finishing is its own signal. Watching `busy()` alone
    // would leave this loop ticking forever on the one path that finishes
    // without changing the phase: a success under `auto_restart(false)`,
    // where the host — not the prompt — decides what happens next.
    let finished = Arc::new(AtomicBool::new(false));

    let drained = latest.clone();
    let done = finished.clone();
    let ticker = executor.clone();
    cx.spawn(async move |this, cx| loop {
      let stage = drained.lock().ok().and_then(|mut slot| slot.take());
      // Stop as soon as the prompt is no longer installing (or is gone):
      // the install task owns the terminal states.
      let running = this.update(cx, |view, cx| {
        let running = view.busy();
        if running {
          if let Some(stage) = stage {
            view.phase = Phase::Working(stage.clone());
            cx.emit(UpdatePromptEvent::Stage(stage));
            cx.notify();
          }
        }
        running
      });
      // Checked after the drain, so the last stage reported before the
      // installer returned still reaches the view.
      if !matches!(running, Ok(true)) || done.load(Ordering::Relaxed) {
        break;
      }
      ticker.timer(PROGRESS_TICK).await;
    })
    .detach();

    let reported = latest.clone();
    cx.spawn(async move |this, cx| {
      let staged = executor
        .spawn(async move {
          config.install(&release, &kind, &|stage| {
            if let Ok(mut slot) = reported.lock() {
              *slot = Some(stage);
            }
          })
        })
        .await;
      finished.store(true, Ordering::Relaxed);
      match staged {
        Ok(relaunch) => {
          // A prompt in its own window disables its buttons while
          // installing, but the titlebar's close control stays live.
          // Closing it withdraws consent to be restarted, so leave the
          // new version on disk for the next launch instead. A dead
          // entity is how that close reaches us here.
          let dismissed = this.update(cx, |_, _| ()).is_err();
          let _ = cx.update(|cx| set_installing(false, cx));
          if dismissed {
            updater.notify(
              "Update installed",
              &format!(
                "{} will finish updating the next time you open it.",
                updater.app()
              ),
            );
            return;
          }
          let restart = this
            .update(cx, |view, cx| {
              cx.emit(UpdatePromptEvent::Installed(relaunch.clone()));
              view.auto_restart
            })
            .unwrap_or(false);
          if restart {
            let _ = cx.update(|cx| {
              updater.run_before_restart(cx);
              // `Relaunch::Current` restarts with no explicit path
              // on purpose: gpui reopens the running bundle via
              // NSBundle. Handing `open` an explicit path right
              // after an in-place install is what relaunches the
              // bare Mach-O in a terminal.
              if let Relaunch::Binary(path) = relaunch {
                cx.set_restart_path(path);
              }
              cx.restart();
            });
          }
        }
        Err(e) => {
          let _ = cx.update(|cx| set_installing(false, cx));
          updater.notify("Update failed", &e);
          // Show the reason in the prompt and let the user retry it. A
          // failure that lands only in a notification leaves the prompt
          // looking like the click did nothing.
          let _ = this.update(cx, |view, cx| {
            view.phase = Phase::Failed(e.clone());
            cx.emit(UpdatePromptEvent::Failed(e));
            cx.notify();
          });
        }
      }
    })
    .detach();
  }

  fn key_down(&mut self, event: &KeyDownEvent, _window: &mut Window, cx: &mut Context<Self>) {
    if event.keystroke.key == "escape" {
      self.dismiss(cx);
    }
  }

  /// The status area: a live progress bar while installing, the reason when it
  /// failed, and what the button will do when idle.
  fn status(&self, dim: gpui::Hsla, small: f32, gap: f32) -> gpui::AnyElement {
    match &self.phase {
      Phase::Working(stage) => div()
        .flex()
        .flex_col()
        .gap(px(gap))
        .child(Progress::new(percent(stage)).size(Size::Sm))
        .child(
          div()
            .flex()
            .justify_between()
            .text_size(px(small))
            .text_color(dim)
            .child(SharedString::from(stage.label()))
            .child(SharedString::from(detail(stage))),
        )
        .into_any_element(),
      Phase::Failed(reason) => Alert::new(SharedString::from(reason.clone()))
        .title("Update failed")
        .variant(Variant::Light)
        .color(ColorName::Red)
        .into_any_element(),
      Phase::Idle => div()
        .text_size(px(small))
        .child(SharedString::from(if self.installable {
          format!(
            "{} will download the update, install it, and restart.",
            self.updater.app()
          )
        } else {
          "Open the download page to update.".to_string()
        }))
        .into_any_element(),
    }
  }
}

impl Focusable for UpdatePrompt {
  fn focus_handle(&self, _cx: &App) -> FocusHandle {
    self.focus.clone()
  }
}

impl EventEmitter<UpdatePromptEvent> for UpdatePrompt {}

impl Render for UpdatePrompt {
  fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
    let t = theme(cx);
    let bg = t.body().hsla();
    let text = t.text().hsla();
    let dim = t.dimmed().hsla();
    let pad = t.spacing(Size::Lg);
    let gap = t.spacing(Size::Xs);
    let headline = t.font_size(Size::Md);
    let body = t.font_size(Size::Sm);
    let small = t.font_size(Size::Xs);
    // Reserve the status area so the panel doesn't jump between states; the
    // progress bar over its byte counts is the tallest arrangement.
    let status = t.spacing(Size::Xl) + small * 2.0;
    let busy = self.busy();
    let label = action_label(&self.phase, self.installable);
    let title = format!(
      "{} {} is available",
      self.updater.app(),
      self.release.version
    );
    let have = format!("You have {}.", self.updater.version());
    let notes = self.release.url.clone();

    div()
      .size_full()
      .flex()
      .flex_col()
      .track_focus(&self.focus)
      .on_key_down(cx.listener(Self::key_down))
      .bg(bg)
      .text_color(text)
      .pt(px(if self.window_root { TITLEBAR } else { pad }))
      .px(px(pad))
      .pb(px(pad))
      .gap(px(gap))
      .when(self.window_root, |this| this.child(drag_strip()))
      .child(
        div()
          .text_size(px(headline))
          .font_weight(FontWeight::BOLD)
          .child(SharedString::from(title)),
      )
      .child(
        div()
          .text_size(px(small))
          .text_color(dim)
          .child(SharedString::from(have)),
      )
      .child(
        div()
          .min_h(px(status))
          .text_size(px(body))
          .child(self.status(dim, small, gap)),
      )
      .child(div().flex_1())
      .child(
        div()
          .flex()
          .items_center()
          .justify_end()
          .gap(px(gap))
          .child(
            Button::new("guise-update-notes", "Release Notes")
              .variant(Variant::Subtle)
              .disabled(busy || notes.is_empty())
              .on_click(move |_, _, cx| cx.open_url(&notes)),
          )
          .child(
            Button::new("guise-update-later", "Later")
              .variant(Variant::Default)
              .disabled(busy)
              .on_click(cx.listener(|this, _, _, cx| this.dismiss(cx))),
          )
          .child(
            Button::new("guise-update-go", label)
              .variant(Variant::Filled)
              .disabled(busy)
              .on_click(cx.listener(|this, _, _, cx| this.accept(cx))),
          ),
      )
      .probe("UpdatePrompt")
  }
}

/// The strip along the top of an update window that drags it, kept clear of the
/// macOS traffic lights.
fn drag_strip() -> impl IntoElement {
  let lead = if cfg!(target_os = "macos") { 70.0 } else { 0.0 };
  div()
    .absolute()
    .top_0()
    .left(px(lead))
    .right_0()
    .h(px(TITLEBAR - 6.0))
    .window_control_area(WindowControlArea::Drag)
    .on_mouse_down(MouseButton::Left, |_, window, _| window.start_window_move())
}

#[cfg(test)]
mod tests {
  use super::*;

  /// [`Progress`] takes a percentage, not a 0..1 fraction — feeding it a
  /// fraction renders a bar that never visibly leaves the left edge.
  #[test]
  fn download_progress_is_a_percentage_across_most_of_the_bar() {
    assert_eq!(
      percent(&UpdateStage::Downloading {
        done: 0,
        total: 100
      }),
      0.0
    );
    assert!(
      (percent(&UpdateStage::Downloading {
        done: 50,
        total: 100
      }) - 42.5)
        .abs()
        < 0.01
    );
    assert!(
      (percent(&UpdateStage::Downloading {
        done: 100,
        total: 100
      }) - 85.0)
        .abs()
        < 0.01
    );
  }

  #[test]
  fn every_stage_stays_in_percentage_range() {
    for stage in [
      UpdateStage::Downloading { done: 1, total: 2 },
      UpdateStage::Preparing,
      UpdateStage::Installing,
      UpdateStage::Verifying,
    ] {
      let value = percent(&stage);
      assert!((0.0..=100.0).contains(&value), "{stage:?} -> {value}");
    }
  }

  #[test]
  fn stages_after_the_download_only_move_forward() {
    let done = percent(&UpdateStage::Downloading {
      done: 100,
      total: 100,
    });
    assert!(done < percent(&UpdateStage::Preparing));
    assert!(percent(&UpdateStage::Preparing) < percent(&UpdateStage::Installing));
    assert!(percent(&UpdateStage::Installing) < percent(&UpdateStage::Verifying));
  }

  #[test]
  fn an_unknown_total_holds_the_bar_at_zero() {
    // Better a bar that hasn't moved than one inventing progress it can't know.
    assert_eq!(
      percent(&UpdateStage::Downloading {
        done: 900,
        total: 0
      }),
      0.0
    );
  }

  #[test]
  fn overlong_downloads_cannot_overflow_the_bar() {
    assert!(
      percent(&UpdateStage::Downloading {
        done: 500,
        total: 100
      }) <= 85.0
    );
  }

  #[test]
  fn only_the_download_reports_byte_counts() {
    assert_eq!(
      detail(&UpdateStage::Downloading {
        done: 5_000_000,
        total: 20_000_000
      }),
      "5.0 MB of 20.0 MB"
    );
    assert_eq!(detail(&UpdateStage::Downloading { done: 5, total: 0 }), "");
    assert_eq!(detail(&UpdateStage::Preparing), "");
    assert_eq!(detail(&UpdateStage::Verifying), "");
  }

  #[test]
  fn sizes_are_decimal_mb_to_match_what_release_pages_report() {
    // A real 20,314,688-byte dmg: a release page and the OS file browser both
    // call this 20.3 MB. Dividing by 1 MiB would render "19.4 MB" for the same
    // file and read as a stalled or mismatched download.
    assert_eq!(
      detail(&UpdateStage::Downloading {
        done: 0,
        total: 20_314_688
      }),
      "0.0 MB of 20.3 MB"
    );
  }

  #[test]
  fn only_the_working_phase_is_busy() {
    // What stops the action button from starting a second install over the
    // first: every other phase accepts the click, Working never does. Calls
    // the real predicate — asserting on `Phase` literals instead would pass
    // even with `busy` inverted.
    assert!(busy(&Phase::Working(UpdateStage::Preparing)));
    assert!(!busy(&Phase::Idle));
    assert!(!busy(&Phase::Failed("boom".into())));
  }

  #[test]
  fn the_action_label_tracks_phase_and_installability() {
    assert_eq!(action_label(&Phase::Idle, true), "Update & Restart");
    // No installable asset: the button must not promise an install it can't do.
    assert_eq!(action_label(&Phase::Idle, false), "Open Download");
    assert_eq!(
      action_label(&Phase::Working(UpdateStage::Installing), true),
      "Updating…"
    );
    // A failure has to stay retryable rather than dead-ending the prompt.
    assert_eq!(
      action_label(&Phase::Failed("boom".into()), true),
      "Try Again"
    );
  }
}