second-brain-api 0.13.3

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
use std::fmt;
use std::path::Path;

use anyhow::Result;
use chrono::Utc;
use second_brain_core::keys::Epoch;
use second_brain_core::sqlite_store::{ClockFloorRejected, ClockFloors, SqliteStore};
use second_brain_core::store::StoreAdmin;
use second_brain_sync::keyring::Keyring;
use second_brain_sync::protocol::Hello;

use crate::clock_gate::ClockGate;
use crate::device_access::DeviceAccess;
use crate::health::Health;
use crate::identity_report;

#[derive(Debug)]
pub struct HelloRejected(pub String);

impl fmt::Display for HelloRejected {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "sync hello rejected: {}", self.0)
    }
}

impl std::error::Error for HelloRejected {}

pub fn hello_for(
    sqlite: &SqliteStore,
    clock: &ClockGate,
    data_dir: &Path,
    peer_id: &str,
    declared: Option<&[Epoch]>,
) -> Result<Hello> {
    let cursor = sqlite.get_sync_state(peer_id)?.map(|state| state.last_seq);
    Ok(Hello {
        machine_id: sqlite.machine_id().to_string(),
        wall_micros: clock.wall_micros(),
        synced: clock.synced(),
        cursor,
        applied: cursor
            .map(|cursor| sqlite.applied_through(peer_id, cursor))
            .transpose()?,
        merging: crate::snapshot_merge::merging(data_dir)?,
        held_origin_seq: sqlite.highest_origin_seq(peer_id)?,
        keys: Some(Keyring::load(sqlite, data_dir)?.handshake_for(peer_id, declared)?),
        peer_in: sqlite.peer_in(peer_id)?,
        log_floor: sqlite.log_floor()?,
        head: sqlite.log_head()?,
    })
}

/// Refuses a peer of another identity before anything of its hello is
/// applied.
pub fn check_identity(sqlite: &SqliteStore, data_dir: &Path, hello: &Hello) -> Result<()> {
    Keyring::load(sqlite, data_dir)?.check_peer(hello.keys()?, &hello.machine_id)
}

/// The whole of a peer's hello: its identity, the device rows, revocations
/// and key epochs it carries, then its clock. Keys come before the clock so
/// a revoked peer's floors are never raised, yet the revocations it carries
/// are still taken, and ssh access follows the rows even when the peer
/// itself turns out to be revoked.
pub fn accept_handshake(
    sqlite: &SqliteStore,
    clock: &ClockGate,
    health: &Health,
    access: &DeviceAccess,
    data_dir: &Path,
    hello: &Hello,
) -> Result<()> {
    check_identity(sqlite, data_dir, hello)?;
    let keyring = Keyring::load(sqlite, data_dir)?;
    let accepted = keyring.accept(&hello.machine_id, hello.keys()?, clock.wall_micros());
    access.sweep(sqlite, data_dir);
    identity_report::report_keyring(&keyring, health);
    accepted?;
    accept_hello(sqlite, clock, health, hello)
}

/// Floors are raised before a synced peer opens the gate, so the first write
/// after opening already sits above everything the peer has seen. Only a
/// peer value past a bound or the ceiling rejects the hello; a store failure
/// is an ordinary error.
pub fn accept_hello(
    sqlite: &SqliteStore,
    clock: &ClockGate,
    health: &Health,
    hello: &Hello,
) -> Result<()> {
    let raised =
        peer_floors(sqlite, clock, hello).and_then(|floors| sqlite.raise_clock_floors(&floors));
    match raised {
        Err(e) if e.downcast_ref::<ClockFloorRejected>().is_some() => {
            let reason = format!("from {}: {e:#}", hello.machine_id);
            health.clock_handshake_rejected(&hello.machine_id, reason.clone(), Utc::now());
            Err(HelloRejected(reason).into())
        }
        Err(e) => Err(e),
        Ok(()) => {
            if hello.synced {
                clock.open_by_peer();
            }
            health.clock_handshake_accepted(&hello.machine_id, Utc::now());
            Ok(())
        }
    }
}

