second-brain-core 0.13.5

Core library for second-brain: SQLite storage with vector and lexical indexes, BGE embeddings, and hybrid retrieval
Documentation
use std::fs::OpenOptions;
use std::io::Write;
use std::os::unix::fs::OpenOptionsExt;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result};
use fs4::fs_std::FileExt;
use rand::TryRngCore;

const FILE_NAME: &str = "api.token";
const LOCK_NAME: &str = ".api.token.lock";

pub fn path(data_dir: &Path) -> PathBuf {
    data_dir.join(FILE_NAME)
}

pub fn ensure(data_dir: &Path) -> Result<String> {
    std::fs::create_dir_all(data_dir)
        .with_context(|| format!("creating {}", data_dir.display()))?;
    let lock_path = data_dir.join(LOCK_NAME);
    let lock = OpenOptions::new()
        .create(true)
        .truncate(false)
        .write(true)
        .mode(0o600)
        .open(&lock_path)
        .with_context(|| format!("opening {}", lock_path.display()))?;
    lock.lock_exclusive()
        .with_context(|| format!("locking {}", lock_path.display()))?;

    let target = path(data_dir);
    match std::fs::read_to_string(&target) {
        Ok(content) if !content.trim().is_empty() => return Ok(content.trim().to_string()),
        Ok(_) => {}
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
        Err(e) => return Err(e).with_context(|| format!("reading {}", target.display())),
    }

    let token = hex(&random_bytes::<32>()?);
    let tmp = data_dir.join(format!(".{FILE_NAME}.{}", hex(&random_bytes::<8>()?)));
    if let Err(e) = write_private(&tmp, &token) {
        if let Err(cleanup) = std::fs::remove_file(&tmp) {
            tracing::warn!("could not remove {}: {cleanup}", tmp.display());
        }
        return Err(e);
    }
    std::fs::rename(&tmp, &target).with_context(|| format!("creating {}", target.display()))?;
    Ok(token)
}

pub fn read(data_dir: &Path) -> Result<String> {
    let path = path(data_dir);
    let content = std::fs::read_to_string(&path).with_context(|| {
        format!(
            "cannot read the daemon API token at {}; the daemon creates it when it starts, \
             so start the daemon as this user or run as the user the daemon runs as",
            path.display()
        )
    })?;
    let token = content.trim();
    if token.is_empty() {
        anyhow::bail!(
            "the daemon API token at {} is empty; restart the daemon to regenerate it",
            path.display()
        );
    }
    Ok(token.to_string())
}

fn write_private(path: &Path, token: &str) -> Result<()> {
    let mut file = OpenOptions::new()
        .write(true)
        .create_new(true)
        .mode(0o600)
        .open(path)
        .with_context(|| format!("creating {}", path.display()))?;
    file.write_all(format!("{token}\n").as_bytes())?;
    file.sync_all()?;
    Ok(())
}

fn random_bytes<const N: usize>() -> Result<[u8; N]> {
    let mut bytes = [0u8; N];
    rand::rngs::OsRng
        .try_fill_bytes(&mut bytes)
        .map_err(|e| anyhow::anyhow!("reading OS randomness: {e}"))?;
    Ok(bytes)
}

fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|b| format!("{b:02x}")).collect()
}

#[cfg(test)]
mod tests {
    use std::os::unix::fs::PermissionsExt;

    use super::*;

    fn mode(p: &Path) -> u32 {
        std::fs::metadata(p).unwrap().permissions().mode() & 0o777
    }

    #[test]
    fn ensure_creates_a_private_64_hex_char_token() {
        let dir = tempfile::tempdir().unwrap();
        let token = ensure(dir.path()).unwrap();
        assert_eq!(token.len(), 64);
        assert!(token.bytes().all(|b| b.is_ascii_hexdigit()));
        assert_eq!(mode(&path(dir.path())), 0o600);
        assert_eq!(read(dir.path()).unwrap(), token);
    }

    #[test]
    fn ensure_creates_a_missing_data_dir() {
        let dir = tempfile::tempdir().unwrap();
        let nested = dir.path().join("a/b");
        let token = ensure(&nested).unwrap();
        assert_eq!(read(&nested).unwrap(), token);
    }

    #[test]
    fn ensure_keeps_an_existing_token() {
        let dir = tempfile::tempdir().unwrap();
        let first = ensure(dir.path()).unwrap();
        assert_eq!(ensure(dir.path()).unwrap(), first);
    }

    #[test]
    fn ensure_replaces_an_empty_token_file() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(path(dir.path()), "\n").unwrap();
        let token = ensure(dir.path()).unwrap();
        assert_eq!(token.len(), 64);
        assert_eq!(read(dir.path()).unwrap(), token);
        assert_eq!(mode(&path(dir.path())), 0o600);
    }

    #[test]
    fn tokens_differ_between_installs() {
        let a = tempfile::tempdir().unwrap();
        let b = tempfile::tempdir().unwrap();
        assert_ne!(ensure(a.path()).unwrap(), ensure(b.path()).unwrap());
    }

    #[test]
    fn racing_creators_all_get_the_same_complete_token() {
        let dir = tempfile::tempdir().unwrap();
        let tokens: Vec<String> = std::thread::scope(|s| {
            let handles: Vec<_> = (0..16)
                .map(|_| s.spawn(|| ensure(dir.path()).unwrap()))
                .collect();
            handles.into_iter().map(|h| h.join().unwrap()).collect()
        });
        assert!(tokens.iter().all(|t| t == &tokens[0]), "{tokens:?}");
        assert_eq!(read(dir.path()).unwrap(), tokens[0]);
        let mut leftovers: Vec<_> = std::fs::read_dir(dir.path())
            .unwrap()
            .map(|e| e.unwrap().file_name())
            .collect();
        leftovers.sort();
        assert_eq!(leftovers, [LOCK_NAME, FILE_NAME]);
    }

    #[test]
    fn racing_repairs_of_an_empty_token_agree() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(path(dir.path()), "").unwrap();
        let tokens: Vec<String> = std::thread::scope(|s| {
            let handles: Vec<_> = (0..16)
                .map(|_| s.spawn(|| ensure(dir.path()).unwrap()))
                .collect();
            handles.into_iter().map(|h| h.join().unwrap()).collect()
        });
        assert!(tokens.iter().all(|t| t == &tokens[0]), "{tokens:?}");
        assert_eq!(read(dir.path()).unwrap(), tokens[0]);
    }

    #[test]
    fn read_errors_name_the_path_when_missing() {
        let dir = tempfile::tempdir().unwrap();
        let err = format!("{:#}", read(dir.path()).unwrap_err());
        assert!(
            err.contains(&path(dir.path()).display().to_string()),
            "{err}"
        );
    }

    #[test]
    fn read_rejects_an_empty_token() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(path(dir.path()), "").unwrap();
        let err = format!("{:#}", read(dir.path()).unwrap_err());
        assert!(err.contains("api.token"), "{err}");
    }
}