Luigit
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();
    }
}