M3.1: PHP detection and pinned Phpactor download

- crates/lsp toolchain: PHP from php.executable or PATH, `php -v` with a
  5 s timeout and capped output, version parsing (proptest), PHP >= 8.2.
- Pinned Phpactor 2026.06.25.0 (SHA-256 832510fe...59e9); newer releases
  need ext-posix and do not start on Windows.
- Download with ureq + rustls (ring, OS roots via rustls-native-certs):
  HTTPS only, 32 MiB cap, SHA-256 verified before an atomic write, retry
  with backoff. Tests use a local HTTP server only.
- Engine: settings php.executable, phpactor.path, phpactor.autoDownload
  (bool and string setting kinds), toolchain.status,
  toolchain.downloadPhpactor, toolchainChanged, notifications; worker
  thread off the engine lock, results via the pump. Downloads only after
  the host calls Engine::allow_downloads (the desktop does).
- Docs: architecture Toolchain section (network access, D15), G6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-18 11:25:20 +02:00
parent 78709dd76b
commit 50f36cce8b
23 changed files with 2577 additions and 10 deletions

View file

@ -194,7 +194,14 @@ fn settings_changes_stream_and_persist() {
let r = client.call(execute("settings.get", Value::Null));
assert_eq!(
r["result"]["values"],
json!({"appearance.theme": "system", "editor.fontSize": 14, "ui.language": "en"}),
json!({
"appearance.theme": "system",
"editor.fontSize": 14,
"ui.language": "en",
"php.executable": "",
"phpactor.path": "",
"phpactor.autoDownload": true
}),
"{r}"
);
let notice = client.event("notification");

View file

@ -0,0 +1,159 @@
//! The toolchain over a real TCP control connection: `toolchain.status`
//! answers at once, the check runs off the engine lock and its result
//! arrives as `toolchainChanged` and a notification from the pump. No
//! network: the test backend never allows downloads.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::indexing_slicing,
clippy::panic
)]
use std::io::{BufRead, BufReader, Write};
use std::net::TcpStream;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::time::Duration;
use lutra_testkit::EngineBackend;
use serde_json::{Value, json};
/// A client that keeps responses and event lines apart.
struct Client {
reader: BufReader<TcpStream>,
writer: TcpStream,
events: Vec<Value>,
}
impl Client {
fn connect(addr: std::net::SocketAddr) -> Self {
let stream = TcpStream::connect(addr).unwrap();
stream
.set_read_timeout(Some(Duration::from_secs(30)))
.unwrap();
Self {
writer: stream.try_clone().unwrap(),
reader: BufReader::new(stream),
events: Vec::new(),
}
}
fn line(&mut self) -> Value {
let mut line = String::new();
self.reader.read_line(&mut line).expect("line within 30 s");
serde_json::from_str(&line).unwrap()
}
fn call(&mut self, request: Value) -> Value {
self.writer
.write_all(format!("{request}\n").as_bytes())
.unwrap();
loop {
let line = self.line();
if line.get("event").is_some() {
self.events.push(line["event"].clone());
} else {
return line;
}
}
}
/// The next event (queued or read) for which `pick` holds.
fn event(&mut self, pick: impl Fn(&Value) -> bool) -> Value {
if let Some(i) = self.events.iter().position(&pick) {
return self.events.remove(i);
}
loop {
let line = self.line();
if let Some(event) = line.get("event") {
if pick(event) {
return event.clone();
}
self.events.push(event.clone());
}
}
}
}
fn execute(command: &str, params: Value) -> Value {
json!({"id": command, "method": "engine.execute", "params": {"command": command, "params": params}})
}
/// Pumps the backend every 20 ms, like the desktop's pump thread, until
/// dropped.
struct Pump(Arc<AtomicBool>);
impl Pump {
fn start(backend: Arc<EngineBackend>) -> Self {
let stop = Arc::new(AtomicBool::new(false));
let flag = stop.clone();
std::thread::spawn(move || {
while !flag.load(Ordering::Relaxed) {
backend.pump();
std::thread::sleep(Duration::from_millis(20));
}
});
Self(stop)
}
}
impl Drop for Pump {
fn drop(&mut self) {
self.0.store(true, Ordering::Relaxed);
}
}
#[test]
fn status_and_check_over_tcp() {
let dir = tempfile::tempdir().unwrap();
let missing = dir.path().join("no-php").join("php");
let backend = Arc::new(EngineBackend::new());
let server = lutra_control::start(0, backend.clone()).unwrap();
let mut client = Client::connect(server.local_addr());
client.call(json!({"id": 1, "method": "events.subscribe"}));
let r = client.call(execute(
"settings.set",
json!({"key": "php.executable", "value": missing.display().to_string()}),
));
assert!(r["error"].is_null(), "{r}");
let _pump = Pump::start(backend.clone());
let r = client.call(execute("toolchain.status", Value::Null));
let status = &r["result"];
assert_eq!(status["php"]["found"], false, "{r}");
assert!(status["php"].get("path").is_some());
assert!(status["php"].get("version").is_some());
assert_eq!(status["phpactor"]["state"], "missing");
let changed = client.event(|e| e["kind"] == "toolchainChanged");
assert_eq!(changed["php"]["found"], false, "{changed}");
assert!(
changed["php"]["error"]
.as_str()
.unwrap()
.contains("php.executable"),
"{changed}"
);
assert_eq!(changed["phpactor"]["state"], "missing");
let note = client.event(|e| e["kind"] == "notification");
assert_eq!(note["messageKey"], "notification.toolchain.phpMissing");
assert_eq!(note["level"], "warning");
assert_eq!(note["params"]["min"], "8.2.0");
let r = client.call(execute("toolchain.status", Value::Null));
assert_eq!(
r["result"],
changed
.as_object()
.map(|o| {
let mut o = o.clone();
o.remove("kind");
Value::Object(o)
})
.unwrap()
);
let r = client.call(execute("toolchain.downloadPhpactor", Value::Null));
assert_eq!(r["error"]["code"], "failed", "{r}");
}

View file

@ -13,6 +13,7 @@ layer = 4
[dependencies]
lutra-index.workspace = true
lutra-lsp.workspace = true
lutra-search.workspace = true
lutra-syntax.workspace = true
lutra-text.workspace = true

View file

@ -11,6 +11,7 @@ pub mod search;
mod settings;
pub mod syntax;
pub mod theme;
pub mod toolchain;
pub mod ui;
use crate::{EngineError, Registry};
@ -49,5 +50,7 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> {
registry.register(Box::new(goto::Class))?;
registry.register(Box::new(goto::Symbol))?;
registry.register(Box::new(syntax::OutlineCommand))?;
registry.register(Box::new(toolchain::Status))?;
registry.register(Box::new(toolchain::DownloadPhpactor))?;
Ok(())
}

View file

@ -19,7 +19,7 @@ impl Command for List {
label: "List Settings",
menu_path: None,
default_shortcut: None,
params: "none; returns [{ key, type: enum|int, default, enumValues?, min?, max?, labelKey, descriptionKey, section }]",
params: "none; returns [{ key, type: enum|int|bool|string, default, enumValues?, min?, max?, labelKey, descriptionKey, section }]",
}
}

View file

