second-brain-core 0.12.0

Core library for second-brain: SQLite storage with vector and lexical indexes, BGE embeddings, and hybrid retrieval
Documentation
use std::cell::Cell;
use std::marker::PhantomData;
use std::path::{Path, PathBuf};
use std::sync::{Condvar, Mutex, MutexGuard};
use std::thread;
use std::time::{Duration, Instant};

use anyhow::{Context, Result};
use rusqlite::{Connection, ErrorCode};

pub(super) const BUSY_TIMEOUT: Duration = Duration::from_secs(5);

/// Opens one connection with the pragmas every connection in the store needs.
/// `busy_timeout` is armed before any pragma: switching journal_mode takes a
/// brief exclusive lock, so two processes opening the same fresh database
/// concurrently can otherwise hit a hard SQLITE_BUSY with no busy handler
/// installed yet to retry it.
pub(super) fn open_connection(path: &Path) -> Result<Connection> {
    let conn = Connection::open(path)
        .with_context(|| format!("opening sqlite db at {}", path.display()))?;
    conn.busy_timeout(BUSY_TIMEOUT)
        .context("arming busy_timeout")?;
    set_wal_mode(&conn)?;
    conn.pragma_update(None, "synchronous", "NORMAL")
        .context("setting synchronous=NORMAL")?;
    Ok(conn)
}

/// `busy_timeout`'s built-in retry loop does not cover the exclusive lock
/// SQLite takes while switching journal_mode to WAL: two connections racing
/// to make that switch on the same fresh database can still see a bare
/// SQLITE_BUSY from the pragma itself, confirmed against this rusqlite
/// version by a concurrent-open regression test. Retry it by hand, bounded
/// by the same window `busy_timeout` uses, instead of trusting the driver to
/// cover a case it does not.
fn set_wal_mode(conn: &Connection) -> Result<()> {
    let deadline = Instant::now() + BUSY_TIMEOUT;
    loop {
        match conn.pragma_update(None, "journal_mode", "WAL") {
            Ok(()) => return Ok(()),
            Err(err) if is_database_busy(&err) && Instant::now() < deadline => {
                thread::sleep(Duration::from_millis(20));
            }
            Err(err) => return Err(err).context("setting journal_mode=WAL"),
        }
    }
}

fn is_database_busy(err: &rusqlite::Error) -> bool {
    err.sqlite_error_code() == Some(ErrorCode::DatabaseBusy)
}

/// A sane default reader pool size: enough connections that concurrent
/// readers stop queueing behind each other, bounded so a store never opens
/// more file descriptors than the machine has cores to use them with.
pub(super) fn default_pool_size() -> usize {
    std::thread::available_parallelism()
        .map(|n| n.get())
        .unwrap_or(4)
        .clamp(2, 16)
}

thread_local! {
    static READ_DEADLINE: Cell<Option<Instant>> = const { Cell::new(None) };
}

/// Bounds the wait for a pooled read connection on this thread until the
/// guard drops: a read that finds the pool empty waits at most until
/// `deadline`, then opens a connection of its own, which closes on drop.
/// That open is bounded by `BUSY_TIMEOUT`, not by the deadline, and if it
/// fails the read waits for the pool as an unbounded read would.
/// Thread-local because every store read takes a connection through
/// `reader()` and a recall's reads all run on the one thread that holds the
/// guard; the guard is not `Send`, so it cannot be dropped on another.
pub struct ReadDeadline {
    previous: Option<Instant>,
    not_send: PhantomData<*const ()>,
}

impl ReadDeadline {
    pub fn set(deadline: Instant) -> Self {
        ReadDeadline {
            previous: READ_DEADLINE.replace(Some(deadline)),
            not_send: PhantomData,
        }
    }
}

impl Drop for ReadDeadline {
    fn drop(&mut self) {
        READ_DEADLINE.set(self.previous);
    }
}

/// Fixed-size pool of read connections to the same file: `checkout` waits
/// for a connection to come back rather than ever pooling one past `size`.
/// WAL gives one writer and many concurrent readers across separate
/// connections, so each pooled connection is a full physical connection,
/// not a wrapper over the writer's.
pub(super) struct ReaderPool {
    path: PathBuf,
    free: Mutex<Vec<Connection>>,
    returned: Condvar,
}

