//! Engine ↔ language server wiring (M3.3): one Phpactor per open project, //! document sync of PHP buffers, `lspStatus` and diagnostics. //! //! Lifecycle, all decided in [`pump`] (called by //! [`crate::Engine::pump_vfs`]): //! - A session starts when a project is open and the toolchain reports a //! usable PHP and a ready Phpactor (`toolchain.status`), or at once when //! the host set its own server ([`Lsp::set_launch`], tests and the fake //! server). The server runs `php language-server` in the project //! root. //! - It stops when the project closes, when the PHP or Phpactor path //! changes (a new session starts with the new ones), on `lsp.restart`, //! and when the engine is dropped. The stop happens on the session thread //! ([`session`]), never under the engine lock. //! //! Document sync: [`record_edits`] (called by `buffer.edit`) queues the //! edit batch as a `didChange`; the pump opens newly opened PHP buffers, //! closes closed ones, sends `didSave` when a buffer's saved version moves //! and resends the whole text when the version moved without a recorded //! edit (a reload from disk, a restore) or a `didChange` no longer fit. //! Under the lock that is a cheap rope clone and a channel send; the text //! is built on the session thread. //! //! The pump drains the server's events: status changes become `lspStatus` //! (`starting`, `ready`, `restarting`, `failed`, `stopped`), published //! diagnostics of project files become `diagnosticsChanged` and are kept //! for `diagnostics.list`. Diagnostics are dropped when the session ends or //! the server gives up, so stale ones never stay on screen. //! //! Requests (completion, hover, definition, … in M3.4/M3.5) go through //! [`submit`], on the same queue as document sync, so they never overtake //! an edit. pub mod session; use std::collections::BTreeMap; use std::ffi::OsString; use std::path::{Path, PathBuf}; use std::sync::Arc; use std::sync::mpsc::Receiver; use std::time::{Duration, Instant}; use lutra_lsp::{PublishDiagnostics, Server, ServerEvent, Severity, Status}; use lutra_text::{Edit, Position}; use serde::Serialize; use serde_json::{Map, Value}; pub use lutra_lsp::{RestartPolicy, ServerOptions}; pub use session::Launch; use session::{Job, Report, Session}; use crate::buffers::BufferId; use crate::cmd::toolchain::PhpactorState; use crate::workspace::path_string; use crate::{Event, NotificationLevel, State}; /// Most server events handled per pump; the rest wait for the next one, /// so a chatty server cannot hold the engine lock. pub const MAX_EVENTS_PER_PUMP: usize = 2_000; /// Most files with diagnostics kept; publications for further files are /// ignored until others clear. pub const MAX_FILES: usize = 10_000; /// The state of the language server as `lspStatus` and `lsp.status` /// report it. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] #[serde(rename_all = "camelCase")] pub enum LspState { /// The process runs and `initialize` is in flight. Starting, /// Initialized; diagnostics and requests work. Ready, /// The server crashed and is restarted after a delay. Restarting, /// The server could not be started or crashed too often. Failed, /// No server runs (no project, toolchain not ready, or shut down). Stopped, } /// The payload of `lspStatus`. #[derive(Debug, Clone, PartialEq, Eq, Serialize)] pub struct LspStatus { /// The state. pub state: LspState, /// Why it is restarting or failed. #[serde(skip_serializing_if = "Option::is_none")] pub message: Option, } impl LspStatus { /// No server. fn stopped() -> Self { Self { state: LspState::Stopped, message: None, } } } /// How severe a diagnostic is, as the UI shows it. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)] #[serde(rename_all = "camelCase")] pub enum DiagnosticSeverity { /// An error (also when the server gave no severity). Error, /// A warning. Warning, /// Information. Info, /// A hint. Hint, } impl From> for DiagnosticSeverity { fn from(severity: Option) -> Self { match severity { Some(Severity::Warning) => Self::Warning, Some(Severity::Information) => Self::Info, Some(Severity::Hint) => Self::Hint, Some(Severity::Error) | None => Self::Error, } } } /// A position with a UTF-16 column, as everywhere in Lutra's protocol. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] pub struct LinePosition { /// 0-based line. pub line: usize, /// 0-based column in UTF-16 code units. pub column: usize, } impl From for LinePosition { fn from(p: Position) -> Self { Self { line: p.line, column: p.column, } } } /// A range between two positions, end exclusive. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] pub struct LineRange { /// Start. pub start: LinePosition, /// End. pub end: LinePosition, } /// One diagnostic of a file. #[derive(Debug, Clone, PartialEq, Eq, Serialize)] pub struct DiagnosticItem { /// Where it applies. pub range: LineRange, /// How severe it is. pub severity: DiagnosticSeverity, /// The message (at most 8 KiB). pub message: String, /// Who produced it (`phpactor`, `php-lint`, …). #[serde(skip_serializing_if = "Option::is_none")] pub source: Option, /// The diagnostic code. #[serde(skip_serializing_if = "Option::is_none")] pub code: Option, } /// The payload of `diagnosticsChanged`, and one file of /// `diagnostics.list`. #[derive(Debug, Clone, PartialEq, Eq, Serialize)] pub struct FileDiagnostics { /// Project-relative path with `/`. pub path: String, /// The diagnostics, in the server's order; empty when they cleared. pub items: Vec, } /// The language server part of the engine state. #[derive(Default)] pub struct Lsp { /// A server the host chose instead of Phpactor from the toolchain. launch: Option, /// The running session. active: Option, /// Status as last reported. status: Option, /// Diagnostics by project-relative path; files without any are absent. diagnostics: BTreeMap>, /// Set by [`shutdown_now`] (`app.quit`): no session starts any more. quitting: bool, } impl std::fmt::Debug for Lsp { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("Lsp") .field("launch", &self.launch) .field("running", &self.active.is_some()) .field("status", &self.status) .field("files_with_diagnostics", &self.diagnostics.len()) .finish() } } impl Lsp { /// Makes sessions start `launch` instead of Phpactor from the toolchain /// (`None` goes back to the toolchain). A running session is replaced /// at the next pump. pub fn set_launch(&mut self, launch: Option) { self.launch = launch; } /// The status as last reported; stopped without a session. pub fn status(&self) -> LspStatus { self.status.clone().unwrap_or_else(LspStatus::stopped) } /// Milliseconds from the start of the session to the server's first /// `ready`, once it was reached. pub fn startup_ms(&self) -> Option { self.active.as_ref().and_then(|a| a.ready_ms) } /// The diagnostics of one file (project-relative, `/`), or of every /// file, sorted by path. pub fn diagnostics(&self, path: Option<&str>) -> Vec { self.diagnostics .iter() .filter(|(p, _)| path.is_none_or(|want| want == p.as_str())) .map(|(p, items)| FileDiagnostics { path: p.clone(), items: items.clone(), }) .collect() } /// The server of the running session, once its process started. For /// reading its status and capabilities; send requests with [`submit`]. pub fn server(&self) -> Option<&Arc> { self.active.as_ref().and_then(|a| a.server.as_ref()) } } /// What a session was started for; a change replaces the session. #[derive(Debug, Clone, PartialEq)] struct Key { /// The project root. root: PathBuf, /// The server command line and options. launch: Launch, } /// A PHP buffer as the server knows it. #[derive(Debug, Clone)] struct Doc { /// Absolute path. path: PathBuf, /// The buffer version the server has (after the queued jobs). version: u64, /// The buffer's saved version last seen. saved_version: u64, /// The whole text must be resent. stale: bool, } /// The running session and what the engine knows about it. struct Active { /// Why it runs. key: Key, /// The session thread. session: Session, /// The server, once started. server: Option>, /// Its events, once started. events: Option>, /// When the session started. started: Instant, /// Milliseconds to the first `ready`. ready_ms: Option, /// Synced buffers. docs: BTreeMap, } /// Queues `f` on the session thread, after every document change queued /// so far. It runs with the server and must not block (use /// [`Server::request_with`] or keep the [`lutra_lsp::RequestHandle`] and /// poll it from the pump); without a running session it is dropped /// unrun, which a caller notices through a dropped channel sender it /// captured. /// /// # Returns /// Whether it was queued. pub fn submit(state: &mut State, f: impl FnOnce(&Server) + Send + 'static) -> bool { state .lsp .active .as_ref() .is_some_and(|a| a.session.send(Job::Run(Box::new(f)))) } /// Records an edit batch `buffer.edit` applied to buffer `id` (moving it /// from version `base` to `base + 1`) and queues it as a `didChange`. A /// buffer the server does not have yet, or whose synced version is not /// `base`, is resent whole by the next pump instead. pub fn record_edits(state: &mut State, id: BufferId, base: u64, edits: &[Edit]) { let Some(active) = state.lsp.active.as_mut() else { return; }; let Some(doc) = active.docs.get_mut(&id) else { return; }; if doc.stale || doc.version != base { doc.stale = true; return; } let job = Job::Change { path: doc.path.clone(), edits: edits.to_vec(), }; if active.session.send(job) { doc.version = base.saturating_add(1); } else { doc.stale = true; } } /// Starts, replaces or stops the session, applies the session thread's /// reports and the server's events, and syncs open PHP buffers. See the /// module docs. Never blocks. pub fn pump(state: &mut State) { let wanted = wanted(state); let current = state.lsp.active.as_ref().map(|a| a.key.clone()); if current != wanted { if current.is_some() { stop(state); } if let Some(key) = wanted { start(state, key); } } if state.lsp.active.is_none() { return; } drain_reports(state); drain_events(state); sync_docs(state); } /// Stops the running session at the next pump and lets the pump start a /// fresh one if the project and toolchain still allow it. pub fn restart(state: &mut State) { if state.lsp.active.is_some() { stop(state); } } /// Stops the language server now and waits for it (at most about 3 s), for /// `app.quit`: the host exits right after, which would cut a background /// shutdown short and leave the Phpactor process running. Clears the /// diagnostics and reports `stopped`. pub fn shutdown_now(state: &mut State) { state.lsp.quitting = true; let Some(active) = state.lsp.active.take() else { return; }; let Active { session, server, events, .. } = active; drop(server); drop(events); session.join(); clear_diagnostics(state); set_status(state, LspState::Stopped, None); } /// The session the state calls for: none without a project; the host's /// server if it set one; otherwise Phpactor once the toolchain found PHP /// and has the PHAR ready. fn wanted(state: &State) -> Option { if state.lsp.quitting { return None; } let root = state.project.as_ref()?.project.root().to_path_buf(); if let Some(launch) = &state.lsp.launch { return Some(Key { root, launch: launch.clone(), }); } let status = state.toolchain.status(); if !status.php.found || status.phpactor.state != PhpactorState::Ready { return None; } let php = status.php.path.as_ref()?; let phar = status.phpactor.path.as_ref()?; Some(Key { root, launch: phpactor_launch(php, phar, cfg!(windows)), }) } /// How Lutra starts Phpactor: `php language-server`. /// /// On Windows, Phpactor 2026.06.25.0 needs two adjustments (found in the /// M3.3 live check, see `docs/architecture.md` › Engine wiring): /// - Every subprocess it starts through amphp fails there with /// `CreateProcess failed` (outsourced diagnostics, the PHP lint provider, /// the `find` file watcher of the indexer). The `initializationOptions` /// run diagnostics in the server process /// (`language_server.diagnostic_outsource: false`) and let the indexer /// poll in PHP (`indexer.enabled_watchers: ["php"]`). The PHP lint /// provider still fails once and removes itself; its warning arrives as /// `window/showMessage`, which Lutra does not show. /// - Its event loop only runs when a message arrives on stdin, so timers /// (the diagnostics debounce, the watcher) stall while the client is /// quiet. The session thread sends [`TICK_METHOD`] every 25 ms while /// busy; Phpactor's analysis advances one step per message, so the /// interval sets the latency (edit to diagnostics with its 1 s debounce: /// 5.9 s at 200 ms, 2.5 s at 50 ms, 1.5 s at 20 ms, measured). For the /// same reason it rarely answers `shutdown` in time, so the shutdown /// timeout is 500 ms instead of 2 s before the process is killed (quit /// took 3 s otherwise). /// /// Nothing is written into the user's project. /// /// # Parameters /// - `php`, `phar`: the executables from `toolchain.status`. /// - `windows`: whether to apply the Windows adjustments. pub fn phpactor_launch(php: &str, phar: &str, windows: bool) -> Launch { let options = ServerOptions { initialization_options: windows.then(|| { serde_json::json!({ "language_server.diagnostic_outsource": false, "indexer.enabled_watchers": ["php"], }) }), shutdown_timeout: if windows { Duration::from_millis(500) } else { ServerOptions::default().shutdown_timeout }, ..ServerOptions::default() }; Launch { command: OsString::from(php), args: vec![OsString::from(phar), OsString::from("language-server")], options, tick: windows.then_some(TICK_INTERVAL), } } /// The no-op notification that keeps a server's event loop turning /// ([`Launch::tick`]). Servers ignore `$/` notifications they do not know. pub const TICK_METHOD: &str = "$/lutra/tick"; /// How often a busy session sends [`TICK_METHOD`] to Phpactor on Windows /// (from its own thread, independent of the host's pump). pub const TICK_INTERVAL: Duration = Duration::from_millis(25); /// How long a session counts as busy after its last document change, /// open, save or submitted request. Long enough for Phpactor's first /// analysis of a project on a cold cache (16 s measured in M3.3). pub const TICK_WINDOW: Duration = Duration::from_secs(60); /// Whether a session with tick interval `interval` sends a tick at `now`. /// /// # Parameters /// - `ready`: whether the server is ready. /// - `last_activity`: the last change, open, save or request, if any. /// - `last_tick`: when the last tick was sent, if any. pub fn tick_due( interval: Option, ready: bool, last_activity: Option, last_tick: Option, now: Instant, ) -> bool { let Some(interval) = interval else { return false; }; let busy = last_activity.is_some_and(|t| now.saturating_duration_since(t) <= TICK_WINDOW); let due = last_tick.is_none_or(|t| now.saturating_duration_since(t) >= interval); ready && busy && due } /// Starts a session for `key` and reports `starting`, or `failed` if the /// thread cannot be started. fn start(state: &mut State, key: Key) { match Session::start(key.launch.clone(), key.root.clone()) { Ok(session) => { state.lsp.active = Some(Active { key, session, server: None, events: None, started: Instant::now(), ready_ms: None, docs: BTreeMap::new(), }); set_status(state, LspState::Starting, None); } Err(message) => fail(state, message), } } /// Drops the session (its thread shuts the server down), clears the /// diagnostics and reports `stopped`. fn stop(state: &mut State) { state.lsp.active = None; clear_diagnostics(state); set_status(state, LspState::Stopped, None); } /// Reports `failed` with `message`, clears the diagnostics and tells the /// user once. fn fail(state: &mut State, message: String) { clear_diagnostics(state); let changed = set_status(state, LspState::Failed, Some(message.clone())); if changed { let mut params = Map::new(); params.insert("reason".into(), Value::from(message.clone())); state.notify( NotificationLevel::Error, Some("notification.lsp.failed"), Some(format!( "The PHP language server stopped: {message}. Run \"Restart Language Server\" to try again." )), Some(params), ); } } /// Stores the status and queues `lspStatus` if it changed. /// /// # Returns /// Whether it changed. fn set_status(state: &mut State, lsp_state: LspState, message: Option) -> bool { let status = LspStatus { state: lsp_state, message, }; if state.lsp.status.as_ref() == Some(&status) { return false; } state.lsp.status = Some(status.clone()); state.emit(Event::LspStatus(status)); true } /// Applies the session thread's reports. fn drain_reports(state: &mut State) { let mut reports = Vec::new(); if let Some(active) = &state.lsp.active { while let Ok(report) = active.session.reports.try_recv() { reports.push(report); } } for report in reports { match report { Report::Started { server, events } => { if let Some(active) = state.lsp.active.as_mut() { active.server = Some(server); active.events = Some(events); } } Report::SpawnFailed(message) => fail(state, message), Report::Desync(path) => { if let Some(active) = state.lsp.active.as_mut() { for doc in active.docs.values_mut().filter(|d| d.path == path) { doc.stale = true; } } } } } } /// Handles up to [`MAX_EVENTS_PER_PUMP`] server events. fn drain_events(state: &mut State) { let mut events = Vec::new(); if let Some(receiver) = state.lsp.active.as_ref().and_then(|a| a.events.as_ref()) { while events.len() < MAX_EVENTS_PER_PUMP { let Ok(event) = receiver.try_recv() else { break; }; events.push(event); } } for event in events { match event { ServerEvent::Status(status) => apply_status(state, status), ServerEvent::Diagnostics(published) => publish(state, published), _ => {} } } } /// Maps a client status onto `lspStatus`. fn apply_status(state: &mut State, status: Status) { match status { Status::Starting => { set_status(state, LspState::Starting, None); } Status::Ready => { if let Some(active) = state.lsp.active.as_mut() && active.ready_ms.is_none() { active.ready_ms = Some(u64::try_from(active.started.elapsed().as_millis()).unwrap_or(u64::MAX)); } set_status(state, LspState::Ready, None); } Status::Restarting { reason, .. } => { set_status(state, LspState::Restarting, Some(reason)); } Status::Failed { message } => fail(state, message), Status::Stopped => { clear_diagnostics(state); set_status(state, LspState::Stopped, None); } } } /// Stores the diagnostics of one file and queues `diagnosticsChanged`. /// Files outside the project are ignored. fn publish(state: &mut State, published: PublishDiagnostics) { let Some(root) = state.lsp.active.as_ref().map(|a| a.key.root.clone()) else { return; }; let Some(relative) = published.path.as_deref().and_then(|p| relative(&root, p)) else { return; }; let path = path_string(&relative); let items: Vec = published .diagnostics .into_iter() .map(|d| DiagnosticItem { range: LineRange { start: d.range.start.into(), end: d.range.end.into(), }, severity: d.severity.into(), message: d.message, source: d.source, code: d.code, }) .collect(); let diagnostics = &mut state.lsp.diagnostics; if items.is_empty() { if diagnostics.remove(&path).is_none() { return; } } else { if diagnostics.get(&path) == Some(&items) { return; } if !diagnostics.contains_key(&path) && diagnostics.len() >= MAX_FILES { return; } diagnostics.insert(path.clone(), items.clone()); } state.emit(Event::DiagnosticsChanged(FileDiagnostics { path, items })); } /// Drops every diagnostic, queuing an empty `diagnosticsChanged` per file /// that had some. fn clear_diagnostics(state: &mut State) { let files = std::mem::take(&mut state.lsp.diagnostics); for path in files.into_keys() { state.emit(Event::DiagnosticsChanged(FileDiagnostics { path, items: Vec::new(), })); } } /// `path` relative to `root`; `None` outside it. Windows paths compare /// without regard to case, as the file system does. fn relative(root: &Path, path: &Path) -> Option { if let Ok(rel) = path.strip_prefix(root) { return Some(rel.to_path_buf()); } if !cfg!(windows) { return None; } let root_text = root.to_str()?.trim_end_matches(['\\', '/']); let text = path.to_str()?; let head = text.get(..root_text.len())?; let rest = text.get(root_text.len()..)?; if !head.eq_ignore_ascii_case(root_text) || !rest.starts_with(['\\', '/']) { return None; } Some(PathBuf::from(rest.trim_start_matches(['\\', '/']))) } /// Whether a project-relative path is synced as PHP. fn is_php(path: &Path) -> bool { path.extension().and_then(|e| e.to_str()).is_some_and(|e| { ["php", "phtml", "inc"] .iter() .any(|x| e.eq_ignore_ascii_case(x)) }) } /// Opens new PHP buffers, closes closed ones, resends stale texts and /// reports saves. fn sync_docs(state: &mut State) { let State { buffers, lsp, .. } = state; let Some(active) = lsp.active.as_mut() else { return; }; let gone: Vec = active .docs .keys() .copied() .filter(|id| !buffers.get(*id).is_some_and(|b| is_php(&b.path))) .collect(); for id in gone { if let Some(doc) = active.docs.remove(&id) { active.session.send(Job::Close { path: doc.path }); } } for id in buffers.ids() { let Some(open) = buffers.get(id) else { continue; }; if !is_php(&open.path) { continue; } let path = active.key.root.join(&open.path); let Some(doc) = active.docs.get_mut(&id) else { active.session.send(Job::Open { path: path.clone(), text: open.buffer.clone(), }); active.docs.insert( id, Doc { path, version: open.version, saved_version: open.saved_version, stale: false, }, ); continue; }; if doc.path != path { active.session.send(Job::Close { path: std::mem::replace(&mut doc.path, path.clone()), }); active.session.send(Job::Open { path, text: open.buffer.clone(), }); doc.version = open.version; doc.stale = false; } else if doc.stale || doc.version != open.version { active.session.send(Job::Full { path: doc.path.clone(), text: open.buffer.clone(), }); doc.version = open.version; doc.stale = false; } if doc.saved_version != open.saved_version { doc.saved_version = open.saved_version; if !open.dirty() { active.session.send(Job::Save { path: doc.path.clone(), }); } } } } #[cfg(test)] mod tests { use std::path::{Path, PathBuf}; use std::time::{Duration, Instant}; use super::{ DiagnosticSeverity, TICK_INTERVAL, TICK_WINDOW, phpactor_launch, relative, tick_due, }; use lutra_lsp::Severity; #[test] fn severity_defaults_to_error() { assert_eq!(DiagnosticSeverity::from(None), DiagnosticSeverity::Error); assert_eq!( DiagnosticSeverity::from(Some(Severity::Information)), DiagnosticSeverity::Info ); assert_eq!( DiagnosticSeverity::from(Some(Severity::Hint)), DiagnosticSeverity::Hint ); } #[test] fn relative_paths_stay_inside_the_root() { let root = if cfg!(windows) { PathBuf::from(r"C:\work\demo") } else { PathBuf::from("/work/demo") }; let inside = root.join("src").join("a.php"); assert_eq!( relative(&root, &inside), Some(Path::new("src").join("a.php")) ); let sibling = if cfg!(windows) { PathBuf::from(r"C:\work\demo2\a.php") } else { PathBuf::from("/work/demo2/a.php") }; assert_eq!(relative(&root, &sibling), None); if cfg!(windows) { assert_eq!( relative(&root, Path::new(r"c:\WORK\demo\b.php")), Some(PathBuf::from("b.php")) ); } } #[test] fn phpactor_gets_the_windows_adjustments_only_there() { let windows = phpactor_launch("php.exe", r"C: \phpactor.phar", true); assert_eq!(windows.tick, Some(TICK_INTERVAL)); let options = windows.options.initialization_options.unwrap(); assert_eq!(options["language_server.diagnostic_outsource"], false); assert_eq!( options["indexer.enabled_watchers"], serde_json::json!(["php"]) ); assert_eq!(windows.args.len(), 2); let unix = phpactor_launch("php", "/t/phpactor.phar", false); assert_eq!(unix.tick, None); assert_eq!(unix.options.initialization_options, None); assert_eq!(windows.options.shutdown_timeout, Duration::from_millis(500)); assert_eq!(unix.options.shutdown_timeout, Duration::from_secs(2)); } #[test] fn ticks_only_while_ready_and_busy() { let now = Instant::now() + Duration::from_secs(3600); let tick = Some(TICK_INTERVAL); let recent = Some(now - Duration::from_secs(1)); assert!(tick_due(tick, true, recent, None, now)); assert!(!tick_due(None, true, recent, None, now)); assert!(!tick_due(tick, false, recent, None, now)); let quiet = Some(now - TICK_WINDOW - Duration::from_secs(1)); assert!(!tick_due(tick, true, quiet, None, now)); assert!(!tick_due( tick, true, recent, Some(now - TICK_INTERVAL / 2), now )); assert!(tick_due(tick, true, recent, Some(now - TICK_INTERVAL), now)); } }