second-brain-sync 0.12.0

Bidirectional sync for second-brain: SSH transport, JSONL change log, conflict resolution
Documentation
use std::fs;
use std::io;
use std::path::Path;
use std::sync::{Mutex, PoisonError};

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

pub const PEERS_FILE: &str = "sync-peers";
pub const SUCCESS_FILE: &str = "sync-succeeded";

/// The lines of `sync-peers`, each read by [`Peer::parse`]; blank lines and
/// `#` comments are skipped. None when there is no such file.
pub fn configured_peers(data_dir: &Path) -> io::Result<Option<Vec<String>>> {
    let text = match fs::read_to_string(data_dir.join(PEERS_FILE)) {
        Ok(text) => text,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e),
    };
    Ok(Some(
        text.lines()
            .map(str::trim)
            .filter(|line| !line.is_empty() && !line.starts_with('#'))
            .map(str::to_string)
            .collect(),
    ))
}

/// A `sync-peers` line: the ssh destination, then optionally the path of `sb`
/// on that peer, for a peer whose non-interactive ssh PATH lacks it.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Peer {
    pub host: String,
    pub sb: String,
}

impl Peer {
    pub fn parse(line: &str) -> Self {
        let mut fields = line.split_whitespace();
        Self {
            host: fields.next().unwrap_or_default().to_string(),
            sb: fields.next().unwrap_or("sb").to_string(),
        }
    }
}

pub fn configured_peer(data_dir: &Path, host: &str) -> io::Result<Option<Peer>> {
    Ok(configured_peers(data_dir)?
        .unwrap_or_default()
        .iter()
        .map(|line| Peer::parse(line))
        .find(|peer| peer.host == host))
}

/// The staged file is named by pid, so threads of one process take turns.
static RECORDING: Mutex<()> = Mutex::new(());

/// Call only once a pull and a push have both finished; health counts it as
/// a sync that succeeded.
pub fn record_success(data_dir: &Path, at: DateTime<Utc>) -> Result<()> {
    let _turn = RECORDING.lock().unwrap_or_else(PoisonError::into_inner);
    fs::create_dir_all(data_dir).with_context(|| format!("creating {}", data_dir.display()))?;
    let path = data_dir.join(SUCCESS_FILE);
    let staged = data_dir.join(format!("{SUCCESS_FILE}.{}.tmp", std::process::id()));
    fs::write(&staged, format!("{}\n", at.to_rfc3339()))
        .with_context(|| format!("writing {}", staged.display()))?;
    fs::rename(&staged, &path).with_context(|| format!("replacing {}", path.display()))?;
    Ok(())
}

pub fn last_success(data_dir: &Path) -> Result<Option<DateTime<Utc>>> {
    let path = data_dir.join(SUCCESS_FILE);
    let text = match fs::read_to_string(&path) {
        Ok(text) => text,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e).with_context(|| format!("reading {}", path.display())),
    };
    let at = DateTime::parse_from_rfc3339(text.trim())
        .with_context(|| format!("{} does not hold an RFC 3339 time", path.display()))?;
    Ok(Some(at.with_timezone(&Utc)))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_missing_peers_file_is_told_apart_from_an_empty_one() {
        let dir = tempfile::tempdir().unwrap();
        assert_eq!(configured_peers(dir.path()).unwrap(), None);
        std::fs::write(dir.path().join(PEERS_FILE), "# none yet\n").unwrap();
        assert_eq!(configured_peers(dir.path()).unwrap(), Some(Vec::new()));
    }

    #[test]
    fn peers_skip_blank_lines_and_comments() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join(PEERS_FILE),
            "# laptop\nuser@laptop\n\n   \n  user@desktop.local  \n#user@old\n",
        )
        .unwrap();
        assert_eq!(
            configured_peers(dir.path()).unwrap(),
            Some(vec![
                "user@laptop".to_string(),
                "user@desktop.local".to_string()
            ])
        );
    }

    #[test]
    fn the_last_success_is_what_was_last_recorded() {
        let dir = tempfile::tempdir().unwrap();
        assert_eq!(last_success(dir.path()).unwrap(), None);
        let first = Utc::now() - chrono::Duration::hours(30);
        let second = Utc::now();
        record_success(dir.path(), first).unwrap();
        assert_eq!(last_success(dir.path()).unwrap(), Some(first));
        record_success(dir.path(), second).unwrap();
        assert_eq!(last_success(dir.path()).unwrap(), Some(second));
    }

    #[test]
    fn recording_creates_the_data_dir() {
        let dir = tempfile::tempdir().unwrap();
        let data_dir = dir.path().join("fresh");
        let at = Utc::now();
        record_success(&data_dir, at).unwrap();
        assert_eq!(last_success(&data_dir).unwrap(), Some(at));
    }

    #[test]
    fn a_peer_line_names_the_host_and_optionally_the_peers_sb() {
        assert_eq!(
            Peer::parse("user@laptop"),
            Peer {
                host: "user@laptop".to_string(),
                sb: "sb".to_string()
            }
        );
        assert_eq!(
            Peer::parse("user@pi.local   /home/user/.cargo/bin/sb"),
            Peer {
                host: "user@pi.local".to_string(),
                sb: "/home/user/.cargo/bin/sb".to_string()
            }
        );
    }

    #[test]
    fn a_configured_peer_is_found_by_its_host() {
        let dir = tempfile::tempdir().unwrap();
        assert_eq!(configured_peer(dir.path(), "user@pi").unwrap(), None);
        std::fs::write(
            dir.path().join(PEERS_FILE),
            "user@laptop\nuser@pi /opt/sb\n",
        )
        .unwrap();
        assert_eq!(
            configured_peer(dir.path(), "user@pi").unwrap(),
            Some(Peer::parse("user@pi /opt/sb"))
        );
        assert_eq!(configured_peer(dir.path(), "user@desk").unwrap(), None);
    }

    #[test]
    fn threads_recording_at_once_all_succeed() {
        let dir = tempfile::tempdir().unwrap();
        let handles: Vec<_> = (0..16)
            .map(|_| {
                let dir = dir.path().to_path_buf();
                std::thread::spawn(move || {
                    for _ in 0..50 {
                        record_success(&dir, Utc::now()).unwrap();
                    }
                })
            })
            .collect();
        for handle in handles {
            handle.join().unwrap();
        }
        assert!(last_success(dir.path()).unwrap().is_some());
    }

    #[test]
    fn an_unreadable_success_stamp_is_an_error() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join(SUCCESS_FILE), "yesterday\n").unwrap();
        assert!(last_success(dir.path()).is_err());
    }
}