second-brain-api 0.13.2

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

use anyhow::Result;
use chrono::{DateTime, Utc};
use second_brain_core::sqlite_store::{FLOOR_TICK_MICROS, FloorPass, SqliteStore, Truncation};
use tokio::task::JoinHandle;
use tokio::time::MissedTickBehavior;

use crate::health::Health;
use crate::write_gate::WriteGate;

pub const TRUNCATION: Truncation = Truncation::On;

/// Ticks on an unconditional interval, not gated on
/// `config.maintenance.enabled`.
pub fn spawn(
    sqlite: Arc<SqliteStore>,
    gate: Arc<WriteGate>,
    health: Arc<Health>,
) -> JoinHandle<()> {
    tokio::spawn(async move {
        let mut interval =
            tokio::time::interval(Duration::from_micros(FLOOR_TICK_MICROS.unsigned_abs()));
        interval.set_missed_tick_behavior(MissedTickBehavior::Delay);
        loop {
            interval.tick().await;
            let (sqlite, gate, health) = (sqlite.clone(), gate.clone(), health.clone());
            let ticked = tokio::task::spawn_blocking(move || {
                let now = Utc::now();
                let pass = tick(&sqlite, &gate, now.timestamp_micros())?;
                report_floor(&sqlite, &health, now)?;
                Ok::<_, anyhow::Error>(pass)
            })
            .await;
            match ticked {
                Ok(Ok(Some(pass))) => tracing::info!(
                    floor = pass.floor,
                    dropped = pass.dropped,
                    log_floor = pass.log_floor,
                    "log floor pass finished"
                ),
                Ok(Ok(None)) => {}
                Ok(Err(e)) => tracing::warn!("log floor tick failed: {e:#}"),
                Err(e) => tracing::warn!("log floor tick panicked: {e}"),
            }
        }
    })
}

fn report_floor(sqlite: &SqliteStore, health: &Health, now: DateTime<Utc>) -> Result<()> {
    let floor = sqlite.floor_health(now.timestamp_micros())?;
    let failed = sqlite.failed_record_counts()?;
    health.floor_checked(floor, failed, now);
    Ok(())
}

/// Advances the store's uptime clock, then runs the pass when a day has
/// passed since the last one, unless store maintenance holds the gate.
pub fn tick(sqlite: &SqliteStore, gate: &WriteGate, now_micros: i64) -> Result<Option<FloorPass>> {
    sqlite.advance_floor_uptime(now_micros)?;
    if !sqlite.floor_pass_due(now_micros)? {
        return Ok(None);
    }
    let Some(_slot) = gate.try_enter() else {
        return Ok(None);
    };
    sqlite.run_floor_pass(TRUNCATION, now_micros).map(Some)
}

#[cfg(test)]
mod tests {
    use second_brain_core::schema::{Memory, MemoryType};
    use second_brain_core::sqlite_store::SqliteStore;
    use second_brain_core::store::{Store, StoreAdmin};

    use super::tick;
    use crate::write_gate::WriteGate;

    const NOW: i64 = 1_790_000_000_000_000;
    const DAY: i64 = 86_400_000_000;

    fn store_with_log() -> SqliteStore {
        let store =
            SqliteStore::in_memory("00000000-0000-4000-8000-000000000000".to_string()).unwrap();
        for _ in 0..3 {
            store
                .store_memory(&Memory::new(
                    "floor tick".to_string(),
                    MemoryType::Semantic,
                    "test".to_string(),
                    String::new(),
                ))
                .unwrap();
        }
        store
    }

    #[test]
    fn the_daily_pass_frees_log_rows_up_to_the_floor() {
        let store = store_with_log();
        let gate = WriteGate::default();
        let head = store.log_head().unwrap();
        let before = store.sync_log_since(0).unwrap().len();

        let pass = tick(&store, &gate, NOW)
            .unwrap()
            .expect("the first tick runs the pass");

        assert_eq!(pass.floor, head, "no neighbour: F is the head");
        assert_eq!(pass.dropped as usize, before);
        assert_eq!(pass.log_floor, head);
        assert_eq!(store.log_floor().unwrap(), head);
        assert!(store.sync_log_since(0).unwrap().is_empty());

        store
            .store_memory(&Memory::new(
                "after the pass".to_string(),
                MemoryType::Semantic,
                "test".to_string(),
                String::new(),
            ))
            .unwrap();
        assert!(!store.sync_log_since(head).unwrap().is_empty());
    }

    #[test]
    fn the_pass_runs_once_a_day() {
        let store = store_with_log();
        let gate = WriteGate::default();

        assert!(tick(&store, &gate, NOW).unwrap().is_some());
        assert!(tick(&store, &gate, NOW + DAY / 2).unwrap().is_none());
        assert!(tick(&store, &gate, NOW + DAY).unwrap().is_some());
    }

    #[test]
    fn store_maintenance_defers_the_pass_to_a_later_tick() {
        let store = store_with_log();
        let gate = WriteGate::default();
        let closed = gate.close();

        assert!(tick(&store, &gate, NOW).unwrap().is_none());
        drop(closed);
        assert!(tick(&store, &gate, NOW + 1).unwrap().is_some());
    }

    #[test]
    fn each_tick_reports_the_floor_to_health() {
        let store = store_with_log();
        let gate = WriteGate::default();
        let health = crate::health::Health::new(chrono::Utc::now(), None);
        assert!(health.report().sync.floor.is_none());

        let pass = tick(&store, &gate, NOW).unwrap().unwrap();
        super::report_floor(&store, &health, chrono::Utc::now()).unwrap();

        let floor = health.report().sync.floor.expect("the floor is reported");
        assert_eq!(floor.log_floor, pass.log_floor);
        assert_eq!(floor.floor, pass.floor);
    }
}