second-brain-api 0.13.5

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
use std::sync::Arc;

use axum::Json;
use axum::extract::State;
use axum::http::StatusCode;
use axum::response::IntoResponse;
use second_brain_core::store::StoreAdmin;
use serde::Serialize;

use super::internal_error;
use crate::AppState;

#[derive(Serialize)]
struct HealthResponse {
    /// "ok" whenever the daemon answers, for callers that only probe
    /// liveness; `state` carries the assessment.
    status: &'static str,
    version: &'static str,
    /// Sync resolves a peer through `sb whoami`, which reads this under a
    /// 5 s timeout, so `/health` must answer without touching the store.
    machine_id: String,
    /// Recalls still working, including ones whose caller gave up; a load
    /// test waits for 0 to pace its requests.
    recalls_in_flight: usize,
    /// Present only while ingest waits for a pairing bootstrap.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    bootstrap_pending: bool,
    #[serde(flatten)]
    report: crate::health::HealthReport,
}

pub(super) async fn health(State(state): State<Arc<AppState>>) -> impl IntoResponse {
    Json(HealthResponse {
        status: "ok",
        version: env!("CARGO_PKG_VERSION"),
        machine_id: state.machine.id.clone(),
        recalls_in_flight: super::recall::recalls_in_flight(),
        bootstrap_pending: state.bootstrap.is_pending(),
        report: state.health.report(),
    })
}

pub(super) async fn status(State(state): State<Arc<AppState>>) -> impl IntoResponse {
    let sqlite = state.sqlite.clone();
    let indexes = state.indexes.clone();
    let embedder_available = state.embedder.is_some();
    let heap_state = state.clone();
    let raw_index = state.raw_index.as_ref().and_then(|raw| {
        let raw = raw.try_read().ok()?;
        let mut body =
            serde_json::json!({"passages": raw.len(), "resident_bytes": raw.resident_bytes()});
        if let Some(coverage) = &state.raw_coverage {
            body["max_age_days"] = coverage.max_age_days().into();
            body["skipped_by_age"] = coverage.skipped_by_age().into();
        }
        Some(body)
    });
    let result = tokio::task::spawn_blocking(move || -> anyhow::Result<_> {
        let counts = sqlite.live_counts()?;
        let files = sqlite.ingested_file_count()?;
        let diag = sqlite.diagnostic()?;
        let consolidation = sqlite.consolidation_stats()?;
        let index = index_status(&sqlite, indexes.as_deref())?;
        let chunks = sqlite.chunk_progress()?;
        let heap = crate::heap::heap_report(&heap_state);
        let cold = match sqlite.cold_stats() {
            Ok(stats) => serde_json::to_value(stats)?,
            Err(e) => serde_json::json!({"error": format!("{e:#}")}),
        };
        Ok((
            counts,
            files,
            diag,
            consolidation,
            index,
            chunks,
            heap,
            cold,
        ))
    })
    .await;

    let (counts, ingested_file_count, diagnostic, consolidation, index, chunks, heap, cold) =
        match result {
            Ok(Ok(parts)) => parts,
            Ok(Err(e)) => return internal_error(e),
            Err(e) => return internal_error(e),
        };
    let near_duplicates = crate::near_duplicates::cached_count(&state.near_duplicates);
    let maintenance = match state.maintenance.read() {
        Ok(g) => g.clone(),
        Err(poisoned) => poisoned.into_inner().clone(),
    };

    Json(serde_json::json!({
        "memory_count": counts.live,
        "stored_total": counts.stored_total,
        "archived": counts.archived,
        "superseded": counts.superseded,
        "by_type": counts.by_type,
        "index": index,
        "raw_index": raw_index,
        "cold": cold,
        // memories_pending is as of the drain thread's last chunk backfill,
        // not a fresh count: counting means splitting every live row.
        "chunks": {
            "memories_chunked": chunks.0,
            "memories_pending": chunks.1,
        },
        "ingested_file_count": ingested_file_count,
        "version": env!("CARGO_PKG_VERSION"),
        "embedder_available": embedder_available,
        "diagnostic": diagnostic,
        "machine_id": state.machine.id,
        "heap": heap,
        "consolidation": consolidation,
        "near_duplicate_groups_pending": near_duplicates.as_ref().map(|c| c.groups),
        "near_duplicates_counted_at": near_duplicates.as_ref().map(|c| c.counted_at),
        "maintenance": maintenance,
        "identity": state.health.report().identity,
    }))
    .into_response()
}

/// Checked on every status call rather than read from the last repair,
/// so the verdict describes the index as it is now.
fn index_status(
    sqlite: &second_brain_core::sqlite_store::SqliteStore,
    indexes: Option<&std::sync::RwLock<second_brain_core::index::Indexes>>,
) -> anyhow::Result<serde_json::Value> {
    let Some(indexes) = indexes else {
        return Ok(serde_json::json!({"verdict": "unavailable"}));
    };
    let pending = sqlite.outbox_pending()?;
    let guard = match indexes.read() {
        Ok(g) => g,
        Err(poisoned) => poisoned.into_inner(),
    };
    let verdict = if pending > 0 {
        "draining"
    } else if guard.consistent_with(sqlite)? {
        "consistent"
    } else {
        "inconsistent"
    };
    Ok(serde_json::json!({
        "verdict": verdict,
        "outbox_pending": pending,
        "vectors": guard.vector_len(),
        "documents": guard.lexical_len(),
    }))
}

/// The full integrity report, measured now against the reader indexes.
pub(super) async fn health_report(State(state): State<Arc<AppState>>) -> impl IntoResponse {
    let sqlite = state.sqlite.clone();
    let indexes = state.indexes.clone();
    let result = tokio::task::spawn_blocking(move || match indexes {
        Some(idx) => {
            let guard = match idx.read() {
                Ok(g) => g,
                Err(poisoned) => poisoned.into_inner(),
            };
            sqlite.integrity_report(Some(&guard))
        }
        None => sqlite.integrity_report(None),
    })
    .await;
    match result {
        Ok(Ok(report)) => Json(report).into_response(),
        Ok(Err(e)) => internal_error(e),
        Err(e) => internal_error(e),
    }
}

pub(super) async fn list_projects(State(state): State<Arc<AppState>>) -> impl IntoResponse {
    let store = state.store.clone();
    let result = tokio::task::spawn_blocking(move || store.distinct_project_paths()).await;
    match result {
        Ok(Ok(projects)) => {
            let projects: Vec<serde_json::Value> = projects
                .into_iter()
                .map(|(path, count)| serde_json::json!({"project_path": path, "count": count}))
                .collect();
            Json(serde_json::json!({"projects": projects})).into_response()
        }
        Ok(Err(e)) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({"error": e.to_string()})),
        )
            .into_response(),
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(serde_json::json!({"error": e.to_string()})),
        )
            .into_response(),
    }
}