impl ReaderPool {
    pub(super) fn open(path: &Path, size: usize) -> Result<Self> {
        let free = (0..size)
            .map(|_| open_connection(path))
            .collect::<Result<Vec<_>>>()?;
        Ok(Self {
            path: path.to_path_buf(),
            free: Mutex::new(free),
            returned: Condvar::new(),
        })
    }

    pub(super) fn checkout(&self) -> PooledConn<'_> {
        let mut free = self.lock();
        if let Some(deadline) = READ_DEADLINE.get() {
            let wait = deadline.saturating_duration_since(Instant::now());
            free = self
                .returned
                .wait_timeout_while(free, wait, |f| f.is_empty())
                .unwrap_or_else(|e| e.into_inner())
                .0;
            if free.is_empty() {
                drop(free);
                match open_connection(&self.path) {
                    Ok(conn) => {
                        return PooledConn {
                            conn: Some(conn),
                            pool: None,
                        };
                    }
                    Err(e) => {
                        tracing::warn!("no read connection to spare past a deadline: {e:#}");
                        free = self.lock();
                    }
                }
            }
        }
        let mut free = self
            .returned
            .wait_while(free, |f| f.is_empty())
            .unwrap_or_else(|e| e.into_inner());
        PooledConn {
            conn: free.pop(),
            pool: Some(self),
        }
    }

    fn lock(&self) -> MutexGuard<'_, Vec<Connection>> {
        self.free.lock().unwrap_or_else(|e| e.into_inner())
    }
}

/// A connection from the pool, or one opened past a read deadline, which
/// closes on drop instead of joining the pool.
pub(crate) struct PooledConn<'a> {
    conn: Option<Connection>,
    pool: Option<&'a ReaderPool>,
}

impl std::ops::Deref for PooledConn<'_> {
    type Target = Connection;

    fn deref(&self) -> &Connection {
        self.conn.as_ref().expect("taken only in Drop")
    }
}

impl Drop for PooledConn<'_> {
    fn drop(&mut self) {
        if let (Some(conn), Some(pool)) = (self.conn.take(), self.pool) {
            pool.lock().push(conn);
            pool.returned.notify_one();
        }
    }
}

#[cfg(test)]
mod tests {
    use std::sync::mpsc;
    use std::time::Duration;

    use super::*;

    fn pool(size: usize) -> (tempfile::TempDir, ReaderPool) {
        let dir = tempfile::tempdir().unwrap();
        let pool = ReaderPool::open(&dir.path().join("brain.db"), size).unwrap();
        (dir, pool)
    }

    #[test]
    fn a_read_past_its_deadline_opens_a_spare_connection_instead_of_waiting() {
        let (_dir, pool) = pool(1);
        let held = pool.checkout();
        let (done, answered) = mpsc::channel();
        thread::scope(|scope| {
            scope.spawn(|| {
                let _bound = ReadDeadline::set(Instant::now() + Duration::from_millis(50));
                let spare = pool.checkout();
                let one: i64 = spare.query_row("SELECT 1", [], |r| r.get(0)).unwrap();
                done.send(one).unwrap();
            });
            let answer = answered.recv_timeout(Duration::from_secs(10));
            drop(held);
            assert_eq!(
                answer,
                Ok(1),
                "the bounded read waited for the held connection"
            );
        });
        assert_eq!(pool.lock().len(), 1, "only the pooled connection came back");
    }

    #[test]
    fn a_read_without_a_deadline_waits_for_a_pooled_connection() {
        let (_dir, pool) = pool(1);
        let held = pool.checkout();
        let (done, answered) = mpsc::channel();
        thread::scope(|scope| {
            scope.spawn(|| {
                let conn = pool.checkout();
                done.send(conn.is_autocommit()).unwrap();
            });
            assert!(answered.recv_timeout(Duration::from_millis(100)).is_err());
            drop(held);
            assert!(answered.recv_timeout(Duration::from_secs(10)).is_ok());
        });
    }

    #[test]
    fn a_deadline_guard_restores_the_one_before_it() {
        let outer = Instant::now() + Duration::from_secs(60);
        let _outer = ReadDeadline::set(outer);
        {
            let _inner = ReadDeadline::set(Instant::now());
        }
        assert_eq!(READ_DEADLINE.get(), Some(outer));
    }
}