//! The PHP toolchain: `toolchain.status`, `toolchain.downloadPhpactor` and //! the `toolchainChanged` event (owner decision D15). //! //! Finding PHP runs `php -v`, verifying Phpactor hashes a 4 MB file and //! downloading it uses the network, so all of it happens on one worker //! thread ([`lutra_lsp::toolchain`]), never under the engine lock. Commands //! and [`pump`] only queue jobs; the worker's reports wait in a channel //! until the next [`crate::Engine::pump_vfs`] turns them into the stored //! status, `toolchainChanged` and notifications, like search results. //! //! When the worker runs: //! - the first `toolchain.status` (a check, no download); //! - a project opens (a check; a download if the project has PHP files, //! PHP is usable, Phpactor is missing and `phpactor.autoDownload` is on); //! - `php.executable`, `phpactor.path` or `phpactor.autoDownload` changes //! after the first check; //! - `toolchain.downloadPhpactor` (a download even with auto-download off). //! //! Downloads need the host's consent: an engine downloads nothing until //! the host calls [`crate::Engine::allow_downloads`] (the desktop does; tests //! never do, so no test reaches the network) and it has a data directory. use std::path::PathBuf; use std::sync::mpsc::{self, Receiver, Sender, TryRecvError}; use std::time::Duration; use lutra_lsp::toolchain::download::{self, DownloadError, Hash, Retry, Source}; use lutra_lsp::toolchain::{has_php_files, php, phpactor}; use serde::Serialize; use serde_json::{Map, Value, json}; use crate::{Command, CommandSpec, EngineError, Event, NotificationLevel, Outcome, State}; /// The toolchain as `toolchain.status` and `toolchainChanged` report it. #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)] pub struct ToolchainStatus { /// The user's PHP. pub php: PhpStatus, /// The Phpactor PHAR. pub phpactor: PhpactorStatus, } /// PHP as last checked. #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)] pub struct PhpStatus { /// A PHP new enough for Phpactor was found. pub found: bool, /// The executable, also when it is too old or failed; `null` if none /// was found or no check ran yet. pub path: Option, /// Its version, `major.minor.patch`. pub version: Option, /// Why PHP is not usable. #[serde(skip_serializing_if = "Option::is_none")] pub error: Option, } /// State of the Phpactor PHAR. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)] #[serde(rename_all = "camelCase")] pub enum PhpactorState { /// Not there (yet). #[default] Missing, /// Being downloaded. Downloading, /// Verified (or given by `phpactor.path`) and ready to run. Ready, /// The download or the configured path failed. Failed, /// Missing, and `phpactor.autoDownload` is off. Disabled, } /// Phpactor as last checked. #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)] pub struct PhpactorStatus { /// Its state. pub state: PhpactorState, /// The PHAR, when ready. #[serde(skip_serializing_if = "Option::is_none")] pub path: Option, /// Its version; absent for a `phpactor.path` of unknown version. #[serde(skip_serializing_if = "Option::is_none")] pub version: Option, /// What failed. #[serde(skip_serializing_if = "Option::is_none")] pub error: Option, } /// The toolchain part of the engine state. #[derive(Debug, Default)] pub struct Toolchain { /// The status as of the last report. status: ToolchainStatus, /// Where downloads come from; `None` until the host allows downloads. source: Option, /// The worker, started with the first job. worker: Option, /// The settings the last job ran with; `None` before the first job. config: Option, /// The project root the last job saw. root: Option, /// Where the managed tools live (`tools/phpactor//`) when that /// is not the engine's data directory; see /// [`crate::Engine::share_tools_from`]. tools_dir: Option, } impl Toolchain { /// The status as of the last report. pub fn status(&self) -> &ToolchainStatus { &self.status } /// Allows downloads from `source` ([`crate::Engine::allow_downloads`] /// passes the pinned release; tests pass a local server). pub fn allow_downloads(&mut self, source: Source) { self.source = Some(source); } /// Keeps the managed tools in `dir` instead of the engine's data /// directory. pub fn set_tools_dir(&mut self, dir: PathBuf) { self.tools_dir = Some(dir); } } /// The settings and directories a job runs with. #[derive(Debug, Clone, PartialEq, Eq)] struct Config { /// `php.executable`. php: String, /// `phpactor.path`. phpactor_path: String, /// `phpactor.autoDownload`. auto_download: bool, /// The directory holding the managed tools: the toolchain's tools /// directory if set, else the engine's data directory. data_dir: Option, } /// What a job may do besides checking. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] enum Mode { /// Only check. Check, /// Download if this project has PHP files and auto-download is on. Auto(PathBuf), /// Download if missing, whatever the setting says. Force, } /// One job for the worker. #[derive(Debug)] struct Job { /// Settings. config: Config, /// Check or download. mode: Mode, /// Download source; `None` forbids downloads. source: Option, } /// A user-visible step of a download. #[derive(Debug, Clone, PartialEq, Eq)] enum Notice { /// The download started. Started { /// Phpactor version. version: String, }, /// The file was downloaded and verified. Done { /// Phpactor version. version: String, /// Wall time in milliseconds. elapsed_ms: u64, }, /// The download failed. Failed { /// Phpactor version. version: String, /// Why. reason: String, }, } /// A worker report; `None` fields are unchanged. #[derive(Debug, Default)] struct Report { /// New PHP status. php: Option, /// New Phpactor status. phpactor: Option, /// A step to tell the user about. notice: Option, } /// The worker thread's channels. #[derive(Debug)] struct Worker { /// Jobs to it. jobs: Sender, /// Reports from it. reports: Receiver, } /// Queues a job, starting the worker if needed. A worker that vanished is /// restarted. fn request(state: &mut State, mode: Mode) { let config = config(state); let toolchain = &mut state.toolchain; toolchain.config = Some(config.clone()); let job = Job { config, mode, source: toolchain.source.clone(), }; let job = match &toolchain.worker { Some(worker) => match worker.jobs.send(job) { Ok(()) => return, Err(mpsc::SendError(job)) => job, }, None => job, }; toolchain.worker = spawn_worker(); if let Some(worker) = &toolchain.worker { let _ = worker.jobs.send(job); } } /// The job settings from the current state. fn config(state: &State) -> Config { let text = |key: &str| { state .settings .get(key) .and_then(|v| v.as_str().map(str::to_string)) .unwrap_or_default() }; Config { php: text("php.executable"), phpactor_path: text("phpactor.path"), auto_download: state .settings .get("phpactor.autoDownload") .and_then(|v| v.as_bool()) .unwrap_or(true), data_dir: state .toolchain .tools_dir .clone() .or_else(|| state.config.as_ref().map(|c| c.data_dir.clone())), } } /// Starts the worker thread; `None` if the OS refuses a thread, in which /// case the next request tries again. fn spawn_worker() -> Option { let (jobs, job_rx) = mpsc::channel::(); let (report_tx, reports) = mpsc::channel(); std::thread::Builder::new() .name("lutra-toolchain".into()) .spawn(move || { while let Ok(mut job) = job_rx.recv() { while let Ok(next) = job_rx.try_recv() { job = merge(job, next); } if run_job(&job, &report_tx).is_err() { return; } } }) .ok()?; Some(Worker { jobs, reports }) } /// Two queued jobs as one: the newer settings and source, the stronger /// mode. fn merge(older: Job, newer: Job) -> Job { let mode = older.mode.max(newer.mode); Job { mode, ..newer } } /// Runs one job on the worker: checks PHP, then Phpactor, downloading it if /// the job asks for it. Each step is reported as it ends. /// /// # Errors /// When the engine dropped the report channel; the worker stops then. fn run_job(job: &Job, reports: &Sender) -> Result<(), Gone> { let php = php_status(&job.config.php); let php_usable = php.found; send( reports, Report { php: Some(php), ..Report::default() }, )?; let config = &job.config; if !config.phpactor_path.trim().is_empty() { return send( reports, Report { phpactor: Some(configured(config.phpactor_path.trim())), ..Report::default() }, ); } let (version, hash) = match &job.source { Some(source) => (source.version.clone(), Some(source.sha256)), None => ( phpactor::VERSION.to_string(), Hash::from_hex(phpactor::SHA256), ), }; let managed = config .data_dir .as_ref() .map(|dir| phpactor::managed_path(dir, &version)); if let (Some(path), Some(hash)) = (&managed, &hash) && phpactor::verify(path, hash).unwrap_or(false) { return send( reports, Report { phpactor: Some(ready(path, Some(version))), ..Report::default() }, ); } let wanted = match &job.mode { Mode::Check => false, Mode::Auto(root) => config.auto_download && php_usable && has_php_files(root), Mode::Force => true, }; let (Some(source), Some(path), true) = (&job.source, &managed, wanted) else { let state = if config.auto_download { PhpactorState::Missing } else { PhpactorState::Disabled }; return send( reports, Report { phpactor: Some(PhpactorStatus { state, ..PhpactorStatus::default() }), ..Report::default() }, ); }; send( reports, Report { phpactor: Some(PhpactorStatus { state: PhpactorState::Downloading, version: Some(version.clone()), ..PhpactorStatus::default() }), notice: Some(Notice::Started { version: version.clone(), }), ..Report::default() }, )?; let result = download::install_with_retry( source, path, phpactor::MAX_SIZE, Retry::default(), |_, _| {}, ); send( reports, match result { Ok(stats) => Report { phpactor: Some(ready(path, Some(version.clone()))), notice: Some(Notice::Done { version, elapsed_ms: millis(stats.elapsed), }), ..Report::default() }, Err(e) => failed_download(version, &e), }, ) } /// The engine dropped the report channel. struct Gone; /// Sends a report to the engine. /// /// # Errors /// [`Gone`] if the engine dropped the channel. fn send(reports: &Sender, report: Report) -> Result<(), Gone> { reports.send(report).map_err(|_| Gone) } /// The report of a failed download. fn failed_download(version: String, error: &DownloadError) -> Report { Report { phpactor: Some(PhpactorStatus { state: PhpactorState::Failed, version: Some(version.clone()), error: Some(error.to_string()), ..PhpactorStatus::default() }), notice: Some(Notice::Failed { version, reason: error.to_string(), }), ..Report::default() } } /// Checks PHP with [`php::detect`]. fn php_status(setting: &str) -> PhpStatus { match php::detect(setting) { Ok(found) => PhpStatus { found: true, path: Some(found.path.display().to_string()), version: Some(found.version.to_string()), error: None, }, Err(e) => PhpStatus { found: false, path: e.path().map(|p| p.display().to_string()), version: e.version().map(|v| v.to_string()), error: Some(e.to_string()), }, } } /// The status of a PHAR given by `phpactor.path`: ready if it is a file. /// Its version is unknown and its hash is not checked: the user chose it. fn configured(path: &str) -> PhpactorStatus { let file = PathBuf::from(path); if file.is_file() { ready(&file, None) } else { PhpactorStatus { state: PhpactorState::Failed, error: Some(format!("phpactor.path {path} is not a file")), ..PhpactorStatus::default() } } } /// A ready status for `path`. fn ready(path: &std::path::Path, version: Option) -> PhpactorStatus { PhpactorStatus { state: PhpactorState::Ready, path: Some(path.display().to_string()), version, error: None, } } /// Whole milliseconds, saturating. fn millis(elapsed: Duration) -> u64 { u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX) } /// Starts jobs for a newly opened project or changed settings, and applies /// the worker's reports: stores the status, queues `toolchainChanged` when /// it changed and notifications for missing PHP and download steps. Runs /// on every [`crate::Engine::pump_vfs`]; it never blocks. pub fn pump(state: &mut State) { let root = state .project .as_ref() .map(|w| w.project.root().to_path_buf()); if root != state.toolchain.root { state.toolchain.root.clone_from(&root); if let Some(root) = root.clone() { request(state, Mode::Auto(root)); } } else if state .toolchain .config .as_ref() .is_some_and(|c| *c != config(state)) { request(state, root.map_or(Mode::Check, Mode::Auto)); } let mut reports = Vec::new(); if let Some(worker) = &state.toolchain.worker { loop { match worker.reports.try_recv() { Ok(report) => reports.push(report), Err(TryRecvError::Empty) => break, Err(TryRecvError::Disconnected) => { state.toolchain.worker = None; break; } } } } for report in reports { apply(state, report); } } /// Applies one report. fn apply(state: &mut State, report: Report) { let before = state.toolchain.status.clone(); if let Some(php) = report.php { if !php.found && php != before.php { let mut params = Map::new(); params.insert( "reason".into(), Value::from(php.error.clone().unwrap_or_default()), ); params.insert("min".into(), Value::from(php::MIN_VERSION.to_string())); state.notify( NotificationLevel::Warning, Some("notification.toolchain.phpMissing"), Some(format!( "PHP language features need PHP {} or newer: {}. Install PHP or set php.executable.", php::MIN_VERSION, php.error.as_deref().unwrap_or("not found") )), Some(params), ); } state.toolchain.status.php = php; } if let Some(phpactor) = report.phpactor { state.toolchain.status.phpactor = phpactor; } if let Some(notice) = report.notice { notify_download(state, notice); } if state.toolchain.status != before { let status = state.toolchain.status.clone(); state.emit(Event::ToolchainChanged(status)); } } /// Queues the notification of a download step. fn notify_download(state: &mut State, notice: Notice) { let mut params = Map::new(); let (level, key, message) = match notice { Notice::Started { version } => { let message = format!("Downloading Phpactor {version} for PHP language features…"); params.insert("version".into(), Value::from(version)); ( NotificationLevel::Info, "notification.toolchain.downloadStarted", message, ) } Notice::Done { version, elapsed_ms, } => { let seconds = format!("{:.1}", elapsed_ms as f64 / 1000.0); let message = format!("Phpactor {version} is ready (downloaded and verified in {seconds} s)."); params.insert("version".into(), Value::from(version)); params.insert("seconds".into(), Value::from(seconds)); ( NotificationLevel::Info, "notification.toolchain.downloadDone", message, ) } Notice::Failed { version, reason } => { let message = format!("Phpactor {version} could not be downloaded: {reason}"); params.insert("version".into(), Value::from(version)); params.insert("reason".into(), Value::from(reason)); ( NotificationLevel::Error, "notification.toolchain.downloadFailed", message, ) } }; state.notify(level, Some(key), Some(message), Some(params)); } /// `toolchain.status`: PHP and Phpactor as last checked. pub struct Status; impl Command for Status { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "toolchain.status", label: "Toolchain Status", menu_path: None, default_shortcut: None, params: "none; returns { php: { found, path, version, error? }, phpactor: { state: missing|downloading|ready|failed|disabled, path?, version?, error? } } as last checked; the first call starts a check in the background and toolchainChanged (same shape) follows when it ends", } } fn run(&self, state: &mut State, _params: Value) -> Result { if state.toolchain.config.is_none() { let mode = state .project .as_ref() .map_or(Mode::Check, |w| Mode::Auto(w.project.root().to_path_buf())); request(state, mode); } let value = serde_json::to_value(&state.toolchain.status) .map_err(|e| EngineError::Internal(e.to_string()))?; Ok(Outcome::value(value)) } } /// `toolchain.downloadPhpactor`: downloads the pinned Phpactor now. pub struct DownloadPhpactor; impl Command for DownloadPhpactor { fn spec(&self) -> &CommandSpec { &CommandSpec { id: "toolchain.downloadPhpactor", label: "Download Phpactor", menu_path: None, default_shortcut: None, params: "none; returns { started } at once (false while a download runs); downloads the pinned, SHA-256-verified Phpactor PHAR in the background even with phpactor.autoDownload off, unless phpactor.path is set or it is already there; progress comes as toolchainChanged and notifications; failed if this host allows no downloads", } } fn run(&self, state: &mut State, _params: Value) -> Result { if state.toolchain.source.is_none() || state.config.is_none() { return Err(EngineError::Failed( "downloads are not enabled in this host".into(), )); } if state.toolchain.status.phpactor.state == PhpactorState::Downloading { return Ok(Outcome::value(json!({ "started": false }))); } request(state, Mode::Force); Ok(Outcome::value(json!({ "started": true }))) } } #[cfg(test)] mod tests { use std::io::{Read, Write}; use std::net::TcpListener; use std::time::Instant; use serde_json::json; use super::*; use crate::{Engine, EngineConfig}; /// Serves `body` once on a local port; no real network. fn serve_once(body: Vec) -> String { let listener = TcpListener::bind("127.0.0.1:0").unwrap(); let url = format!("http://{}/phpactor.phar", listener.local_addr().unwrap()); std::thread::spawn(move || { let (mut stream, _) = listener.accept().unwrap(); let mut head = Vec::new(); let mut byte = [0u8; 1]; while !head.ends_with(b"\r\n\r\n") && stream.read(&mut byte).unwrap_or(0) == 1 { head.push(byte[0]); } let _ = stream.write_all( format!( "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n", body.len() ) .as_bytes(), ); let _ = stream.write_all(&body); }); url } fn engine(dir: &std::path::Path) -> Engine { Engine::with_config(EngineConfig { config_dir: dir.join("config"), data_dir: dir.join("data"), }) .unwrap() } /// Pumps until `done` holds for the collected events or 20 s pass. fn pump_until(engine: &mut Engine, done: impl Fn(&[Event]) -> bool) -> Vec { let mut events = Vec::new(); let deadline = Instant::now() + Duration::from_secs(20); while Instant::now() < deadline { events.extend(engine.pump_vfs().unwrap()); if done(&events) { return events; } std::thread::sleep(Duration::from_millis(20)); } panic!("timed out; events: {events:?}"); } fn last_status(events: &[Event]) -> Option<&ToolchainStatus> { events.iter().rev().find_map(|e| match e { Event::ToolchainChanged(s) => Some(s), _ => None, }) } fn keys(events: &[Event]) -> Vec { events .iter() .filter_map(|e| match e { Event::Notification { message_key, .. } => message_key.clone(), _ => None, }) .collect() } #[test] fn status_shape() { let status = ToolchainStatus::default(); assert_eq!( serde_json::to_value(&status).unwrap(), json!({"php": {"found": false, "path": null, "version": null}, "phpactor": {"state": "missing"}}) ); assert_eq!( serde_json::to_value(Event::ToolchainChanged(status)).unwrap()["kind"], "toolchainChanged" ); } #[test] fn no_downloads_without_the_hosts_consent() { let dir = tempfile::tempdir().unwrap(); let mut engine = engine(dir.path()); let err = engine .execute("toolchain.downloadPhpactor", Value::Null) .unwrap_err(); assert_eq!(err.code(), "failed"); let mut bare = Engine::new().unwrap(); bare.allow_downloads_from(phpactor::pinned().unwrap()); assert_eq!( bare.execute("toolchain.downloadPhpactor", Value::Null) .unwrap_err() .code(), "failed", "no data directory" ); } #[test] fn manual_download_installs_and_verifies() { let dir = tempfile::tempdir().unwrap(); let body = b"