diff --git a/crates/rocm-core/src/codex_bridge.rs b/crates/rocm-core/src/codex_bridge.rs new file mode 100644 index 0000000000..1feb9828a6 --- /dev/null +++ b/crates/rocm-core/src/codex_bridge.rs @@ -0,0 +1,56 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! The `rocmd-codex-bridge-v0` host snapshot: the serde DTOs describing a +//! host — examine summary, GPU snapshot, config, automation state, engines, +//! and managed services — at one point in time. +//! +//! Plain data only. `rocm` and `rocmd` each build and emit their own snapshot +//! of this shape (`rocmd`'s automation watchers also use the GPU part on its +//! own); sharing the types here keeps the two from drifting apart. + +use serde::{Deserialize, Serialize}; + +use crate::{ + AutomationEventRecord, AutomationRuntimeState, ExamineSummary, ManagedServiceRecord, + RocmCliConfig, +}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct CodexBridgeSnapshot { + pub protocol: String, + pub generated_at_unix_ms: u128, + pub examine: ExamineSummary, + pub gpu: CodexBridgeGpuSnapshot, + pub config: RocmCliConfig, + #[serde(default)] + pub automation_runtime: Option, + #[serde(default)] + pub recent_automation_events: Vec, + #[serde(default)] + pub engines: Vec, + #[serde(default)] + pub services: Vec, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct CodexBridgeGpuSnapshot { + pub amd_smi_available: bool, + #[serde(skip_serializing_if = "Option::is_none")] + pub static_snapshot: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub monitor_snapshot: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub note: Option, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct CodexBridgeEngine { + pub id: String, + pub summary: String, + pub default_for_platform: bool, + pub installed_binary: bool, + #[serde(skip_serializing_if = "Option::is_none")] + pub binary_path: Option, +} diff --git a/crates/rocm-core/src/endpoint_key.rs b/crates/rocm-core/src/endpoint_key.rs new file mode 100644 index 0000000000..df1683c065 --- /dev/null +++ b/crates/rocm-core/src/endpoint_key.rs @@ -0,0 +1,92 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! The bearer key that guards a managed service's endpoint. +//! +//! The endpoint-API-key generator and its header-safety check. Drawn from a +//! CSPRNG — deliberately never derived from [`crate::service_identity`]'s +//! timestamp-based, guessable [`crate::generate_service_id`] — the two meet +//! only at the filesystem layer, where a service's endpoint key is stored in a +//! sidecar named after its [`crate::ServiceId`]. + +/// Number of random alphanumeric characters in a generated endpoint API key. +/// 48 chars from a 62-symbol alphabet is ~285 bits of entropy — far beyond what +/// a bearer token guarding a network endpoint needs, with no padding characters +/// that would complicate copy/paste into client configs or shell env vars. +const ENDPOINT_API_KEY_LEN: usize = 48; + +/// Generate a fresh, cryptographically-random API key for a public endpoint. +/// +/// The value is URL-safe alphanumeric (`[A-Za-z0-9]`) so it can be dropped +/// verbatim into an `Authorization: Bearer` header, a client config file, or an +/// environment variable without escaping. +/// +/// Drawn from `rand::rng()`, a CSPRNG seeded from the operating system; +/// deliberately *not* derived from `generate_service_id` (a timestamp-based, +/// guessable identifier — unsuitable as a secret). +pub fn generate_endpoint_api_key() -> String { + use rand::Rng; + use rand::distr::Alphanumeric; + + rand::rng() + .sample_iter(&Alphanumeric) + .take(ENDPOINT_API_KEY_LEN) + .map(char::from) + .collect() +} + +/// Return `true` if `key` contains a character that must never appear in an API +/// key used verbatim in an `Authorization: Bearer` header. +/// +/// The CLI and engine adapters build those header lines by raw string +/// interpolation (`Authorization: Bearer {key}\r\n`), so an embedded CR or LF in +/// the key would inject additional header lines (HTTP header injection). A +/// control character has no legitimate place in a bearer token, so we reject the +/// whole class rather than only CR/LF. Callers apply this at input validation +/// (rejecting a supplied key) and defensively when reading the key file. +pub fn endpoint_api_key_has_forbidden_chars(key: &str) -> bool { + key.chars().any(char::is_control) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn generate_endpoint_api_key_is_random_and_alphanumeric() { + let key = generate_endpoint_api_key(); + assert_eq!(key.len(), ENDPOINT_API_KEY_LEN); + // The message deliberately omits the key: it is a credential, and a + // failing assertion's message ends up in CI logs. + assert!( + key.chars().all(|c| c.is_ascii_alphanumeric()), + "key must be URL-safe alphanumeric" + ); + // Two draws must differ — a constant key would be catastrophic for auth. + assert_ne!(generate_endpoint_api_key(), generate_endpoint_api_key()); + // A freshly generated key must itself pass the header-safety predicate. + assert!(!endpoint_api_key_has_forbidden_chars( + &generate_endpoint_api_key() + )); + } + + #[test] + fn endpoint_api_key_has_forbidden_chars_flags_control_chars() { + // Control characters (notably CR/LF) enable header injection when the key + // is interpolated into a raw `Authorization: Bearer` line. + for bad in ["key\r\ninject", "key\nother", "tab\there", "nul\0byte"] { + assert!( + endpoint_api_key_has_forbidden_chars(bad), + "should reject {bad:?}" + ); + } + // Ordinary printable keys are accepted. + for good in ["my-key", "AbC123._~-", "sk-proj-abcDEF0123456789"] { + assert!( + !endpoint_api_key_has_forbidden_chars(good), + "should accept {good:?}" + ); + } + } +} diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index ec4163dc25..aab8837920 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -3,7 +3,6 @@ // SPDX-License-Identifier: MIT use anyhow::{Context, Result, bail}; -use serde::{Deserialize, Serialize}; use std::ffi::OsString; use std::fs; use std::path::{Path, PathBuf}; @@ -14,10 +13,12 @@ mod archive_props; pub mod automation; pub mod binary_paths; pub mod browser; +pub mod codex_bridge; pub mod config; pub mod crypto; pub mod diagnose; pub mod disk_space; +pub mod endpoint_key; pub mod examine; pub mod fake_executable; pub mod fix; @@ -37,6 +38,7 @@ pub mod report; pub mod report_delivery; pub mod rocm_install; pub mod runtime; +pub mod service_identity; pub mod service_record; pub mod terminal; pub mod user_path; @@ -55,6 +57,7 @@ pub use automation::{ update_automation_proposal_status, }; pub use binary_paths::{daemon_binary_path, engine_binary_path, sibling_binary_path}; +pub use codex_bridge::{CodexBridgeEngine, CodexBridgeGpuSnapshot, CodexBridgeSnapshot}; pub use config::{ AutomationsConfig, DashboardConfig, DashboardDaemonConfig, DashboardTuiConfig, EngineUserConfig, ManagedToolConfig, PERMISSIONS_MODE_ASK, PERMISSIONS_MODE_FULL_ACCESS, @@ -76,6 +79,7 @@ pub use disk_space::{ estimated_extracted_size, format_bytes, insufficient_space_message, map_write_error, mount_for_path, on_same_mount, warn_if_low_space, with_margin, }; +pub use endpoint_key::{endpoint_api_key_has_forbidden_chars, generate_endpoint_api_key}; pub use examine::{ Examination, FrameworkProbe, WSL_PLATFORM_NOTE, gfx_is_apu_family, probe_wsl_distro_from_host, }; @@ -174,6 +178,7 @@ pub use runtime::{ runtime_python_env_bin_dir, runtime_python_executable_in_env, runtime_python_executable_name, runtime_rocm_library_filename, shell_command_for_host, user_runtime_dir, }; +pub use service_identity::{ServiceId, generate_service_id}; pub use service_record::ManagedServiceRecord; pub use uv::{ DEFAULT_UV_TIMEOUT_SECS, DependencyViolation, UV_CACHE_DIR_ENV, UV_CACHE_DIR_OVERRIDE_ENV, @@ -226,83 +231,6 @@ pub fn command_failure_detail(output: &std::process::Output) -> String { "no output".to_owned() } -/// Number of random alphanumeric characters in a generated endpoint API key. -/// 48 chars from a 62-symbol alphabet is ~285 bits of entropy — far beyond what -/// a bearer token guarding a network endpoint needs, with no padding characters -/// that would complicate copy/paste into client configs or shell env vars. -const ENDPOINT_API_KEY_LEN: usize = 48; - -/// Generate a fresh, cryptographically-random API key for a public endpoint. -/// -/// The value is URL-safe alphanumeric (`[A-Za-z0-9]`) so it can be dropped -/// verbatim into an `Authorization: Bearer` header, a client config file, or an -/// environment variable without escaping. -/// -/// Drawn from `rand::rng()`, a CSPRNG seeded from the operating system; -/// deliberately *not* derived from `generate_service_id` (a timestamp-based, -/// guessable identifier — unsuitable as a secret). -pub fn generate_endpoint_api_key() -> String { - use rand::Rng; - use rand::distr::Alphanumeric; - - rand::rng() - .sample_iter(&Alphanumeric) - .take(ENDPOINT_API_KEY_LEN) - .map(char::from) - .collect() -} - -/// Return `true` if `key` contains a character that must never appear in an API -/// key used verbatim in an `Authorization: Bearer` header. -/// -/// The CLI and engine adapters build those header lines by raw string -/// interpolation (`Authorization: Bearer {key}\r\n`), so an embedded CR or LF in -/// the key would inject additional header lines (HTTP header injection). A -/// control character has no legitimate place in a bearer token, so we reject the -/// whole class rather than only CR/LF. Callers apply this at input validation -/// (rejecting a supplied key) and defensively when reading the key file. -pub fn endpoint_api_key_has_forbidden_chars(key: &str) -> bool { - key.chars().any(char::is_control) -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct CodexBridgeSnapshot { - pub protocol: String, - pub generated_at_unix_ms: u128, - pub examine: ExamineSummary, - pub gpu: CodexBridgeGpuSnapshot, - pub config: RocmCliConfig, - #[serde(default)] - pub automation_runtime: Option, - #[serde(default)] - pub recent_automation_events: Vec, - #[serde(default)] - pub engines: Vec, - #[serde(default)] - pub services: Vec, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct CodexBridgeGpuSnapshot { - pub amd_smi_available: bool, - #[serde(skip_serializing_if = "Option::is_none")] - pub static_snapshot: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub monitor_snapshot: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub note: Option, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct CodexBridgeEngine { - pub id: String, - pub summary: String, - pub default_for_platform: bool, - pub installed_binary: bool, - #[serde(skip_serializing_if = "Option::is_none")] - pub binary_path: Option, -} - pub fn resolve_amd_smi_binary() -> OsString { if let Some(path) = default_data_dir() .map(|data_dir| data_dir.join("runtimes").join("registry")) @@ -386,82 +314,6 @@ fn resolve_amd_smi_binary_in_home(home_dir: Option<&Path>) -> OsString { "amd-smi".into() } -/// A validated managed-service identifier that is safe to use as a single -/// filesystem path component. -/// -/// Every managed-service path (e.g. the endpoint-key sidecar) is built as -/// `services_dir().join(format!("{service_id}..."))`. A `ServiceId` can only be -/// constructed through [`ServiceId::new`], which rejects path separators, `..` -/// traversal, and control characters — so a value of this type can never make a -/// join escape its intended directory. Prefer threading a `ServiceId` (or -/// validating with it) over passing raw `&str` ids into path builders. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct ServiceId(String); - -impl ServiceId { - /// Validate an untrusted string as a service id. - /// - /// Rejects empty/whitespace-only input, path separators (`/` and `\`), `..` - /// traversal sequences, and control characters. Ids produced by - /// [`generate_service_id`] are always accepted. - /// - /// # Errors - /// Returns an error describing the first rule the input violates. - pub fn new(value: &str) -> Result { - if value.trim().is_empty() { - bail!("service id must not be empty"); - } - if value.contains('/') || value.contains('\\') { - bail!("service id must not contain path separators"); - } - if value.contains("..") { - bail!("service id must not contain `..`"); - } - if value.chars().any(char::is_control) { - bail!("service id must not contain control characters"); - } - Ok(Self(value.to_owned())) - } - - #[must_use] - pub fn as_str(&self) -> &str { - &self.0 - } -} - -impl std::convert::TryFrom<&str> for ServiceId { - type Error = anyhow::Error; - fn try_from(value: &str) -> Result { - Self::new(value) - } -} - -impl std::fmt::Display for ServiceId { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.write_str(&self.0) - } -} - -impl AsRef for ServiceId { - fn as_ref(&self) -> &str { - &self.0 - } -} - -pub fn generate_service_id(engine: &str, model_ref: &str) -> String { - let model_slug = sanitize_component(model_ref) - .trim_matches('-') - .chars() - .take(24) - .collect::(); - format!( - "{}-{}-{}", - sanitize_component(engine), - model_slug, - unix_time_millis() - ) -} - pub fn sanitize_component(value: &str) -> String { value .chars() @@ -527,74 +379,6 @@ mod tests { use std::fs; use std::path::Path; - #[test] - fn service_id_accepts_generated_and_plain_ids() { - // A freshly generated id must always validate. - let generated = generate_service_id("vllm", "Qwen/Qwen3.5"); - assert!(ServiceId::new(&generated).is_ok()); - // Plain alphanumeric-with-dashes ids validate and round-trip verbatim. - let id = ServiceId::new("svc-vllm-qwen-1730000000000").expect("valid id"); - assert_eq!(id.as_str(), "svc-vllm-qwen-1730000000000"); - assert_eq!(id.to_string(), "svc-vllm-qwen-1730000000000"); - } - - #[test] - fn service_id_rejects_traversal_and_separators() { - // Anything that could make `services_dir().join(id)` escape the directory - // (or otherwise not resolve to a single child component) is rejected. - for bad in [ - "", - " ", - "../../etc/passwd", - "..", - "a/b", - "a\\b", - "/abs", - "svc\r\ninject", - "svc\0nul", - ] { - assert!( - ServiceId::new(bad).is_err(), - "expected {bad:?} to be rejected" - ); - } - } - - #[test] - fn generate_endpoint_api_key_is_random_and_alphanumeric() { - let key = generate_endpoint_api_key(); - assert_eq!(key.len(), ENDPOINT_API_KEY_LEN); - assert!( - key.chars().all(|c| c.is_ascii_alphanumeric()), - "key must be URL-safe alphanumeric, got {key:?}" - ); - // Two draws must differ — a constant key would be catastrophic for auth. - assert_ne!(generate_endpoint_api_key(), generate_endpoint_api_key()); - // A freshly generated key must itself pass the header-safety predicate. - assert!(!endpoint_api_key_has_forbidden_chars( - &generate_endpoint_api_key() - )); - } - - #[test] - fn endpoint_api_key_has_forbidden_chars_flags_control_chars() { - // Control characters (notably CR/LF) enable header injection when the key - // is interpolated into a raw `Authorization: Bearer` line. - for bad in ["key\r\ninject", "key\nother", "tab\there", "nul\0byte"] { - assert!( - endpoint_api_key_has_forbidden_chars(bad), - "should reject {bad:?}" - ); - } - // Ordinary printable keys are accepted. - for good in ["my-key", "AbC123._~-", "sk-proj-abcDEF0123456789"] { - assert!( - !endpoint_api_key_has_forbidden_chars(good), - "should accept {good:?}" - ); - } - } - #[test] fn resolve_amd_smi_binary_prefers_home_rocm_venv_path() -> Result<()> { let temp_root = diff --git a/crates/rocm-core/src/service_identity.rs b/crates/rocm-core/src/service_identity.rs new file mode 100644 index 0000000000..cc39bb7fe3 --- /dev/null +++ b/crates/rocm-core/src/service_identity.rs @@ -0,0 +1,147 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! A managed service's identifier. +//! +//! [`ServiceId`], the validator every per-service id should pass before it +//! reaches a path builder, and [`generate_service_id`], which mints one for a +//! new launch. +//! +//! An id is a readable, timestamp-based name — never a secret. The bearer key +//! that guards a service's endpoint lives in [`crate::endpoint_key`] instead, +//! drawn from a CSPRNG and deliberately never derived from the id; the two +//! meet only at the filesystem layer, where the endpoint-key sidecar is named +//! after the service id. +//! +//! The slugging and clock helpers [`generate_service_id`] builds on, +//! [`crate::sanitize_component`] and [`crate::unix_time_millis`], stay at the +//! crate root: both have consumers outside this module. + +use anyhow::{Result, bail}; + +use crate::{sanitize_component, unix_time_millis}; + +/// A validated managed-service identifier that is safe to use as a single +/// filesystem path component. +/// +/// Every managed-service path (e.g. the endpoint-key sidecar) is built as +/// `services_dir().join(format!("{service_id}..."))`. A `ServiceId` can only be +/// constructed through [`ServiceId::new`], which rejects path separators, `..` +/// traversal, and control characters — so a value of this type can never make a +/// join escape its intended directory. Prefer threading a `ServiceId` (or +/// validating with it) over passing raw `&str` ids into path builders. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ServiceId(String); + +impl ServiceId { + /// Validate an untrusted string as a service id. + /// + /// Rejects empty/whitespace-only input, path separators (`/` and `\`), `..` + /// traversal sequences, and control characters. Ids produced by + /// [`generate_service_id`] are always accepted. + /// + /// # Errors + /// Returns an error describing the first rule the input violates. + pub fn new(value: &str) -> Result { + if value.trim().is_empty() { + bail!("service id must not be empty"); + } + if value.contains('/') || value.contains('\\') { + bail!("service id must not contain path separators"); + } + if value.contains("..") { + bail!("service id must not contain `..`"); + } + if value.chars().any(char::is_control) { + bail!("service id must not contain control characters"); + } + Ok(Self(value.to_owned())) + } + + #[must_use] + pub fn as_str(&self) -> &str { + &self.0 + } +} + +impl std::convert::TryFrom<&str> for ServiceId { + type Error = anyhow::Error; + fn try_from(value: &str) -> Result { + Self::new(value) + } +} + +impl std::fmt::Display for ServiceId { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.0) + } +} + +impl AsRef for ServiceId { + fn as_ref(&self) -> &str { + &self.0 + } +} + +/// Mint a new id for a managed-service launch, as `{engine}-{model-slug}-{millis}`. +/// +/// Always passes [`ServiceId::new`]: `sanitize_component` strips anything that +/// validation would reject, and the model slug is capped at 24 characters so a +/// long model reference cannot produce an unwieldy id. +/// +/// The trailing `unix_time_millis()` makes every call mint a distinct id, which +/// callers rely on to tell two launches of the same engine+model apart — never +/// match on `service_id` to detect a duplicate launch; key on `(engine, +/// canonical_model_id)` instead. +pub fn generate_service_id(engine: &str, model_ref: &str) -> String { + let model_slug = sanitize_component(model_ref) + .trim_matches('-') + .chars() + .take(24) + .collect::(); + format!( + "{}-{}-{}", + sanitize_component(engine), + model_slug, + unix_time_millis() + ) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn service_id_accepts_generated_and_plain_ids() { + // A freshly generated id must always validate. + let generated = generate_service_id("vllm", "Qwen/Qwen3.5"); + assert!(ServiceId::new(&generated).is_ok()); + // Plain alphanumeric-with-dashes ids validate and round-trip verbatim. + let id = ServiceId::new("svc-vllm-qwen-1730000000000").expect("valid id"); + assert_eq!(id.as_str(), "svc-vllm-qwen-1730000000000"); + assert_eq!(id.to_string(), "svc-vllm-qwen-1730000000000"); + } + + #[test] + fn service_id_rejects_traversal_and_separators() { + // Anything that could make `services_dir().join(id)` escape the directory + // (or otherwise not resolve to a single child component) is rejected. + for bad in [ + "", + " ", + "../../etc/passwd", + "..", + "a/b", + "a\\b", + "/abs", + "svc\r\ninject", + "svc\0nul", + ] { + assert!( + ServiceId::new(bad).is_err(), + "expected {bad:?} to be rejected" + ); + } + } +} diff --git a/docs/architecture.md b/docs/architecture.md index d2e1c90348..c39933d1f2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -76,9 +76,11 @@ Already-extracted subsystem modules, following the same full-domain-extraction p - [`automation.rs`](../crates/rocm-core/src/automation.rs) — (ROCMAI-151, Phase 7d) the built-in automation-watcher catalog, automation-daemon runtime state, and its on-disk event/proposal/audit records — see the module's own doc comment for what it owns. [`config.rs`](../crates/rocm-core/src/config.rs) and this module depend on each other — `config.rs` imports `BuiltinWatcherSpec` from here, and this module imports `WatcherMode` from `config.rs` — a back-edge the split introduces without eliminating; `WatcherMode` stays with the persisted config because it is part of `RocmCliConfig`'s own on-disk shape, not an automation-daemon concern. - [`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. - [`config.rs`](../crates/rocm-core/src/config.rs) — (ROCMAI-151, Phase 7d) the unified `RocmCliConfig` and its nested sections, including the persisted `WatcherMode` enum (the built-in watcher catalog itself lives in [`automation.rs`](../crates/rocm-core/src/automation.rs)) and the rocm-dash dashboard sub-config — see the module's own doc comment for what it owns. - [`crypto.rs`](../crates/rocm-core/src/crypto.rs) — (ROCMAI-152, Phase 7c) RSASSA-PKCS#1 v1.5/SHA-256 sign/verify, generic — not model-catalog-specific. - [`diagnose.rs`](../crates/rocm-core/src/diagnose.rs) +- [`endpoint_key.rs`](../crates/rocm-core/src/endpoint_key.rs) — (ROCMAI-662) the bearer key that guards a managed service's endpoint: the CSPRNG-drawn generator and its header-safety check. Split out of [`service_identity.rs`](../crates/rocm-core/src/service_identity.rs): an id and its endpoint key are made by unrelated mechanisms (readable/timestamp-based vs. CSPRNG) and meet only at the filesystem layer, where the key's sidecar is named after the id — not a reason to keep the two in one module. - [`examine.rs`](../crates/rocm-core/src/examine.rs) - [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) — (ROCMAI-85, Phase 7a of EAI-7768's sequencing) GPU/host hardware detection — see the module's own doc comment for what it owns. - [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) — (ROCMAI-85, Phase 7a) the TheRock managed-runtime-environment surface — see the module's own doc comment for what it owns. @@ -88,11 +90,22 @@ Already-extracted subsystem modules, following the same full-domain-extraction p - [`paths.rs`](../crates/rocm-core/src/paths.rs) — (ROCMAI-154, Phase 7b) `AppPaths` and its filesystem-location primitives. - [`process.rs`](../crates/rocm-core/src/process.rs) — (ROCMAI-154, Phase 7b) process-spawn/terminate primitives, including `FileLock`, plus `run_with_timeout`: it drains both pipes on their own threads from the moment the child starts, so output size cannot stall a command into its own timeout, and it bounds how much of a timed-out child's output the error quotes, because that text reaches persisted automation logs. It is not yet the *only* such helper — [`therock.rs`](../apps/rocm/src/therock.rs)'s `wait_with_output_bounded`, [`examine.rs`](../crates/rocm-core/src/examine.rs)'s `run_raw`, and [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs)'s `capture_optional_command_candidate_with_timeout` (plus its Windows-only `capture_diagnostic_command`) still join their reader threads with no time limit, so a grandchild holding the pipe can outlast their timeout; converging them onto `run_with_timeout` is follow-up work to ROCMAI-448 tracked in [#623](https://github.com/ROCm/rocm-cli/issues/623). - [`rocm_install.rs`](../crates/rocm-core/src/rocm_install.rs) — (ROCMAI-85, Phase 7a) unmanaged ("legacy") ROCm install discovery — see the module's own doc comment for what it owns. +- [`service_identity.rs`](../crates/rocm-core/src/service_identity.rs) — (ROCMAI-662) a managed service's identifier: the validated `ServiceId` and `generate_service_id`. The bearer key guarding a service's endpoint lives in [`endpoint_key.rs`](../crates/rocm-core/src/endpoint_key.rs) instead — see that entry for why. - [`service_record.rs`](../crates/rocm-core/src/service_record.rs) — (ROCMAI-151, Phase 7d) `ManagedServiceRecord`, the on-disk manifest for a managed inference service — see the module's own doc comment for what it owns. -Still in [`lib.rs`](../crates/rocm-core/src/lib.rs), none of it claimed by any phase-7 cluster (see ROCMAI-200 for each): amd-smi binary resolution (`resolve_amd_smi_binary*`), which consumes [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs)'s registry records but is a distinct, not-yet-scoped concern; the generic cross-cutting helpers `torch_alignment_disabled`/`require_nonempty`/`command_failure_detail`/`write_atomic` (the last shared by [`config.rs`](../crates/rocm-core/src/config.rs), [`automation.rs`](../crates/rocm-core/src/automation.rs), and [`service_record.rs`](../crates/rocm-core/src/service_record.rs) for their own atomic-replace writes); `VLLM_GPU_MEMORY_UTILIZATION_HINT`, embedded in the middle of the amd-smi resolution family despite being unrelated to it; the generated endpoint-API-key helpers (`generate_endpoint_api_key`/`endpoint_api_key_has_forbidden_chars`), unrelated to crypto or model-catalog despite sitting in the same stretch of the file pre-split; the `CodexBridgeSnapshot`/`CodexBridgeGpuSnapshot`/`CodexBridgeEngine` bridge DTOs, deliberately excluded from [`binary_paths.rs`](../crates/rocm-core/src/binary_paths.rs) by that phase's own scope but not claimed by anything else either; and `ServiceId`/`generate_service_id`/`sanitize_component`/`unix_time_millis`, not part of either [`service_record.rs`](../crates/rocm-core/src/service_record.rs) or [`binary_paths.rs`](../crates/rocm-core/src/binary_paths.rs) (`unix_time_millis` in particular is a crate-wide generic time helper used by several of this crate's own sibling modules, not service-record-specific). +What else stays in [`lib.rs`](../crates/rocm-core/src/lib.rs), beside module declarations and re-exports, was left unclaimed by every phase-7 cluster and is now decided (ROCMAI-662), so a later cleanup pass places it by domain rather than by where it happens to sit in the file: -[`lib.rs`](../crates/rocm-core/src/lib.rs) itself is **not yet fully modularized** — see EAI-7768, planned last in the modularization effort: highest fan-in (every app and engine crate depends on it), but lowest novelty since the existing sibling modules already prove the pattern works. +- **Permanent crate-root primitives.** Each is consumed from more than one module or crate, and none belongs to a domain an existing module owns; a dedicated module would add a path segment and nothing else. + - `unix_time_millis` — the crate-wide clock helper, used across this crate's own modules and throughout `rocm` and `rocmd`. + - `require_nonempty` — non-empty field validation, used by this crate's automation, binary-path and model-catalog modules and by both engine crates. + - `command_failure_detail` — picks the best detail string from a failed subprocess's output, used by [`process.rs`](../crates/rocm-core/src/process.rs) and the vLLM engine. + - `sanitize_component` — the lowercase-alphanumeric slugger shared by [`service_identity.rs`](../crates/rocm-core/src/service_identity.rs)'s `generate_service_id` and [`model_catalog.rs`](../crates/rocm-core/src/model_catalog.rs)'s artifact cache-marker names. It is not model-catalog-specific, so it does not move there. + - `TORCH_ALIGNMENT_DISABLED_ENV`/`torch_alignment_disabled` — the one read of the torch-alignment opt-out, shared by the CLI and the vLLM engine so the two cannot disagree. + - `VLLM_GPU_MEMORY_UTILIZATION_HINT` — a single wording contract between the CLI, the vLLM engine, and this crate's own `fix-16-vllm-oom` diagnosis; `rocm-core` is the only crate all of them can reach. +- **amd-smi binary resolution** (`resolve_amd_smi_binary*`) — belongs in its own `amd_smi.rs` module: locating the tool is a distinct concern that only reads [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs)'s registry records. The move is deferred to ROCMAI-723 and sequenced after the open [#447](https://github.com/ROCm/rocm-cli/pull/447), which adds amd-smi invocation code to the same stretch of `lib.rs`; moving the family first would make that PR relocate its additions mid-review. Until then `VLLM_GPU_MEMORY_UTILIZATION_HINT` stays physically inside that stretch; the extraction leaves it behind at the root. +- **`write_atomic`** — not permanent. It is the crate-private temp-then-rename writer [`config.rs`](../crates/rocm-core/src/config.rs), [`automation.rs`](../crates/rocm-core/src/automation.rs), and [`service_record.rs`](../crates/rocm-core/src/service_record.rs) use for their atomic replaces. The open [#610](https://github.com/ROCm/rocm-cli/pull/610) adds a shared, stronger atomic writer to this crate for `rocm` and `rocmd`, and the open [#541](https://github.com/ROCm/rocm-cli/pull/541) moves `RocmCliConfig::save` onto it. Once #610 lands, the automation and service-record callers follow and `write_atomic` is deleted (ROCMAI-724). That is a behavior change, not a pure move, so it is not done here. + +Once those two deferred moves land, [`lib.rs`](../crates/rocm-core/src/lib.rs) holds only module declarations, re-exports, and the crate-root primitives above — the end state of the modularization effort for this crate (EAI-7768, planned last: highest fan-in, since every app and engine crate depends on it, but lowest novelty, since the sibling modules already prove the pattern). ### `crates/rocm-dash-core`, `rocm-dash-collectors`, `rocm-dash-daemon`, `rocm-dash-tui` — dashboard/telemetry