@ -0,0 +1,886 @@
//! 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<String>,
/// Its version, `major.minor.patch`.
pub version: Option<String>,
/// Why PHP is not usable.
#[serde(skip_serializing_if = "Option::is_none")]
pub error: Option<String>,
}
/// 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<String>,
/// Its version; absent for a `phpactor.path` of unknown version.
#[serde(skip_serializing_if = "Option::is_none")]
pub version: Option<String>,
/// What failed.
#[serde(skip_serializing_if = "Option::is_none")]
pub error: Option<String>,
}
/// 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<Source>,
/// The worker, started with the first job.
worker: Option<Worker>,
/// The settings the last job ran with; `None` before the first job.
config: Option<Config>,
/// The project root the last job saw.
root: Option<PathBuf>,
}
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);
}
}
/// 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 engine's data directory.
data_dir: Option<PathBuf>,
}
/// 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<Source>,
}
/// 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<PhpStatus>,
/// New Phpactor status.
phpactor: Option<PhpactorStatus>,
/// A step to tell the user about.
notice: Option<Notice>,
}
/// The worker thread's channels.
#[derive(Debug)]
struct Worker {
/// Jobs to it.
jobs: Sender<Job>,
/// Reports from it.
reports: Receiver<Report>,
}
/// 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.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<Worker> {
let (jobs, job_rx) = mpsc::channel::<Job>();
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<Report>) -> 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: 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<String>) -> 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<Outcome, EngineError> {
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<Outcome, EngineError> {
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<u8>) -> 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<Event> {
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<String> {
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"<?php // fake phar".to_vec();
let url = serve_once(body.clone());
let mut engine = engine(dir.path());
engine
.execute("settings.set", json!({"key": "php.executable", "value": dir.path().join("no/php").display().to_string()}))
.unwrap();
engine.allow_downloads_from(Source {
url,
version: "9.9.9".into(),
sha256: Hash::of_bytes(&body),
https_only: false,
});
let out = engine
.execute("toolchain.downloadPhpactor", Value::Null)
.unwrap();
assert_eq!(out.value, json!({"started": true}));
let events = pump_until(&mut engine, |ev| {
last_status(ev).is_some_and(|s| s.phpactor.state == PhpactorState::Ready)
});
let path = phpactor::managed_path(&dir.path().join("data"), "9.9.9");
assert_eq!(std::fs::read(&path).unwrap(), body);
let status = last_status(&events).unwrap();
assert_eq!(
status.phpactor.path.as_deref(),
Some(path.display().to_string().as_str())
);
assert_eq!(status.phpactor.version.as_deref(), Some("9.9.9"));
assert!(!status.php.found);
assert_eq!(
keys(&events),
vec![
"notification.toolchain.phpMissing",
"notification.toolchain.downloadStarted",
"notification.toolchain.downloadDone",
]
);
let status = engine.execute("toolchain.status", Value::Null).unwrap();
assert_eq!(status.value["phpactor"]["state"], "ready");
}
#[test]
fn a_tampered_download_fails_and_writes_nothing() {
let dir = tempfile::tempdir().unwrap();
let url = serve_once(b"tampered".to_vec());
let mut engine = engine(dir.path());
engine.allow_downloads_from(Source {
url,
version: "9.9.9".into(),
sha256: Hash::of_bytes(b"genuine"),
https_only: false,
});
engine
.execute("toolchain.downloadPhpactor", Value::Null)
.unwrap();
let events = pump_until(&mut engine, |ev| {
last_status(ev).is_some_and(|s| s.phpactor.state == PhpactorState::Failed)
});
let status = last_status(&events).unwrap();
assert!(
status
.phpactor
.error
.as_deref()
.unwrap()
.contains("SHA-256 mismatch"),
"{status:?}"
);
assert!(keys(&events).contains(&"notification.toolchain.downloadFailed".to_string()));
assert!(
!dir.path()
.join("data/tools/phpactor/9.9.9")
.join("phpactor.phar")
.exists()
);
}
#[test]
fn configured_phar_and_disabled_auto_download() {
let dir = tempfile::tempdir().unwrap();
let mut engine = engine(dir.path());
engine
.execute(
"settings.set",
json!({"key": "phpactor.autoDownload", "value": false}),
)
.unwrap();
engine.execute("toolchain.status", Value::Null).unwrap();
let events = pump_until(&mut engine, |ev| {
last_status(ev).is_some_and(|s| s.phpactor.state == PhpactorState::Disabled)
});
assert!(last_status(&events).is_some());
let phar = dir.path().join("own.phar");
std::fs::write(&phar, b"x").unwrap();
engine
.execute(
"settings.set",
json!({"key": "phpactor.path", "value": phar.display().to_string()}),
)
.unwrap();
let events = pump_until(&mut engine, |ev| {
last_status(ev).is_some_and(|s| s.phpactor.state == PhpactorState::Ready)
});
let status = last_status(&events).unwrap();
assert_eq!(status.phpactor.version, None);
assert_eq!(
status.phpactor.path.as_deref(),
Some(phar.display().to_string().as_str())
);
}
#[test]
fn a_verified_managed_phar_is_ready_without_download() {
let dir = tempfile::tempdir().unwrap();
let body = b"already here".to_vec();
let path = phpactor::managed_path(&dir.path().join("data"), "1.0.0");
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, &body).unwrap();
let mut engine = engine(dir.path());
engine.allow_downloads_from(Source {
url: "http://127.0.0.1:9/never".into(),
version: "1.0.0".into(),
sha256: Hash::of_bytes(&body),
https_only: false,
});
engine.execute("toolchain.status", Value::Null).unwrap();
let events = pump_until(&mut engine, |ev| {
last_status(ev).is_some_and(|s| s.phpactor.state == PhpactorState::Ready)
});
assert!(!keys(&events).iter().any(|k| k.contains("download")));
}
#[test]
fn merging_keeps_the_strongest_mode() {
let config = Config {
php: String::new(),
phpactor_path: String::new(),
auto_download: true,
data_dir: None,
};
let job = |mode| Job {
config: config.clone(),
mode,
source: None,
};
assert_eq!(merge(job(Mode::Force), job(Mode::Check)).mode, Mode::Force);
assert_eq!(
merge(job(Mode::Check), job(Mode::Auto(PathBuf::from("p")))).mode,
Mode::Auto(PathBuf::from("p"))
);
}
}

View file

@ -147,6 +147,7 @@ impl Engine {
cmd::search::pump(state);
cmd::goto::sync(state);
cmd::syntax::pump(state, std::time::Instant::now());
cmd::toolchain::pump(state);
Ok(())
})?;
Ok(state.take_events())
@ -219,6 +220,24 @@ impl Engine {
list
}
/// Allows the one network access Lutra makes: downloading the pinned
/// Phpactor release (owner decision D15, see [`cmd::toolchain`]). Without
/// this call the engine downloads nothing, which keeps tests offline.
///
/// # Errors
/// [`EngineError::Internal`] if the pinned hash is malformed.
pub fn allow_downloads(&mut self) -> Result<(), EngineError> {
let source = lutra_lsp::toolchain::phpactor::pinned().map_err(EngineError::Internal)?;
self.allow_downloads_from(source);
Ok(())
}
/// Allows Phpactor downloads from `source` instead of the pinned
/// release, for tests against a local server.
pub fn allow_downloads_from(&mut self, source: lutra_lsp::toolchain::download::Source) {
self.state.toolchain.allow_downloads(source);
}
/// Read access to the state.
pub fn state(&self) -> &State {
&self.state
@ -393,6 +412,8 @@ mod tests {
"test.disabled",
"theme.list",
"theme.systemPreference",
"toolchain.downloadPhpactor",
"toolchain.status",
"ui.registerCommands",
]
);

View file

@ -194,6 +194,9 @@ pub enum Event {
/// Buffer id.
id: u64,
},
/// PHP or Phpactor changed: `{php, phpactor}` as `toolchain.status`
/// returns it.
ToolchainChanged(crate::cmd::toolchain::ToolchainStatus),
}
/// One match of [`Event::SearchResults`]. Positions are 0-based; columns

