//! Host-owned models.dev catalog refresh (`SMH-SPEC-SPEC0001`, Catalogs). use fs2::FileExt; use serde::{Deserialize, Serialize}; use smith::error::{ProviderFault, Result, SmithError}; use smith::http::{HttpBodyEnd, HttpBodyItem, HttpExchange, HttpExecutorRef, HttpMethod}; use smith::tool::CancelHandle; use smith_ai::models::{Catalog, MODELS_DEV_BYTES_MAX}; use smith_ai::refresh::{CatalogProvenance, CatalogSnapshot, CatalogState, RefreshOutcome}; use std::io::{Read, Write}; use std::path::{Path, PathBuf}; use std::sync::atomic::{AtomicU64, Ordering}; use std::time::SystemTime; /// Pinned upstream endpoint used only by explicit runtime refresh. pub const MODELS_DEV_URL: &str = "https://models.dev/api.json"; static CACHE_TEMPORARY_SEQUENCE: AtomicU64 = AtomicU64::new(0); /// Durable cache record. The revision is the generation that produced source. #[derive(Deserialize, Serialize)] struct CachedCatalog { revision: u64, source: String, } /// Load a valid persistent catalog cache, otherwise the bundled snapshot. /// /// # Errors /// /// Returns only bundled-catalog failures. An invalid cache falls back to the /// offline snapshot. pub fn startup_catalog(cache_path: &Path) -> Result { let Some(cached) = read_cache(cache_path) else { return CatalogState::with_builtin(); }; let Ok(catalog) = Catalog::from_models_dev_json(&cached.source) else { return CatalogState::with_builtin(); }; Ok(CatalogState::from_snapshot(CatalogSnapshot { catalog, generation: cached.revision, published_at: None, provenance: CatalogProvenance::Cache, })) } /// Fetch, atomically persist, then publish one catalog snapshot. /// /// Fetch failures and cancellation retain the previous snapshot. Cache I/O /// failures are explicit: no in-memory publication occurs before durability. /// /// # Errors /// /// Returns a configuration error when the validated snapshot cannot be made /// durable. pub fn refresh_models_dev( state: &mut CatalogState, cache_path: &Path, executor: &HttpExecutorRef, cancel: &CancelHandle, ) -> Result { let fetched = fetch_models_dev(executor, cancel).and_then(|source| { let catalog = Catalog::from_models_dev_json(&source)?; Ok((source, catalog)) }); let Ok((source, catalog)) = fetched else { return Ok(if cancel.is_cancelled() { RefreshOutcome::Cancelled } else { RefreshOutcome::KeptCache }); }; if cancel.is_cancelled() { return Ok(RefreshOutcome::Cancelled); } let generation = state.snapshot().generation; let Some(revision) = generation.checked_add(1) else { return Err(cache_error("catalog generation overflow")); }; let written = match write_cache(cache_path, &source, generation, revision, cancel) { Ok(Some(written)) => written, Ok(None) => return Ok(RefreshOutcome::Cancelled), Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => { return Ok(RefreshOutcome::KeptCache); } Err(error) => { return Err(cache_error(format!( "cannot persist {}: {error}", cache_path.display() ))); } }; if !written { return Ok(RefreshOutcome::StaleDiscarded); } *state = CatalogState::from_snapshot(CatalogSnapshot { catalog, generation: revision, published_at: Some(SystemTime::now()), provenance: CatalogProvenance::ModelsDev, }); Ok(RefreshOutcome::Published { generation: revision, }) } fn fetch_models_dev(executor: &HttpExecutorRef, cancel: &CancelHandle) -> Result { let response = executor.execute( HttpExchange { method: HttpMethod::Get, url: MODELS_DEV_URL.to_string(), headers: Vec::new(), body: Vec::new(), }, cancel.clone(), )?; if !(200..300).contains(&response.head.status) { return Err(transient(format!( "models.dev returned HTTP {}", response.head.status ))); } let mut bytes = Vec::new(); for item in response.body { match item { HttpBodyItem::Chunk(chunk) => { let Some(length) = bytes.len().checked_add(chunk.bytes.len()) else { return Err(transient("models.dev response size overflow")); }; if length > MODELS_DEV_BYTES_MAX { return Err(transient(format!( "models.dev response exceeds {MODELS_DEV_BYTES_MAX} bytes" ))); } bytes.extend_from_slice(&chunk.bytes); } HttpBodyItem::End(HttpBodyEnd::Complete) => { return String::from_utf8(bytes).map_err(|error| { transient(format!("models.dev response is not UTF-8: {error}")) }); } HttpBodyItem::End(HttpBodyEnd::Cancelled) => return Err(SmithError::Cancelled), HttpBodyItem::End(HttpBodyEnd::Truncated { limit }) => { return Err(transient(format!( "models.dev response exceeds {limit} bytes" ))); } HttpBodyItem::End(HttpBodyEnd::Failed { message }) => return Err(transient(message)), } } Err(transient( "models.dev response ended without a terminal outcome", )) } fn read_cache(cache_path: &Path) -> Option { let metadata = std::fs::metadata(cache_path).ok()?; if metadata.len() > MODELS_DEV_BYTES_MAX as u64 { return None; } let mut bytes = Vec::new(); let file = std::fs::File::open(cache_path).ok()?; #[expect( clippy::disallowed_methods, reason = "Take bounds the catalog cache read" )] file.take((MODELS_DEV_BYTES_MAX + 1) as u64) .read_to_end(&mut bytes) .ok()?; if bytes.len() > MODELS_DEV_BYTES_MAX { return None; } let cached: CachedCatalog = serde_json::from_slice(&bytes).ok()?; (cached.revision > 0 && cached.source.len() <= MODELS_DEV_BYTES_MAX).then_some(cached) } /// Write only when no newer durable revision exists. fn write_cache( cache_path: &Path, source: &str, expected_revision: u64, revision: u64, cancel: &CancelHandle, ) -> std::io::Result> { if cancel.is_cancelled() { return Ok(None); } let parent = cache_path.parent().ok_or_else(|| { std::io::Error::new( std::io::ErrorKind::InvalidInput, "catalog cache has no parent", ) })?; std::fs::create_dir_all(parent)?; let lock_path = cache_path.with_extension("lock"); let lock = std::fs::OpenOptions::new() .create(true) .truncate(false) .read(true) .write(true) .open(lock_path)?; lock.try_lock_exclusive()?; let result = if cancel.is_cancelled() { Ok(None) } else { write_cache_locked(cache_path, source, expected_revision, revision).map(Some) }; let _unlock_result = FileExt::unlock(&lock); result } fn write_cache_locked( cache_path: &Path, source: &str, expected_revision: u64, revision: u64, ) -> std::io::Result { if read_cache(cache_path).is_some_and(|cached| cached.revision > expected_revision) { return Ok(false); } let bytes = serde_json::to_vec(&CachedCatalog { revision, source: source.to_string(), }) .map_err(std::io::Error::other)?; let temporary = cache_temporary_path(cache_path)?; let mut file = std::fs::OpenOptions::new() .create_new(true) .write(true) .open(&temporary)?; file.write_all(&bytes)?; file.sync_all()?; drop(file); std::fs::rename(temporary, cache_path)?; Ok(true) } fn cache_temporary_path(cache_path: &Path) -> std::io::Result { let name = cache_path.file_name().ok_or_else(|| { std::io::Error::new( std::io::ErrorKind::InvalidInput, "catalog cache has no file name", ) })?; let sequence = CACHE_TEMPORARY_SEQUENCE.fetch_add(1, Ordering::Relaxed); Ok(cache_path.with_file_name(format!( ".{}.{}.{}.next", name.to_string_lossy(), std::process::id(), sequence ))) } fn cache_error(message: impl Into) -> SmithError { SmithError::Config { field: "catalog.cache".to_string(), message: message.into(), } } fn transient(message: impl Into) -> SmithError { SmithError::Provider { fault: ProviderFault::Transient { message: message.into(), }, } } #[cfg(test)] mod tests { use super::*; use smith::http::{HttpBodyItem, HttpChunk, HttpExecutor, HttpHead, HttpResponse}; use std::sync::Arc; struct CatalogResponse(String); struct CancellingCatalogResponse { source: String, cancel: CancelHandle, } impl HttpExecutor for CancellingCatalogResponse { fn execute(&self, exchange: HttpExchange, _cancel: CancelHandle) -> Result { self.cancel.cancel(); CatalogResponse(self.source.clone()).execute(exchange, CancelHandle::new()) } } impl HttpExecutor for CatalogResponse { fn execute(&self, exchange: HttpExchange, _cancel: CancelHandle) -> Result { assert_eq!(exchange.method, HttpMethod::Get); assert_eq!(exchange.url, MODELS_DEV_URL); let (sender, body) = std::sync::mpsc::channel(); sender .send(HttpBodyItem::Chunk(HttpChunk { bytes: self.0.as_bytes().to_vec(), })) .map_err(|error| transient(error.to_string()))?; sender .send(HttpBodyItem::End(HttpBodyEnd::Complete)) .map_err(|error| transient(error.to_string()))?; Ok(HttpResponse { head: HttpHead { status: 200 }, body, }) } } fn root(name: &str) -> PathBuf { std::env::temp_dir().join(format!("smith-catalog-{name}-{}", std::process::id())) } #[test] fn invalid_cache_and_invalid_refresh_retain_the_bundled_snapshot() { let root = root("invalid"); let cache = root.join("catalog.json"); std::fs::create_dir_all(&root).unwrap(); std::fs::write(&cache, "not json").unwrap(); let mut state = startup_catalog(&cache).unwrap(); assert_eq!(state.snapshot().generation, 0); assert_eq!(state.snapshot().provenance, CatalogProvenance::Bundled); let executor: HttpExecutorRef = Arc::new(CatalogResponse("not json".to_string())); assert_eq!( refresh_models_dev(&mut state, &cache, &executor, &CancelHandle::new()).unwrap(), RefreshOutcome::KeptCache ); assert_eq!(state.snapshot().generation, 0); std::fs::remove_dir_all(root).unwrap(); } #[test] fn refresh_persists_revision_before_publishing_cache_provenance() { let root = root("refresh"); let cache = root.join("catalog.json"); let source = r#"{"zai":{"models":{"glm":{"id":"glm","attachment":false,"reasoning":false,"tool_call":true,"structured_output":false,"limit":{"context":8,"output":4}}}}}"#.to_string(); let executor: HttpExecutorRef = Arc::new(CatalogResponse(source)); let mut state = CatalogState::with_builtin().unwrap(); assert_eq!( refresh_models_dev(&mut state, &cache, &executor, &CancelHandle::new()).unwrap(), RefreshOutcome::Published { generation: 1 } ); assert_eq!(state.snapshot().provenance, CatalogProvenance::ModelsDev); assert_eq!(state.snapshot().generation, 1); let reloaded = startup_catalog(&cache).unwrap(); assert_eq!(reloaded.snapshot().provenance, CatalogProvenance::Cache); assert_eq!(reloaded.snapshot().generation, 1); assert!( reloaded .snapshot() .catalog .model_for_provider(smith_ai::models::ProviderKind::Zai, "glm") .is_ok() ); std::fs::remove_dir_all(root).unwrap(); } #[test] fn refresh_keeps_cache_when_catalog_lock_is_held() { let root = root("locked"); let cache = root.join("catalog.json"); std::fs::create_dir_all(&root).unwrap(); let lock = std::fs::OpenOptions::new() .create(true) .truncate(false) .read(true) .write(true) .open(cache.with_extension("lock")) .unwrap(); lock.lock_exclusive().unwrap(); let source = r#"{"zai":{"models":{}}}"#.to_string(); let executor: HttpExecutorRef = Arc::new(CatalogResponse(source)); let mut state = CatalogState::with_builtin().unwrap(); assert_eq!( refresh_models_dev(&mut state, &cache, &executor, &CancelHandle::new()).unwrap(), RefreshOutcome::KeptCache ); assert_eq!(state.snapshot().generation, 0); assert!(!cache.exists()); FileExt::unlock(&lock).unwrap(); std::fs::remove_dir_all(root).unwrap(); } #[test] fn cancelled_refresh_does_not_publish_or_write_cache() { let root = root("cancelled"); let cache = root.join("catalog.json"); let cancel = CancelHandle::new(); let executor: HttpExecutorRef = Arc::new(CancellingCatalogResponse { source: r#"{"zai":{"models":{}}}"#.to_string(), cancel: cancel.clone(), }); let mut state = CatalogState::with_builtin().unwrap(); assert_eq!( refresh_models_dev(&mut state, &cache, &executor, &cancel).unwrap(), RefreshOutcome::Cancelled ); assert_eq!(state.snapshot().generation, 0); assert!(!cache.exists()); std::fs::remove_dir_all(root).unwrap_or(()); } #[test] fn stale_cache_writer_cannot_replace_newer_revision() { let root = root("stale"); let cache = root.join("catalog.json"); let cancel = CancelHandle::new(); assert_eq!( write_cache(&cache, "{\"zai\":{\"models\":{}}}", 0, 2, &cancel).unwrap(), Some(true) ); assert_eq!( write_cache(&cache, "{\"zai\":{\"models\":{}}}", 0, 1, &cancel).unwrap(), Some(false) ); assert_eq!(read_cache(&cache).unwrap().revision, 2); std::fs::remove_dir_all(root).unwrap(); } }