second-brain-api 0.9.0

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
//! The drain thread: applies the index outbox every few seconds and, when
//! the outbox is quiet and the interval has passed, repairs the store with
//! the writable indexes it owns. On-demand repairs arrive over a channel so
//! the same thread services them; two writers never exist.

use std::sync::mpsc::{Receiver, RecvTimeoutError, Sender};
use std::sync::{Arc, RwLock};
use std::time::{Duration, Instant};

use anyhow::Result;
use chrono::Utc;
use second_brain_core::config::MaintenanceConfig;
use second_brain_core::embedding::Embedder;
use second_brain_core::index::Indexes;
use second_brain_core::maintenance::{MaintenanceSummary, RepairStats};
use second_brain_core::sqlite_store::SqliteStore;

const DRAIN_INTERVAL: Duration = Duration::from_secs(5);

pub struct RepairRequest {
    pub dry_run: bool,
    pub reply: Sender<Result<MaintenanceSummary>>,
}

/// Runs a repair and re-measures the store afterwards, on whatever index
/// handle the caller owns (the writer on the drain thread, none when the
/// indexes never opened).
pub fn run_repair(
    store: &SqliteStore,
    mut indexes: Option<&mut Indexes>,
    embedder: Option<&Embedder>,
    dry_run: bool,
) -> Result<MaintenanceSummary> {
    let embed = embedder.map(|e| move |text: &str| e.embed(text));
    let embed_ref = embed
        .as_ref()
        .map(|f| f as &dyn Fn(&str) -> Result<Vec<f32>>);
    let stats = store.repair(indexes.as_deref_mut(), embed_ref, dry_run)?;
    let report_after = store.integrity_report(indexes.as_deref())?;
    Ok(MaintenanceSummary {
        ran_at: Utc::now(),
        stats,
        report_after,
    })
}

fn log_stats(source: &str, stats: &RepairStats) {
    if stats.is_clean() {
        tracing::info!("{source} store repair: nothing to do");
    } else {
        tracing::info!("{source} store repair: {}", summarize(stats));
    }
}

fn summarize(s: &RepairStats) -> String {
    let mut parts = Vec::new();
    let mut push = |name: &str, n: u64| {
        if n > 0 {
            parts.push(format!("{name}={n}"));
        }
    };
    push("duplicates_superseded", s.duplicates_superseded);
    push("markers_inherited", s.distillation_markers_inherited);
    push("orphaned_markers_dropped", s.orphaned_markers_dropped);
    push("raws_retired", s.raws_retired);
    push("relations_pruned", s.relations_pruned);
    push("vec_keys_deleted", s.vec_keys_deleted);
    push("sync_log_rows_deleted", s.sync_log_rows_deleted);
    push("stale_cursors_dropped", s.stale_cursors_dropped);
    push("embeddings_backfilled", s.embeddings_backfilled);
    push("embedding_failures", s.embedding_failures);
    if s.vec_keys_gc_skipped {
        parts.push("vec_keys_gc=skipped".to_string());
    }
    if s.index_rebuilt {
        parts.push("index=rebuilt".to_string());
    }
    if s.dry_run {
        parts.push("dry_run".to_string());
    }
    parts.join(" ")
}

pub struct DrainLoop {
    pub store: Arc<SqliteStore>,
    pub reader: Arc<RwLock<Indexes>>,
    pub writer: Indexes,
    pub embedder: Option<Arc<Embedder>>,
    pub summary: Arc<RwLock<Option<MaintenanceSummary>>>,
    pub config: MaintenanceConfig,
    pub requests: Receiver<RepairRequest>,
}

impl DrainLoop {
    pub fn spawn(self) {
        std::thread::Builder::new()
            .name("index-drain".to_string())
            .spawn(move || self.run())
            .expect("spawning the index drain thread");
    }

    fn run(mut self) {
        let mut last_repair: Option<Instant> = None;
        loop {
            match self.requests.recv_timeout(DRAIN_INTERVAL) {
                Ok(request) => {
                    let result = self.repair("requested", request.dry_run);
                    if result.is_ok() && !request.dry_run {
                        last_repair = Some(Instant::now());
                    }
                    // A caller that gave up waiting is not an error here.
                    let _ = request.reply.send(result);
                }
                Err(RecvTimeoutError::Timeout) | Err(RecvTimeoutError::Disconnected) => {
                    let applied = self.drain();
                    let due = last_repair.is_none_or(|t| {
                        t.elapsed() >= Duration::from_secs(self.config.interval_secs)
                    });
                    if applied == Some(0) && self.config.enabled && due {
                        if self.repair("scheduled", false).is_ok() {
                            last_repair = Some(Instant::now());
                        } else {
                            // Retry sooner than the full interval, but not
                            // every tick against a store that keeps failing.
                            last_repair = Some(
                                Instant::now()
                                    - Duration::from_secs(
                                        self.config.interval_secs.saturating_sub(600),
                                    ),
                            );
                        }
                    }
                }
            }
        }
    }

    /// Applies pending outbox rows; None when the drain itself failed.
    fn drain(&mut self) -> Option<usize> {
        match self.writer.drain(&self.store) {
            Ok(0) => Some(0),
            Ok(n) => {
                tracing::info!("index drain applied {n} outbox rows");
                self.reload_reader();
                Some(n)
            }
            Err(e) => {
                tracing::warn!("index drain failed: {e:#}");
                None
            }
        }
    }

    fn repair(&mut self, source: &str, dry_run: bool) -> Result<MaintenanceSummary> {
        let started = Instant::now();
        let result = run_repair(
            &self.store,
            Some(&mut self.writer),
            self.embedder.as_deref(),
            dry_run,
        );
        match &result {
            Ok(summary) => {
                log_stats(source, &summary.stats);
                tracing::info!(
                    "{source} store repair finished in {:.1}s; drift remaining: {:?}",
                    started.elapsed().as_secs_f64(),
                    summary.report_after.drift()
                );
                if !dry_run {
                    self.reload_reader();
                    let mut guard = match self.summary.write() {
                        Ok(g) => g,
                        Err(poisoned) => poisoned.into_inner(),
                    };
                    *guard = Some(summary.clone());
                }
            }
            Err(e) => tracing::warn!("{source} store repair failed: {e:#}"),
        }
        result
    }

    fn reload_reader(&self) {
        let mut guard = match self.reader.write() {
            Ok(g) => g,
            Err(poisoned) => poisoned.into_inner(),
        };
        if let Err(e) = guard.reload_view() {
            tracing::warn!("index reader reload failed: {e:#}");
        }
    }
}