View file

@ -34,15 +34,24 @@ pub enum Kind {
/// Largest allowed value.
max: i64,
},
/// `true` or `false`.
Bool,
/// Any string of at most `max_len` bytes, such as a file path.
Str {
/// Longest accepted value in bytes.
max_len: usize,
},
}
/// The default value of a setting.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DefaultValue {
/// A string, for [`Kind::Enum`].
/// A string, for [`Kind::Enum`] and [`Kind::Str`].
Str(&'static str),
/// An integer, for [`Kind::Int`].
Int(i64),
/// A boolean, for [`Kind::Bool`].
Bool(bool),
}
impl DefaultValue {
@ -51,6 +60,7 @@ impl DefaultValue {
match self {
Self::Str(s) => Value::from(s),
Self::Int(i) => Value::from(i),
Self::Bool(b) => Value::from(b),
}
}
}
@ -100,6 +110,17 @@ impl Def {
self.key
)),
},
Kind::Bool => match value {
Value::Bool(_) => Ok(()),
_ => Err(format!("{} must be true or false, got {value}", self.key)),
},
Kind::Str { max_len } => match value.as_str() {
Some(s) if s.len() <= max_len && !s.contains(char::from(0)) => Ok(()),
_ => Err(format!(
"{} must be a string of at most {max_len} bytes without NUL",
self.key
)),
},
}
}
@ -108,6 +129,8 @@ impl Def {
let (kind, enum_values, min, max) = match self.kind {
Kind::Enum(values) => ("enum", Some(values.to_vec()), None, None),
Kind::Int { min, max } => ("int", None, Some(min), Some(max)),
Kind::Bool => ("bool", None, None, None),
Kind::Str { .. } => ("string", None, None, None),
};
SettingInfo {
key: self.key,
@ -129,7 +152,7 @@ impl Def {
pub struct SettingInfo {
/// Dotted key.
pub key: &'static str,
/// `enum` or `int`.
/// `enum`, `int`, `bool` or `string`.
#[serde(rename = "type")]
pub kind: &'static str,
/// Default value.
@ -177,6 +200,30 @@ pub const DEFS: &[Def] = &[
description_key: "settings.ui.language.description",
section: "appearance",
},
Def {
key: "php.executable",
kind: Kind::Str { max_len: 4096 },
default: DefaultValue::Str(""),
label_key: "settings.php.executable.label",
description_key: "settings.php.executable.description",
section: "php",
},
Def {
key: "phpactor.path",
kind: Kind::Str { max_len: 4096 },
default: DefaultValue::Str(""),
label_key: "settings.phpactor.path.label",
description_key: "settings.phpactor.path.description",
section: "php",
},
Def {
key: "phpactor.autoDownload",
kind: Kind::Bool,
default: DefaultValue::Bool(true),
label_key: "settings.phpactor.autoDownload.label",
description_key: "settings.phpactor.autoDownload.description",
section: "php",
},
];
/// Looks a known setting up by key.

View file

@ -41,6 +41,8 @@ pub struct State {
pub index: crate::cmd::goto::IndexState,
/// Syntax trees and outlines of open PHP buffers (`syntax.outline`).
pub syntax: crate::cmd::syntax::Syntax,
/// PHP and Phpactor (`toolchain.status`).
pub toolchain: crate::cmd::toolchain::Toolchain,
/// Number of notifications emitted, for their ids.
notifications: u64,
/// Events queued for the host, oldest first.

View file

@ -41,7 +41,17 @@ fn list_describes_the_c2_keys_with_catalog_keys_only() {
.iter()
.map(|s| s["key"].as_str().unwrap())
.collect();
assert_eq!(keys, ["appearance.theme", "editor.fontSize", "ui.language"]);
assert_eq!(
keys,
[
"appearance.theme",
"editor.fontSize",
"ui.language",
"php.executable",
"phpactor.path",
"phpactor.autoDownload"
]
);
for s in list.as_array().unwrap() {
assert!(s.get("label").is_none());
assert!(s["labelKey"].as_str().unwrap().starts_with("settings."));
@ -55,6 +65,40 @@ fn list_describes_the_c2_keys_with_catalog_keys_only() {
assert_eq!(list[1]["type"], "int");
assert_eq!(list[1]["default"], 14);
assert_eq!(list[2]["enumValues"], json!(["en"]));
assert_eq!(list[3]["type"], "string");
assert_eq!(list[3]["default"], "");
assert_eq!(list[5]["type"], "bool");
assert_eq!(list[5]["default"], true);
assert_eq!(list[5]["section"], "php");
}
#[test]
fn string_and_bool_settings_are_validated() {
let mut e = Engine::new().unwrap();
for (key, bad) in [
("php.executable", json!(3)),
("php.executable", json!("x".repeat(4097))),
("php.executable", json!(format!("a{}b", char::from(0)))),
("phpactor.autoDownload", json!("yes")),
] {
let err = e
.execute("settings.set", json!({"key": key, "value": bad}))
.unwrap_err();
assert_eq!(err.code(), "invalid_params", "{key}");
}
e.execute(
"settings.set",
json!({"key": "phpactor.autoDownload", "value": false}),
)
.unwrap();
e.execute(
"settings.set",
json!({"key": "php.executable", "value": "C:/PHP/php.exe"}),
)
.unwrap();
let values = get_all(&mut e);
assert_eq!(values["phpactor.autoDownload"], false);
assert_eq!(values["php.executable"], "C:/PHP/php.exe");
}
#[test]
@ -62,7 +106,14 @@ fn get_set_reset_and_events() {
let mut e = Engine::new().unwrap();
assert_eq!(
get_all(&mut e),
json!({"appearance.theme": "system", "editor.fontSize": 14, "ui.language": "en"})
json!({
"appearance.theme": "system",
"editor.fontSize": 14,
"ui.language": "en",
"php.executable": "",
"phpactor.path": "",
"phpactor.autoDownload": true
})
);
let out = e
.execute(

View file

@ -19,7 +19,13 @@ doc = false
[dependencies]
lutra-text.workspace = true
lutra-vfs.workspace = true
ring = "0.17.14"
rustls = { version = "0.23.22", default-features = false, features = ["ring", "std", "tls12"] }
rustls-native-certs = "0.8.5"
serde_json = "1.0.154"
thiserror = "2.0.21"
ureq = { version = "3.4.2", default-features = false, features = ["rustls-no-provider"] }
[dev-dependencies]
proptest.workspace = true

View file

@ -10,12 +10,14 @@
//! - [`types`]: the LSP structures the client parses (diagnostics,
//! locations, workspace edits), read leniently and capped.
//! - [`uri`]: `file:` URIs from and to paths.
//! - [`toolchain`]: the user's PHP and the pinned, verified Phpactor PHAR.
mod capabilities;
mod documents;
mod error;
pub mod jsonrpc;
mod server;
pub mod toolchain;
pub mod types;
pub mod uri;

View file

@ -0,0 +1,533 @@
//! Downloading a pinned file: the only network access in Lutra.
//!
//! [`install`] fetches a [`Source`] over HTTP(S) with `ureq` (pure Rust,
//! `rustls` with the `ring` provider, certificates checked against the
//! operating system's trusted roots, loaded with `rustls-native-certs`). The body is
//! read into memory with a size cap and its SHA-256 compared with the
//! pinned hash; only a verified body is written, atomically
//! ([`lutra_vfs::write_atomic`]), so the target path never holds a partial
//! or unverified file. [`install_with_retry`] retries network failures and
//! server errors with exponential backoff; a hash mismatch, an oversized
//! body or a client error is final.
use std::fmt;
use std::io::Read;
use std::path::Path;
use std::sync::Arc;
use std::time::{Duration, Instant};
use ureq::tls::{Certificate, RootCerts, TlsConfig, TlsProvider};
/// Connect timeout of one attempt.
pub const CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
/// Time limit of one attempt, from connecting to the last byte.
pub const ATTEMPT_TIMEOUT: Duration = Duration::from_secs(300);
/// Most redirects followed (GitHub release assets redirect once).
pub const MAX_REDIRECTS: u32 = 5;
/// A SHA-256 digest.
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct Hash([u8; 32]);
impl Hash {
/// Parses 64 hex digits, either case; `None` otherwise.
pub fn from_hex(hex: &str) -> Option<Self> {
let bytes = hex.as_bytes();
if bytes.len() != 64 {
return None;
}
let mut out = [0u8; 32];
let (pairs, _) = bytes.as_chunks::<2>();
for (slot, [hi, lo]) in out.iter_mut().zip(pairs) {
*slot = nibble(*hi)?.checked_mul(16)?.checked_add(nibble(*lo)?)?;
}
Some(Self(out))
}
/// Lowercase hex.
pub fn to_hex(&self) -> String {
self.0.iter().map(|b| format!("{b:02x}")).collect()
}
/// The SHA-256 of `bytes`.
pub fn of_bytes(bytes: &[u8]) -> Self {
let mut context = ring::digest::Context::new(&ring::digest::SHA256);
context.update(bytes);
Self::of(context)
}
/// Finishes a SHA-256 `context`.
pub fn of(context: ring::digest::Context) -> Self {
let digest = context.finish();
let mut out = [0u8; 32];
for (slot, b) in out.iter_mut().zip(digest.as_ref()) {
*slot = *b;
}
Self(out)
}
}
impl fmt::Debug for Hash {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "Hash({})", self.to_hex())
}
}
/// The value of one hex digit.
fn nibble(c: u8) -> Option<u8> {
match c {
b'0'..=b'9' => Some(c - b'0'),
b'a'..=b'f' => Some(c - b'a' + 10),
b'A'..=b'F' => Some(c - b'A' + 10),
_ => None,
}
}
/// What to download and how to check it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Source {
/// The URL.
pub url: String,
/// The version it holds, for messages and the install path.
pub version: String,
/// The expected SHA-256 of the body.
pub sha256: Hash,
/// Refuse plain HTTP, also on redirects. Always set for real downloads;
/// tests against a local server clear it.
pub https_only: bool,
}
/// Why a download failed.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum DownloadError {
/// Connecting, TLS, a timeout or reading the body failed.
#[error("network error: {0}")]
Network(String),
/// The server answered with an error status.
#[error("the server answered HTTP {0}")]
Status(u16),
/// The body is larger than allowed.
#[error("the file is larger than {0} bytes")]
TooLarge(u64),
/// The body does not have the pinned hash; it was not written.
#[error("SHA-256 mismatch: expected {expected}, got {actual}; the file was discarded")]
HashMismatch {
/// The pinned hash, hex.
expected: String,
/// The hash of what arrived, hex.
actual: String,
},
/// Writing the verified file failed.
#[error("cannot write {path}: {reason}")]
Write {
/// The target.
path: String,
/// The I/O error.
reason: String,
},
}
impl DownloadError {
/// Whether another attempt may succeed: network errors, server errors
/// (5xx), 408 and 429.
pub fn retryable(&self) -> bool {
match self {
Self::Network(_) => true,
Self::Status(code) => *code >= 500 || *code == 408 || *code == 429,
Self::TooLarge(_) | Self::HashMismatch { .. } | Self::Write { .. } => false,
}
}
}
/// How often and how patiently to retry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Retry {
/// Attempts in total, at least 1.
pub attempts: u32,
/// Wait before the second attempt; doubled for each further one.
pub first_delay: Duration,
/// Longest wait between attempts.
pub max_delay: Duration,
}
impl Default for Retry {
/// Four attempts, waiting 2 s, 4 s and 8 s in between.
fn default() -> Self {
Self {
attempts: 4,
first_delay: Duration::from_secs(2),
max_delay: Duration::from_secs(30),
}
}
}
/// What a successful download took.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Stats {
/// Bytes written.
pub bytes: u64,
/// Attempts made, the successful one included.
pub attempts: u32,
/// Wall time from the first attempt to the written file.
pub elapsed: Duration,
}
/// Downloads `source` to `dest` with [`install`], retrying retryable
/// failures as `retry` says. `on_retry` is called before each wait with the
/// attempt that failed (1-based) and its error.
///
/// # Errors
/// The last attempt's error, or the first final one.
pub fn install_with_retry(
source: &Source,
dest: &Path,
max_size: u64,
retry: Retry,
mut on_retry: impl FnMut(u32, &DownloadError),
) -> Result<Stats, DownloadError> {
let started = Instant::now();
let attempts = retry.attempts.max(1);
let mut delay = retry.first_delay;
let mut attempt = 1u32;
loop {
match install(source, dest, max_size) {
Ok(bytes) => {
return Ok(Stats {
bytes,
attempts: attempt,
elapsed: started.elapsed(),
});
}
Err(e) if e.retryable() && attempt < attempts => {
on_retry(attempt, &e);
std::thread::sleep(delay.min(retry.max_delay));
delay = delay.saturating_mul(2);
attempt = attempt.saturating_add(1);
}
Err(e) => return Err(e),
}
}
}
/// Downloads `source`, checks the size and the SHA-256, creates `dest`'s
/// directory and writes the verified bytes to `dest` atomically. Nothing is
/// written unless the hash matches.
///
/// # Returns
/// The number of bytes written.
///
/// # Errors
/// [`DownloadError`] saying what failed.
pub fn install(source: &Source, dest: &Path, max_size: u64) -> Result<u64, DownloadError> {
let bytes = fetch(source, max_size)?;
let actual = Hash::of_bytes(&bytes);
if actual != source.sha256 {
return Err(DownloadError::HashMismatch {
expected: source.sha256.to_hex(),
actual: actual.to_hex(),
});
}
let write_error = |reason: String| DownloadError::Write {
path: dest.display().to_string(),
reason,
};
if let Some(parent) = dest.parent() {
std::fs::create_dir_all(parent).map_err(|e| write_error(e.to_string()))?;
}
lutra_vfs::write_atomic(dest, &bytes).map_err(|e| write_error(e.to_string()))?;
Ok(u64::try_from(bytes.len()).unwrap_or(u64::MAX))
}
/// Fetches the body of `source.url`, at most `max_size` bytes.
///
/// # Errors
/// [`DownloadError::Network`], [`DownloadError::Status`] or
/// [`DownloadError::TooLarge`].
pub fn fetch(source: &Source, max_size: u64) -> Result<Vec<u8>, DownloadError> {
let agent = agent(source.https_only);
let response = agent.get(&source.url).call().map_err(|e| match e {
ureq::Error::StatusCode(code) => DownloadError::Status(code),
other => DownloadError::Network(other.to_string()),
})?;
let mut body = response.into_body();
if body.content_length().is_some_and(|n| n > max_size) {
return Err(DownloadError::TooLarge(max_size));
}
let mut bytes = Vec::new();
body.as_reader()
.take(max_size.saturating_add(1))
.read_to_end(&mut bytes)
.map_err(|e| DownloadError::Network(e.to_string()))?;
if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > max_size {
return Err(DownloadError::TooLarge(max_size));
}
Ok(bytes)
}
/// The HTTP agent: rustls with the `ring` provider, the operating system's
/// trusted root certificates ([`native_roots`]), the timeouts and redirect
/// limit above, proxies from the environment (`HTTPS_PROXY`, `ALL_PROXY`,
/// `NO_PROXY`), no cookies.
///
/// `rustls-platform-verifier` would ask the OS verifier directly, but it
/// pulls `webpki-root-certs` (CDLA-Permissive-2.0, outside Lutra's allowed
/// licences) into the graph, so the roots are loaded instead.
fn agent(https_only: bool) -> ureq::Agent {
let tls = TlsConfig::builder()
.provider(TlsProvider::Rustls)
.root_certs(RootCerts::Specific(Arc::new(native_roots())))
.unversioned_rustls_crypto_provider(Arc::new(rustls::crypto::ring::default_provider()))
.build();
ureq::Agent::config_builder()
.https_only(https_only)
.max_redirects(MAX_REDIRECTS)
.timeout_connect(Some(CONNECT_TIMEOUT))
.timeout_global(Some(ATTEMPT_TIMEOUT))
.user_agent(concat!("Lutra/", env!("CARGO_PKG_VERSION")))
.tls_config(tls)
.build()
.into()
}
/// The trusted root certificates of the operating system (Windows
/// certificate store, macOS keychain, the usual files on Linux or
/// `SSL_CERT_FILE` / `SSL_CERT_DIR`). Certificates that fail to load are
/// skipped; with none at all every HTTPS connection fails with a
/// certificate error, which is reported as a network error.
fn native_roots() -> Vec<Certificate<'static>> {
rustls_native_certs::load_native_certs()
.certs
.iter()
.map(|der| Certificate::from_der(der.as_ref()).to_owned())
.collect()
}
#[cfg(test)]
mod tests {
use std::io::Write;
use std::net::TcpListener;
use std::sync::Mutex;
use super::*;
/// One canned answer of the test server.
enum Reply {
/// A full response with status and body.
Ok(Vec<u8>),
/// An error status without body.
Status(u16),
/// A 200 response without Content-Length whose body ends with the
/// connection.
Unsized(Vec<u8>),
}
/// A local HTTP server that answers each request with the next reply
/// and counts requests. No real network.
fn serve(replies: Vec<Reply>) -> (String, Arc<Mutex<usize>>) {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let url = format!("http://{}/phpactor.phar", listener.local_addr().unwrap());
let count = Arc::new(Mutex::new(0));
let seen = count.clone();
std::thread::spawn(move || {
for reply in replies {
let Ok((mut stream, _)) = listener.accept() else {
return;
};
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]);
}
*seen.lock().unwrap() += 1;
let _ = match reply {
Reply::Ok(body) => stream
.write_all(
format!(
"HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
body.len()
)
.as_bytes(),
)
.and_then(|_| stream.write_all(&body)),
Reply::Status(code) => stream.write_all(
format!(
"HTTP/1.1 {code} Nope\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
)
.as_bytes(),
),
Reply::Unsized(body) => stream
.write_all(b"HTTP/1.1 200 OK\r\nConnection: close\r\n\r\n")
.and_then(|_| stream.write_all(&body)),
};
}
});
(url, count)
}
fn source(url: &str, body: &[u8]) -> Source {
Source {
url: url.to_string(),
version: "9.9.9".into(),
sha256: Hash::of_bytes(body),
https_only: false,
}
}
fn quick() -> Retry {
Retry {
attempts: 3,
first_delay: Duration::from_millis(10),
max_delay: Duration::from_millis(20),
}
}
#[test]
fn hex_round_trip_and_rejects() {
let h = Hash::of_bytes(b"abc");
assert_eq!(
h.to_hex(),
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
);
assert_eq!(Hash::from_hex(&h.to_hex().to_uppercase()), Some(h));
assert_eq!(Hash::from_hex("ab"), None);
assert_eq!(Hash::from_hex(&"g".repeat(64)), None);
assert_eq!(Hash::from_hex(&"é".repeat(32)), None);
}
#[test]
fn installs_a_verified_file() {
let body = b"<?php // phar".repeat(1000);
let (url, count) = serve(vec![Reply::Ok(body.clone())]);
let dir = tempfile::tempdir().unwrap();
let dest = dir.path().join("tools/phpactor/9.9.9/phpactor.phar");
let stats =
install_with_retry(&source(&url, &body), &dest, 1 << 20, quick(), |_, _| {}).unwrap();
assert_eq!(std::fs::read(&dest).unwrap(), body);
assert_eq!(stats.bytes, body.len() as u64);
assert_eq!(stats.attempts, 1);
assert_eq!(*count.lock().unwrap(), 1);
let names: Vec<_> = std::fs::read_dir(dest.parent().unwrap())
.unwrap()
.map(|e| e.unwrap().file_name())
.collect();
assert_eq!(names, vec!["phpactor.phar"], "no temporary files left");
}
#[test]
fn hash_mismatch_is_rejected_and_keeps_the_old_file() {
let (url, count) = serve(vec![Reply::Ok(b"tampered".to_vec())]);
let dir = tempfile::tempdir().unwrap();
let dest = dir.path().join("phpactor.phar");
std::fs::write(&dest, b"old").unwrap();
let err = install_with_retry(
&source(&url, b"genuine"),
&dest,
1 << 20,
quick(),
|_, _| {},
)
.unwrap_err();
assert!(matches!(err, DownloadError::HashMismatch { .. }), "{err:?}");
assert!(!err.retryable());
assert_eq!(*count.lock().unwrap(), 1, "a mismatch is not retried");
assert_eq!(std::fs::read(&dest).unwrap(), b"old");
assert_eq!(std::fs::read_dir(dir.path()).unwrap().count(), 1);
}
#[test]
fn missing_target_stays_missing_on_mismatch() {
let (url, _) = serve(vec![Reply::Ok(b"tampered".to_vec())]);
let dir = tempfile::tempdir().unwrap();
let dest = dir.path().join("v/phpactor.phar");
assert!(install(&source(&url, b"genuine"), &dest, 1 << 20).is_err());
assert!(!dest.exists());
}
#[test]
fn retries_server_errors_with_backoff() {
let body = b"payload".to_vec();
let (url, count) = serve(vec![
Reply::Status(503),
Reply::Status(500),
Reply::Ok(body.clone()),
]);
let dir = tempfile::tempdir().unwrap();
let dest = dir.path().join("phpactor.phar");
let mut failures = Vec::new();
let stats = install_with_retry(&source(&url, &body), &dest, 1 << 20, quick(), |n, e| {
failures.push((n, e.clone()))
})
.unwrap();
assert_eq!(stats.attempts, 3);
assert_eq!(*count.lock().unwrap(), 3);
assert_eq!(
failures,
vec![
(1, DownloadError::Status(503)),
(2, DownloadError::Status(500))
]
);
assert_eq!(std::fs::read(&dest).unwrap(), body);
}
#[test]
fn client_errors_are_final() {
let (url, count) = serve(vec![Reply::Status(404), Reply::Status(404)]);
let dir = tempfile::tempdir().unwrap();
let err = install_with_retry(
&source(&url, b"x"),
&dir.path().join("p"),
1 << 20,
quick(),
|_, _| {},
)
.unwrap_err();
assert_eq!(err, DownloadError::Status(404));
assert_eq!(*count.lock().unwrap(), 1);
}
#[test]
fn size_cap_applies_with_and_without_content_length() {
let body = vec![b'x'; 2048];
let (url, _) = serve(vec![Reply::Ok(body.clone()), Reply::Unsized(body.clone())]);
let dir = tempfile::tempdir().unwrap();
let dest = dir.path().join("phpactor.phar");
let src = source(&url, &body);
assert_eq!(
install(&src, &dest, 1024),
Err(DownloadError::TooLarge(1024))
);
assert_eq!(
install(&src, &dest, 1024),
Err(DownloadError::TooLarge(1024))
);
assert!(!dest.exists());
}
#[test]
fn https_only_refuses_plain_http_without_a_request() {
let (url, count) = serve(vec![Reply::Ok(b"x".to_vec())]);
let mut src = source(&url, b"x");
src.https_only = true;
let dir = tempfile::tempdir().unwrap();
let err = install(&src, &dir.path().join("p"), 1 << 20).unwrap_err();
assert!(matches!(err, DownloadError::Network(_)), "{err:?}");
std::thread::sleep(Duration::from_millis(50));
assert_eq!(*count.lock().unwrap(), 0);
}
#[test]
fn unreachable_server_is_a_network_error() {
let port = TcpListener::bind("127.0.0.1:0")
.unwrap()
.local_addr()
.unwrap()
.port();
let src = source(&format!("http://127.0.0.1:{port}/x"), b"x");
let dir = tempfile::tempdir().unwrap();
let err = install(&src, &dir.path().join("p"), 1 << 20).unwrap_err();
assert!(err.retryable(), "{err:?}");
}
}

