repositories / smith
smith
There are many coding harnesses - but this one is fast
owned by admin
smith-harness/src/catalog.rs
Raw//! 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<CatalogState> {
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<RefreshOutcome> {
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<String> {
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<CachedCatalog> {
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<Option<bool>> {
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<bool> {
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<PathBuf> {
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<String>) -> SmithError {
SmithError::Config {
field: "catalog.cache".to_string(),
message: message.into(),
}
}
fn transient(message: impl Into<String>) -> 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<HttpResponse> {
self.cancel.cancel();
CatalogResponse(self.source.clone()).execute(exchange, CancelHandle::new())
}
}
impl HttpExecutor for CatalogResponse {
fn execute(&self, exchange: HttpExchange, _cancel: CancelHandle) -> Result<HttpResponse> {
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();
}
}