second-brain-api 0.13.1

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
use std::io;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;

use anyhow::{Context, Result};
use chrono::{DateTime, Utc};

use crate::AppState;
use crate::health::{Health, MaintenanceState};
use crate::heap::heap_report;
use crate::value_metrics::{ResidentSize, StoreSize};

pub const INTERVAL: Duration = Duration::from_secs(5 * 60);

pub struct StorePaths {
    pub db: PathBuf,
    pub indexes: PathBuf,
    pub archive: PathBuf,
    pub raw_index: PathBuf,
}

pub struct FootprintCheck {
    pub paths: StorePaths,
    pub state: Arc<AppState>,
    pub health: Arc<Health>,
}

impl FootprintCheck {
    pub fn spawn(self) -> tokio::task::JoinHandle<()> {
        let check = Arc::new(self);
        tokio::spawn(async move {
            let mut interval = tokio::time::interval(INTERVAL);
            loop {
                interval.tick().await;
                let pass = check.clone();
                if let Err(e) = tokio::task::spawn_blocking(move || pass.run_once(Utc::now())).await
                {
                    tracing::error!("store and memory footprint check panicked: {e}");
                }
            }
        })
    }

    pub fn run_once(&self, now: DateTime<Utc>) {
        self.measure_store(now);
        let heap = heap_report(&self.state);
        let resident = (heap.stats.rss_anon_bytes > 0).then(|| ResidentSize {
            checked_at: Some(now),
            rss_anon_bytes: heap.stats.rss_anon_bytes,
            components: heap.components,
            raw_index_bytes: self.raw_index_bytes(),
            unattributed_bytes: heap.unattributed_bytes,
            limit_bytes: memory_limit(Path::new("/")),
        });
        self.health.resident_measured(resident, now);
    }
}

impl FootprintCheck {
    /// The compaction's index merge and VACUUM briefly double part of the
    /// store on disk, so a pass that overlaps either keeps the last reading.
    fn measure_store(&self, now: DateTime<Utc>) {
        if self.compacting() {
            return;
        }
        let store = match store_size(&self.paths, now) {
            Ok(size) => Some(size),
            Err(e) => {
                tracing::warn!("cannot measure the store on disk: {e:#}");
                None
            }
        };
        if !self.compacting() {
            self.health.store_measured(store, now);
        }
    }

    fn compacting(&self) -> bool {
        matches!(
            self.health.report().maintenance.state,
            MaintenanceState::MergingIndex | MaintenanceState::Vacuuming
        )
    }

    /// Kept apart from the heap components and their unattributed rest
    /// because it is an upper bound that counts mmapped, file-backed pages.
    fn raw_index_bytes(&self) -> u64 {
        let Some(raw) = &self.state.raw_index else {
            return 0;
        };
        match raw.read() {
            Ok(raw) => raw.resident_bytes(),
            Err(poisoned) => poisoned.into_inner().resident_bytes(),
        }
    }
}

pub fn store_size(paths: &StorePaths, now: DateTime<Utc>) -> Result<StoreSize> {
    let mut db_bytes = 0;
    let mut wal_bytes = 0;
    for suffix in ["", "-wal", "-shm"] {
        let mut file = paths.db.clone().into_os_string();
        file.push(suffix);
        let file = PathBuf::from(file);
        let bytes = tree_bytes(&file).with_context(|| format!("reading {}", file.display()))?;
        db_bytes += bytes;
        if !suffix.is_empty() {
            wal_bytes += bytes;
        }
    }
    let dir_bytes =
        |dir: &Path| tree_bytes(dir).with_context(|| format!("reading {}", dir.display()));
    let index_bytes = dir_bytes(&paths.indexes)?;
    let archive_bytes = dir_bytes(&paths.archive)?;
    let raw_index_bytes = dir_bytes(&paths.raw_index)?;
    let cold_bytes = dir_bytes(&second_brain_core::cold::dir_for_db(&paths.db))?;
    let db_dir = match paths.db.parent() {
        Some(dir) if !dir.as_os_str().is_empty() => dir,
        _ => Path::new("."),
    };
    Ok(StoreSize {
        checked_at: Some(now),
        db_bytes,
        wal_bytes,
        index_bytes,
        archive_bytes,
        raw_index_bytes,
        cold_bytes,
        total_bytes: db_bytes + index_bytes + archive_bytes + raw_index_bytes + cold_bytes,
        free_bytes: fs4::available_space(db_dir).ok(),
    })
}

/// Bytes of the regular files at or under `path`, without following
/// symlinks. A missing `path` is 0 and any other error reading `path` itself
/// fails. Entries below it that vanish or cannot be read count as 0, because
/// index merges and archive rotation delete files during the walk.
fn tree_bytes(path: &Path) -> io::Result<u64> {
    let meta = match std::fs::symlink_metadata(path) {
        Ok(meta) => meta,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(0),
        Err(e) => return Err(e),
    };
    if !meta.is_dir() {
        return Ok(if meta.is_file() { meta.len() } else { 0 });
    }
    let mut total = 0;
    let entries = match std::fs::read_dir(path) {
        Ok(entries) => entries,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(0),
        Err(e) => return Err(e),
    };
    let mut pending: Vec<PathBuf> = entries.flatten().map(|entry| entry.path()).collect();
    while let Some(path) = pending.pop() {
        let Ok(meta) = std::fs::symlink_metadata(&path) else {
            continue;
        };
        if meta.is_file() {
            total += meta.len();
        } else if meta.is_dir()
            && let Ok(entries) = std::fs::read_dir(&path)
        {
            pending.extend(entries.flatten().map(|entry| entry.path()));
        }
    }
    Ok(total)
}

/// The memory this process may use, read under the filesystem `root`: the
/// lowest cgroup v2 `memory.max` on the way from the process's cgroup up to
/// the hierarchy's root, capped by `MemTotal`, since a cgroup limit above
/// physical memory never binds.
pub fn memory_limit(root: &Path) -> Option<u64> {
    let physical = std::fs::read_to_string(root.join("proc/meminfo"))
        .ok()
        .and_then(|meminfo| mem_total(&meminfo));
    let cgroup = std::fs::read_to_string(root.join("proc/self/cgroup"))
        .ok()
        .and_then(|cgroup| cgroup_v2_path(&cgroup).map(str::to_string))
        .and_then(|path| cgroup_memory_max(&root.join("sys/fs/cgroup"), &path));
    match (cgroup, physical) {
        (Some(c), Some(p)) => Some(c.min(p)),
        (c, p) => c.or(p),
    }
}

fn cgroup_v2_path(cgroup: &str) -> Option<&str> {
    cgroup.lines().find_map(|line| line.strip_prefix("0::"))
}

fn cgroup_memory_max(hierarchy: &Path, path: &str) -> Option<u64> {
    let mut dir = hierarchy.to_path_buf();
    let mut dirs = vec![dir.clone()];
    for part in path.split('/').filter(|p| !p.is_empty()) {
        dir.push(part);
        dirs.push(dir.clone());
    }
    dirs.iter()
        .filter_map(|dir| std::fs::read_to_string(dir.join("memory.max")).ok())
        .filter_map(|max| memory_max(&max))
        .min()
}

fn memory_max(file: &str) -> Option<u64> {
    file.trim().parse().ok()
}

fn mem_total(meminfo: &str) -> Option<u64> {
    let line = meminfo.lines().find_map(|l| l.strip_prefix("MemTotal:"))?;
    let kb: u64 = line.trim().strip_suffix("kB")?.trim().parse().ok()?;
    kb.checked_mul(1024)
}