View file

@ -0,0 +1,118 @@
//! The toolchain Lutra needs for PHP language features: the user's PHP
//! and a Phpactor PHAR (owner decision D15).
//!
//! - [`php`] finds the PHP executable (a setting or `PATH`), runs `php -v`
//! with a timeout and checks the version. Its output is untrusted.
//! - [`phpactor`] knows the pinned Phpactor release (version, URL,
//! SHA-256), where Lutra keeps it (`<data_dir>/tools/phpactor/<version>/`)
//! and verifies a file against the pinned hash.
//! - [`download`] fetches a file over HTTPS (pure Rust: `ureq` with
//! `rustls`, roots from the operating system), capped in size, verified
//! against a SHA-256 before it is written atomically, with retries and
//! backoff. It is the only network access in Lutra; nothing in this crate
//! starts it on its own.
//! - [`has_php_files`] tells whether a project contains PHP code, which is
//! when Lutra downloads Phpactor.
//!
//! Every function here blocks (process runs, file hashing, network), so
//! callers run them off the engine lock.
pub mod download;
pub mod php;
pub mod phpactor;
use std::path::Path;
/// Directory names [`has_php_files`] does not descend into.
const SKIPPED_DIRS: &[&str] = &["vendor", "node_modules", ".git", ".idea", "var", "storage"];
/// Most directory entries [`has_php_files`] looks at.
pub const MAX_SCAN_ENTRIES: usize = 20_000;
/// Deepest directory level [`has_php_files`] looks at; the root is 0.
pub const MAX_SCAN_DEPTH: usize = 6;
/// Whether `root` contains PHP code: a `composer.json` at the root or a file
/// with a PHP extension (`php`, `phtml`, `inc`) within [`MAX_SCAN_DEPTH`]
/// levels, looking at no more than [`MAX_SCAN_ENTRIES`] entries. Hidden
/// directories, dependency and cache directories ([`SKIPPED_DIRS`]) and
/// symbolic links are skipped. Directories that cannot be read are skipped
/// too, since the answer only decides whether a download is worth it.
pub fn has_php_files(root: &Path) -> bool {
if root.join("composer.json").is_file() {
return true;
}
let mut queue = std::collections::VecDeque::from([(root.to_path_buf(), 0usize)]);
let mut seen = 0usize;
while let Some((dir, depth)) = queue.pop_front() {
let Ok(entries) = std::fs::read_dir(&dir) else {
continue;
};
for entry in entries.flatten() {
seen = seen.saturating_add(1);
if seen > MAX_SCAN_ENTRIES {
return false;
}
let Ok(kind) = entry.file_type() else {
continue;
};
let name = entry.file_name();
let name = name.to_string_lossy();
if kind.is_file() && is_php_name(&name) {
return true;
}
if kind.is_dir()
&& depth < MAX_SCAN_DEPTH
&& !name.starts_with('.')
&& !SKIPPED_DIRS.contains(&name.as_ref())
{
queue.push_back((entry.path(), depth.saturating_add(1)));
}
}
}
false
}
/// Whether a file name has a PHP extension, ignoring case.
fn is_php_name(name: &str) -> bool {
let Some((_, ext)) = name.rsplit_once('.') else {
return false;
};
["php", "phtml", "inc"]
.iter()
.any(|e| ext.eq_ignore_ascii_case(e))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn finds_php_files_and_composer_projects() {
let dir = tempfile::tempdir().unwrap();
assert!(!has_php_files(dir.path()));
std::fs::create_dir_all(dir.path().join("vendor/x")).unwrap();
std::fs::write(dir.path().join("vendor/x/a.php"), "<?php").unwrap();
std::fs::write(dir.path().join("readme.md"), "hi").unwrap();
assert!(!has_php_files(dir.path()), "vendor is skipped");
std::fs::create_dir_all(dir.path().join("src/App")).unwrap();
std::fs::write(dir.path().join("src/App/User.PHP"), "<?php").unwrap();
assert!(has_php_files(dir.path()));
let other = tempfile::tempdir().unwrap();
std::fs::write(other.path().join("composer.json"), "{}").unwrap();
assert!(has_php_files(other.path()));
}
#[test]
fn stops_at_the_depth_cap() {
let dir = tempfile::tempdir().unwrap();
let mut deep = dir.path().to_path_buf();
for i in 0..=MAX_SCAN_DEPTH {
deep.push(format!("d{i}"));
}
std::fs::create_dir_all(&deep).unwrap();
std::fs::write(deep.join("a.php"), "<?php").unwrap();
assert!(!has_php_files(dir.path()));
}
}