/// A cursor at or below this store's own `last` is a seq it minted itself:
/// it raises nothing, so it is never bounded.
fn peer_floors(sqlite: &SqliteStore, clock: &ClockGate, hello: &Hello) -> Result<ClockFloors> {
    let rejected = |what: &str, e: String| ClockFloorRejected(format!("{what}: {e}"));
    let basis_micros = if hello.synced {
        clock
            .check_peer_time(hello.wall_micros)
            .map_err(|e| rejected("wall clock", e))?;
        Some(hello.wall_micros)
    } else {
        None
    };
    let last_seq = match hello.applied_of_receiver() {
        Some(cursor) => {
            let cursor = i64::try_from(cursor)
                .map_err(|_| ClockFloorRejected(format!("cursor {cursor} overflows")))?;
            if cursor <= sqlite.clock_state()?.last {
                None
            } else {
                clock
                    .check_peer_time(cursor)
                    .map_err(|e| rejected("cursor", e))?;
                Some(cursor)
            }
        }
        None => None,
    };
    Ok(ClockFloors {
        basis_micros,
        last_seq,
        held_origin_seq: hello.held_origin_seq,
    })
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use second_brain_core::sqlite_store::{ClockFloors, SqliteStore};

    use super::{HelloRejected, accept_hello};
    use crate::clock_gate::{ClockGate, TimeSignals};
    use crate::health::Health;
    use second_brain_sync::protocol::Hello;

    const DAY: i64 = 86_400_000_000;

    struct Synced(i64);

    impl TimeSignals for Synced {
        fn now_micros(&self) -> i64 {
            self.0
        }

        fn ntp_synced(&self) -> bool {
            true
        }

        fn rtc_secs(&self) -> Option<i64> {
            None
        }
    }

    fn synced_gate(dir: &std::path::Path, now: i64) -> Arc<ClockGate> {
        let gate = ClockGate::new(dir, Arc::new(Synced(now)), 0);
        assert!(gate.is_open());
        gate
    }

    fn hello(cursor: Option<i64>, held_origin_seq: Option<i64>) -> Hello {
        Hello {
            machine_id: "peer".to_string(),
            wall_micros: 0,
            synced: false,
            cursor: cursor.map(|c| c as u64),
            held_origin_seq,
            keys: None,
            peer_in: None,
            log_floor: 0,
            head: 0,
            applied: None,
            merging: None,
        }
    }

    fn rejection_shown(health: &Health) -> bool {
        health
            .report()
            .reason
            .is_some_and(|r| r.contains("handshake was refused"))
    }

    #[test]
    fn a_store_failure_while_raising_floors_is_an_error_not_a_rejection() {
        let dir = tempfile::tempdir().unwrap();
        let now = 1_790_000_000 * 1_000_000;
        let gate = synced_gate(dir.path(), now);
        let db = dir.path().join("brain.db");
        let sqlite = SqliteStore::open(&db, "machine-a".to_string()).unwrap();
        rusqlite::Connection::open(&db)
            .unwrap()
            .execute_batch(
                "CREATE TRIGGER fail_meta BEFORE INSERT ON index_meta \
                 BEGIN SELECT RAISE(ABORT, 'disk I/O error'); END;",
            )
            .unwrap();
        let health = Health::new(chrono::Utc::now(), None);

        let err =
            accept_hello(&sqlite, &gate, &health, &hello(None, Some(5 << 32 | 1))).unwrap_err();

        assert!(err.downcast_ref::<HelloRejected>().is_none(), "{err:#}");
        assert!(!rejection_shown(&health), "{:?}", health.report().reason);
    }

    #[test]
    fn a_cursor_at_this_stores_own_last_passes_however_far_ahead_of_the_clock() {
        let dir = tempfile::tempdir().unwrap();
        let now = 1_790_000_000 * 1_000_000;
        let gate = synced_gate(dir.path(), now);
        let sqlite = SqliteStore::in_memory("machine-a".to_string()).unwrap();
        let last = now + 3 * DAY;
        sqlite
            .raise_clock_floors(&ClockFloors {
                last_seq: Some(last),
                ..Default::default()
            })
            .unwrap();
        let health = Health::new(chrono::Utc::now(), None);

        accept_hello(&sqlite, &gate, &health, &hello(Some(last), None)).unwrap();
        assert!(!rejection_shown(&health));

        let err = accept_hello(&sqlite, &gate, &health, &hello(Some(last + 1), None)).unwrap_err();
        assert!(err.downcast_ref::<HelloRejected>().is_some(), "{err:#}");
        assert_eq!(sqlite.clock_state().unwrap().last, last);
    }

    #[test]
    fn a_receivers_peer_in_raises_last_like_a_cursor() {
        let dir = tempfile::tempdir().unwrap();
        let now = 1_790_000_000 * 1_000_000;
        let gate = synced_gate(dir.path(), now);
        let sqlite = SqliteStore::in_memory("machine-a".to_string()).unwrap();
        let health = Health::new(chrono::Utc::now(), None);
        let held = (now - 1_000) as u64;
        let pushed_into = Hello {
            peer_in: Some(held),
            ..hello(None, None)
        };

        accept_hello(&sqlite, &gate, &health, &pushed_into).unwrap();

        assert_eq!(sqlite.clock_state().unwrap().last, held as i64);
    }

    #[test]
    fn an_accepted_hello_clears_only_a_refusal_of_the_same_peer() {
        let dir = tempfile::tempdir().unwrap();
        let now = 1_790_000_000 * 1_000_000;
        let gate = synced_gate(dir.path(), now);
        let sqlite = SqliteStore::in_memory("machine-a".to_string()).unwrap();
        let health = Health::new(chrono::Utc::now(), None);
        let from = |machine: &str, cursor: i64| Hello {
            machine_id: machine.to_string(),
            ..hello(Some(cursor), None)
        };

        accept_hello(&sqlite, &gate, &health, &from("peer-p", now + 3 * DAY)).unwrap_err();
        assert!(rejection_shown(&health));
        accept_hello(&sqlite, &gate, &health, &from("peer-q", now)).unwrap();
        assert!(
            rejection_shown(&health),
            "another peer's handshake says nothing about peer-p"
        );
        accept_hello(&sqlite, &gate, &health, &from("peer-p", now)).unwrap();
        assert!(!rejection_shown(&health), "{:?}", health.report().reason);
        assert_eq!(health.report().state, crate::health::State::Ok);
    }
}