//! Remote Git commands (M4.10, owner decision D23): fetch, pull, push, //! clone, cancel, and the list of remotes with add, set-url and remove, //! through the user's git (`lutra-vcs`). //! //! **Credentials stay with git.** HTTPS sign-in is git's credential //! helper's (it may show its own window, such as Git Credential Manager's); //! SSH uses the user's ssh with its agent and keys. Lutra never sees, //! stores or logs a credential, terminal prompts are off, and URLs in //! values, errors and progress have their userinfo redacted. //! //! **Off the lock.** Every command but `git.cancel` returns a pending //! outcome: under the lock it parses its params and takes the setting; a //! `lutra-git-remote` thread detects git, opens the project's repository //! (`git.clone` needs none), runs the call and fills a reply slot. The //! finish, under the lock again, emits `gitChanged` after a change. //! //! **One network call at a time.** fetch, pull, push and clone share one //! slot; a second is refused while one runs. Its progress (git's //! `--progress` lines) is kept by the thread and sent as `gitProgress` //! from [`pump`] when it changed, so at most once per pump. `git.cancel` //! sets its cancel flag: git and every process it started are killed and //! the call fails with "cancelled". When the call ends, `gitProgress` //! with `active: false` follows. use std::path::PathBuf; use std::sync::mpsc; use std::sync::{Arc, Mutex, PoisonError}; use std::time::Duration; use lutra_vcs::{Cancel, Git, Network, ProgressSink, PullMode, Remote, Repo, VcsError}; use serde::{Deserialize, Serialize}; use serde_json::{Value, json}; use super::git::{EXECUTABLE_SETTING, GitChanged, RepoSummary}; use super::params::parse; use crate::workspace::path_string; use crate::{Command, CommandSpec, EngineError, Event, Outcome, Pending, Registry, State}; /// The setting choosing how `git.pull` joins the fetched commits. pub const PULL_MODE_SETTING: &str = "git.pull.mode"; /// Longest wait for a call: detection and opening (30 s each) and the /// network timeout, plus slack. The runner kills git first. const WAIT: Duration = Duration::from_secs(30 * 60 + 120); /// Registers the remote `git.*` commands. /// /// # Errors /// [`EngineError::Internal`] if an id is taken. pub fn register(registry: &mut Registry) -> Result<(), EngineError> { registry.register(Box::new(Fetch))?; registry.register(Box::new(Pull))?; registry.register(Box::new(Push))?; registry.register(Box::new(CloneRepo))?; registry.register(Box::new(CancelCommand))?; registry.register(Box::new(Remotes))?; registry.register(Box::new(RemoteAdd))?; registry.register(Box::new(RemoteSetUrl))?; registry.register(Box::new(RemoteRemove))?; Ok(()) } /// Payload of [`Event::GitProgress`]: the running network call and its /// latest progress line. #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)] #[serde(rename_all = "camelCase")] pub struct GitProgress { /// A network call runs. pub active: bool, /// Which: `fetch`, `pull`, `push` or `clone`. #[serde(skip_serializing_if = "Option::is_none")] pub operation: Option, /// The phase of the latest line, e.g. `Receiving objects`, or the /// whole line when it has no percentage. #[serde(skip_serializing_if = "Option::is_none")] pub phase: Option, /// The phase's percentage, when git printed one. #[serde(skip_serializing_if = "Option::is_none")] pub percent: Option, } /// The running network call. #[derive(Debug)] struct Active { /// Which command runs. operation: &'static str, /// Stops it. cancel: Cancel, /// Its latest progress line, written by the reading thread. latest: Arc>>, } /// State of the remote commands. #[derive(Debug, Default)] pub struct GitRemote { /// The running network call. active: Option, /// The `gitProgress` sent last, so an unchanged one is not sent again. sent: Option, } /// What one command does on its thread. enum Op { /// `git.fetch`. Fetch(Option), /// `git.pull`. Pull(PullMode), /// `git.push`. Push(Option), /// `git.clone`. Clone { /// The URL or path. url: String, /// The new work tree. dir: PathBuf, }, /// `git.remotes`. Remotes, /// `git.remoteAdd`. Add(String, String), /// `git.remoteSetUrl`. SetUrl(String, String), /// `git.remoteRemove`. Remove(String), } impl Op { /// The network operation's name; `None` for the local ones. fn network(&self) -> Option<&'static str> { match self { Self::Fetch(_) => Some("fetch"), Self::Pull(_) => Some("pull"), Self::Push(_) => Some("push"), Self::Clone { .. } => Some("clone"), _ => None, } } } /// What a thread hands back to the finish. struct Reply { /// The command's value or error. value: Result, /// After a successful change in the open project: its summary for /// `gitChanged`. changed: Option, } /// Turns a backend error into the engine's: the caller's mistakes are /// `invalid_params`, everything else `failed`. fn engine_error(command: &str, error: VcsError) -> EngineError { if error.is_invalid_input() { EngineError::invalid_params(command, error.to_string()) } else { EngineError::Failed(error.to_string()) } } /// Runs `op` on a new thread and returns the pending outcome. /// /// # Errors /// [`EngineError::Disabled`] without a project (except for clone), /// [`EngineError::Failed`] while another network call runs. fn start(state: &mut State, command: &'static str, op: Op) -> Result { let project = state .project .as_ref() .map(|w| w.project.root().to_path_buf()); if project.is_none() && !matches!(op, Op::Clone { .. }) { return Err(EngineError::Disabled(command.to_string())); } let setting = state .settings .get(EXECUTABLE_SETTING) .and_then(|v| v.as_str().map(str::to_string)) .unwrap_or_default(); let mut net = Network::default(); let mut slot_taken = false; if let Some(operation) = op.network() { if let Some(active) = &state.git_remote.active { return Err(EngineError::Failed(format!( "another Git operation is running ({}); wait for it or cancel it", active.operation ))); } let cancel = Cancel::new(); let latest: Arc>> = Arc::new(Mutex::new(None)); let writer = Arc::clone(&latest); net = Network { progress: Some(ProgressSink(Arc::new(move |line: &str| { *writer.lock().unwrap_or_else(PoisonError::into_inner) = Some(line.to_string()); }))), cancel: Some(cancel.clone()), }; state.git_remote.active = Some(Active { operation, cancel, latest, }); state.git_remote.sent = None; slot_taken = true; } let slot: Arc>> = Arc::new(Mutex::new(None)); let (tx, rx) = mpsc::channel(); let filled = Arc::clone(&slot); let thread_project = project.clone(); let spawned = std::thread::Builder::new() .name("lutra-git-remote".into()) .spawn(move || { let reply = work(command, &setting, thread_project, &op, &net); *filled.lock().unwrap_or_else(PoisonError::into_inner) = Some(reply); let _ = tx.send(Ok(Value::Null)); }); if let Err(e) = spawned { if slot_taken { state.git_remote.active = None; } return Err(EngineError::Failed(format!("cannot start git: {e}"))); } Ok(Outcome::pending(Pending::new(rx, WAIT, move |state, _| { if slot_taken { finish_network(state); } let reply = slot .lock() .unwrap_or_else(PoisonError::into_inner) .take() .ok_or_else(|| EngineError::Failed("git did not answer in time".into()))?; let current = state .project .as_ref() .map(|w| w.project.root().to_path_buf()); if let Some(summary) = reply.changed && current.is_some() && current == project { state.emit(Event::GitChanged(GitChanged { available: true, repo: Some(summary), files_changed: true, })); } reply.value }))) } /// Frees the network slot and sends `gitProgress {active: false}`. fn finish_network(state: &mut State) { let Some(active) = state.git_remote.active.take() else { return; }; let done = GitProgress { active: false, operation: Some(active.operation.to_string()), phase: None, percent: None, }; state.git_remote.sent = None; state.emit(Event::GitProgress(done)); } /// The thread's work: detect git, open the repository unless cloning, run /// `op`. fn work( command: &'static str, setting: &str, project: Option, op: &Op, net: &Network, ) -> Reply { let fail = |value: EngineError| Reply { value: Err(value), changed: None, }; let git = match Git::detect(setting) { Ok(git) => git, Err(e) => return fail(EngineError::Failed(e.to_string())), }; if let Op::Clone { url, dir } = op { return Reply { value: git .clone_repo(url, dir, net) .map(|()| json!({"root": path_string(dir)})) .map_err(|e| engine_error(command, e)), changed: None, }; } let Some(project) = project else { return fail(EngineError::Disabled(command.to_string())); }; let repo = match git.open(&project) { Ok(Some(repo)) => repo, Ok(None) => { return fail(EngineError::Failed( "the project is not inside a Git repository".into(), )); } Err(e) => return fail(EngineError::Failed(e.to_string())), }; let value = run_op(&repo, op, net).map_err(|e| engine_error(command, e)); let changed = (value.is_ok() && !matches!(op, Op::Remotes)).then(|| summary(&repo)); Reply { value, changed } } /// The repository summary for `gitChanged`; a failed query gives an empty /// head (the event only asks clients to re-read). fn summary(repo: &Repo) -> RepoSummary { let head = repo.head().unwrap_or_default(); RepoSummary { root: path_string(repo.root()), branch: head.branch, detached: head.detached, head: head.head, upstream: head.upstream, ahead: head.ahead, behind: head.behind, } } /// One remote of `git.remotes`. fn remote_json(remote: &Remote) -> Value { let mut value = json!({"name": remote.name}); if let Some(map) = value.as_object_mut() { if let Some(url) = &remote.fetch_url { map.insert("fetchUrl".into(), json!(url)); } if let Some(url) = &remote.push_url { map.insert("pushUrl".into(), json!(url)); } } value } /// Runs one operation against the repository. fn run_op(repo: &Repo, op: &Op, net: &Network) -> Result { match op { Op::Fetch(remote) => repo.fetch(remote.as_deref(), net).map(|()| json!({})), Op::Pull(mode) => repo.pull(*mode, net).map(|()| json!({})), Op::Push(remote) => { let pushed = repo.push(remote.as_deref(), net)?; Ok(json!({ "remote": pushed.remote, "branch": pushed.branch, "upstreamSet": pushed.upstream_set, })) } Op::Remotes => { let remotes: Vec = repo.remotes()?.iter().map(remote_json).collect(); Ok(json!({"remotes": remotes})) } Op::Add(name, url) => repo.remote_add(name, url).map(|()| json!({})), Op::SetUrl(name, url) => repo.remote_set_url(name, url).map(|()| json!({})), Op::Remove(name) => repo.remote_remove(name).map(|()| json!({})), Op::Clone { .. } => Err(VcsError::Git("clone needs no repository".into())), } } /// Sends `gitProgress` when the running call's latest line changed. /// Called from [`crate::Engine::pump_vfs`]. pub fn pump(state: &mut State) { let Some(active) = &state.git_remote.active else { return; }; let line = active .latest .lock() .unwrap_or_else(PoisonError::into_inner) .clone(); let (phase, percent) = match line { Some(line) => { let (phase, percent) = lutra_vcs::parse_progress(&line); (Some(phase), percent) } None => (None, None), }; let now = GitProgress { active: true, operation: Some(active.operation.to_string()), phase, percent, }; if state.git_remote.sent.as_ref() != Some(&now) { state.git_remote.sent = Some(now.clone()); state.emit(Event::GitProgress(now)); } } /// Params of `git.fetch` and `git.push`. #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] struct RemoteParams { /// A remote's name; absent means all remotes (fetch) or the upstream's /// (push). #[serde(default)] remote: Option, } /// `git.fetch`. struct Fetch; impl Command for Fetch { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.fetch", label: "Git: Fetch", menu_path: None, default_shortcut: None, params: "{ remote?: remote name (all remotes when absent) }; returns {}; progress as gitProgress events, git.cancel stops it; sign-in through git's credential helper or ssh agent only", } } fn enabled(&self, state: &State) -> bool { state.has_project() } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let p: RemoteParams = parse(command, params)?; start(state, command, Op::Fetch(p.remote)) } } /// How `git.pull` joins. #[derive(Debug, Clone, Copy, Deserialize)] #[serde(rename_all = "lowercase")] enum ModeParam { /// A merge. Merge, /// A rebase. Rebase, } /// Params of `git.pull`. #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] struct PullParams { /// Overrides the `git.pull.mode` setting. #[serde(default)] mode: Option, } /// `git.pull`. struct Pull; impl Command for Pull { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.pull", label: "Git: Pull", menu_path: None, default_shortcut: None, params: "{ mode?: \"merge\" | \"rebase\" (the git.pull.mode setting when absent) }; pulls the current branch's upstream; returns {}; refusals (no upstream, local changes, conflicts) explain themselves; progress as gitProgress events. Save dirty buffers first.", } } fn enabled(&self, state: &State) -> bool { state.has_project() } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let p: PullParams = parse(command, params)?; let rebase = match p.mode { Some(ModeParam::Rebase) => true, Some(ModeParam::Merge) => false, None => state .settings .get(PULL_MODE_SETTING) .is_some_and(|v| v.as_str() == Some("rebase")), }; let mode = if rebase { PullMode::Rebase } else { PullMode::Merge }; start(state, command, Op::Pull(mode)) } } /// `git.push`. struct Push; impl Command for Push { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.push", label: "Git: Push", menu_path: None, default_shortcut: None, params: "{ remote?: remote name for a branch without upstream (the only remote, else origin) }; pushes the current branch to its upstream, or sets one with the first push; returns { remote, branch, upstreamSet }; a rejected push explains itself; progress as gitProgress events", } } fn enabled(&self, state: &State) -> bool { state.has_project() } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let p: RemoteParams = parse(command, params)?; start(state, command, Op::Push(p.remote)) } } /// Params of `git.clone`. #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] struct CloneParams { /// The URL (HTTPS, SSH, scp-like) or path. url: String, /// The new work tree: absolute, missing or empty. dir: String, } /// `git.clone`. struct CloneRepo; impl Command for CloneRepo { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.clone", label: "Git: Clone Repository", menu_path: None, default_shortcut: None, params: "{ url: HTTPS, SSH or scp-like URL or a path, dir: absolute folder that is missing or empty (its parent must exist) }; returns { root }; works without a project; open it with project.open; progress as gitProgress events, git.cancel stops it and removes what it left", } } fn enabled(&self, _state: &State) -> bool { true } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let p: CloneParams = parse(command, params)?; lutra_vcs::check_url(&p.url).map_err(|e| engine_error(command, e))?; let dir = PathBuf::from(p.dir.trim()); if !dir.is_absolute() { return Err(EngineError::invalid_params( command, "dir must be an absolute path", )); } start(state, command, Op::Clone { url: p.url, dir }) } } /// `git.cancel`. struct CancelCommand; impl Command for CancelCommand { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.cancel", label: "Git: Cancel Fetch, Pull, Push or Clone", menu_path: None, default_shortcut: None, params: "none; stops the running fetch, pull, push or clone (it then fails with \"cancelled\"); returns { cancelled: true }; disabled while none runs", } } fn enabled(&self, state: &State) -> bool { state.git_remote.active.is_some() } fn run(&self, state: &mut State, params: Value) -> Result { let _: serde_json::Map = parse(self.spec().id, params)?; let cancelled = state.git_remote.active.as_ref().is_some_and(|active| { active.cancel.cancel(); true }); Ok(Outcome::value(json!({"cancelled": cancelled}))) } } /// `git.remotes`. struct Remotes; impl Command for Remotes { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.remotes", label: "Git: Remotes", menu_path: None, default_shortcut: None, params: "none; returns { remotes: [{ name, fetchUrl?, pushUrl? }] } in config order; URLs with userinfo are redacted (https://***@host/…); pushUrl only when it differs", } } fn enabled(&self, state: &State) -> bool { state.has_project() } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let _: serde_json::Map = parse(command, params)?; start(state, command, Op::Remotes) } } /// Params of `git.remoteAdd` and `git.remoteSetUrl`. #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] struct NameUrlParams { /// The remote's name. name: String, /// Its URL or path. url: String, } /// Params of `git.remoteRemove`. #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] struct NameParams { /// The remote's name. name: String, } /// Checks a name and URL under the lock, so bad input fails at once. fn check_name_url(command: &str, p: &NameUrlParams) -> Result<(), EngineError> { lutra_vcs::check_remote_name(&p.name).map_err(|e| engine_error(command, e))?; lutra_vcs::check_url(&p.url).map_err(|e| engine_error(command, e)) } /// `git.remoteAdd`. struct RemoteAdd; impl Command for RemoteAdd { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.remoteAdd", label: "Git: Add Remote", menu_path: None, default_shortcut: None, params: "{ name, url }; adds a remote without fetching; returns {}", } } fn enabled(&self, state: &State) -> bool { state.has_project() } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let p: NameUrlParams = parse(command, params)?; check_name_url(command, &p)?; start(state, command, Op::Add(p.name, p.url)) } } /// `git.remoteSetUrl`. struct RemoteSetUrl; impl Command for RemoteSetUrl { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.remoteSetUrl", label: "Git: Change Remote URL", menu_path: None, default_shortcut: None, params: "{ name, url }; changes the remote's URL; returns {}", } } fn enabled(&self, state: &State) -> bool { state.has_project() } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let p: NameUrlParams = parse(command, params)?; check_name_url(command, &p)?; start(state, command, Op::SetUrl(p.name, p.url)) } } /// `git.remoteRemove`. struct RemoteRemove; impl Command for RemoteRemove { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "git.remoteRemove", label: "Git: Remove Remote", menu_path: None, default_shortcut: None, params: "{ name }; removes the remote with its remote-tracking branches; returns {}", } } fn enabled(&self, state: &State) -> bool { state.has_project() } fn run(&self, state: &mut State, params: Value) -> Result { let command = self.spec().id; let p: NameParams = parse(command, params)?; lutra_vcs::check_remote_name(&p.name).map_err(|e| engine_error(command, e))?; start(state, command, Op::Remove(p.name)) } }