View file

@ -0,0 +1,371 @@
//! Finding the user's PHP and checking its version.
//!
//! Lutra does not ship PHP (owner decision D15). The executable comes from
//! the `php.executable` setting or from `PATH`; [`detect`] runs `php -v`
//! with a timeout and parses the first line. The output is untrusted: it is
//! read with a size cap, and anything that does not look like a PHP
//! version line is an error, never a crash.
use std::ffi::OsString;
use std::fmt;
use std::io::Read;
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::mpsc;
use std::time::{Duration, Instant};
/// Oldest PHP the pinned Phpactor release runs on
/// ([`super::phpactor::VERSION`] declares `"php": "^8.2"` in its
/// `composer.json`).
pub const MIN_VERSION: PhpVersion = PhpVersion {
major: 8,
minor: 2,
patch: 0,
};
/// How long `php -v` may take.
pub const PROBE_TIMEOUT: Duration = Duration::from_secs(5);
/// Most bytes of `php -v` output that are read.
pub const MAX_OUTPUT: u64 = 64 * 1024;
/// A PHP version, `major.minor.patch`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PhpVersion {
/// Major version, e.g. 8.
pub major: u32,
/// Minor version, e.g. 4.
pub minor: u32,
/// Patch level, e.g. 24; 0 when the output had none.
pub patch: u32,
}
impl fmt::Display for PhpVersion {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
}
}
/// A PHP executable that runs and is new enough.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Php {
/// The executable.
pub path: PathBuf,
/// Its version.
pub version: PhpVersion,
}
/// Why no usable PHP was found.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum PhpError {
/// Neither the setting nor `PATH` names an existing executable.
#[error("{0}")]
NotFound(String),
/// The executable could not be run, timed out or failed.
#[error("{path}: {reason}")]
Failed {
/// The executable.
path: PathBuf,
/// What went wrong.
reason: String,
},
/// `php -v` did not print a PHP version line.
#[error("{path}: no PHP version in the output of php -v")]
NoVersion {
/// The executable.
path: PathBuf,
},
/// The version is older than [`MIN_VERSION`].
#[error("{path} is PHP {version}; Phpactor needs PHP {MIN_VERSION} or newer")]
TooOld {
/// The executable.
path: PathBuf,
/// Its version.
version: PhpVersion,
},
}
impl PhpError {
/// The executable the error is about, if one was found.
pub fn path(&self) -> Option<&Path> {
match self {
Self::NotFound(_) => None,
Self::Failed { path, .. } | Self::NoVersion { path } | Self::TooOld { path, .. } => {
Some(path)
}
}
}
/// The version found, for [`PhpError::TooOld`].
pub fn version(&self) -> Option<PhpVersion> {
match self {
Self::TooOld { version, .. } => Some(*version),
_ => None,
}
}
}
/// Finds PHP and checks it: the `setting` (`php.executable`; empty means
/// look in `PATH`), resolved with [`locate`], then `php -v` with
/// [`PROBE_TIMEOUT`].
///
/// # Errors
/// [`PhpError`] saying what is missing or wrong.
pub fn detect(setting: &str) -> Result<Php, PhpError> {
let path = locate(setting, std::env::var_os("PATH"))?;
let output = run_version(&path, PROBE_TIMEOUT)?;
let version =
parse_version(&output).ok_or_else(|| PhpError::NoVersion { path: path.clone() })?;
if version < MIN_VERSION {
return Err(PhpError::TooOld { path, version });
}
Ok(Php { path, version })
}
/// Resolves the PHP executable.
///
/// - `setting` is the `php.executable` value, trimmed. A value with a path
/// separator must name an existing file. A bare name (`php8.3`) is looked
/// up in `path_env` like the default.
/// - Empty: `php` is looked up in `path_env` (on Windows `php.exe`, then
/// `php.bat` and `php.cmd`).
///
/// # Errors
/// [`PhpError::NotFound`] with a message naming the setting.
pub fn locate(setting: &str, path_env: Option<OsString>) -> Result<PathBuf, PhpError> {
let setting = setting.trim();
if setting.contains(['/', '\\']) {
let path = PathBuf::from(setting);
return if path.is_file() {
Ok(path)
} else {
Err(PhpError::NotFound(format!(
"php.executable {setting} is not a file"
)))
};
}
let name = if setting.is_empty() { "php" } else { setting };
let dirs = path_env
.map(|p| std::env::split_paths(&p).collect::<Vec<_>>())
.unwrap_or_default();
dirs.iter()
.flat_map(|dir| candidates(name).into_iter().map(move |n| dir.join(n)))
.find(|p| p.is_file())
.ok_or_else(|| {
PhpError::NotFound(format!(
"{name} was not found in PATH; install PHP {MIN_VERSION} or newer or set php.executable"
))
})
}
/// File names that run `name` on this platform.
fn candidates(name: &str) -> Vec<String> {
if cfg!(windows) && !name.contains('.') {
["exe", "bat", "cmd"]
.iter()
.map(|ext| format!("{name}.{ext}"))
.collect()
} else {
vec![name.to_string()]
}
}
/// Runs `path -v` and returns at most [`MAX_OUTPUT`] bytes of its standard
/// output, killing it after `timeout`. On Windows no console window opens.
///
/// # Errors
/// [`PhpError::Failed`] if it cannot start, times out or exits with an
/// error.
pub fn run_version(path: &Path, timeout: Duration) -> Result<Vec<u8>, PhpError> {
let failed = |reason: String| PhpError::Failed {
path: path.to_path_buf(),
reason,
};
let mut command = Command::new(path);
command
.arg("-v")
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::null());
hide_window(&mut command);
let mut child = command.spawn().map_err(|e| failed(e.to_string()))?;
let stdout = child
.stdout
.take()
.ok_or_else(|| failed("no output pipe".into()))?;
let (tx, rx) = mpsc::channel();
std::thread::Builder::new()
.name("lutra-php-probe".into())
.spawn(move || {
let mut out = Vec::new();
let _ = stdout.take(MAX_OUTPUT).read_to_end(&mut out);
let _ = tx.send(out);
})
.map_err(|e| failed(e.to_string()))?;
let started = Instant::now();
let deadline = started.checked_add(timeout).unwrap_or(started);
let status = loop {
match child.try_wait() {
Ok(Some(status)) => break status,
Ok(None) if Instant::now() >= deadline => {
let _ = child.kill();
let _ = child.wait();
return Err(failed(format!(
"php -v did not finish within {} s",
timeout.as_secs()
)));
}
Ok(None) => std::thread::sleep(Duration::from_millis(10)),
Err(e) => return Err(failed(e.to_string())),
}
};
let out = rx
.recv_timeout(Duration::from_secs(1))
.map_err(|_| failed("its output did not end".into()))?;
if !status.success() {
return Err(failed(format!("php -v exited with {status}")));
}
Ok(out)
}
/// Keeps a console window from flashing up when a GUI app runs PHP on
/// Windows (`CREATE_NO_WINDOW`).
#[cfg(windows)]
fn hide_window(command: &mut Command) {
use std::os::windows::process::CommandExt;
command.creation_flags(0x0800_0000);
}
/// Nothing to hide outside Windows.
#[cfg(not(windows))]
fn hide_window(_command: &mut Command) {}
/// Finds the version in `php -v` output: the first line that starts with
/// `PHP ` followed by `major.minor` and optionally `.patch`, such as
/// `PHP 8.4.24 (cli) (built: …)` or `PHP 8.3.6-1ubuntu1 (cli)`. Lines before
/// it (startup warnings) are skipped. Numbers that overflow, missing parts
/// and invalid UTF-8 give `None` or are skipped, never a panic.
pub fn parse_version(output: &[u8]) -> Option<PhpVersion> {
let text = String::from_utf8_lossy(output);
text.lines().find_map(|line| {
let rest = line.trim_start().strip_prefix("PHP ")?;
let token = rest.split_whitespace().next()?;
let mut parts = token.splitn(3, '.');
let major = number(parts.next()?)?;
let minor = number(parts.next()?)?;
let patch = match parts.next() {
Some(p) => number(p)?,
None => 0,
};
Some(PhpVersion {
major,
minor,
patch,
})
})
}
/// The leading decimal digits of `part` as a number; `None` without digits
/// or on overflow.
fn number(part: &str) -> Option<u32> {
let end = part
.char_indices()
.find(|(_, c)| !c.is_ascii_digit())
.map_or(part.len(), |(i, _)| i);
part.get(..end)?.parse().ok()
}
#[cfg(test)]
mod tests {
use proptest::prelude::*;
use super::*;
fn v(major: u32, minor: u32, patch: u32) -> Option<PhpVersion> {
Some(PhpVersion {
major,
minor,
patch,
})
}
#[test]
fn parses_real_outputs() {
let windows = b"PHP 8.4.24 (cli) (built: Jul 29 2026 06:00:56) (ZTS Visual C++ 2022 x64)\r\nCopyright (c) The PHP Group\r\nZend Engine v4.4.24\r\n";
assert_eq!(parse_version(windows), v(8, 4, 24));
assert_eq!(
parse_version(b"PHP 8.3.6-1ubuntu1.2 (cli) (built: Jan 1 2026)"),
v(8, 3, 6)
);
assert_eq!(parse_version(b"PHP 8.5.0-dev (cli)"), v(8, 5, 0));
assert_eq!(
parse_version(b"PHP Warning: Module 'x' already loaded\nPHP 8.2.1 (cli)"),
v(8, 2, 1)
);
assert_eq!(parse_version(b"PHP 8.1 (cli)"), v(8, 1, 0));
}
#[test]
fn rejects_non_versions() {
assert_eq!(parse_version(b""), None);
assert_eq!(parse_version(b"HHVM 4.0"), None);
assert_eq!(parse_version(b"PHP x.y"), None);
assert_eq!(parse_version(b"PHP 99999999999.1.1"), None);
assert_eq!(parse_version(b"\xff\xfePHP"), None);
}
#[test]
fn version_order_and_minimum() {
assert!(v(8, 1, 30) < Some(MIN_VERSION));
assert!(v(8, 2, 0) >= Some(MIN_VERSION));
assert!(v(9, 0, 0) > Some(MIN_VERSION));
assert_eq!(MIN_VERSION.to_string(), "8.2.0");
}
#[test]
fn locate_reports_the_setting() {
let dir = tempfile::tempdir().unwrap();
let err = locate("", Some(dir.path().as_os_str().to_owned())).unwrap_err();
assert!(err.to_string().contains("php.executable"), "{err}");
let missing = dir.path().join("nope").join("php");
let err = locate(missing.to_str().unwrap(), None).unwrap_err();
assert!(matches!(err, PhpError::NotFound(_)));
let name = if cfg!(windows) { "php.exe" } else { "php" };
std::fs::write(dir.path().join(name), b"").unwrap();
let found = locate(" ", Some(dir.path().as_os_str().to_owned())).unwrap();
assert_eq!(found, dir.path().join(name));
let given = dir.path().join(name);
assert_eq!(locate(given.to_str().unwrap(), None).unwrap(), given);
}
#[test]
fn a_program_that_is_not_php_fails_cleanly() {
let dir = tempfile::tempdir().unwrap();
let fake = dir
.path()
.join(if cfg!(windows) { "php.exe" } else { "php" });
std::fs::write(&fake, b"not a program").unwrap();
let err = run_version(&fake, Duration::from_secs(2)).unwrap_err();
assert!(matches!(err, PhpError::Failed { .. }), "{err:?}");
}
proptest! {
#[test]
fn never_panics_on_random_output(bytes in proptest::collection::vec(any::<u8>(), 0..512)) {
let _ = parse_version(&bytes);
}
#[test]
fn finds_any_formatted_version(
noise in "[a-zA-Z :]{0,40}",
major in 0u32..100,
minor in 0u32..100,
patch in 0u32..1000,
suffix in "(-[a-z0-9.]{1,10})?",
) {
let text = format!("{noise}\nPHP {major}.{minor}.{patch}{suffix} (cli)\nCopyright");
prop_assert_eq!(parse_version(text.as_bytes()), v(major, minor, patch));
}
}
}

