diff --git a/README.md b/README.md index 313a7f4ee1..c5a40ac246 100644 --- a/README.md +++ b/README.md @@ -1578,6 +1578,27 @@ rocm config set-provider-key rocm config clear-provider-key ``` +Settings live in `config.json` in the config directory and are replaced in one +step, so an interrupted save leaves the previous file rather than a truncated +one. On Windows, a replace that fails part-way can instead leave the new +settings in a `config.json.tmp-*` file beside it, which the error names: rename +it back to `config.json` before running another command. If the file exists +but cannot be read — a bad hand edit, for example — +rocm-cli reports it and does not save over it, so the settings in it are never +replaced with defaults. Unless `ROCM_CLI_DATA_DIR` is set, the file also records +where runtimes are kept; when it is too damaged to read even that, commands stop +and say how to recover (`rocm diagnose` still runs). Repairing the file +restores everything. Setting `ROCM_CLI_DATA_DIR` (the error names the folder +when the file still shows it) points commands back at your runtimes' folder +meanwhile; until the file is repaired, any command that changes settings still +stops on it, and other commands either stop too or run on default settings. +To start over instead, rename the file yourself: the error names the exact +file it read (under `ROCM_CLI_CONFIG_DIR` when that is set) and a name to give +it, `config.json.broken` beside it, and rocm-cli does not rename or move it for +you. That resets every setting to its default, and runtimes in a custom folder +then need `ROCM_CLI_DATA_DIR`, which the error names when the file recorded +that folder. + ### Setup ``` diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 3ca1ff1a55..d355f7055e 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -212,8 +212,30 @@ fn save_managed_python_manifest(paths: &AppPaths, manifest: &ManagedPythonManife .with_context(|| format!("failed to write {}", path.display())) } +/// `config.json` for the managed-Python step, failing with what was left +/// alone and how to recover (the advice comes from [`RocmCliConfig::load`]). +fn load_config_for_managed_python(paths: &AppPaths) -> Result { + RocmCliConfig::load(paths).with_context(|| { + format!( + "cannot record the managed Python in {} because that file cannot be read; it was \ + left unchanged", + paths.config_path().display() + ) + }) +} + +/// Record the managed interpreter under `tools.python` in `config.json`. +/// +/// A `config.json` that exists but cannot be read is an error here, as it is +/// for [`RocmCliConfig::load`] itself: it is not "no config yet", and saving +/// over it would replace the user's active runtime, TheRock folder, providers +/// and preferences with defaults. The callers fail rather than skip the +/// record: the install cannot finish against that file anyway (activating the +/// new runtime loads it strictly). `ensure_managed_python` checks the file +/// before it downloads anything, so this only fails there when the file +/// changed meanwhile. fn record_managed_python_config(paths: &AppPaths, python: &Path) -> Result<()> { - let mut config = RocmCliConfig::load(paths).unwrap_or_default(); + let mut config = load_config_for_managed_python(paths)?; config.tools.insert( "python".to_owned(), ManagedToolConfig { @@ -290,6 +312,10 @@ fn ensure_managed_python( requirement: PythonRequirement, version: String, ) -> Result { + // The step ends by recording the interpreter in config.json. Check that + // the file can be read before downloading uv or Python, so an unreadable + // one stops the step before it fetches anything. + load_config_for_managed_python(paths)?; progress_line(format!("Preparing Python {version}...")); let uv = ensure_uv_binary(paths)?; @@ -309,7 +335,7 @@ fn ensure_managed_python( "Using existing Python {version} at {}.", manifest.executable.display() )); - let _ = record_managed_python_config(paths, &manifest.executable); + record_managed_python_config(paths, &manifest.executable)?; return Ok(PythonLauncher { executable: manifest.executable, source: PythonSource::Managed, @@ -379,7 +405,7 @@ fn ensure_managed_python( installed_at_unix_ms: unix_time_millis(), }; save_managed_python_manifest(paths, &manifest)?; - let _ = record_managed_python_config(paths, &executable); + record_managed_python_config(paths, &executable)?; progress_line(format!( "Python {version} is ready at {}.", executable.display() @@ -1009,6 +1035,10 @@ fn python_venv_probe_temp_root() -> Result { } } +#[cfg(test)] +#[path = "python_config_props.rs"] +mod config_props; + #[cfg(test)] mod tests { use super::*; @@ -2521,4 +2551,212 @@ exit 1 fs::remove_dir_all(root).ok(); } + + /// A stand-in `uv` that records every invocation and answers + /// `python install` / `python find` without touching the network. + /// Planted where `ensure_uv_binary` looks for the managed copy, so no + /// download and no environment override is needed. + #[cfg(unix)] + fn plant_fake_uv(paths: &AppPaths, python: &Path, log: &Path) -> Result<()> { + use rocm_core::fake_executable::write_fake_executable; + let dir = managed_tools_dir(&paths.data_dir).join("uv").join("latest"); + fs::create_dir_all(&dir)?; + let uv = dir.join(rocm_core::uv_binary_name()); + let script = format!( + "#!/bin/sh\necho \"$*\" >> '{log}'\nif [ \"$1 $2\" = \"python find\" ]; then echo '{python}'; fi\nexit 0\n", + log = log.display(), + python = python.display(), + ); + write_fake_executable(&uv, script)?; + Ok(()) + } + + /// A config.json `load` rejects, holding settings that must survive. + #[cfg(unix)] + fn plant_unreadable_config(paths: &AppPaths) -> Result> { + fs::create_dir_all(&paths.config_dir)?; + let damaged = br#"{"active_runtime_key": "kept-runtime", "onboarding_dismissed": "yes"}"#; + fs::write(paths.config_path(), damaged)?; + assert!(RocmCliConfig::load(paths).is_err()); + Ok(damaged.to_vec()) + } + + /// The error names the exact file to rename and what to rename it to. + /// The advice text itself is `AppPaths::config_aside_advice`; that + /// following it keeps the data dir is + /// `config_rename_advice_keeps_a_recorded_data_dir_when_followed` in + /// rocm-core's paths.rs. + #[cfg(unix)] + fn assert_names_the_file_to_rename(message: &str, paths: &AppPaths) { + let config = paths.config_path(); + assert!( + message.contains(&format!( + "rename \"{}\" to \"{}.broken\"", + config.display(), + config.display() + )) && message.contains(&paths.config_aside_advice()), + "the error does not name the file to rename: {message}" + ); + } + + /// The reuse path: a usable managed Python is already recorded, so + /// `ensure_managed_python` returns early. Meeting an unreadable config + /// there must fail — not report success with the record silently skipped + /// — before `uv` is run at all, and leave the file as it was. + #[cfg(unix)] + #[test] + fn ensure_managed_python_reuse_path_fails_on_an_unreadable_config() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + // Held because the uv and Python versions are read from the + // environment, which other tests in this module set. + let _guard = PROCESS_ENV_TEST_LOCK.lock().unwrap(); + let (root, paths) = test_paths("ensure-python-reuse-unreadable"); + let python_dir = managed_tools_dir(&paths.data_dir).join("python"); + fs::create_dir_all(&python_dir)?; + let python = write_fake_python_with_venv(&python_dir, "python")?; + save_managed_python_manifest( + &paths, + &ManagedPythonManifest { + executable: python.clone(), + version: managed_python_version(python_requirement(SourceLayout::Canonical)), + installed_at_unix_ms: 1, + }, + )?; + let uv_log = root.join("uv.log"); + plant_fake_uv(&paths, &python, &uv_log)?; + let damaged = plant_unreadable_config(&paths)?; + + // `PythonLauncher` is not `Debug`, so `expect_err` is unavailable. + let requirement = python_requirement(SourceLayout::Canonical); + let Err(error) = + ensure_managed_python(&paths, requirement, managed_python_version(requirement)) + else { + panic!("an unreadable config must fail the reuse path"); + }; + let uv_calls = fs::read_to_string(&uv_log).unwrap_or_default(); + let after = fs::read(paths.config_path())?; + fs::remove_dir_all(root).ok(); + + let message = format!("{error:#}"); + assert!( + message.contains("cannot record the managed Python") + && message.contains("it was left unchanged"), + "unexpected error: {message}" + ); + assert_names_the_file_to_rename(&message, &paths); + assert_eq!(after, damaged, "config.json was rewritten"); + assert!( + uv_calls.is_empty(), + "uv ran before the unreadable config stopped the step: {uv_calls}" + ); + Ok(()) + } + + /// The install path: no managed Python yet, so `uv python install` runs + /// and the new interpreter is recorded at the end. An unreadable config + /// fails the bootstrap before `uv` is run at all, with the file left as it + /// was. + #[cfg(unix)] + #[test] + fn ensure_managed_python_install_path_fails_on_an_unreadable_config() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let _guard = PROCESS_ENV_TEST_LOCK.lock().unwrap(); + let (root, paths) = test_paths("ensure-python-install-unreadable"); + let python_dir = root.join("uv-python"); + fs::create_dir_all(&python_dir)?; + let python = write_fake_python_with_venv(&python_dir, "python")?; + let uv_log = root.join("uv.log"); + plant_fake_uv(&paths, &python, &uv_log)?; + let damaged = plant_unreadable_config(&paths)?; + + // `PythonLauncher` is not `Debug`, so `expect_err` is unavailable. + let requirement = python_requirement(SourceLayout::Canonical); + let Err(error) = + ensure_managed_python(&paths, requirement, managed_python_version(requirement)) + else { + panic!("an unreadable config must fail the install path"); + }; + let uv_calls = fs::read_to_string(&uv_log).unwrap_or_default(); + let after = fs::read(paths.config_path())?; + fs::remove_dir_all(root).ok(); + + let message = format!("{error:#}"); + assert!( + message.contains("cannot record the managed Python") + && message.contains("it was left unchanged"), + "unexpected error: {message}" + ); + assert_names_the_file_to_rename(&message, &paths); + assert_eq!(after, damaged, "config.json was rewritten"); + assert!( + uv_calls.is_empty(), + "uv ran before the unreadable config stopped the step: {uv_calls}" + ); + Ok(()) + } + + /// A config.json that reads fine but cannot be saved: its folder is made + /// read-only, so the save cannot create its temp file. Both paths must + /// report that the interpreter was not recorded, rather than finish as if + /// it had been. Skipped where the folder stays writable (running as root). + #[cfg(unix)] + #[test] + fn ensure_managed_python_fails_when_the_record_cannot_be_saved() -> Result<()> { + use std::os::unix::fs::PermissionsExt; + + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let _guard = PROCESS_ENV_TEST_LOCK.lock().unwrap(); + for reuse in [true, false] { + let (root, paths) = test_paths("ensure-python-record-unsaved"); + let python_dir = if reuse { + managed_tools_dir(&paths.data_dir).join("python") + } else { + root.join("uv-python") + }; + fs::create_dir_all(&python_dir)?; + let python = write_fake_python_with_venv(&python_dir, "python")?; + if reuse { + save_managed_python_manifest( + &paths, + &ManagedPythonManifest { + executable: python.clone(), + version: managed_python_version(python_requirement( + SourceLayout::Canonical, + )), + installed_at_unix_ms: 1, + }, + )?; + } + plant_fake_uv(&paths, &python, &root.join("uv.log"))?; + RocmCliConfig::default().save(&paths)?; + fs::set_permissions(&paths.config_dir, fs::Permissions::from_mode(0o555))?; + let probe = paths.config_dir.join("probe"); + if fs::write(&probe, b"").is_ok() { + fs::remove_file(&probe).ok(); + fs::set_permissions(&paths.config_dir, fs::Permissions::from_mode(0o755))?; + fs::remove_dir_all(root).ok(); + return Ok(()); + } + + let requirement = python_requirement(SourceLayout::Canonical); + let result = + ensure_managed_python(&paths, requirement, managed_python_version(requirement)); + fs::set_permissions(&paths.config_dir, fs::Permissions::from_mode(0o755))?; + fs::remove_dir_all(root).ok(); + let Err(error) = result else { + panic!("reuse={reuse}: an unsaved record must fail the step"); + }; + assert!( + format!("{error:#}").contains("config.json"), + "reuse={reuse}: {error:#}" + ); + } + Ok(()) + } } diff --git a/apps/rocm/src/therock/python_config_props.rs b/apps/rocm/src/therock/python_config_props.rs new file mode 100644 index 0000000000..a2cb3bb92e --- /dev/null +++ b/apps/rocm/src/therock/python_config_props.rs @@ -0,0 +1,353 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Property tests for how the managed-Python step, a `config.json` writer in +//! this module, treats a `config.json` it cannot read, and for the legacy +//! rocm-dash TOML migration that could produce one. +//! +//! A child of `python` so it can drive the private +//! `record_managed_python_config`. No test here sets the process environment: +//! every `AppPaths` is built by hand under the system temp dir. The recovery +//! advice in the errors does read it (`ROCM_CLI_DATA_DIR` and the home +//! folder, through `AppPaths::config_aside_advice`), which is why the tests +//! compare against that method's output rather than a fixed string. + +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicUsize, Ordering}; + +use proptest::prelude::*; +use proptest::test_runner::{Config as RunnerConfig, TestCaseError, TestError, TestRunner}; +use rocm_core::{AppPaths, RocmCliConfig}; + +use super::record_managed_python_config; + +static NEXT_DIR: AtomicUsize = AtomicUsize::new(0); + +fn fresh_paths(tag: &str) -> (PathBuf, AppPaths) { + let root = std::env::temp_dir().join(format!( + "rocm-props-{tag}-{}-{}", + std::process::id(), + NEXT_DIR.fetch_add(1, Ordering::Relaxed) + )); + let paths = AppPaths { + config_dir: root.join("config"), + data_dir: root.join("data"), + cache_dir: root.join("cache"), + }; + (root, paths) +} + +fn report(name: &str, result: Result<(), TestError>) { + match result { + Ok(()) => {} + Err(TestError::Fail(reason, value)) => { + panic!("{name}: minimal failing input {value:#?}\nreason: {reason}") + } + Err(TestError::Abort(reason)) => panic!("{name}: aborted: {reason}"), + } +} + +// --------------------------------------------------------------------------- +// config.json: a corrupt file must not be silently replaced by defaults. +// --------------------------------------------------------------------------- + +/// The user settings a later command acts on. If any of these vanish, `rocm` +/// forgets which runtime is active, where TheRock lives, and its defaults. +#[derive(Debug, Clone)] +struct UserSettings { + active_runtime_key: String, + default_runtime_id: String, + default_engine: String, + therock_venv: PathBuf, +} + +fn user_settings() -> BoxedStrategy { + ( + "[a-z0-9-]{1,16}", + "[a-z0-9:-]{1,16}", + prop_oneof![Just("vllm".to_owned()), Just("lemonade".to_owned())], + "/[a-z/]{1,16}", + ) + .prop_map(|(key, id, engine, venv)| UserSettings { + active_runtime_key: key, + default_runtime_id: id, + default_engine: engine, + therock_venv: PathBuf::from(venv), + }) + .boxed() +} + +/// Ways a real `config.json` becomes unreadable to this binary. Each is applied +/// to the bytes `RocmCliConfig::save` actually wrote, not to JSON built from +/// scratch. +#[derive(Debug, Clone)] +enum Corruption { + /// Interrupted write, as a plain `fs::write` in `RocmCliConfig::save` used to + /// leave behind (it is atomic now), or a truncating hand edit. + TruncateAt(usize), + /// What a non-finite tick serializes to (see the rocm-core property test). + NullTick, + /// A hand edit or a newer binary that changed a field's type. + RetypeOnboardingDismissed, + /// A value the loader's own validators reject. + TopPOutOfRange, +} + +fn corruption() -> BoxedStrategy { + prop_oneof![ + (1_usize..400).prop_map(Corruption::TruncateAt), + Just(Corruption::NullTick), + Just(Corruption::RetypeOnboardingDismissed), + Just(Corruption::TopPOutOfRange), + ] + .boxed() +} + +fn corrupt(bytes: &[u8], how: &Corruption) -> Vec { + let mut value: serde_json::Value = serde_json::from_slice(bytes).unwrap(); + match how { + Corruption::TruncateAt(at) => return bytes[..(*at).min(bytes.len() - 1)].to_vec(), + Corruption::NullTick => { + value["dashboard"]["daemon"]["gpu_tick_secs"] = serde_json::Value::Null; + } + Corruption::RetypeOnboardingDismissed => { + value["onboarding_dismissed"] = serde_json::json!("yes"); + } + Corruption::TopPOutOfRange => { + value["dashboard"]["tui"]["chat_top_p"] = serde_json::json!(1.5); + } + } + serde_json::to_vec_pretty(&value).unwrap() +} + +/// `RocmCliConfig::load` deliberately fails loudly on a corrupt file. A writer +/// that meets the same file must not "repair" it by saving defaults over it: +/// that turns "unreadable, fix it" into "valid but empty", and every later +/// command acts on the empty state. +#[test] +fn managed_python_recording_never_replaces_an_unreadable_config_with_defaults() { + let total = AtomicUsize::new(0); + let unreadable = AtomicUsize::new(0); + let mut runner = TestRunner::new(RunnerConfig { + cases: crate::test_support::proptest_cases(128), + ..RunnerConfig::default() + }); + let result = runner.run(&(user_settings(), corruption()), |(settings, how)| { + total.fetch_add(1, Ordering::Relaxed); + let (root, paths) = fresh_paths("config-wipe"); + let mut config = RocmCliConfig { + active_runtime_key: Some(settings.active_runtime_key.clone()), + default_runtime_id: Some(settings.default_runtime_id.clone()), + default_engine: Some(settings.default_engine.clone()), + ..RocmCliConfig::default() + }; + config.setup.therock_venv = Some(settings.therock_venv.clone()); + config.save(&paths).unwrap(); + let original = std::fs::read(paths.config_path()).unwrap(); + let damaged = corrupt(&original, &how); + std::fs::write(paths.config_path(), &damaged).unwrap(); + if RocmCliConfig::load(&paths).is_ok() { + // A truncation that happens to land on valid JSON; not this property. + let _ = std::fs::remove_dir_all(root); + return Ok(()); + } + unreadable.fetch_add(1, Ordering::Relaxed); + + let _ = record_managed_python_config(&paths, Path::new("/usr/bin/python3")); + + let after = std::fs::read(paths.config_path()).unwrap(); + let _ = std::fs::remove_dir_all(root); + if after == damaged { + return Ok(()); // left alone: the user still sees the loud error + } + let reloaded: RocmCliConfig = serde_json::from_slice(&after) + .map_err(|e| TestCaseError::fail(format!("rewritten config unreadable: {e}")))?; + prop_assert_eq!( + reloaded.active_runtime_key.as_deref(), + Some(settings.active_runtime_key.as_str()), + "config.json was rewritten and the active runtime was forgotten" + ); + prop_assert_eq!( + reloaded.setup.therock_venv.as_deref(), + Some(settings.therock_venv.as_path()) + ); + Ok(()) + }); + eprintln!( + "reach: {} of {} cases produced a config.json that load() rejects", + unreadable.load(Ordering::Relaxed), + total.load(Ordering::Relaxed) + ); + report("config wipe", result); + assert!( + unreadable.load(Ordering::Relaxed) > 0, + "no case produced a config.json that load() rejects" + ); +} + +/// The property above stops at its first (shrunk) counterexample. This walks +/// every corruption class once, and asserts what the user is told together +/// with what is left on disk: the error says the file was left unchanged, and +/// it was, byte for byte. +#[test] +fn no_corruption_class_is_wiped_by_managed_python_recording() { + let classes = [ + Corruption::TruncateAt(40), + Corruption::NullTick, + Corruption::RetypeOnboardingDismissed, + Corruption::TopPOutOfRange, + ]; + for how in classes { + let (root, paths) = fresh_paths("config-wipe-class"); + let mut config = RocmCliConfig { + active_runtime_key: Some("therock-release-gfx1151-7.13.0".to_owned()), + ..RocmCliConfig::default() + }; + config.setup.therock_venv = Some(PathBuf::from("/data/rocm")); + config.save(&paths).unwrap(); + let damaged = corrupt(&std::fs::read(paths.config_path()).unwrap(), &how); + std::fs::write(paths.config_path(), &damaged).unwrap(); + assert!( + RocmCliConfig::load(&paths).is_err(), + "{how:?} is unreadable" + ); + + let error = record_managed_python_config(&paths, Path::new("/usr/bin/python3")) + .expect_err("recording over an unreadable config must fail"); + let after = std::fs::read(paths.config_path()).unwrap(); + let _ = std::fs::remove_dir_all(&root); + + let message = format!("{error:#}"); + assert!( + message.contains("cannot record the managed Python") + && message.contains("it was left unchanged") + && message.contains("config.json"), + "{how:?}: unexpected error: {message}" + ); + assert_eq!(after, damaged, "{how:?}: config.json was rewritten"); + } +} + +/// A `config.json` that cannot be read at all — here a directory, which +/// fails the read on every platform without chmod or root — is not "no +/// settings yet" either. Recording must refuse with the same message, and +/// leave what is at that path alone. +#[test] +fn managed_python_recording_refuses_a_config_path_it_cannot_read() { + let (root, paths) = fresh_paths("config-unreadable-path"); + std::fs::create_dir_all(paths.config_path()).unwrap(); + let kept = paths.config_path().join("kept"); + std::fs::write(&kept, b"user data").unwrap(); + + let error = record_managed_python_config(&paths, Path::new("/usr/bin/python3")) + .expect_err("recording over an unreadable config path must fail"); + let still_a_dir = paths.config_path().is_dir(); + let kept_after = std::fs::read(&kept); + let _ = std::fs::remove_dir_all(&root); + + let message = format!("{error:#}"); + assert!( + message.contains("cannot record the managed Python") + && message.contains("it was left unchanged"), + "unexpected error: {message}" + ); + // Pinned here; `config_rename_advice_keeps_a_recorded_data_dir_when_followed` + // in rocm-core's paths.rs follows the advice and checks the data dir. + assert!( + message.contains(&paths.config_aside_advice()), + "the error does not name the file to rename: {message}" + ); + assert!(still_a_dir, "the path was replaced"); + assert_eq!(kept_after.unwrap(), b"user data"); +} + +/// With no `config.json` at all, recording the managed Python is the first +/// write and must still succeed: "missing" is defaults, as `load` promises. +#[test] +fn managed_python_recording_creates_a_missing_config() { + let (root, paths) = fresh_paths("config-missing"); + record_managed_python_config(&paths, Path::new("/usr/bin/python3")).unwrap(); + let loaded = RocmCliConfig::load(&paths).unwrap(); + let _ = std::fs::remove_dir_all(&root); + let tool = loaded.tools.get("python").expect("python was recorded"); + assert!(tool.managed); + assert_eq!(tool.path.as_deref(), Some(Path::new("/usr/bin/python3"))); +} + +/// The end-to-end path a user could reach without hand-editing `config.json`: +/// a legacy rocm-dash `config.toml` holding `inf`. It used to migrate into a +/// config the loader rejects, which the next managed-Python step then replaced +/// with defaults. Now the migration refuses the file, so nothing unreadable is +/// written, and the managed-Python step meets a missing config, which it may +/// create. +#[test] +fn legacy_inf_tick_never_reaches_config_json() { + let (root, paths) = fresh_paths("legacy-chain"); + std::fs::create_dir_all(&root).unwrap(); + let legacy = root.join("config.toml"); + let text = "default_engine = \"vllm\"\n[daemon]\ngpu_tick = inf\n[tui]\ntheme = \"nord\"\n"; + std::fs::write(&legacy, text).unwrap(); + + let error = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy) + .expect_err("a legacy file with an infinite tick must not migrate"); + assert!( + format!("{error:#}").contains("daemon.gpu_tick = inf"), + "unexpected error: {error:#}" + ); + assert!(!paths.config_path().exists(), "config.json was written"); + + record_managed_python_config(&paths, Path::new("/usr/bin/python3")).unwrap(); + let after = RocmCliConfig::load(&paths); + let legacy_after = std::fs::read_to_string(&legacy).unwrap(); + let _ = std::fs::remove_dir_all(&root); + assert!(after.is_ok(), "config.json is readable: {:?}", after.err()); + assert_eq!(legacy_after, text, "the legacy TOML was modified"); +} + +/// rocm-dash's reader and the migration into `config.json` read the same +/// legacy file. They must agree on whether it is readable: a file the +/// dashboard rejects must not be migrated, and one it accepts must migrate +/// into a `config.json` that loads. +#[test] +fn legacy_tick_readers_agree_on_which_files_are_readable() { + let ticks = [ + "0", + "0.5", + "120", + "nan", + "inf", + "-inf", + "-1.0", + "-0.0", + "1.7976931348623157e308", + ]; + let mut disagreements = Vec::new(); + for tick in ticks { + let (root, paths) = fresh_paths("legacy-agree"); + std::fs::create_dir_all(&root).unwrap(); + let legacy = root.join("config.toml"); + // rocm-dash requires the whole `[daemon]` table, so every other key + // holds a value both readers accept; only `instance_tick` varies. + std::fs::write( + &legacy, + format!( + "[daemon]\nlisten = \"unix:/tmp/rocm-dash.sock\"\ngpu_tick = 1.0\n\ + discovery_tick = 5.0\ninstance_tick = {tick}\n" + ), + ) + .unwrap(); + let dash_accepts = rocm_dash_core::config::Config::load(&legacy).is_ok(); + let migrated = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy); + let migration_accepts = matches!(migrated, Ok(Some(_))); + let loadable = RocmCliConfig::load(&paths).is_ok(); + let _ = std::fs::remove_dir_all(&root); + if dash_accepts != migration_accepts || !loadable { + disagreements.push(format!( + "{tick}: dashboard accepts={dash_accepts}, migration accepts={migration_accepts}, \ + config.json loadable={loadable}" + )); + } + } + assert!(disagreements.is_empty(), "{disagreements:#?}"); +} diff --git a/crates/rocm-core/src/atomic_write.rs b/crates/rocm-core/src/atomic_write.rs index 0ba0d41032..e63f3e70b8 100644 --- a/crates/rocm-core/src/atomic_write.rs +++ b/crates/rocm-core/src/atomic_write.rs @@ -44,10 +44,20 @@ //! destination existed beforehand, so a second writer that created the //! destination in between cannot turn it into a deletion. //! -//! Atomic, not durable: neither the temp file nor its directory is fsynced -//! before the publish. That survives a crashed process and a concurrent -//! writer, but after a power loss a filesystem that does not order data before -//! the rename can still show an empty or stale destination. +//! Durable as well as atomic: the temp file is flushed to disk before it is +//! published, so the new name never points at data still in the cache. On +//! Unix the directory is flushed after the rename too, so a power loss leaves +//! the old file or the new one rather than an empty one. Windows has no +//! directory flush here; there the rename's durability is the filesystem's. +//! +//! Replacing a file this way must not quietly change what the user set up: +//! +//! - on Unix the new file keeps the old one's permission bits, applied to the +//! temp file before any byte is written into it (on Windows nothing is +//! copied; see the note on attributes above); +//! - a destination that is a symbolic link — a dotfiles checkout linking +//! `config.json`, say — has its *target* replaced through +//! [`write_file_atomically`], so the link survives. A link loop is an error. //! //! This makes each file individually atomic. It does not serialize a //! read-modify-write across processes: two writers that each read, change and @@ -64,6 +74,10 @@ use std::path::{Path, PathBuf}; const ATOMIC_WRITE_TEMP_ATTEMPTS: u32 = 128; +/// How many symbolic links [`write_file_atomically`] follows before giving up, +/// matching the usual kernel limit (`MAXSYMLINKS` on Linux). +const MAX_SYMLINK_HOPS: usize = 40; + /// The raw values of Windows' `ERROR_UNABLE_TO_MOVE_REPLACEMENT` (1176) and /// `ERROR_UNABLE_TO_MOVE_REPLACEMENT_2` (1177), the two codes with which /// `ReplaceFileW` reports that it moved the old file off the destination name @@ -265,9 +279,38 @@ where P: FnOnce(), F: FnOnce(&Path, &Path) -> io::Result<()>, { - let tmp = stage_file_for_atomic_publish_with(path, bytes, suffix_for_attempt)?; + let path = resolve_symlink_target(path)?; + let tmp = stage_file_for_atomic_publish_with(&path, bytes, suffix_for_attempt)?; before_publish(); - publish_staged_file_with(&tmp, path, publish) + publish_staged_file_with(&tmp, &path, publish) +} + +/// The file a write to `path` should replace: `path` itself, or — when it is +/// a symbolic link — the file the link chain ends at, so the link survives. +/// A dangling link resolves to where its target would be, which is created. +fn resolve_symlink_target(path: &Path) -> Result { + let mut current = path.to_path_buf(); + for _ in 0..MAX_SYMLINK_HOPS { + match fs::symlink_metadata(¤t) { + Ok(metadata) if metadata.file_type().is_symlink() => { + let target = fs::read_link(¤t) + .with_context(|| format!("failed to read link {}", current.display()))?; + current = if target.is_absolute() { + target + } else { + current + .parent() + .context("link path has no parent directory")? + .join(target) + }; + } + _ => return Ok(current), + } + } + bail!( + "too many levels of symbolic links resolving {}", + path.display() + ) } /// Write `bytes` to a fresh, uniquely named sibling of `path` and return the @@ -277,6 +320,10 @@ where /// staging failure nothing is left behind. To *replace* `path` with the bytes, /// call [`write_file_atomically`] instead, which also removes the staged file /// when the publish fails. +/// +/// Unlike [`write_file_atomically`], `path` is taken as given: a symbolic link +/// there is not resolved, so the temp file sits next to the link, and +/// publishing it over that `path` replaces the link with a regular file. pub fn stage_file_for_atomic_publish(path: &Path, bytes: &[u8]) -> Result { let temp_id = process_temp_id(); stage_file_for_atomic_publish_with(path, bytes, |attempt| { @@ -292,8 +339,11 @@ fn stage_file_for_atomic_publish_with( where S: FnMut(u32) -> OsString, { + // Flushed before it can be published: a rename that reaches the disk + // before the data would leave an empty file under the real name after a + // crash. A full disk can surface in the flush rather than in `write_all`. stage_file_for_atomic_publish_with_writer(path, bytes, suffix_for_attempt, |file, bytes| { - file.write_all(bytes) + write_then_flush(file, bytes, fs::File::sync_all) }) } @@ -340,6 +390,13 @@ where ); }; + // Before any byte is written, so a private file's new contents are never + // readable under the wider default mode, even for a moment. + if let Err(error) = keep_existing_permissions(path, &tmp) { + drop(file); + let _ = fs::remove_file(&tmp); + return Err(error); + } if let Err(error) = write(&mut file, bytes) { drop(file); let _ = fs::remove_file(&tmp); @@ -349,6 +406,45 @@ where Ok(tmp) } +/// Write `bytes` into the staged file, then flush it to disk with `flush`, so +/// the data reaches the disk before the rename can. A flush error fails the +/// write like any other, so the caller removes the temp file. `flush` is +/// injected so a test can see that it runs, and after the bytes; production +/// passes `File::sync_all`. +fn write_then_flush(file: &mut fs::File, bytes: &[u8], flush: F) -> io::Result<()> +where + F: FnOnce(&fs::File) -> io::Result<()>, +{ + file.write_all(bytes)?; + flush(file) +} + +/// Give the staged file the permission bits of the file it will replace, so a +/// `0600` file is not republished as `0644`. Nothing to keep for a new file. +#[cfg(unix)] +fn keep_existing_permissions(path: &Path, tmp: &Path) -> Result<()> { + match fs::metadata(path) { + Ok(existing) => fs::set_permissions(tmp, existing.permissions()) + .with_context(|| format!("failed to copy the permissions of {}", path.display())), + Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()), + Err(error) => Err(error) + .with_context(|| format!("failed to read the permissions of {}", path.display())), + } +} + +/// Nothing is copied on Windows: a publish by rename leaves the new file with +/// the staged file's attributes and the ACL its directory hands down (see the +/// module doc), and no caller sets a mode-like attribute it needs kept. +#[cfg(not(unix))] +#[allow(clippy::unnecessary_wraps)] +// Platform stub. The `cfg` sibling calls non-const code, so making only this +// arm `const` would give the two platforms different signatures and push +// `missing_const_for_fn` onto every caller in turn. +#[allow(clippy::missing_const_for_fn)] +fn keep_existing_permissions(_path: &Path, _tmp: &Path) -> Result<()> { + Ok(()) +} + #[cfg(test)] fn publish_staged_file(tmp: &Path, path: &Path) -> Result<()> { publish_staged_file_with(tmp, path, publish_temp_file) @@ -368,8 +464,25 @@ fn publish_staged_file(tmp: &Path, path: &Path) -> Result<()> { fn publish_staged_file_with(tmp: &Path, path: &Path, publish: F) -> Result<()> where F: FnOnce(&Path, &Path) -> io::Result<()>, +{ + publish_staged_file_with_dir_sync(tmp, path, publish, sync_parent_dir) +} + +/// [`publish_staged_file_with`] with the directory flush injected, so a test +/// can see that a successful publish flushes the destination's directory and +/// a failed one does not; production passes `sync_parent_dir`. +fn publish_staged_file_with_dir_sync( + tmp: &Path, + path: &Path, + publish: F, + sync_dir: D, +) -> Result<()> +where + F: FnOnce(&Path, &Path) -> io::Result<()>, + D: FnOnce(&Path), { let Err(error) = publish(tmp, path) else { + sync_dir(path); return Ok(()); }; if removed_the_destination(&error) && tmp.exists() { @@ -383,6 +496,34 @@ where Err(error).with_context(|| format!("failed to publish {}", path.display())) } +/// Flush the directory entry the rename just changed, so the new name — not +/// the old file, or no file — is what a crash leaves behind. +/// +/// Best-effort: the file is already published, and some filesystems refuse to +/// sync a directory. Reporting failure here would claim the write failed when +/// it did not. +#[cfg(unix)] +fn sync_parent_dir(path: &Path) { + // A bare relative name has the empty path as its parent, which cannot be + // opened; its folder is the current one. + let parent = match path.parent() { + Some(parent) if parent.as_os_str().is_empty() => Path::new("."), + Some(parent) => parent, + None => return, + }; + if let Ok(dir) = fs::File::open(parent) { + let _ = dir.sync_all(); + } +} + +/// Not done on Windows: the rename's durability is left to the filesystem. +#[cfg(not(unix))] +// Platform stub. The `cfg` sibling calls non-const code, so making only this +// arm `const` would give the two platforms different signatures and push +// `missing_const_for_fn` onto every caller in turn. +#[allow(clippy::missing_const_for_fn)] +fn sync_parent_dir(_path: &Path) {} + /// Test seam: move the staged file `tmp` over `path` in one step, replacing /// any existing file without first removing it. /// @@ -1197,4 +1338,228 @@ mod tests { "destination must not exist after failure" ); } + + /// The names in `dir`, sorted. + #[cfg(unix)] + fn names_in(dir: &Path) -> Vec { + let mut names: Vec = fs::read_dir(dir) + .unwrap() + .map(|entry| entry.unwrap().file_name().to_string_lossy().into_owned()) + .collect(); + names.sort(); + names + } + + /// Replacing a file keeps its permission bits: a `0600` file must not be + /// republished as `0644`, and an unusual mode survives as set. + #[cfg(unix)] + #[test] + fn write_file_atomically_keeps_the_existing_permissions() { + use std::os::unix::fs::PermissionsExt; + + let root = scratch_dir("permissions"); + fs::create_dir_all(&root).unwrap(); + let destination = root.join("config.json"); + for mode in [0o600, 0o640, 0o604] { + fs::write(&destination, b"old").unwrap(); + fs::set_permissions(&destination, fs::Permissions::from_mode(mode)).unwrap(); + + write_file_atomically(&destination, b"new").unwrap(); + + let after = fs::metadata(&destination).unwrap().permissions().mode() & 0o777; + assert_eq!(after, mode, "mode {mode:o} was not kept"); + assert_eq!(fs::read(&destination).unwrap(), b"new"); + } + let _ = fs::remove_dir_all(&root); + } + + /// The kept mode is on the temp file before the first byte reaches it, so + /// a private file's new contents are never readable under the default mode. + #[cfg(unix)] + #[test] + fn staging_applies_the_kept_mode_before_writing_any_byte() { + use std::os::unix::fs::PermissionsExt; + + // 0o604 is a mode no usual umask gives a new file (022 gives 0o644, + // 077 gives 0o600), so seeing it on the temp file means it was set. + for mode in [0o600, 0o604] { + let root = scratch_dir("permissions-before-write"); + fs::create_dir_all(&root).unwrap(); + let destination = root.join("config.json"); + fs::write(&destination, b"old").unwrap(); + fs::set_permissions(&destination, fs::Permissions::from_mode(mode)).unwrap(); + + let mut mode_while_writing = None; + stage_file_for_atomic_publish_with_writer( + &destination, + b"secret", + |attempt| OsString::from(format!("mode-{attempt}")), + |file, bytes| { + mode_while_writing = Some(file.metadata()?.permissions().mode() & 0o777); + file.write_all(bytes) + }, + ) + .unwrap(); + let _ = fs::remove_dir_all(&root); + + assert_eq!(mode_while_writing, Some(mode), "mode {mode:o}"); + } + } + + /// When the existing file's permissions cannot be read, staging fails + /// with that error and removes its temp file. A symlink loop at the + /// destination makes the read fail on Unix without root or chmod; + /// `stage_file_for_atomic_publish` takes the path as given, so the loop + /// reaches the permission read rather than the link resolution. + #[cfg(unix)] + #[test] + fn staging_that_cannot_read_the_existing_permissions_removes_its_temp_file() { + use std::os::unix::fs::symlink; + + let root = scratch_dir("permissions-unreadable"); + fs::create_dir_all(&root).unwrap(); + let a = root.join("a.json"); + let b = root.join("b.json"); + symlink(&b, &a).unwrap(); + symlink(&a, &b).unwrap(); + + let error = stage_file_for_atomic_publish(&a, b"x").expect_err("the read must fail"); + let names = names_in(&root); + let _ = fs::remove_dir_all(&root); + assert!( + format!("{error:#}").contains("failed to read the permissions of"), + "{error:#}" + ); + assert_eq!(names, ["a.json", "b.json"], "the temp file was left behind"); + } + + /// The staged bytes are flushed, after they are written, and a flush + /// error fails the write. Whether the flush reaches the disk cannot be + /// observed from a test; that it is asked for can. + #[test] + fn staged_bytes_are_flushed_after_they_are_written() { + let root = scratch_dir("flush-order"); + fs::create_dir_all(&root).unwrap(); + let path = root.join("staged"); + let mut file = fs::File::create(&path).unwrap(); + + let mut seen_at_flush = None; + write_then_flush(&mut file, b"payload", |_| { + seen_at_flush = Some(fs::read(&path).unwrap()); + Ok(()) + }) + .unwrap(); + let failed = write_then_flush(&mut file, b"more", |_| { + Err(io::Error::other("flush refused")) + }); + drop(file); + let _ = fs::remove_dir_all(&root); + + assert_eq!(seen_at_flush.as_deref(), Some(&b"payload"[..])); + assert_eq!(failed.unwrap_err().to_string(), "flush refused"); + } + + /// A publish that succeeds flushes the destination's directory once; one + /// that fails does not. + #[test] + fn a_successful_publish_flushes_the_directory_and_a_failed_one_does_not() { + let root = scratch_dir("dir-flush"); + fs::create_dir_all(&root).unwrap(); + let destination = root.join("target.json"); + let tmp = root.join("target.json.tmp-1"); + fs::write(&tmp, b"new").unwrap(); + + let mut flushed = Vec::new(); + publish_staged_file_with_dir_sync(&tmp, &destination, publish_temp_file, |path| { + flushed.push(path.to_path_buf()); + }) + .unwrap(); + fs::write(&tmp, b"newer").unwrap(); + let mut flushed_after_failure = 0; + publish_staged_file_with_dir_sync( + &tmp, + &destination, + |_, _| Err(io::Error::other("publish refused")), + |_| flushed_after_failure += 1, + ) + .expect_err("the publish was refused"); + let _ = fs::remove_dir_all(&root); + + assert_eq!(flushed, [destination]); + assert_eq!(flushed_after_failure, 0); + } + + /// A destination that is a symbolic link keeps being one: the file it + /// points at is replaced, through a chain of links and a relative link + /// alike, and nothing is left next to either end. + #[cfg(unix)] + #[test] + fn write_file_atomically_replaces_a_symlinks_target_and_keeps_the_link() { + use std::os::unix::fs::{PermissionsExt, symlink}; + + let root = scratch_dir("symlink"); + let dotfiles = root.join("dotfiles"); + let config_dir = root.join("config"); + fs::create_dir_all(&dotfiles).unwrap(); + fs::create_dir_all(&config_dir).unwrap(); + let target = dotfiles.join("rocm-config.json"); + fs::write(&target, b"old").unwrap(); + fs::set_permissions(&target, fs::Permissions::from_mode(0o600)).unwrap(); + // config/config.json -> links/deeper/hop.json + // -> ../../dotfiles/rocm-config.json, a relative hop in a directory + // two levels deep, so resolving it against the entry link's directory + // instead of the hop's own would miss the target. + let hop_dir = root.join("links").join("deeper"); + fs::create_dir_all(&hop_dir).unwrap(); + let hop = hop_dir.join("hop.json"); + symlink(Path::new("../../dotfiles/rocm-config.json"), &hop).unwrap(); + let link = config_dir.join("config.json"); + symlink(&hop, &link).unwrap(); + + write_file_atomically(&link, b"new").unwrap(); + + let link_kept = fs::symlink_metadata(&link) + .unwrap() + .file_type() + .is_symlink(); + let hop_kept = fs::symlink_metadata(&hop).unwrap().file_type().is_symlink(); + let through_link = fs::read(&link).unwrap(); + let target_contents = fs::read(&target).unwrap(); + let target_mode = fs::metadata(&target).unwrap().permissions().mode() & 0o777; + let config_names = names_in(&config_dir); + let hop_names = names_in(&hop_dir); + let dotfiles_names = names_in(&dotfiles); + let _ = fs::remove_dir_all(&root); + + assert!(link_kept && hop_kept, "a link was replaced by a file"); + assert_eq!(through_link, b"new"); + assert_eq!(target_contents, b"new"); + assert_eq!(target_mode, 0o600); + assert_eq!(config_names, ["config.json"]); + assert_eq!(hop_names, ["hop.json"]); + assert_eq!(dotfiles_names, ["rocm-config.json"]); + } + + /// A link loop is an error, not a hang, and writes nothing. + #[cfg(unix)] + #[test] + fn write_file_atomically_refuses_a_symlink_loop() { + use std::os::unix::fs::symlink; + + let root = scratch_dir("symlink-loop"); + fs::create_dir_all(&root).unwrap(); + let a = root.join("a.json"); + let b = root.join("b.json"); + symlink(&b, &a).unwrap(); + symlink(&a, &b).unwrap(); + + let error = write_file_atomically(&a, b"x").expect_err("a link loop must fail"); + let names = names_in(&root); + let _ = fs::remove_dir_all(&root); + assert!( + format!("{error:#}").contains("too many levels of symbolic links"), + "{error:#}" + ); + assert_eq!(names, ["a.json", "b.json"]); + } } diff --git a/crates/rocm-core/src/config.rs b/crates/rocm-core/src/config.rs index e577241ff4..d6a6cbce20 100644 --- a/crates/rocm-core/src/config.rs +++ b/crates/rocm-core/src/config.rs @@ -10,7 +10,7 @@ //! whose entries carry a default `WatcherMode`), and the rocm-dash dashboard //! sub-config (daemon + TUI), including its one-shot legacy-TOML migration. -use anyhow::{Context, Result}; +use anyhow::{Context, Result, bail}; use serde::{Deserialize, Serialize}; use std::collections::BTreeMap; use std::fs; @@ -591,36 +591,72 @@ struct LegacyDashTui { } impl RocmCliConfig { + /// Read `config.json`, or the defaults when there is none yet. + /// + /// Only a file that is not there means "no settings yet". Anything else + /// that stops the read — a directory where the file should be, a + /// permission problem, a symlink loop — is an error, just as unparseable + /// contents are: answering with defaults would let the next save replace + /// the user's settings with them. Data-dir discovery draws the same line. + /// + /// The error says how to recover, so every command that loads the + /// settings strictly gives the same advice: repair the file, or rename the + /// exact file it names ([`AppPaths::config_aside_advice`]). pub fn load(paths: &AppPaths) -> Result { let path = paths.config_path(); - if !path.is_file() { - return Ok(Self::default()); - } - - let bytes = - fs::read(&path).with_context(|| format!("failed to read {}", path.display()))?; - serde_json::from_slice(&bytes) - .with_context(|| format!("failed to parse {}", path.display())) + let unreadable = |what: &str, error: &dyn std::fmt::Display| { + anyhow::anyhow!( + "failed to {what} {}: {error}. Repair that file, then run the command again. {}", + path.display(), + paths.config_aside_advice() + ) + }; + let bytes = match fs::read(&path) { + Ok(bytes) => bytes, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Ok(Self::default()); + } + Err(error) => return Err(unreadable("read", &error)), + }; + serde_json::from_slice(&bytes).map_err(|error| unreadable("parse", &error)) } - /// Persist the config by replacing it via the shared - /// [`write_file_atomically`](crate::atomic_write::write_file_atomically) - /// helper (write a uniquely named sibling temp file, then publish it over - /// `config.json`; see that helper's module doc for the - /// write/publish/cleanup guarantees). + /// Write the config so that [`Self::load`] can always read it back. + /// + /// - The bytes are parsed back before anything is written. A value that + /// serializes but does not deserialize, such as a non-finite `f64` + /// (JSON has no NaN, so it is written as `null`), fails the save and + /// leaves the existing file as it was. + /// - The file is replaced in one step through the shared writer in + /// [`crate::atomic_write`]: a reader sees the old file or the new one, + /// never a truncated one, and the existing file is never removed first + /// (`load` would read a missing `config.json` as "no settings"). The new + /// contents are flushed before the replace, the replaced file's Unix + /// mode is kept, and a symlinked `config.json` keeps its link while its + /// target is replaced. /// - /// The destination is never removed first, because `load` reads a - /// missing `config.json` as "no config" and answers with defaults — a - /// removed-then-not-yet-replaced window would lose every setting without - /// so much as an error. + /// Not guaranteed, on Windows: + /// - Replacing a `config.json` that another process holds open without + /// delete sharing. The replace then fails with a sharing violation, the + /// save returns that error, and the old config stays in place. + /// - A replace that fails part-way. `ReplaceFileW` can move the old file + /// off the `config.json` name and then fail to move the new one on; the + /// writer retries once with a plain rename, and if that fails too the new + /// contents stay in the `config.json.tmp-*` file the error names. Until + /// it is renamed back there is no `config.json`, which `load` reads as + /// "no settings". pub fn save(&self, paths: &AppPaths) -> Result<()> { let path = paths.config_path(); - fs::create_dir_all(&paths.config_dir) - .with_context(|| format!("failed to create {}", paths.config_dir.display()))?; let bytes = serde_json::to_vec_pretty(self).context("failed to serialize rocm-cli config")?; + serde_json::from_slice::(&bytes).with_context(|| { + format!( + "refusing to write {}: the new contents would not load back", + path.display() + ) + })?; crate::atomic_write::write_file_atomically(&path, &bytes) - .with_context(|| format!("failed to save rocm-cli config to {}", path.display())) + .with_context(|| format!("failed to write {}", path.display())) } pub fn engine_config(&self, engine: &str) -> Option<&EngineUserConfig> { @@ -687,13 +723,20 @@ impl RocmCliConfig { } /// One-shot migration of a legacy rocm-dash `config.toml` into the unified - /// JSON config. If no `config.json` exists yet **and** a legacy TOML is - /// present, its knobs are mapped into `dashboard` (and the canonical - /// `default_engine`/`engines`), `config.json` is written once, and the - /// migrated legacy path is returned so the caller can print a notice. The - /// TOML is left untouched. Returns `Ok(None)` when there is nothing to do - /// (already on the unified config, or no legacy file) — never clobbers an - /// existing `config.json`. + /// JSON config. If nothing is at the `config.json` path yet **and** a + /// legacy TOML is present, its knobs are mapped into `dashboard` (and the + /// canonical `default_engine`/`engines`), `config.json` is written once, + /// and the migrated legacy path is returned so the caller can print a + /// notice. The TOML is left untouched. + /// + /// Returns `Ok(None)` when there is nothing to do: no legacy file, or + /// anything at all already at the `config.json` path — a settings file, + /// but also a directory or a symbolic link, dangling or not. Only an empty + /// path is "no settings yet" here, so the migration never writes over, + /// beside or through something the user put there; `load` reports a + /// directory itself. Returns an error, writing nothing and leaving the TOML + /// alone, when a daemon tick is not a valid `Duration` (rocm-dash's own + /// reader rejects such a file) or the TOML cannot be read or parsed. pub fn migrate_legacy_dashboard_toml(paths: &AppPaths) -> Result> { let Some(legacy) = Self::legacy_dashboard_toml_path() else { return Ok(None); @@ -707,9 +750,20 @@ impl RocmCliConfig { paths: &AppPaths, legacy: &Path, ) -> Result> { - if paths.config_path().is_file() || !legacy.is_file() { + if !legacy.is_file() { return Ok(None); } + // `symlink_metadata`, not `exists`/`is_file`: a directory, or a link + // whose target is missing, is something the user put there, not an + // empty slot to migrate into. + match fs::symlink_metadata(paths.config_path()) { + Ok(_) => return Ok(None), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => { + return Err(error) + .with_context(|| format!("failed to check {}", paths.config_path().display())); + } + } let raw = fs::read_to_string(legacy) .with_context(|| format!("failed to read {}", legacy.display()))?; @@ -720,6 +774,29 @@ impl RocmCliConfig { // Dashboard-specific knobs map into the new sub-config. let d = &parsed.daemon; + // rocm-dash's own reader (`rocm_dash_core::config`) rejects a tick that + // is not a valid `Duration` — NaN, infinite, negative, or too large — + // so it already treats this file as unreadable. Migrating it anyway + // would also write a non-finite value as JSON `null`, which `load` + // rejects. Refuse on the same rule, leaving the TOML untouched. + for (key, value) in [ + ("gpu_tick", d.gpu_tick), + ("discovery_tick", d.discovery_tick), + ("instance_tick", d.instance_tick), + ] { + if let Some(secs) = value + && let Err(error) = Duration::try_from_secs_f64(secs) + { + bail!( + "legacy config {} sets daemon.{key} = {secs}, which is not a valid tick \ + ({error}); set it to a finite, non-negative number of seconds to migrate the file. \ + Migration only runs while {} does not exist, so fix it before any rocm command \ + saves settings, or re-enter the dashboard settings by hand afterwards", + legacy.display(), + paths.config_path().display() + ); + } + } if let Some(v) = &d.listen { config.dashboard.daemon.listen = v.clone(); } @@ -756,6 +833,12 @@ impl RocmCliConfig { } } +// Property tests of save, load and the legacy migration, a child module so they +// can use the crate's `proptest_cases`. +#[cfg(test)] +#[path = "config_proptests.rs"] +mod props; + #[cfg(test)] mod tests { use super::*; @@ -918,6 +1001,84 @@ mod tests { Ok(()) } + /// Every strict load of an unreadable file says how to recover, naming the + /// exact file to rename and the name to give it, and leaves the file + /// alone; renaming it as told makes the next load start from defaults. + #[test] + fn load_of_an_unreadable_config_says_which_file_to_rename() -> Result<()> { + // The advice reads `ROCM_CLI_DATA_DIR`, which other tests set. + let _guard = crate::test_env::DATA_DIR_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = temp_app_paths("config-load-advice"); + fs::create_dir_all(&paths.config_dir)?; + let damaged = br#"{"active_runtime_key": "kept", "onboarding_dismissed": "yes"}"#; + fs::write(paths.config_path(), damaged)?; + + let error = RocmCliConfig::load(&paths).expect_err("a retyped field must not load"); + let message = format!("{error:#}"); + let after = fs::read(paths.config_path())?; + let rename = format!( + "rename \"{config}\" to \"{config}.broken\"", + config = paths.config_path().display() + ); + let renamed = paths.config_dir.join("config.json.broken"); + let followed = message + .contains(&rename) + .then(|| fs::rename(paths.config_path(), &renamed)); + let reloaded = RocmCliConfig::load(&paths); + let kept = fs::read(&renamed); + fs::remove_dir_all(root).ok(); + + assert!( + message.contains("failed to parse") + && message.contains("Repair that file") + && message.contains(&paths.config_aside_advice()), + "unexpected error: {message}" + ); + assert_eq!(after, damaged, "load changed config.json"); + assert!( + followed.is_some(), + "the error does not say {rename:?}: {message}" + ); + assert_eq!(reloaded?.active_runtime_key, None); + assert_eq!(kept?, damaged, "the renamed file lost its contents"); + Ok(()) + } + + /// A value that serializes but cannot be read back (a non-finite tick is + /// written as JSON `null`) must fail the save and leave the existing file + /// exactly as it was, rather than replace a good config with one `load` + /// rejects. + #[test] + fn config_save_refuses_contents_load_would_reject_and_keeps_the_old_file() -> Result<()> { + let (root, paths) = temp_app_paths("config-save-refuses"); + let good = RocmCliConfig { + active_runtime_key: Some("kept-runtime".to_owned()), + ..RocmCliConfig::default() + }; + good.save(&paths)?; + let before = fs::read(paths.config_path())?; + + let mut bad = good; + bad.dashboard.daemon.gpu_tick_secs = f64::NAN; + let error = bad + .save(&paths) + .expect_err("a config load would reject must not be saved"); + let after = fs::read(paths.config_path())?; + let reloaded = RocmCliConfig::load(&paths)?; + fs::remove_dir_all(root).ok(); + + let rendered = format!("{error:#}"); + assert!( + rendered.contains("refusing to write") && rendered.contains("config.json"), + "unexpected error: {rendered}" + ); + assert_eq!(after, before, "the existing config.json was changed"); + assert_eq!(reloaded.active_runtime_key.as_deref(), Some("kept-runtime")); + Ok(()) + } + #[test] fn legacy_config_without_telemetry_uses_default_policy() -> Result<()> { let config = serde_json::from_value::(serde_json::json!({ @@ -1134,6 +1295,150 @@ last_installed_runtime_id = "therock-release" Ok(()) } + /// A tick that is not a valid duration is refused, naming the key, and the + /// refusal writes nothing: no `config.json` appears and the TOML is + /// unchanged, so the startup notice "skipped legacy dashboard config + /// migration" is true and fixing the value lets the next run migrate — + /// provided nothing has created `config.json` meanwhile, which the refusal + /// itself warns about. + #[test] + fn migrate_legacy_dashboard_toml_refuses_an_invalid_tick_and_writes_nothing() -> Result<()> { + // Every tick key, and every way a value can fail to be a Duration: + // not a number, infinite, negative, and finite but too large. + for key in ["gpu_tick", "discovery_tick", "instance_tick"] { + for (value, rendered) in [ + ("nan", "NaN"), + ("inf", "inf"), + ("-inf", "-inf"), + ("-1.0", "-1"), + // Above `Duration::MAX` (about 1.8e19 seconds). + ("1e20", "100000000000000000000"), + ] { + let (root, paths) = temp_app_paths("migrate-dash-bad-tick"); + fs::create_dir_all(&root)?; + let legacy = root.join("legacy-config.toml"); + let text = format!( + "default_engine = \"vllm\"\n[daemon]\n{key} = {value}\n[tui]\ntheme = \"nord\"\n" + ); + fs::write(&legacy, &text)?; + + let error = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy) + .expect_err("an invalid tick must not migrate"); + let config_written = paths.config_path().exists(); + let legacy_after = fs::read_to_string(&legacy)?; + let _ = fs::remove_dir_all(&root); + + let message = format!("{error:#}"); + assert!( + message.contains(&format!("daemon.{key} = {rendered}")), + "{key} = {value}: unexpected error: {message}" + ); + assert!(!config_written, "{key} = {value}: config.json was written"); + assert_eq!( + legacy_after, text, + "{key} = {value}: the legacy TOML was modified" + ); + } + } + + // The refusal warns that the window closes once config.json exists — + // and it does: after any save, the still-broken legacy file is skipped + // without a word, and fixing it later no longer migrates it either. + let (root, paths) = temp_app_paths("migrate-dash-window-closes"); + fs::create_dir_all(&root)?; + let legacy = root.join("legacy-config.toml"); + fs::write( + &legacy, + "[daemon]\ngpu_tick = nan\n[tui]\ntheme = \"nord\"\n", + )?; + let error = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy) + .expect_err("an invalid tick must not migrate"); + let message = format!("{error:#}"); + RocmCliConfig::default().save(&paths)?; + let while_broken = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy)?; + fs::write( + &legacy, + "[daemon]\ngpu_tick = 1.0\n[tui]\ntheme = \"nord\"\n", + )?; + let once_fixed = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy)?; + let theme = RocmCliConfig::load(&paths)?.dashboard.tui.theme; + let _ = fs::remove_dir_all(&root); + assert!( + message.contains(&format!( + "Migration only runs while {} does not exist", + paths.config_path().display() + )) && message.contains("re-enter the dashboard settings by hand"), + "unexpected error: {message}" + ); + assert_eq!(while_broken, None); + assert_eq!(once_fixed, None); + assert_ne!(theme, "nord", "the legacy theme was migrated after all"); + + // Zero is a valid duration for rocm-dash too, so it still migrates. + let (root, paths) = temp_app_paths("migrate-dash-zero-tick"); + fs::create_dir_all(&root)?; + let legacy = root.join("legacy-config.toml"); + fs::write(&legacy, "[daemon]\ngpu_tick = 0\n")?; + let migrated = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy)?; + let loaded = RocmCliConfig::load(&paths); + let _ = fs::remove_dir_all(&root); + assert!(migrated.is_some()); + assert!(loaded.is_ok()); + Ok(()) + } + + /// Only an empty `config.json` path is "no settings yet". A directory + /// there (which `load` rejects) and a link whose target is missing are the + /// user's, so the migration writes nothing: not into the directory, not + /// through the link, and the TOML stays as it was. + #[test] + fn migrate_legacy_dashboard_toml_leaves_a_directory_or_link_at_config_json_alone() -> Result<()> + { + let legacy_text = "default_engine = \"vllm\"\n[tui]\ntheme = \"nord\"\n"; + + let (root, paths) = temp_app_paths("migrate-dash-dir-at-config"); + fs::create_dir_all(paths.config_path())?; + let legacy = root.join("legacy-config.toml"); + fs::write(&legacy, legacy_text)?; + let migrated = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy); + let entries = fs::read_dir(paths.config_path())?.count(); + let still_a_dir = paths.config_path().is_dir(); + let legacy_after = fs::read_to_string(&legacy)?; + let leftovers: Vec = fs::read_dir(&paths.config_dir)? + .filter_map(std::result::Result::ok) + .map(|entry| entry.file_name().to_string_lossy().into_owned()) + .filter(|name| name != "config.json") + .collect(); + fs::remove_dir_all(&root).ok(); + assert_eq!(migrated?, None, "migrated over a directory at config.json"); + assert!(still_a_dir && entries == 0, "the directory was changed"); + assert!( + leftovers.is_empty(), + "files were left beside it: {leftovers:?}" + ); + assert_eq!(legacy_after, legacy_text); + + #[cfg(unix)] + { + let (root, paths) = temp_app_paths("migrate-dash-dangling-link"); + fs::create_dir_all(&paths.config_dir)?; + let target = root.join("dotfiles").join("rocm-config.json"); + std::os::unix::fs::symlink(&target, paths.config_path())?; + let legacy = root.join("legacy-config.toml"); + fs::write(&legacy, legacy_text)?; + let migrated = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy); + let target_written = target.exists(); + let still_a_link = fs::symlink_metadata(paths.config_path())? + .file_type() + .is_symlink(); + fs::remove_dir_all(&root).ok(); + assert_eq!(migrated?, None, "migrated through a dangling link"); + assert!(!target_written, "the link's target was created"); + assert!(still_a_link, "the link was replaced"); + } + Ok(()) + } + #[test] fn migrate_legacy_dashboard_toml_without_legacy_is_noop() -> Result<()> { let (root, paths) = temp_app_paths("migrate-dash-absent"); @@ -1152,7 +1457,7 @@ last_installed_runtime_id = "therock-release" /// behind, so deleting the cleanup would go unnoticed until a user with a /// failing disk accumulated one `config.json.tmp---` per attempt. /// - /// A directory at the destination is what makes the rename fail on both + /// A directory at the destination is what makes the publish fail on both /// supported platforms without needing permissions a root CI lane ignores — /// the same device `write_file_atomically_cleans_up_temp_when_the_rename_fails` /// uses in `rocm_core::atomic_write`. @@ -1267,11 +1572,17 @@ last_installed_runtime_id = "therock-release" }; config.save(&paths)?; let before = fs::metadata(paths.config_path())?.ino(); + let before_bytes = fs::read(paths.config_path())?; + // A second name for the old file: if the save rewrote it in place, the + // new contents would show through this link too. + let witness = root.join("config-before-save.json"); + fs::hard_link(paths.config_path(), &witness)?; config.default_engine = Some("lemonade".to_owned()); config.save(&paths)?; let after = fs::metadata(paths.config_path())?.ino(); + let witnessed = fs::read(&witness)?; let loaded = RocmCliConfig::load(&paths)?; let _ = fs::remove_dir_all(&root); @@ -1280,6 +1591,10 @@ last_installed_runtime_id = "therock-release" "an overwrite that keeps the same inode rewrote the live config in \ place, so an interrupted save can leave it truncated" ); + assert_eq!( + witnessed, before_bytes, + "save rewrote the existing config.json in place" + ); assert_eq!(loaded.default_engine.as_deref(), Some("lemonade")); Ok(()) } diff --git a/crates/rocm-core/src/config_proptests.rs b/crates/rocm-core/src/config_proptests.rs new file mode 100644 index 0000000000..0a164d6b57 --- /dev/null +++ b/crates/rocm-core/src/config_proptests.rs @@ -0,0 +1,439 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Property tests for the persisted `config.json` (`RocmCliConfig`) and its +//! one-shot migration from the legacy rocm-dash `config.toml`. +//! +//! Each property runs through an explicit `TestRunner` rather than the +//! `proptest!` macro so it can count how often the generator actually reached +//! the interesting classes (absent optionals, empty and non-ASCII strings, +//! non-finite floats), print that, and fail a run that never reached them +//! rather than pass vacuously. + +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::sync::atomic::{AtomicUsize, Ordering}; + +use crate::test_support::proptest_cases; +use crate::{AppPaths, EngineUserConfig, RocmCliConfig}; +use proptest::prelude::*; +use proptest::test_runner::{Config as RunnerConfig, TestCaseError, TestError, TestRunner}; + +static NEXT_DIR: AtomicUsize = AtomicUsize::new(0); + +/// A fresh, empty `AppPaths` under the system temp dir. No environment is read +/// or written. +fn fresh_paths(tag: &str) -> (PathBuf, AppPaths) { + let root = std::env::temp_dir().join(format!( + "rocm-core-props-{tag}-{}-{}", + std::process::id(), + NEXT_DIR.fetch_add(1, Ordering::Relaxed) + )); + let paths = AppPaths { + config_dir: root.join("config"), + data_dir: root.join("data"), + cache_dir: root.join("cache"), + }; + (root, paths) +} + +/// Strings biased toward the cases uniform generators miss. +fn text() -> impl Strategy { + prop_oneof![ + 2 => Just(String::new()), + 2 => "[a-z0-9:._-]{1,12}", + 1 => Just("gfx1151-é-日本-\u{1F600}".to_owned()), + 1 => Just(" padded ".to_owned()), + 2 => any::(), + ] +} + +fn opt_text() -> impl Strategy> { + prop_oneof![3 => Just(None), 2 => text().prop_map(Some)] +} + +fn path_text() -> impl Strategy { + prop_oneof![ + Just(PathBuf::from("")), + Just(PathBuf::from("/opt/rocm/../rocm-7/")), + Just(PathBuf::from(r"D:\ROCm\therock_venvs")), + Just(PathBuf::from("/mnt/d/ROCm venvs/é")), + "[a-z/. ]{1,20}".prop_map(PathBuf::from), + ] +} + +fn tick() -> BoxedStrategy { + prop_oneof![ + 4 => 0.001_f64..120.0, + 1 => Just(f64::NAN), + 1 => Just(f64::INFINITY), + 1 => Just(f64::NEG_INFINITY), + 1 => Just(-0.0), + 1 => Just(-1.0), + 1 => Just(f64::MAX), + 1 => Just(f64::from_bits(1)), + ] + .boxed() +} + +fn engine_cfg() -> impl Strategy { + (opt_text(), opt_text(), opt_text(), opt_text()).prop_map(|(a, b, c, d)| EngineUserConfig { + preferred_runtime_id: a, + preferred_env_id: b, + last_installed_runtime_id: c, + last_installed_env_id: d, + }) +} + +#[derive(Debug, Clone)] +struct ConfigSeed { + default_engine: Option, + default_runtime_id: Option, + active_runtime_key: Option, + previous_runtime_key: Option, + onboarding_dismissed: bool, + telemetry_mode: String, + therock_venv: Option, + engines: BTreeMap, + ticks: (f64, f64, f64), + chat_temperature: Option, + chat_top_p: Option, + chat_max_tokens: Option, +} + +fn config_seed(ticks: BoxedStrategy) -> impl Strategy { + ( + (opt_text(), opt_text(), opt_text(), opt_text()), + any::(), + text(), + prop_oneof![2 => Just(None), 1 => path_text().prop_map(Some)], + prop::collection::btree_map(text(), engine_cfg(), 0..3), + (ticks.clone(), ticks.clone(), ticks), + ( + prop_oneof![Just(None), (0.0_f32..2.0).prop_map(Some)], + prop_oneof![Just(None), (0.0_f32..=1.0).prop_map(Some)], + prop_oneof![Just(None), (1_u32..=u32::MAX).prop_map(Some)], + ), + ) + .prop_map( + |((de, dr, ak, pk), od, tm, tv, engines, ticks, (temp, top_p, max_tokens))| { + ConfigSeed { + default_engine: de, + default_runtime_id: dr, + active_runtime_key: ak, + previous_runtime_key: pk, + onboarding_dismissed: od, + telemetry_mode: tm, + therock_venv: tv, + engines, + ticks, + chat_temperature: temp, + chat_top_p: top_p, + chat_max_tokens: max_tokens, + } + }, + ) +} + +fn build_config(seed: &ConfigSeed) -> RocmCliConfig { + let mut config = RocmCliConfig { + default_engine: seed.default_engine.clone(), + default_runtime_id: seed.default_runtime_id.clone(), + active_runtime_key: seed.active_runtime_key.clone(), + previous_runtime_key: seed.previous_runtime_key.clone(), + onboarding_dismissed: seed.onboarding_dismissed, + engines: seed.engines.clone(), + ..RocmCliConfig::default() + }; + config.telemetry.mode.clone_from(&seed.telemetry_mode); + config.setup.therock_venv.clone_from(&seed.therock_venv); + config.dashboard.daemon.gpu_tick_secs = seed.ticks.0; + config.dashboard.daemon.discovery_tick_secs = seed.ticks.1; + config.dashboard.daemon.instance_tick_secs = seed.ticks.2; + config.dashboard.tui.chat_temperature = seed.chat_temperature; + config.dashboard.tui.chat_top_p = seed.chat_top_p; + config.dashboard.tui.chat_max_tokens = seed.chat_max_tokens; + config +} + +/// Compare configs by their JSON text re-read through the same parser, not by +/// `serde_json::to_value`: `to_value` widens an `f32` to `f64` (`0.17120193` +/// becomes `0.1712019294500351`), and serde_json's default float parser is not +/// correctly rounded (`59.913248351550116` reads back as `59.91324835155011`). +/// Both are serde_json properties, harmless for these fields, and must not mask +/// real loss. +fn as_value(config: &RocmCliConfig) -> serde_json::Value { + let text = serde_json::to_string(config).expect("config serializes"); + serde_json::from_str(&text).expect("serialized config parses as JSON") +} + +fn report(name: &str, result: Result<(), TestError>) { + match result { + Ok(()) => {} + Err(TestError::Fail(reason, value)) => { + panic!("{name}: minimal failing input {value:#?}\nreason: {reason}") + } + Err(TestError::Abort(reason)) => panic!("{name}: aborted: {reason}"), + } +} + +/// `load(save(x)) == x` for every config whose ticks are finite. This is the +/// half of the round-trip that holds; it stays enabled as a regression guard. +#[test] +fn config_round_trips_through_save_and_load_for_finite_values() { + let (root, paths) = fresh_paths("roundtrip-finite"); + let total = AtomicUsize::new(0); + let none_active = AtomicUsize::new(0); + let empty_strings = AtomicUsize::new(0); + let non_ascii = AtomicUsize::new(0); + let finite_ticks = (0.001_f64..120.0).boxed(); + let finite = prop_oneof![ + 3 => finite_ticks, + 1 => Just(-0.0), + 1 => Just(f64::MAX), + 1 => Just(f64::from_bits(1)), + 1 => Just(-1.0), + ] + .boxed(); + let mut runner = TestRunner::new(RunnerConfig { + cases: proptest_cases(512), + ..RunnerConfig::default() + }); + let result = runner.run(&config_seed(finite), |seed| { + total.fetch_add(1, Ordering::Relaxed); + let config = build_config(&seed); + let json = serde_json::to_string(&config).unwrap_or_default(); + if seed.active_runtime_key.is_none() { + none_active.fetch_add(1, Ordering::Relaxed); + } + if json.contains("\"\"") { + empty_strings.fetch_add(1, Ordering::Relaxed); + } + if !json.is_ascii() { + non_ascii.fetch_add(1, Ordering::Relaxed); + } + config + .save(&paths) + .map_err(|e| TestCaseError::fail(format!("{e:#}")))?; + let loaded = + RocmCliConfig::load(&paths).map_err(|e| TestCaseError::fail(format!("{e:#}")))?; + prop_assert_eq!(as_value(&loaded), as_value(&config)); + Ok(()) + }); + eprintln!( + "reach: of {} cases, active_runtime_key=None {}, empty strings {}, non-ASCII {}", + total.load(Ordering::Relaxed), + none_active.load(Ordering::Relaxed), + empty_strings.load(Ordering::Relaxed), + non_ascii.load(Ordering::Relaxed) + ); + let _ = std::fs::remove_dir_all(root); + report("finite round-trip", result); + // A property that never generated the inputs it is about passed without + // testing them. + assert!( + none_active.load(Ordering::Relaxed) > 0 + && empty_strings.load(Ordering::Relaxed) > 0 + && non_ascii.load(Ordering::Relaxed) > 0, + "the round-trip never generated an unset key, an empty string and non-ASCII text" + ); +} + +/// `save` must never write a file that `load` then refuses. A non-finite tick +/// serializes as JSON `null`, which the `f64` field then rejects, so the saved +/// config cannot be read back at all. +#[test] +fn config_save_never_writes_a_file_load_rejects() { + let (root, paths) = fresh_paths("roundtrip-any"); + let non_finite = AtomicUsize::new(0); + let mut runner = TestRunner::new(RunnerConfig { + cases: proptest_cases(256), + ..RunnerConfig::default() + }); + let result = runner.run(&config_seed(tick()), |seed| { + if ![seed.ticks.0, seed.ticks.1, seed.ticks.2] + .iter() + .all(|t| t.is_finite()) + { + non_finite.fetch_add(1, Ordering::Relaxed); + } + let config = build_config(&seed); + if config.save(&paths).is_err() { + // Refusing to save is acceptable; writing an unreadable file is not. + return Ok(()); + } + RocmCliConfig::load(&paths) + .map(|_| ()) + .map_err(|e| TestCaseError::fail(format!("{e:#}"))) + }); + eprintln!( + "reach: non-finite tick in {} cases", + non_finite.load(Ordering::Relaxed) + ); + let _ = std::fs::remove_dir_all(root); + report("save/load agreement", result); + assert!( + non_finite.load(Ordering::Relaxed) > 0, + "no case had a non-finite tick" + ); +} + +fn toml_float(value: f64) -> String { + if value.is_nan() { + "nan".to_owned() + } else if value == f64::INFINITY { + "inf".to_owned() + } else if value == f64::NEG_INFINITY { + "-inf".to_owned() + } else { + format!("{value:?}") + } +} + +/// Run the legacy-TOML migration property over the given tick strategy. +/// +/// The migration writes `config.json` once and never again, so it has to write +/// something the unified loader accepts, carrying the user's values. Generated +/// as TOML *text* so the real `toml` 1.x parser is in the loop. +/// +/// With `must_migrate`, every case must migrate, and carry its ticks over +/// unchanged: the strategy then generates only ticks rocm-dash accepts, so a +/// refusal is a defect rather than the safe outcome it is for any tick. +fn legacy_migration_property(ticks: &BoxedStrategy, label: &str, must_migrate: bool) { + use std::fmt::Write as _; + let total = AtomicUsize::new(0); + let non_finite = AtomicUsize::new(0); + let non_ascii_engine = AtomicUsize::new(0); + let mut runner = TestRunner::new(RunnerConfig { + cases: proptest_cases(256), + ..RunnerConfig::default() + }); + let strategy = (ticks.clone(), ticks.clone(), ticks.clone(), opt_text()); + let result = runner.run(&strategy, |(g, d, i, engine)| { + total.fetch_add(1, Ordering::Relaxed); + if ![g, d, i].iter().all(|t| t.is_finite()) { + non_finite.fetch_add(1, Ordering::Relaxed); + } + if engine.as_deref().is_some_and(|e| !e.is_ascii()) { + non_ascii_engine.fetch_add(1, Ordering::Relaxed); + } + let (root, paths) = fresh_paths("legacy"); + std::fs::create_dir_all(&root).unwrap(); + let legacy = root.join("config.toml"); + let mut toml_text = String::new(); + if let Some(engine) = &engine { + let _ = writeln!( + toml_text, + "default_engine = {}", + toml_string_literal(engine) + ); + } + let _ = write!( + toml_text, + "[daemon]\ngpu_tick = {}\ndiscovery_tick = {}\ninstance_tick = {}\n", + toml_float(g), + toml_float(d), + toml_float(i) + ); + std::fs::write(&legacy, &toml_text).unwrap(); + let migrated = RocmCliConfig::migrate_legacy_dashboard_toml_from(&paths, &legacy); + let loaded = RocmCliConfig::load(&paths); + let _ = std::fs::remove_dir_all(root); + match migrated { + Err(error) if must_migrate => Err(TestCaseError::fail(format!( + "refused to migrate ticks rocm-dash accepts: {error:#}\nlegacy toml:\n{toml_text}" + ))), + Ok(None) if must_migrate => Err(TestCaseError::fail(format!( + "did not migrate\nlegacy toml:\n{toml_text}" + ))), + // Refusing to migrate is fine otherwise: the legacy file is left + // untouched. + Err(_) | Ok(None) => Ok(()), + Ok(Some(_)) => { + let loaded = loaded.map_err(|e| { + TestCaseError::fail(format!( + "migrated config.json is unreadable: {e:#}\nlegacy toml:\n{toml_text}" + )) + })?; + prop_assert_eq!(loaded.default_engine, engine); + let daemon = &loaded.dashboard.daemon; + // Within one unit in the last place, and with the same sign, so + // `-0.0` stays `-0.0`. Not bit-exact: serde_json is built + // without its `float_roundtrip` feature, so reading + // `config.json` back can land one ULP off (`97.95315202189215` + // does), whatever the migration wrote. + let migrated = [ + daemon.gpu_tick_secs, + daemon.discovery_tick_secs, + daemon.instance_tick_secs, + ]; + prop_assert!( + migrated.iter().zip([g, d, i]).all(|(got, want)| { + got.is_sign_negative() == want.is_sign_negative() + && got.to_bits().abs_diff(want.to_bits()) <= 1 + }), + "migrated ticks {:?} differ from {:?}\nlegacy toml:\n{}", + migrated, + [g, d, i], + toml_text + ); + Ok(()) + } + } + }); + eprintln!( + "reach ({label}): of {} cases, non-finite tick {}, non-ASCII default_engine {}", + total.load(Ordering::Relaxed), + non_finite.load(Ordering::Relaxed), + non_ascii_engine.load(Ordering::Relaxed) + ); + report(label, result); + assert!( + non_ascii_engine.load(Ordering::Relaxed) > 0, + "{label}: no case had a non-ASCII default_engine" + ); + assert!( + must_migrate || non_finite.load(Ordering::Relaxed) > 0, + "{label}: no case had a non-finite tick" + ); +} + +/// Ticks rocm-dash accepts and arbitrary strings migrate, and load back with +/// the same values. Every generated tick passes `Duration::try_from_secs_f64`, +/// which is the rule the migration applies, so each case must migrate: a +/// refusal fails it. Also the `toml` 0.8 -> 1.x string guard. +#[test] +fn legacy_toml_migration_round_trips_accepted_ticks() { + let accepted = prop_oneof![ + 3 => 0.001_f64..120.0, + 1 => Just(0.0), + 1 => Just(-0.0), + ] + .prop_filter("a tick rocm-dash accepts", |secs| { + std::time::Duration::try_from_secs_f64(*secs).is_ok() + }) + .boxed(); + legacy_migration_property(&accepted, "legacy migration (accepted ticks)", true); +} + +#[test] +fn legacy_toml_migration_always_produces_a_loadable_config() { + legacy_migration_property(&tick(), "legacy migration (any)", false); +} + +fn toml_string_literal(value: &str) -> String { + use std::fmt::Write as _; + // A basic string with every char escaped as \u/\U keeps any input valid TOML. + let mut out = String::from("\""); + for ch in value.chars() { + let code = u32::from(ch); + if code <= 0xFFFF { + let _ = write!(out, "\\u{code:04X}"); + } else { + let _ = write!(out, "\\U{code:08X}"); + } + } + out.push('"'); + out +} diff --git a/crates/rocm-core/src/examine/library_copies.rs b/crates/rocm-core/src/examine/library_copies.rs index 090c71dfc5..ccbf0ec8b5 100644 --- a/crates/rocm-core/src/examine/library_copies.rs +++ b/crates/rocm-core/src/examine/library_copies.rs @@ -1265,10 +1265,7 @@ mod tests { assert!(rocm_install_siblings(&missing).is_empty()); } - /// Serializes the tests that point `ROCM_CLI_DATA_DIR` at a scratch - /// registry. Named `*_TEST_LOCK` so the env-mutation contract guard - /// recognises the discipline by suffix. - static DATA_DIR_ENV_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + use crate::test_env::DATA_DIR_ENV_TEST_LOCK; /// A wheel-format managed runtime's recorded library directories reach the /// search through the real chain, even though none of them sits under the diff --git a/crates/rocm-core/src/paths.rs b/crates/rocm-core/src/paths.rs index 7d526244e4..d8eecc41c9 100644 --- a/crates/rocm-core/src/paths.rs +++ b/crates/rocm-core/src/paths.rs @@ -10,6 +10,7 @@ use anyhow::{Context, Result}; use serde::Serialize; +use std::ffi::OsString; use std::fs; use std::path::{Path, PathBuf}; @@ -35,6 +36,17 @@ pub struct AppPaths { } impl AppPaths { + /// Resolve the config, data and cache dirs from the environment and + /// `config.json`. + /// + /// Errors when no data dir is given through `ROCM_CLI_DATA_DIR` and + /// `config.json` exists but cannot be read: the managed root it records + /// decides the data dir, so guessing the default would point every command + /// at the wrong runtimes. Startup logging and `rocm diagnose` treat an error + /// here as "no paths". Engines started by `rocm` are handed + /// `ROCM_CLI_DATA_DIR` and so never reach it; an engine started by hand + /// does, and the AIM engine then keeps its state file in the working + /// directory, as it already did when no data dir could be found. pub fn discover() -> Result { let data_dir_override = env_path_override("ROCM_CLI_DATA_DIR"); let cache_dir_override = env_path_override("ROCM_CLI_CACHE_DIR"); @@ -43,11 +55,11 @@ impl AppPaths { data: data_dir_override.clone(), cache: cache_dir_override.clone(), })?; - Ok(Self::discover_from_paths( + Self::discover_from_paths( paths, data_dir_override.is_some(), cache_dir_override.is_some(), - )) + ) } /// The three roots from their `ROCM_CLI_*_DIR` overrides, before any @@ -85,17 +97,20 @@ impl AppPaths { .normalize_for_host()) } + /// Fails when `ROCM_CLI_DATA_DIR` is unset and `config.json` exists but + /// cannot be read, because the data dir it records is then unknown; see + /// `configured_managed_root_from_config`. fn discover_from_paths( mut paths: Self, data_dir_overridden: bool, cache_dir_overridden: bool, - ) -> Self { + ) -> Result { if !data_dir_overridden - && let Some(managed_root) = configured_managed_root_from_config(&paths) + && let Some(managed_root) = configured_managed_root_from_config(&paths)? { paths = paths.with_managed_root(managed_root, cache_dir_overridden); } - paths.normalize_for_host() + Ok(paths.normalize_for_host()) } fn normalize_for_host(mut self) -> Self { @@ -333,16 +348,213 @@ impl AppPaths { } } -fn configured_managed_root_from_config(paths: &AppPaths) -> Option { - let bytes = fs::read(paths.config_path()).ok()?; - let value = serde_json::from_slice::(&bytes).ok()?; - value - .get("setup")? - .get("therock_venv")? - .as_str() - .map(str::trim) - .filter(|value| !value.is_empty()) - .map(PathBuf::from) +/// The managed root recorded in `config.json` (`setup.therock_venv`), if any. +/// +/// Agrees with [`crate::RocmCliConfig::load`] that a missing file means "nothing +/// configured" and an unreadable one is an error. Treating an unreadable file +/// as "nothing configured" would quietly move the data dir — the runtime +/// registry, the active-runtime marker, service records — back to the default, +/// so a `--prefix` install's runtimes would vanish and new ones would land in +/// the wrong place. +/// +/// Only what this one field needs is checked: a file that is valid JSON but +/// that `load` rejects for some other field still yields its recorded root. +/// That keeps the data dir right, and leaves the complaint about the other +/// field to `load`, which names it. +fn configured_managed_root_from_config(paths: &AppPaths) -> Result> { + let path = paths.config_path(); + let bytes = match fs::read(&path) { + Ok(bytes) => bytes, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None), + Err(error) => return Err(unreadable_config_error(&path, &error.to_string(), None)), + }; + let unreadable = |detail: String| { + unreadable_config_error(&path, &detail, recorded_root_in_damaged_config(&bytes)) + }; + // One reading for every file: a file `load` accepts holds `setup` as an + // object (or not at all) and `therock_venv` as a string (or null), and this + // reads those exactly as `load` does, so a typed parse first would only + // repeat the work. + let value = serde_json::from_slice::(&bytes) + .map_err(|error| unreadable(format!("not valid JSON: {error}")))?; + let Some(top) = value.as_object() else { + return Err(unreadable(format!("expected a JSON object, found {value}"))); + }; + let setup = match top.get("setup") { + None | Some(serde_json::Value::Null) => return Ok(None), + Some(serde_json::Value::Object(setup)) => setup, + Some(other) => { + return Err(unreadable(format!( + "setup should be an object, found {other}" + ))); + } + }; + match setup.get("therock_venv") { + None | Some(serde_json::Value::Null) => Ok(None), + Some(serde_json::Value::String(text)) => Ok(Some(text.trim()) + .filter(|text| !text.is_empty()) + .map(PathBuf::from)), + Some(other) => Err(unreadable(format!( + "setup.therock_venv should be a path, found {other}" + ))), + } +} + +/// The error for a `config.json` that discovery cannot read, with recovery +/// advice that is true of what each way out actually does: +/// +/// - repairing the file restores everything; +/// - `ROCM_CLI_DATA_DIR` only tells discovery where the data is. The file +/// stays broken: every command that changes settings loads it strictly and +/// still stops, and of the read-only ones some stop too while the rest load +/// it leniently and run on default settings. None of the lenient ones saves +/// what it loaded, so none of them overwrites the file; +/// - renaming the file (the message names the exact path to rename and a name +/// to give it; nothing renames it for the user) resets every setting, and +/// puts the data dir back to the default, so runtimes in a custom folder +/// need `ROCM_CLI_DATA_DIR`. +/// +/// When the damaged bytes still name the recorded folder, the advice names the +/// exact `ROCM_CLI_DATA_DIR` value that finds it. Every path is quoted and the +/// variable is named in words rather than as `NAME=value`, so the advice reads +/// the same on Windows and Unix and survives a space in a path. +fn unreadable_config_error(path: &Path, detail: &str, recorded: Option) -> anyhow::Error { + let (data_dir_hint, aside_hint) = match recorded { + Some(recorded) => { + let data_root = managed_runtime_data_root(&recorded); + ( + format!( + "It still names {} as the ROCm folder: setting the environment variable \ + ROCM_CLI_DATA_DIR to {} points commands back at it meanwhile", + quoted(&recorded), + quoted(&data_root) + ), + runtimes_need_data_dir_override(&data_root), + ) + } + None => ( + "Setting the environment variable ROCM_CLI_DATA_DIR to the folder that holds your \ + runtimes points commands back at it meanwhile" + .to_owned(), + "runtimes installed into a custom folder then need the environment variable \ + ROCM_CLI_DATA_DIR set to that folder" + .to_owned(), + ), + }; + anyhow::anyhow!( + "cannot tell where rocm-cli keeps its data: {} cannot be read ({detail}). Repair that \ + file to restore your settings. {data_hint}. Until the file is repaired, any command \ + that changes settings still stops on it, and other commands either stop too or run on \ + default settings. Renaming it to {renamed} resets every setting to its default, and \ + {aside_hint}", + quoted(path), + renamed = quoted(&config_rename_target(path)), + data_hint = data_dir_hint, + ) +} + +/// The data dir discovery settles on when `config.json` records no managed +/// root: `ROCM_CLI_DATA_DIR`, else the default. One function, so the advice +/// about renaming `config.json` cannot disagree with discovery. +fn data_dir_without_config() -> Option { + env_path_override("ROCM_CLI_DATA_DIR").or_else(default_data_dir) +} + +/// The clause naming the `ROCM_CLI_DATA_DIR` value that keeps `data_root` +/// once `config.json` no longer records it. +fn runtimes_need_data_dir_override(data_root: &Path) -> String { + // The variable is named in words, not as `NAME=value`, which is one + // shell's syntax and not a command on Windows. + format!( + "the runtimes under {} then also need the environment variable ROCM_CLI_DATA_DIR set to {}", + quoted(data_root), + quoted(data_root) + ) +} + +/// `path` in double quotes, so a path with a space is still one value when +/// the advice is read or copied. +fn quoted(path: &Path) -> String { + format!("\"{}\"", path.display()) +} + +impl AppPaths { + /// How to start from default settings by renaming `config.json`, and what + /// that does to these paths, for a command + /// that found its data dir through the file but cannot load its settings + /// (discovery succeeded, `load` rejected another field). + /// + /// Every setting goes back to its default. When the data dir came from + /// the `setup.therock_venv` the file records, it goes back to the default + /// too, so the advice names the `ROCM_CLI_DATA_DIR` value that keeps it. + #[must_use] + pub fn config_aside_advice(&self) -> String { + let without_config = + data_dir_without_config().map(|dir| normalize_runtime_path_for_host(&dir)); + config_aside_advice( + &self.config_path(), + &self.data_dir, + without_config.as_deref(), + ) + } +} + +/// The name the recovery advice tells the user to give an unreadable +/// `config.json`: a sibling, so it stays next to the original and is never +/// read as settings again. +fn config_rename_target(config_path: &Path) -> PathBuf { + let mut name = config_path + .file_name() + .map_or_else(|| OsString::from("config.json"), ToOwned::to_owned); + name.push(".broken"); + config_path.with_file_name(name) +} + +/// [`AppPaths::config_aside_advice`], with the data dir discovery falls back +/// to when there is no `config.json` passed in rather than read from the +/// environment. +fn config_aside_advice( + config_path: &Path, + data_dir: &Path, + without_config: Option<&Path>, +) -> String { + let rename = format!( + "To start from default settings instead, rename {} to {}", + quoted(config_path), + quoted(&config_rename_target(config_path)) + ); + if without_config == Some(data_dir) { + rename + } else { + format!("{rename}; {}", runtimes_need_data_dir_override(data_dir)) + } +} + +/// Best-effort recovery of `setup.therock_venv` from a `config.json` that does +/// not parse — typically one cut short. Finds the key and reads the JSON string +/// after it only if that string is complete; never guesses past a truncation. +fn recorded_root_in_damaged_config(bytes: &[u8]) -> Option { + let text = String::from_utf8_lossy(bytes); + let after_key = &text[text.find("\"therock_venv\"")? + "\"therock_venv\"".len()..]; + let after_colon = after_key.trim_start().strip_prefix(':')?.trim_start(); + if !after_colon.starts_with('"') { + return None; + } + let mut escaped = false; + for (index, ch) in after_colon.char_indices().skip(1) { + match ch { + _ if escaped => escaped = false, + '\\' => escaped = true, + '"' => { + let literal = &after_colon[..=index]; + let value = serde_json::from_str::(literal).ok()?; + let value = value.trim(); + return (!value.is_empty()).then(|| PathBuf::from(value)); + } + _ => {} + } + } + None } pub fn engine_plugin_dirs(paths: &AppPaths) -> Vec { @@ -352,12 +564,56 @@ pub fn engine_plugin_dirs(paths: &AppPaths) -> Vec { ] } +// Declared here rather than at the crate root so the property can reach the +// private, env-free `AppPaths::discover_from_paths`. +#[cfg(test)] +#[path = "persisted_paths_props.rs"] +mod persisted_paths_props; + #[cfg(test)] mod tests { use super::*; + use crate::RocmCliConfig; use crate::test_support::temp_app_paths; + /// For every `config.json` that `load` accepts, discovery reads the + /// recorded folder as `load` does: the saved `therock_venv`, trimmed, and + /// nothing when it is absent or blank. + #[test] + fn discovery_reads_the_recorded_folder_of_a_loadable_config_as_load_does() -> Result<()> { + let (root, paths) = temp_app_paths("discovery-agrees-with-load"); + for recorded in [ + None, + Some(""), + Some(" "), + Some("/data/rocm"), + Some(" /data/rocm "), + Some("/données/rocm"), + ] { + let config = RocmCliConfig { + setup: crate::SetupConfig { + therock_venv: recorded.map(PathBuf::from), + ..crate::SetupConfig::default() + }, + ..RocmCliConfig::default() + }; + config.save(&paths)?; + let loaded = RocmCliConfig::load(&paths)?; + let expected = loaded.setup.therock_venv.and_then(|root| { + let text = root.to_string_lossy().trim().to_owned(); + (!text.is_empty()).then(|| PathBuf::from(text)) + }); + assert_eq!( + configured_managed_root_from_config(&paths)?, + expected, + "recorded {recorded:?}" + ); + } + let _ = fs::remove_dir_all(&root); + Ok(()) + } + #[test] fn audit_events_path_lives_under_data_audit() { let (_root, paths) = temp_app_paths("audit-path"); @@ -426,22 +682,392 @@ mod tests { }))?, )?; - let discovered = AppPaths::discover_from_paths(paths.clone(), false, false); + let discovered = AppPaths::discover_from_paths(paths.clone(), false, false)?; assert_eq!(discovered.config_dir, paths.config_dir); assert_eq!(discovered.data_dir, managed_root); assert_eq!(discovered.cache_dir, managed_root.join("cache")); - let data_overridden = AppPaths::discover_from_paths(paths.clone(), true, false); + let data_overridden = AppPaths::discover_from_paths(paths.clone(), true, false)?; assert_eq!(data_overridden.data_dir, paths.data_dir); assert_eq!(data_overridden.cache_dir, paths.cache_dir); - let cache_overridden = AppPaths::discover_from_paths(paths.clone(), false, true); + let cache_overridden = AppPaths::discover_from_paths(paths.clone(), false, true)?; assert_eq!(cache_overridden.data_dir, managed_root); assert_eq!(cache_overridden.cache_dir, paths.cache_dir); fs::remove_dir_all(root).ok(); Ok(()) } + /// An unreadable `config.json` stops discovery with a message naming the + /// file and the ways out, and discovery leaves the file alone. Each way + /// out the message names is then shown to do what the message says it + /// does — including what it does *not* fix. + #[test] + fn app_paths_refuse_to_guess_the_data_dir_from_an_unreadable_config() -> Result<()> { + let (root, paths) = temp_app_paths("configured-managed-root-unreadable"); + let managed_root = root.join("managed"); + let mut config = RocmCliConfig::default(); + config.setup.therock_venv = Some(managed_root.clone()); + config.save(&paths)?; + let saved = fs::read(paths.config_path())?; + let healthy = AppPaths::discover_from_paths(paths.clone(), false, false)?; + assert_eq!(healthy.data_dir, managed_root); + + let recorded = serde_json::to_string(&managed_root)?; + let value_at = String::from_utf8_lossy(&saved) + .find(&recorded) + .expect("the saved config records the managed root"); + let cut_after_root = saved[..value_at + recorded.len() + 2].to_vec(); + let cut_inside_root = saved[..value_at + recorded.len() / 2].to_vec(); + let suggested = format!( + "setting the environment variable ROCM_CLI_DATA_DIR to \"{}\"", + managed_root.display() + ); + let rename_advice = format!( + "Renaming it to \"{}\" resets every setting", + paths.config_dir.join("config.json.broken").display() + ); + + for (label, damaged, names_the_root) in [ + ("cut short after the folder", cut_after_root, true), + ("cut short inside the folder", cut_inside_root, false), + ("not an object", br#""x""#.to_vec(), false), + ("setup retyped", br#"{"setup": "x"}"#.to_vec(), false), + ( + "therock_venv retyped", + br#"{"setup": {"therock_venv": 7}}"#.to_vec(), + false, + ), + ] { + fs::write(paths.config_path(), &damaged)?; + let error = AppPaths::discover_from_paths(paths.clone(), false, false) + .expect_err("discovery must not guess the data dir"); + let message = format!("{error:#}"); + for needle in [ + "cannot tell where rocm-cli keeps its data", + "config.json", + "Repair that file", + "any command that changes settings still stops on it", + "run on default settings", + rename_advice.as_str(), + ] { + assert!( + message.contains(needle), + "{label}: missing {needle:?} in: {message}" + ); + } + assert_eq!( + message.contains(&suggested), + names_the_root, + "{label}: whether the recorded folder is named: {message}" + ); + // What renaming does to the data dir, for the folder the file still + // names or, when it no longer names one, for any custom folder. + // That the data dir does go back to the default is the rename way + // out below. + let aside = if names_the_root { + format!( + "resets every setting to its default, and the runtimes under \"{root}\" \ + then also need the environment variable ROCM_CLI_DATA_DIR set to \"{root}\"", + root = managed_root.display() + ) + } else { + "resets every setting to its default, and runtimes installed into a custom \ + folder then need the environment variable ROCM_CLI_DATA_DIR set to that folder" + .to_owned() + }; + assert!( + message.ends_with(&aside), + "{label}: missing {aside:?} at the end of: {message}" + ); + assert_eq!( + fs::read(paths.config_path())?, + damaged, + "{label}: discovery changed config.json" + ); + + // ROCM_CLI_DATA_DIR set to the suggested folder finds the same data + // dir the healthy file did... + let overridden = AppPaths::discover_from_paths( + AppPaths { + data_dir: managed_root.clone(), + ..paths.clone() + }, + true, + false, + )?; + assert_eq!(overridden.data_dir, healthy.data_dir, "{label}"); + // ...but does not make the settings readable, as the message says. + assert!(RocmCliConfig::load(&overridden).is_err(), "{label}"); + } + + // A config.json that exists but cannot be read at all (here, a + // directory: a non-NotFound read error on every platform, no root or + // chmod needed) is an error too, not "nothing configured". + fs::remove_file(paths.config_path())?; + fs::create_dir(paths.config_path())?; + let error = AppPaths::discover_from_paths(paths.clone(), false, false) + .expect_err("an unreadable config.json must not read as absent"); + let message = format!("{error:#}"); + assert!( + message.contains("cannot tell where rocm-cli keeps its data") + && message.contains("Repair that file"), + "unexpected error: {message}" + ); + assert!(paths.config_path().is_dir(), "discovery touched the path"); + // `load` draws the same line: the directory is not "no settings yet". + assert!( + RocmCliConfig::load(&paths).is_err(), + "load read an unreadable config.json as absent" + ); + fs::remove_dir(paths.config_path())?; + + // Way out: repair the file. + fs::write(paths.config_path(), &saved)?; + let repaired = AppPaths::discover_from_paths(paths.clone(), false, false)?; + assert_eq!(repaired.data_dir, managed_root); + + // Way out: rename it to the name the message gives. Settings are back + // to defaults, and the data dir is back to the default too — which is + // why the message says a custom folder then needs ROCM_CLI_DATA_DIR. + fs::rename( + paths.config_path(), + paths.config_dir.join("config.json.broken"), + )?; + let moved_aside = AppPaths::discover_from_paths(paths.clone(), false, false)?; + assert_eq!(moved_aside.data_dir, paths.data_dir); + assert_ne!(moved_aside.data_dir, managed_root); + assert!( + RocmCliConfig::load(&moved_aside)? + .setup + .therock_venv + .is_none() + ); + fs::remove_file(paths.config_dir.join("config.json.broken"))?; + + // A file that is valid JSON but that `load` rejects for another field + // still names the right data dir; `load` reports that field itself. + let mut value = serde_json::from_slice::(&saved)?; + value["dashboard"]["tui"]["chat_top_p"] = serde_json::json!(1.5); + fs::write(paths.config_path(), serde_json::to_vec(&value)?)?; + assert!(RocmCliConfig::load(&paths).is_err()); + let other_field_bad = AppPaths::discover_from_paths(paths, false, false)?; + assert_eq!(other_field_bad.data_dir, managed_root); + + fs::remove_dir_all(root).ok(); + Ok(()) + } + /// The quoted value right after the first `label` in `text`: what a + /// reader copies when told to use the path the advice prints. + fn quoted_after<'a>(text: &'a str, label: &str) -> &'a str { + let rest = &text[text + .find(label) + .unwrap_or_else(|| panic!("no {label:?} in: {text}")) + + label.len()..]; + let rest = rest + .strip_prefix('"') + .unwrap_or_else(|| panic!("no quoted path after {label:?} in: {text}")); + &rest[..rest + .find('"') + .unwrap_or_else(|| panic!("an unclosed quote after {label:?} in: {text}"))] + } + + /// A command that found its data dir through `config.json` but cannot + /// load the settings in it (another field is bad) is told which file to + /// rename, to what, and what renaming it does. Following that advice to + /// the letter — the exact paths it prints — keeps the data dir, while + /// renaming the file without the override it names would not. Both the + /// config folder and the data folder have a space in their names, so a + /// path the advice did not quote would be read as two words. + #[test] + fn config_rename_advice_keeps_a_recorded_data_dir_when_followed() -> Result<()> { + let (root, paths) = temp_app_paths("config-aside-advice"); + let paths = AppPaths { + config_dir: root.join("my config"), + ..paths + }; + let managed_root = root.join("managed rocm"); + let mut config = RocmCliConfig::default(); + config.setup.therock_venv = Some(managed_root.clone()); + config.save(&paths)?; + let mut value = + serde_json::from_slice::(&fs::read(paths.config_path())?)?; + value["dashboard"]["tui"]["chat_top_p"] = serde_json::json!(1.5); + let damaged = serde_json::to_vec(&value)?; + fs::write(paths.config_path(), &damaged)?; + + let discovered = AppPaths::discover_from_paths(paths.clone(), false, false)?; + assert_eq!(discovered.data_dir, managed_root); + assert!(RocmCliConfig::load(&discovered).is_err()); + // `paths.data_dir` stands in for the default data dir. + let advice = config_aside_advice( + &discovered.config_path(), + &discovered.data_dir, + Some(&paths.data_dir), + ); + assert_eq!( + advice, + format!( + "To start from default settings instead, rename \"{config}\" to \ + \"{config}.broken\"; the runtimes under \"{dir}\" then also need the \ + environment variable ROCM_CLI_DATA_DIR set to \"{dir}\"", + config = paths.config_path().display(), + dir = managed_root.display() + ) + ); + // The file it names is the one discovery read — under the custom + // config folder these paths use, not a default location. Each path is + // taken from between its quotes, as a reader would copy it. + let from = PathBuf::from(quoted_after(&advice, "rename ")); + let to = PathBuf::from(quoted_after( + &advice, + &format!("\"{}\" to ", from.display()), + )); + let suggested = PathBuf::from(quoted_after(&advice, "ROCM_CLI_DATA_DIR set to ")); + assert_eq!(from, paths.config_path()); + assert_eq!(to, paths.config_dir.join("config.json.broken")); + assert_eq!(suggested, managed_root); + + fs::rename(&from, &to)?; + assert_eq!( + fs::read(&to)?, + damaged, + "the renamed file lost its contents" + ); + // Without the override the data dir moves back to the default... + let unadvised = AppPaths::discover_from_paths(paths.clone(), false, false)?; + assert_eq!(unadvised.data_dir, paths.data_dir); + // ...and with the value the advice printed it stays where it was, on + // default settings: the renamed file is not read as settings. + let advised = AppPaths::discover_from_paths( + AppPaths { + data_dir: suggested, + ..paths.clone() + }, + true, + false, + )?; + assert_eq!(advised.data_dir, discovered.data_dir); + assert_eq!( + RocmCliConfig::load(&advised)?.setup.therock_venv, + None, + "the renamed file was still read as settings" + ); + fs::remove_file(&to)?; + + // A file that records no folder: renaming it leaves the data dir + // alone, so the advice names no override. + fs::write( + paths.config_path(), + br#"{"dashboard": {"tui": {"chat_top_p": 1.5}}}"#, + )?; + let default_root = AppPaths::discover_from_paths(paths.clone(), false, false)?; + assert!(RocmCliConfig::load(&default_root).is_err()); + let advice = config_aside_advice( + &default_root.config_path(), + &default_root.data_dir, + Some(&paths.data_dir), + ); + assert_eq!( + advice, + format!( + "To start from default settings instead, rename \"{config}\" to \ + \"{config}.broken\"", + config = paths.config_path().display() + ) + ); + let from = PathBuf::from(quoted_after(&advice, "rename ")); + fs::rename( + &from, + quoted_after(&advice, &format!("\"{}\" to ", from.display())), + )?; + let renamed = AppPaths::discover_from_paths(paths, false, false)?; + assert_eq!(renamed.data_dir, default_root.data_dir); + assert!(RocmCliConfig::load(&renamed).is_ok()); + + fs::remove_dir_all(root).ok(); + Ok(()) + } + + /// The public method reads the same fallback discovery uses: paths whose + /// data dir is that fallback get no override advice, and any other data + /// dir is named as the override to set. Holds the data-dir lock because the + /// fallback reads `ROCM_CLI_DATA_DIR`, which other tests set. + #[test] + fn config_rename_advice_names_an_override_only_for_a_data_dir_discovery_would_lose() { + let _guard = crate::test_env::DATA_DIR_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = temp_app_paths("config-aside-advice-method"); + let rename = format!( + "To start from default settings instead, rename \"{config}\" to \"{config}.broken\"", + config = paths.config_path().display() + ); + let fallback = AppPaths { + data_dir: normalize_runtime_path_for_host( + &data_dir_without_config().expect("this host has a default data dir"), + ), + ..paths.clone() + }; + assert_eq!(fallback.config_aside_advice(), rename); + assert_eq!( + paths.config_aside_advice(), + format!( + "{rename}; the runtimes under \"{dir}\" then also need the environment variable \ + ROCM_CLI_DATA_DIR set to \"{dir}\"", + dir = paths.data_dir.display() + ) + ); + fs::remove_dir_all(root).ok(); + } + + /// A user who already set the `ROCM_CLI_DATA_DIR` the refusal suggested is + /// not told to set it again: with the variable naming the data dir, + /// renaming config.json leaves the data dir where it is, so the advice is + /// the rename alone. Drives the real environment read. + #[test] + fn config_rename_advice_names_no_override_once_rocm_cli_data_dir_is_set() { + let _guard = crate::test_env::DATA_DIR_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = temp_app_paths("config-aside-advice-env"); + let restore = crate::test_env::RestoredEnvVar::set("ROCM_CLI_DATA_DIR", &paths.data_dir); + let advice = paths.config_aside_advice(); + drop(restore); + fs::remove_dir_all(root).ok(); + assert_eq!( + advice, + format!( + "To start from default settings instead, rename \"{config}\" to \ + \"{config}.broken\"", + config = paths.config_path().display() + ) + ); + } + + /// The recorded folder is recovered from a damaged file only when its + /// string is complete: a value cut off part-way is never guessed at. + #[test] + fn recorded_root_is_recovered_only_from_a_complete_value() { + let escaped = br#"{"setup": {"therock_venv": "C:\\ROCm \"x\"\\venv", "completed"#; + assert_eq!( + recorded_root_in_damaged_config(escaped), + Some(PathBuf::from(r#"C:\ROCm "x"\venv"#)) + ); + for damaged in [ + &br#"{"setup": {"therock_venv": "/opt/ro"#[..], + br#"{"setup": {"therock_venv": 7"#, + br#"{"setup": {"therock_venv": " ", "#, + br#"{"setup": {"#, + ] { + assert_eq!( + recorded_root_in_damaged_config(damaged), + None, + "{}", + String::from_utf8_lossy(damaged) + ); + } + } #[test] fn cache_dir_follows_an_overridden_data_dir() -> Result<()> { let (root, _) = temp_app_paths("cache-follows-data"); @@ -497,11 +1123,11 @@ mod tests { cache: None, })?; assert_eq!( - configured_managed_root_from_config(&paths), + configured_managed_root_from_config(&paths)?, Some(managed_runtime), "the fixture must be a config the managed-root lookup reads" ); - let discovered = AppPaths::discover_from_paths(paths, true, false); + let discovered = AppPaths::discover_from_paths(paths, true, false)?; assert_eq!(discovered.data_dir, normalize_runtime_path_for_host(&data)); assert_eq!( discovered.cache_dir, diff --git a/crates/rocm-core/src/persisted_paths_props.rs b/crates/rocm-core/src/persisted_paths_props.rs new file mode 100644 index 0000000000..88ef899c22 --- /dev/null +++ b/crates/rocm-core/src/persisted_paths_props.rs @@ -0,0 +1,103 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Property: the two readers of `config.json` agree about where the data dir +//! is. +//! +//! `RocmCliConfig::load` fails loudly on a file it cannot parse. +//! `AppPaths::discover` reads the same file a second way, through +//! `configured_managed_root_from_config`, for the one field that decides where +//! the runtime registry, the active-runtime marker and the service records +//! live. It used to turn any read or parse error into "no managed root", so a +//! config one reader called corrupt the other called "absent", and the data +//! dir moved to the default with no message. Discovery must now either fail +//! or still find the recorded root. +//! +//! No environment is read or written: `discover_from_paths` is the env-free +//! core of `discover`. + +use std::path::PathBuf; +use std::sync::atomic::{AtomicUsize, Ordering}; + +use proptest::prelude::*; +use proptest::test_runner::{Config as RunnerConfig, TestError, TestRunner}; + +use crate::{AppPaths, RocmCliConfig}; + +static NEXT_DIR: AtomicUsize = AtomicUsize::new(0); + +fn fresh_paths() -> (PathBuf, AppPaths) { + let root = std::env::temp_dir().join(format!( + "rocm-core-paths-props-{}-{}", + std::process::id(), + NEXT_DIR.fetch_add(1, Ordering::Relaxed) + )); + let paths = AppPaths { + config_dir: root.join("config"), + data_dir: root.join("default-data"), + cache_dir: root.join("default-cache"), + }; + (root, paths) +} + +#[test] +fn data_dir_never_silently_relocates_when_config_is_unreadable() { + let total = AtomicUsize::new(0); + let unreadable = AtomicUsize::new(0); + let mut runner = TestRunner::new(RunnerConfig { + cases: crate::test_support::proptest_cases(256), + ..RunnerConfig::default() + }); + let strategy = ("[a-z]{1,10}", 1_usize..2048); + let result = runner.run(&strategy, |(leaf, cut)| { + total.fetch_add(1, Ordering::Relaxed); + let (root, paths) = fresh_paths(); + let managed_root = root.join("prefix").join(&leaf); + let mut config = RocmCliConfig::default(); + config.setup.therock_venv = Some(managed_root.clone()); + config.active_runtime_key = Some("therock-release-gfx1151-7.13.0".to_owned()); + config.save(&paths).unwrap(); + let healthy = AppPaths::discover_from_paths(paths.clone(), false, false).unwrap(); + prop_assert_eq!(&healthy.data_dir, &managed_root); + + // A truncated file: a hand edit cut short, or one damaged before saves + // became atomic. + let bytes = std::fs::read(paths.config_path()).unwrap(); + std::fs::write(paths.config_path(), &bytes[..cut.min(bytes.len() - 1)]).unwrap(); + let strict = RocmCliConfig::load(&paths); + let discovered = AppPaths::discover_from_paths(paths, false, false); + let _ = std::fs::remove_dir_all(&root); + if strict.is_ok() { + return Ok(()); + } + unreadable.fetch_add(1, Ordering::Relaxed); + // Failing is the agreement with `load`; a data dir is only acceptable + // if it is still the recorded one. + if let Ok(discovered) = discovered { + prop_assert_eq!( + &discovered.data_dir, + &managed_root, + "config.json is unreadable to RocmCliConfig::load, yet AppPaths::discover \ + silently moved data_dir (registry, marker, services) to the default" + ); + } + Ok(()) + }); + eprintln!( + "reach: {} of {} cases left a config.json that load() rejects", + unreadable.load(Ordering::Relaxed), + total.load(Ordering::Relaxed) + ); + match result { + Ok(()) => {} + Err(TestError::Fail(reason, value)) => { + panic!("minimal failing input {value:?}\nreason: {reason}") + } + Err(TestError::Abort(reason)) => panic!("aborted: {reason}"), + } + assert!( + unreadable.load(Ordering::Relaxed) > 0, + "no case left a config.json that load() rejects" + ); +} diff --git a/crates/rocm-core/src/test_env.rs b/crates/rocm-core/src/test_env.rs index 7e5bd9da58..e1af4d09b2 100644 --- a/crates/rocm-core/src/test_env.rs +++ b/crates/rocm-core/src/test_env.rs @@ -18,6 +18,12 @@ use std::ffi::OsString; use std::path::Path; +/// Serializes the tests that set `ROCM_CLI_DATA_DIR`, and the ones whose +/// expectations depend on it (the recovery advice for an unreadable +/// `config.json` names it). Named `*_TEST_LOCK` so the env-mutation contract +/// guard recognises the discipline by suffix. +pub(crate) static DATA_DIR_ENV_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + /// Sets an environment variable and puts the previous value back on drop. /// /// This RESTORES; it does not SERIALIZE. Two tests holding one of these for the diff --git a/docs/architecture.md b/docs/architecture.md index 93dca4dc8d..21fd12fa0c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -184,7 +184,7 @@ Already-extracted subsystem modules, following the same full-domain-extraction p - [`anthropic_endpoint.rs`](../crates/rocm-core/src/anthropic_endpoint.rs) — (ROCMAI-597) the Anthropic-compatible `/v1/messages` surface of a managed service: `AnthropicEndpointMode` (`rocm` fronts the OpenAI-speaking engine), and the readiness check and wait on the published endpoint. - [`amd_smi.rs`](../crates/rocm-core/src/amd_smi.rs) — (ROCMAI-723) locating the `amd-smi` binary: `resolve_amd_smi_binary` (re-exported at the crate root) prefers the newest managed ROCm SDK runtime recorded in the registry, then the home-directory venv and legacy locations, then the bare name for a `PATH` lookup. It only reads the registry records [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) exposes and [`runtime.rs`](../crates/rocm-core/src/runtime.rs)'s data/home directory lookups. As of EAI-8457 it also owns the *launch*: `amd_smi_json` (also re-exported at the crate root) is the one supported way for a synchronous caller to run `amd-smi`, because it is the only place the mandatory `/dev/kfd` pre-flight runs (`KFD_DEVICE`, `preflight_kfd_device`, `kfd_readable`/`kfd_readable_with`, and the thread-bounded, budget-capped `device_readable`/`device_readable_within_budget` probe behind `KFD_OPEN_TIMEOUT`). A device that cannot be opened declines the spawn rather than letting `amd-smi` park in uninterruptible sleep, where no timeout can reach it. The spawn itself still goes through [`process.rs`](../crates/rocm-core/src/process.rs)'s `run_with_timeout`, and the non-zero-exit quote is bounded with that module's `MAX_QUOTED_OUTPUT_CHARS` rather than a second copy of the constant. Callers: [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s `gpu_vram_usage_amd_smi`/`detect_gpu_count`, both through that module's own `amd_smi_probe_json` (which logs the discarded decline at `info`, since the default filter is `warn,rocm=info` and a decline on a healthy host is otherwise indistinguishable from "no GPU"), and `rocmd`'s [`host_snapshot.rs`](../apps/rocmd/src/host_snapshot.rs)`::capture_amd_smi_json`. That the list stays complete is enforced rather than asserted: [`amd_smi_launch_contract.rs`](../xtask/src/amd_smi_launch_contract.rs) is a static contract test failing any file outside its two-entry allowlist that calls `resolve_amd_smi_binary`, so a new probe cannot be spawned directly without a reviewed exemption. The `rocm dash` collectors keep their own pre-flight *decision* (`preflight_passes`), since they gate an async launch, but share this module's bounded device probe through the `pub fn device_readable_bounded` re-export — an allowlisted `rocm-dash-collectors -> rocm-core` edge recorded in [`crate_edges.rs`](../xtask/src/crate_edges.rs), so the one launch site outside this chokepoint cannot drift away from the bound and the budget. -- [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) — the shared atomic file writer behind `rocm`, `rocmd`, this crate's own atomic replaces ([`config.rs`](../crates/rocm-core/src/config.rs)'s `RocmCliConfig::save`, the automation event and proposal stores in [`automation.rs`](../crates/rocm-core/src/automation.rs), the JSONL stores in [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs), the service-record manifests in [`service_record.rs`](../crates/rocm-core/src/service_record.rs)) and the Lemonade engine's rewrite of `backend_versions.json` in [`install.rs`](../engines/lemonade/src/install.rs) (unique exclusive temp file, then rename, which on Windows falls back to `ReplaceFileW` only if the rename fails); atomic, not durable, since nothing is fsynced. Other hand-rolled temp-then-rename writers remain outside it, for example [`remote/session.rs`](../apps/rocm/src/remote/session.rs)'s session-file write, [`uninstall.rs`](../apps/rocm/src/uninstall.rs)'s profile replacement and `write_atomically` in [`comfyui/source_swap.rs`](../apps/rocm/src/comfyui/source_swap.rs). A new atomic write should call this module rather than add another copy. +- [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) — the shared atomic file writer behind `rocm`, `rocmd`, this crate's own atomic replaces ([`config.rs`](../crates/rocm-core/src/config.rs)'s `RocmCliConfig::save`, the automation event and proposal stores in [`automation.rs`](../crates/rocm-core/src/automation.rs), the JSONL stores in [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs), the service-record manifests in [`service_record.rs`](../crates/rocm-core/src/service_record.rs)) and the Lemonade engine's rewrite of `backend_versions.json` in [`install.rs`](../engines/lemonade/src/install.rs) (unique exclusive temp file, then rename, which on Windows falls back to `ReplaceFileW` only if the rename fails); durable as well as atomic: the temp file is flushed before it is published and, on Unix, the directory after it; on Unix it keeps the replaced file's permission bits, and `write_file_atomically` replaces a symlink's target rather than the link. Other hand-rolled temp-then-rename writers remain outside it, for example [`remote/session.rs`](../apps/rocm/src/remote/session.rs)'s session-file write, [`uninstall.rs`](../apps/rocm/src/uninstall.rs)'s profile replacement and `write_atomically` in [`comfyui/source_swap.rs`](../apps/rocm/src/comfyui/source_swap.rs). A new atomic write should call this module rather than add another copy. - [`automation.rs`](../crates/rocm-core/src/automation.rs) — (ROCMAI-151) automation-daemon runtime state and its on-disk event/proposal/audit records, and the policy applied to each store (which are rotated, and the proposal compaction) — see the module's own doc comment for what it owns. The generic JSONL machinery under those stores lives in [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs). The dependency runs one way: this module reads `WatcherMode` from [`config.rs`](../crates/rocm-core/src/config.rs), and [`config.rs`](../crates/rocm-core/src/config.rs) imports nothing from here, because the built-in watcher catalog (whose entries carry a default `WatcherMode`, and which `RocmCliConfig::watcher_enabled` and `effective_watcher_mode` take as an argument) lives in [`config.rs`](../crates/rocm-core/src/config.rs) beside `WatcherMode`. - [`binary_paths.rs`](../crates/rocm-core/src/binary_paths.rs) — (ROCMAI-151, Phase 7d) locating `rocm-engine-` siblings, and the CLI binary itself (a sibling `rocm` only when running from a cargo `deps/` directory). - [`codex_bridge.rs`](../crates/rocm-core/src/codex_bridge.rs) — (ROCMAI-662) the `CodexBridgeSnapshot`/`CodexBridgeGpuSnapshot`/`CodexBridgeEngine` host-snapshot DTOs. Plain serde data: `rocm` and `rocmd` each build their own snapshot of this shape, so the types live here rather than in either binary. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 0a4aaacc9b..d20769f359 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -111,6 +111,20 @@ Expected result: - `rocm runtimes list` shows the runtime key for the installed TheRock venv. - The active runtime is ready, or the output gives one clear next command. +Optional: an unreadable settings file. Copy `config.json` from the config +directory aside, cut the original off part-way through, and run `rocm version` +without `ROCM_CLI_DATA_DIR` set. Expected result: + +- The command fails and names `config.json`, saying it cannot be read, and + explains the three ways out: repair it; set `ROCM_CLI_DATA_DIR` (it names the + folder if the damaged file still shows it), after which commands that change + settings still stop and others either stop or run on default settings; or + rename it to the `config.json.broken` path it names, which resets every + setting and leaves runtimes in a custom folder reachable only through + `ROCM_CLI_DATA_DIR`. +- `config.json` is byte-for-byte what you left; nothing was saved over it. +- Restoring the copy makes `rocm runtimes list` show the same runtimes as before. + ## 2. TheRock SDK Command-Line Install This tests the command-line install path without using the TUI: diff --git a/docs/testing.md b/docs/testing.md index e7dcd96fd5..32b9b5a2b6 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -450,6 +450,25 @@ append a deliberately unparsable line to it, run the test with `--nocapture` The check does not tell a seed that still reproduces from one that no longer does; it only confirms that something reads the file. +### Property tests for persisted settings + +`config.json`, its migration from a legacy rocm-dash `config.toml`, and how +the data directory is found from it have `proptest` properties, beside the +code they drive. They run in the ordinary `cargo test`; to run only them: + +```bash +cargo test -p rocm-core --lib config::props -- --nocapture +cargo test -p rocm-core --lib persisted_paths_props -- --nocapture +cargo test -p rocm --bin rocm therock::python::config_props -- --nocapture +``` + +Each property counts how many generated cases reached the input it is about +(an unreadable `config.json`, a non-finite tick, non-ASCII text, and so on), +prints that as a `reach:` line (`--nocapture` shows it), and fails when the +count is zero, so a generator that stops producing that input fails the run +instead of passing without testing anything. A property that fails prints its +shrunk counterexample. + ### Known-gap reproducers Most `#[ignore]` attributes in the tree gate on the environment: a GPU, a live diff --git a/tests/e2e-cucumber/features/config.feature b/tests/e2e-cucumber/features/config.feature index abb937cf40..7d1799fa88 100644 --- a/tests/e2e-cucumber/features/config.feature +++ b/tests/e2e-cucumber/features/config.feature @@ -67,3 +67,50 @@ Feature: Configuration mutations When the user saves a provider API key Then the CLI reports it could not save the key securely And the key value never appears in the output + + # A settings file the CLI cannot read must not be mistaken for "no settings". + # It records where the user's runtimes live; guessing the default folder + # instead makes them disappear from every answer, and later writes land in + # the wrong place. The CLI stops, says which file, which folder it still + # names, and how to recover, and leaves the file alone so nothing more is + # lost. Two of the ways out it offers are then taken as printed — naming the + # data folder it suggests, and renaming the exact file it names to the name + # it gives — and what it says each one does is checked. Repairing the file is + # not exercised here. + @id:config-unreadable-settings-not-guessed + Scenario: config-09 - A settings file the CLI cannot read stops it instead of hiding the user's runtimes + Given the CLI's settings file was cut short just after it recorded a custom ROCm folder holding an installed runtime + When the user checks the CLI version without naming a data folder + Then the CLI refuses, naming the settings file, the recorded folder and how to recover + And the settings file is left exactly as it was + When the user opens the CLI with the data folder the refusal suggested + Then the CLI keeps its data in the recorded folder, on default settings + And the settings file is left exactly as it was + When the user changes a setting with the data folder the refusal suggested + Then the CLI refuses to change the setting, naming the settings file to rename + And the settings file is left exactly as it was + When the user renames the settings file as the refusal said and opens the CLI without naming a data folder + Then the CLI keeps its data in its default folder + When the user lists runtimes with the data folder the refusal suggested + Then the runtime installed in the recorded folder is listed + + # Saving settings replaces config.json in one step, but must not change what + # the user set up around it: a file only its owner may read stays that way, + # and a settings file that is a link (a dotfiles checkout, say) stays a link + # while the file it points at gets the new settings. These are Unix + # permissions and links, so the scenarios run on Linux only. + @id:config-save-keeps-a-private-settings-file-private @requires-os:linux + Scenario: config-10 - Changing a setting keeps a private settings file private + Given a settings file that only its owner can read + When the user turns telemetry off + Then the CLI confirms the telemetry mode and states the policy + And the settings file is still readable only by its owner + And the settings file records telemetry as off + + @id:config-save-keeps-a-linked-settings-file-linked @requires-os:linux + Scenario: config-11 - Changing a setting through a linked settings file keeps the link + Given a settings file that is a link to a file kept elsewhere + When the user turns telemetry off + Then the CLI confirms the telemetry mode and states the policy + And the settings file is still a link to that file + And the linked-to file records telemetry as off diff --git a/tests/e2e-cucumber/tests/e2e.rs b/tests/e2e-cucumber/tests/e2e.rs index 63a8f41d00..900b7bad68 100644 --- a/tests/e2e-cucumber/tests/e2e.rs +++ b/tests/e2e-cucumber/tests/e2e.rs @@ -98,6 +98,14 @@ pub struct E2eWorld { /// does not establish that the prune blocked. Set by the When step that /// measures it; `None` everywhere else. pub cli_elapsed: Option, + /// The `ROCM_CLI_DATA_DIR` value a refusal told the user to set, read from + /// its stderr by the first step that follows that advice, so later steps + /// can follow it again after other commands have replaced `cli_stderr`. + pub suggested_data_dir: Option, + /// The file a refusal told the user to rename and the name to give it, + /// read from its stderr by the step that checks the refusal, for the step + /// that follows that advice after other commands have replaced `cli_stderr`. + pub suggested_settings_rename: Option<(String, String)>, /// Extra environment for `rocm remote` scenarios: a `PATH` carrying the /// tailscale stand-in, and the status document it should serve. Set by a /// Given step so the When steps stay about what the user does. @@ -352,6 +360,8 @@ impl Default for E2eWorld { cli_rc: None, serve_runs: None, cli_elapsed: None, + suggested_data_dir: None, + suggested_settings_rename: None, remote_env: Vec::new(), launch_release: None, launch_stage: None, @@ -1023,6 +1033,44 @@ pub fn run_rocm_with_env_and_unset( ) } +/// Like [`run_rocm`], but without `ROCM_CLI_DATA_DIR`, so the CLI has to work +/// out its data folder from its own settings file as it does for a user who +/// never set it. +/// +/// The home directory is pointed inside the scenario's sandbox as well, so the +/// default data folder the CLI falls back to (`~/.rocm`) is never the real +/// one on the runner. +pub fn run_rocm_without_data_dir_override( + world: &E2eWorld, + args: &[&str], +) -> (String, String, i32) { + let binary = rocm_binary(); + let home = world + .isolated_root + .as_ref() + .expect("scenario has an isolated root") + .path() + .join("home"); + std::fs::create_dir_all(&home).expect("failed to create sandbox home"); + let mut cmd = std::process::Command::new(&binary); + cmd.args(args); + world.isolate_cmd(&mut cmd); + cmd.env_remove("ROCM_CLI_DATA_DIR"); + cmd.env("HOME", &home); + cmd.env("USERPROFILE", &home); + let output = cmd + .output() + .unwrap_or_else(|e| panic!("failed to run {binary}: {e}")); + let rc = output.status.code().unwrap_or(-1); + let stdout = String::from_utf8_lossy(&output.stdout).to_string(); + record_command(world.current_scenario.as_deref(), args, rc, &stdout); + ( + stdout, + String::from_utf8_lossy(&output.stderr).to_string(), + rc, + ) +} + /// Run `rocm` with the behavioral fixture established by a Given step, then /// consume it so it cannot leak into a later action in the same scenario. pub fn run_rocm_with_scenario_env(world: &mut E2eWorld, args: &[&str]) -> (String, String, i32) { diff --git a/tests/e2e-cucumber/tests/e2e/config_steps.rs b/tests/e2e-cucumber/tests/e2e/config_steps.rs index 726b3de098..dfb518892b 100644 --- a/tests/e2e-cucumber/tests/e2e/config_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/config_steps.rs @@ -211,6 +211,395 @@ async fn confirm_key_not_echoed(world: &mut E2eWorld) { ); } +// ── Unreadable settings file ────────────────────────────────────── + +/// The custom ROCm folder the damaged settings file records, inside the +/// scenario's sandbox so the suggested `ROCM_CLI_DATA_DIR` can be used as-is. +/// Its name has a space, so the refusal's advice only works if it quotes it. +fn custom_rocm_folder(world: &E2eWorld) -> std::path::PathBuf { + sandbox(world).join("custom rocm") +} + +/// The path in double quotes right after the first `label` in `stderr`: what +/// a user copies when the refusal tells them which path to use. +fn quoted_after(stderr: &str, label: &str) -> String { + let (_, rest) = stderr + .split_once(label) + .unwrap_or_else(|| panic!("the refusal does not say {label:?}:\n{stderr}")); + let rest = rest + .strip_prefix('"') + .unwrap_or_else(|| panic!("no quoted path after {label:?}:\n{stderr}")); + let (path, _) = rest + .split_once('"') + .unwrap_or_else(|| panic!("an unclosed quote after {label:?}:\n{stderr}")); + path.to_owned() +} + +/// A `config.json` cut off just after it recorded `setup.therock_venv`, the +/// field that tells the CLI where a custom-folder install keeps its runtimes. +/// Black-box: plain bytes, as an interrupted write or a bad hand edit leaves +/// them. Derived from the sandbox, so every Then can rebuild it and compare +/// byte for byte. +fn cut_short_settings(world: &E2eWorld) -> String { + let folder = serde_json::to_string(&custom_rocm_folder(world)) + .expect("failed to encode the custom folder"); + format!( + "{{\n \"active_runtime_key\": \"therock-release-gfx1151-7.13.0\",\n \"setup\": {{\n \ + \"therock_venv\": {folder},\n \"comp" + ) +} + +fn sandbox(world: &E2eWorld) -> std::path::PathBuf { + world + .isolated_root + .as_ref() + .expect("scenario has an isolated root") + .path() + .to_path_buf() +} + +fn settings_path(world: &E2eWorld) -> std::path::PathBuf { + sandbox(world).join("config").join("config.json") +} + +fn renamed_settings_path(world: &E2eWorld) -> std::path::PathBuf { + sandbox(world).join("config").join("config.json.broken") +} + +/// The runtime planted in the custom folder; the damaged settings file names +/// it as the active one. +const CUSTOM_FOLDER_RUNTIME_KEY: &str = "therock-release-gfx1151-7.13.0"; + +#[given( + "the CLI's settings file was cut short just after it recorded a custom ROCm folder holding \ + an installed runtime" +)] +async fn settings_cut_short(world: &mut E2eWorld) { + let path = settings_path(world); + std::fs::create_dir_all(path.parent().expect("settings file has a parent")) + .expect("failed to create config dir"); + std::fs::write(&path, cut_short_settings(world)).expect("failed to plant settings file"); + + // A read-only tarball runtime registered in the custom folder's own + // registry, as `rocm install sdk --prefix` leaves it. Plain JSON matching + // the on-disk manifest schema, black-box like the settings file above. + let folder = custom_rocm_folder(world); + let install_root = folder.join("runtime-gfx1151"); + std::fs::create_dir_all(&install_root).expect("failed to create install root"); + std::fs::write(install_root.join("payload.txt"), "payload") + .expect("failed to write runtime payload"); + let registry = folder.join("runtimes").join("registry"); + std::fs::create_dir_all(®istry).expect("failed to create registry dir"); + let manifest = serde_json::to_string_pretty(&serde_json::json!({ + "runtime_key": CUSTOM_FOLDER_RUNTIME_KEY, + "runtime_id": "therock-release:gfx1151", + "channel": "release", + "format": "tarball", + "family": "gfx1151", + "family_source": "manual", + "version": "7.13.0", + "install_root": install_root, + "selected_artifact_url": format!("https://example.invalid/{CUSTOM_FOLDER_RUNTIME_KEY}.tar.gz"), + "read_only": true, + "installed_at_unix_ms": 1_700_000_000_000u64, + })) + .expect("failed to serialize runtime manifest"); + std::fs::write( + registry.join(format!("{CUSTOM_FOLDER_RUNTIME_KEY}.json")), + manifest, + ) + .expect("failed to write runtime manifest"); +} + +#[when("the user checks the CLI version without naming a data folder")] +async fn version_without_data_dir(world: &mut E2eWorld) { + let (stdout, stderr, rc) = crate::run_rocm_without_data_dir_override(world, &["version"]); + record(world, stdout, stderr, rc); +} + +#[when("the user opens the CLI with the data folder the refusal suggested")] +async fn open_with_suggested_data_dir(world: &mut E2eWorld) { + // Take the value from the refusal itself, so this runs the advice as + // printed rather than a value the test already knows. + let folder = suggested_data_dir(world); + let (stdout, stderr, rc) = + crate::run_rocm_with_env(world, &[], &[("ROCM_CLI_DATA_DIR", &folder)]); + record(world, stdout, stderr, rc); +} + +#[when("the user changes a setting with the data folder the refusal suggested")] +async fn change_setting_with_suggested_data_dir(world: &mut E2eWorld) { + let folder = suggested_data_dir(world); + let (stdout, stderr, rc) = crate::run_rocm_with_env( + world, + &["config", "set-telemetry", "off"], + &[("ROCM_CLI_DATA_DIR", &folder)], + ); + record(world, stdout, stderr, rc); +} + +/// The `ROCM_CLI_DATA_DIR` value the refusal told the user to set, read from +/// its stderr — "setting the environment variable ROCM_CLI_DATA_DIR to +/// \"\" ..." — the first time it is needed, and remembered for the +/// steps after that. +fn suggested_data_dir(world: &mut E2eWorld) -> String { + if let Some(folder) = &world.suggested_data_dir { + return folder.clone(); + } + let stderr = world.cli_stderr.as_deref().unwrap_or(""); + let folder = quoted_after( + stderr, + "setting the environment variable ROCM_CLI_DATA_DIR to ", + ); + world.suggested_data_dir = Some(folder.clone()); + folder +} + +#[when( + "the user renames the settings file as the refusal said and opens the CLI without naming a \ + data folder" +)] +async fn open_after_renaming_settings(world: &mut E2eWorld) { + // The paths come from the refusal itself, read by the step that checked + // it, so this follows the advice as printed. + let (from, to) = world + .suggested_settings_rename + .clone() + .expect("the refusal was checked before its advice is followed"); + std::fs::rename(&from, &to).expect("failed to rename the settings file"); + assert_eq!( + std::fs::read_to_string(&to).expect("the renamed settings file is gone"), + cut_short_settings(world), + "renaming the settings file changed its contents" + ); + let (stdout, stderr, rc) = crate::run_rocm_without_data_dir_override(world, &[]); + record(world, stdout, stderr, rc); +} + +#[then("the CLI refuses, naming the settings file, the recorded folder and how to recover")] +async fn refuses_unreadable_settings(world: &mut E2eWorld) { + assert_failed(world); + let stderr = world.cli_stderr.as_deref().unwrap_or(""); + let suggestion = format!( + "setting the environment variable ROCM_CLI_DATA_DIR to \"{}\"", + custom_rocm_folder(world).display() + ); + for needle in [ + "cannot tell where rocm-cli keeps its data", + "config.json", + "cannot be read", + "Repair that file", + suggestion.as_str(), + "any command that changes settings still stops on it", + "run on default settings", + ] { + assert!( + stderr.contains(needle), + "expected stderr to contain {needle:?}, got:\n{}", + combined_output(world) + ); + } + // The file to rename is the exact one the CLI read — here under the + // scenario's own config folder — and the name to give it sits beside it. + // Both are read from between their quotes, as a user would copy them. + let from = quoted_after(stderr, "keeps its data: "); + let to = quoted_after(stderr, "Renaming it to "); + assert_eq!(std::path::Path::new(&from), settings_path(world)); + assert_eq!(std::path::Path::new(&to), renamed_settings_path(world)); + world.suggested_settings_rename = Some((from, to)); +} + +#[then("the settings file is left exactly as it was")] +async fn settings_unchanged(world: &mut E2eWorld) { + let after = std::fs::read_to_string(settings_path(world)).expect("settings file is gone"); + assert_eq!( + after, + cut_short_settings(world), + "the CLI rewrote the settings file" + ); +} + +/// Where config-11 keeps the file its settings link points at: outside the +/// config directory, as a dotfiles checkout would be. +fn linked_settings_target(world: &E2eWorld) -> std::path::PathBuf { + sandbox(world).join("dotfiles").join("rocm-config.json") +} + +fn telemetry_mode_in(path: &std::path::Path) -> String { + let text = std::fs::read_to_string(path) + .unwrap_or_else(|e| panic!("cannot read {}: {e}", path.display())); + let value: serde_json::Value = serde_json::from_str(&text) + .unwrap_or_else(|e| panic!("{} is not JSON ({e}):\n{text}", path.display())); + value["telemetry"]["mode"] + .as_str() + .unwrap_or_else(|| panic!("{} records no telemetry mode:\n{text}", path.display())) + .to_owned() +} + +#[given("a settings file that only its owner can read")] +async fn private_settings_file(world: &mut E2eWorld) { + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + let path = settings_path(world); + std::fs::create_dir_all(path.parent().expect("settings file has a parent")) + .expect("failed to create config dir"); + std::fs::write(&path, "{}\n").expect("failed to plant settings file"); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)) + .expect("failed to make the settings file private"); + } + #[cfg(not(unix))] + { + let _ = world; + panic!("tagged @requires-os:linux: needs Unix permissions"); + } +} + +#[then("the settings file is still readable only by its owner")] +async fn settings_still_private(world: &mut E2eWorld) { + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + let mode = std::fs::metadata(settings_path(world)) + .expect("settings file is gone") + .permissions() + .mode(); + assert_eq!( + mode & 0o777, + 0o600, + "saving changed the settings file's permissions to {:o}", + mode & 0o777 + ); + } + #[cfg(not(unix))] + { + let _ = world; + panic!("tagged @requires-os:linux: needs Unix permissions"); + } +} + +#[then("the settings file records telemetry as off")] +async fn settings_record_telemetry_off(world: &mut E2eWorld) { + assert_eq!(telemetry_mode_in(&settings_path(world)), "off"); +} + +#[given("a settings file that is a link to a file kept elsewhere")] +async fn linked_settings_file(world: &mut E2eWorld) { + #[cfg(unix)] + { + let target = linked_settings_target(world); + std::fs::create_dir_all(target.parent().expect("link target has a parent")) + .expect("failed to create the dotfiles folder"); + std::fs::write(&target, "{}\n").expect("failed to plant the linked-to file"); + let path = settings_path(world); + std::fs::create_dir_all(path.parent().expect("settings file has a parent")) + .expect("failed to create config dir"); + std::os::unix::fs::symlink(&target, &path).expect("failed to link the settings file"); + } + #[cfg(not(unix))] + { + let _ = world; + panic!("tagged @requires-os:linux: needs Unix links"); + } +} + +#[then("the settings file is still a link to that file")] +async fn settings_still_linked(world: &mut E2eWorld) { + let path = settings_path(world); + let metadata = std::fs::symlink_metadata(&path).expect("settings file is gone"); + assert!( + metadata.file_type().is_symlink(), + "saving replaced the linked settings file with a regular file" + ); + assert_eq!( + std::fs::read_link(&path).expect("cannot read the settings link"), + linked_settings_target(world), + "the settings link now points somewhere else" + ); +} + +#[then("the linked-to file records telemetry as off")] +async fn linked_target_records_telemetry_off(world: &mut E2eWorld) { + assert_eq!(telemetry_mode_in(&linked_settings_target(world)), "off"); +} + +/// The launcher summary's `data dir:` line, from a run that succeeded. +fn launcher_data_dir(world: &E2eWorld) -> String { + assert_ok_contains(world, "active runtime key: "); + let stdout = world.cli_output.as_deref().unwrap_or(""); + stdout + .lines() + .find_map(|line| line.trim().strip_prefix("data dir: ")) + .unwrap_or_else(|| panic!("the CLI did not say where its data is:\n{stdout}")) + .to_owned() +} + +// "On default settings" is what `active runtime key: ` shows: the broken +// file records an active runtime key, and the CLI is not reading it. +#[then("the CLI keeps its data in the recorded folder, on default settings")] +async fn data_in_recorded_folder(world: &mut E2eWorld) { + let data_dir = launcher_data_dir(world); + assert_eq!( + std::path::Path::new(&data_dir), + custom_rocm_folder(world), + "the suggested ROCM_CLI_DATA_DIR did not point the CLI at the recorded folder" + ); +} + +/// The default data folder: `.rocm` under the home directory +/// `run_rocm_without_data_dir_override` gives the CLI. +#[then("the CLI keeps its data in its default folder")] +async fn data_in_default_folder(world: &mut E2eWorld) { + let data_dir = launcher_data_dir(world); + assert_eq!( + std::path::Path::new(&data_dir), + sandbox(world).join("home").join(".rocm"), + "with the settings file renamed, the CLI did not go back to its default folder" + ); +} + +#[when("the user lists runtimes with the data folder the refusal suggested")] +async fn list_runtimes_with_suggested_data_dir(world: &mut E2eWorld) { + let folder = suggested_data_dir(world); + let (stdout, stderr, rc) = crate::run_rocm_with_env( + world, + &["runtimes", "list"], + &[("ROCM_CLI_DATA_DIR", &folder)], + ); + record(world, stdout, stderr, rc); +} + +#[then("the runtime installed in the recorded folder is listed")] +async fn custom_folder_runtime_listed(world: &mut E2eWorld) { + assert_ok_contains(world, CUSTOM_FOLDER_RUNTIME_KEY); +} + +/// The data folder is already the one the refusal suggested, so the advice +/// is the rename alone, naming the exact file and the name to give it; that +/// following it works is the rename step later in the same scenario. +#[then("the CLI refuses to change the setting, naming the settings file to rename")] +async fn refuses_to_change_setting(world: &mut E2eWorld) { + assert_failed(world); + let stderr = world.cli_stderr.as_deref().unwrap_or(""); + let rename = format!( + "To start from default settings instead, rename \"{}\" to \"{}\"", + settings_path(world).display(), + renamed_settings_path(world).display() + ); + assert!( + stderr.contains("Repair that file") && stderr.contains(&rename), + "expected the refusal to say {rename:?}, got:\n{}", + combined_output(world) + ); + // The user already set the folder the first refusal suggested, so being + // told to set it again would be wrong. + assert!( + !stderr.contains("then also need the environment variable ROCM_CLI_DATA_DIR"), + "the refusal repeated the ROCM_CLI_DATA_DIR advice the user already followed:\n{}", + combined_output(world) + ); +} + // ── Helpers ──────────────────────────────────────────────────────── fn record(world: &mut E2eWorld, stdout: String, stderr: String, rc: i32) {