View file

@ -0,0 +1,142 @@
//! The pinned Phpactor release and where Lutra keeps it.
//!
//! Pinned release: **phpactor 2026.06.25.0** (MIT), the PHAR asset of the
//! official GitHub release:
//!
//! - URL: <https://github.com/phpactor/phpactor/releases/download/2026.06.25.0/phpactor.phar>
//! - SHA-256: `832510fe4cdaf27ba056b8cb66a779d18352585c74fdaac54e45a37b589559e9`
//! - Size: 4,474,352 bytes.
//!
//! The hash was computed from a download on 2026-10-17 and matches the
//! asset digest GitHub publishes for the release. The newer releases
//! (2026.06.23.0, 2026.07.22.0, 2026.10.07.0) declare `ext-posix` as a
//! requirement, an extension PHP on Windows does not have, so they refuse to
//! start there; 2026.06.25.0 is the newest release without it. It needs
//! PHP 8.2 or newer ([`super::php::MIN_VERSION`]).
//!
//! Updating the pin is a deliberate change: replace [`VERSION`], [`URL`],
//! [`SHA256`] and [`SIZE`] together after checking the new PHAR's hash and
//! that it runs on Windows, macOS and Linux PHP builds.
use std::fs::File;
use std::io::{self, Read};
use std::path::{Path, PathBuf};
use super::download::{Hash, Source};
/// The pinned Phpactor version.
pub const VERSION: &str = "2026.06.25.0";
/// Where the pinned PHAR is downloaded from.
pub const URL: &str =
"https://github.com/phpactor/phpactor/releases/download/2026.06.25.0/phpactor.phar";
/// SHA-256 of the pinned PHAR, lowercase hex.
pub const SHA256: &str = "832510fe4cdaf27ba056b8cb66a779d18352585c74fdaac54e45a37b589559e9";
/// Size of the pinned PHAR in bytes.
pub const SIZE: u64 = 4_474_352;
/// Largest PHAR Lutra downloads or verifies; a download that grows past it
/// is aborted.
pub const MAX_SIZE: u64 = 32 * 1024 * 1024;
/// File name of the PHAR inside its version directory.
pub const FILE_NAME: &str = "phpactor.phar";
/// The pinned release as a download source (HTTPS only).
///
/// # Errors
/// A message if [`SHA256`] is not valid hex, which a unit test rules out.
pub fn pinned() -> Result<Source, String> {
Ok(Source {
url: URL.to_string(),
version: VERSION.to_string(),
sha256: Hash::from_hex(SHA256).ok_or("the pinned SHA-256 is not valid hex")?,
https_only: true,
})
}
/// Where Lutra keeps a managed Phpactor of `version`:
/// `<data_dir>/tools/phpactor/<version>/phpactor.phar`.
pub fn managed_path(data_dir: &Path, version: &str) -> PathBuf {
data_dir
.join("tools")
.join("phpactor")
.join(version)
.join(FILE_NAME)
}
/// Whether the file at `path` has the SHA-256 `expected`. Files larger than
/// [`MAX_SIZE`] never match.
///
/// # Errors
/// The I/O error if the file cannot be read; a missing file is
/// `ErrorKind::NotFound`.
pub fn verify(path: &Path, expected: &Hash) -> io::Result<bool> {
let file = File::open(path)?;
if file.metadata()?.len() > MAX_SIZE {
return Ok(false);
}
let mut hasher = ring::digest::Context::new(&ring::digest::SHA256);
let mut reader = file.take(MAX_SIZE);
let mut chunk = vec![0u8; 64 * 1024];
loop {
let n = reader.read(&mut chunk)?;
let Some(read) = chunk.get(..n) else {
break;
};
if read.is_empty() {
break;
}
hasher.update(read);
}
Ok(Hash::of(hasher) == *expected)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn pinned_source_is_valid() {
let source = pinned().unwrap();
assert_eq!(source.sha256.to_hex(), SHA256);
assert!(
source
.url
.starts_with("https://github.com/phpactor/phpactor/releases/download/")
);
assert!(source.url.contains(VERSION));
assert!(source.https_only);
const { assert!(SIZE < MAX_SIZE) };
}
#[test]
fn managed_path_layout() {
let p = managed_path(Path::new("data"), "1.2.3");
assert_eq!(
p,
Path::new("data")
.join("tools")
.join("phpactor")
.join("1.2.3")
.join("phpactor.phar")
);
}
#[test]
fn verifies_by_hash() {
let dir = tempfile::tempdir().unwrap();
let file = dir.path().join("x.phar");
std::fs::write(&file, b"abc").unwrap();
let abc =
Hash::from_hex("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad")
.unwrap();
assert!(verify(&file, &abc).unwrap());
std::fs::write(&file, b"abd").unwrap();
assert!(!verify(&file, &abc).unwrap());
let err = verify(&dir.path().join("missing"), &abc).unwrap_err();
assert_eq!(err.kind(), io::ErrorKind::NotFound);
}
}