second-brain-sync 0.13.1

Bidirectional sync for second-brain: SSH transport, JSONL change log, conflict resolution
Documentation
use std::io::ErrorKind;
use std::net::{SocketAddr, TcpListener, TcpStream};
use std::sync::{Arc, Mutex, MutexGuard};
use std::thread;
use std::time::{Duration, Instant};

use anyhow::{Context, Result};
use zeroize::Zeroizing;

use super::channel::{Accepted, Channel};
use super::code::HostSecrets;
use super::{
    Admission, HostReply, JoinRequest, JoinerAck, KeyHandover, KeyRequest, MAX_WRONG_TRIES,
};

const ACCEPT_POLL: Duration = Duration::from_millis(100);
/// How long a connection may take to prove the code; joins are served one
/// at a time, so this bounds how long one peer can hold the listener.
const PROVE_LIMIT: Duration = Duration::from_secs(20);
/// The joiner writes everything it was sent before it answers.
const ACK_WAIT: Duration = Duration::from_secs(120);

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HostOutcome {
    Waiting,
    Paired {
        machine_id: String,
        name: String,
    },
    /// `sb pair --restore-keys` handed its epochs to a restoring device.
    HandedOver {
        name: String,
    },
    /// The lifetime ran out.
    Expired,
    /// Closed on request, or because nothing asked for its status within
    /// the idle limit (its `sb pair` stopped).
    Closed,
}

pub struct HostStatus {
    pub outcome: HostOutcome,
    pub code: Zeroizing<String>,
    pub invite: Zeroizing<String>,
    /// Wrong codes taken since the code was last retired.
    pub wrong_tries: u32,
    /// How many times a code was retired after too many wrong tries.
    pub retired: u32,
    pub remaining: Duration,
    /// Why the last proven join did not complete.
    pub last_error: Option<String>,
}

struct State {
    secrets: Arc<HostSecrets>,
    wrong_tries: u32,
    retired: u32,
    outcome: HostOutcome,
    last_poll: Instant,
    last_error: Option<String>,
}

struct Shared {
    state: Mutex<State>,
    hosts: Vec<String>,
    port: u16,
    deadline: Instant,
    idle: Duration,
}

impl Shared {
    fn lock(&self) -> MutexGuard<'_, State> {
        self.state
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }
}

type Admit = dyn Fn(&JoinRequest) -> Result<Admission> + Send + Sync;
type HandOver = dyn Fn(&KeyRequest) -> Result<KeyHandover> + Send + Sync;

/// What a listener does for a device that proved the code.
enum Serve {
    Admit(Box<Admit>),
    HandOver(Box<HandOver>),
}

/// A pairing listener: it takes joins one at a time until one completes,
/// its lifetime runs out, or nobody polls its status for `idle`.
pub struct PairingHost {
    shared: Arc<Shared>,
    hands_over_keys: bool,
}

impl PairingHost {
    /// `hosts` are the addresses the invite names; `admit` signs and wraps
    /// for a device that proved the code.
    pub fn open(
        listener: TcpListener,
        hosts: Vec<String>,
        lifetime: Duration,
        idle: Duration,
        admit: Box<Admit>,
    ) -> Result<Self> {
        Self::serving(listener, hosts, lifetime, idle, Serve::Admit(admit))
    }

    /// A listener for `sb pair --restore-keys`: `hand_over` wraps this
    /// device's epochs for a device restoring a backup, which is admitted
    /// to no identity.
    pub fn open_key_handover(
        listener: TcpListener,
        hosts: Vec<String>,
        lifetime: Duration,
        idle: Duration,
        hand_over: Box<HandOver>,
    ) -> Result<Self> {
        Self::serving(listener, hosts, lifetime, idle, Serve::HandOver(hand_over))
    }

    fn serving(
        listener: TcpListener,
        hosts: Vec<String>,
        lifetime: Duration,
        idle: Duration,
        serve_as: Serve,
    ) -> Result<Self> {
        listener
            .set_nonblocking(true)
            .context("making the pairing listener non-blocking")?;
        let port = listener.local_addr()?.port();
        let now = Instant::now();
        let shared = Arc::new(Shared {
            state: Mutex::new(State {
                secrets: Arc::new(HostSecrets::generate()),
                wrong_tries: 0,
                retired: 0,
                outcome: HostOutcome::Waiting,
                last_poll: now,
                last_error: None,
            }),
            hosts,
            port,
            deadline: now + lifetime,
            idle,
        });
        let served = shared.clone();
        let hands_over_keys = matches!(serve_as, Serve::HandOver(_));
        thread::Builder::new()
            .name("pairing-listener".into())
            .spawn(move || serve(&listener, &served, &serve_as))
            .context("starting the pairing listener")?;
        Ok(Self {
            shared,
            hands_over_keys,
        })
    }

    /// Opened by `open_key_handover`, so it adds no device.
    pub fn hands_over_keys(&self) -> bool {
        self.hands_over_keys
    }

    pub fn port(&self) -> u16 {
        self.shared.port
    }

    pub fn hosts(&self) -> &[String] {
        &self.shared.hosts
    }

    /// Also counts as the poll that keeps the listener open.
    pub fn status(&self) -> HostStatus {
        let mut state = self.shared.lock();
        let now = Instant::now();
        state.last_poll = now;
        HostStatus {
            outcome: state.outcome.clone(),
            code: state.secrets.code(),
            invite: state.secrets.invite(&self.shared.hosts, self.shared.port),
            wrong_tries: state.wrong_tries,
            retired: state.retired,
            remaining: self.shared.deadline.saturating_duration_since(now),
            last_error: state.last_error.clone(),
        }
    }

    pub fn close(&self) {
        let mut state = self.shared.lock();
        if state.outcome == HostOutcome::Waiting {
            state.outcome = HostOutcome::Closed;
        }
    }

    pub fn is_open(&self) -> bool {
        self.shared.lock().outcome == HostOutcome::Waiting
    }
}

/// The listener thread stops within a poll interval, or once the join it
/// is serving ends.
impl Drop for PairingHost {
    fn drop(&mut self) {
        self.close();
    }
}

fn serve(listener: &TcpListener, shared: &Shared, admit: &Serve) {
    loop {
        {
            let mut state = shared.lock();
            if state.outcome != HostOutcome::Waiting {
                return;
            }
            let now = Instant::now();
            if now >= shared.deadline {
                state.outcome = HostOutcome::Expired;
                return;
            }
            if now.duration_since(state.last_poll) > shared.idle {
                state.outcome = HostOutcome::Closed;
                return;
            }
        }
        match listener.accept() {
            Ok((stream, peer)) => take(stream, peer, shared, admit),
            Err(e) if e.kind() == ErrorKind::WouldBlock => thread::sleep(ACCEPT_POLL),
            Err(e) => {
                tracing::warn!("the pairing listener failed to accept: {e}");
                thread::sleep(ACCEPT_POLL);
            }
        }
    }
}

fn take(stream: TcpStream, peer: SocketAddr, shared: &Shared, admit: &Serve) {
    if let Err(e) = stream.set_nonblocking(false) {
        tracing::warn!("pairing: dropping a connection from {peer}: {e}");
        return;
    }
    let secrets = shared.lock().secrets.clone();
    let (mut channel, first) = match Channel::accept(stream, &secrets, Instant::now() + PROVE_LIMIT)
    {
        Accepted::Opened { channel, first } => (channel, first),
        Accepted::WrongCode => {
            wrong_try(shared, &secrets, peer);
            return;
        }
        Accepted::Broken(e) => {
            tracing::info!("pairing: a connection from {peer} broke off: {e:#}");
            return;
        }
    };
    let still_open =
        || shared.lock().outcome == HostOutcome::Waiting && Instant::now() < shared.deadline;
    match finish(&mut channel, &first, admit, &still_open) {
        Ok(outcome) => {
            match &outcome {
                HostOutcome::HandedOver { name } => {
                    tracing::info!("pairing: handed this device's keys to {name} at {peer}");
                }
                HostOutcome::Paired { machine_id, name } => {
                    tracing::info!("pairing: added device {name} ({machine_id}) from {peer}");
                }
                _ => {}
            }
            let mut state = shared.lock();
            state.outcome = outcome;
            state.last_error = None;
        }
        Err(e) => {
            tracing::warn!("pairing: a join from {peer} did not complete: {e:#}");
            shared.lock().last_error = Some(format!("{e:#}"));
        }
    }
}

fn finish(
    channel: &mut Channel,
    first: &[u8],
    serve_as: &Serve,
    still_open: &dyn Fn() -> bool,
) -> Result<HostOutcome> {
    let (name, on_ack, reply) = match serve_as {
        Serve::Admit(admit) => {
            let request: JoinRequest = match serde_json::from_slice(first) {
                Ok(request) => request,
                Err(e) if serde_json::from_slice::<KeyRequest>(first).is_ok() => {
                    refuse(
                        channel,
                        "this device is pairing, not handing over keys; run `sb pair \
                         --restore-keys` on it to restore a backup",
                    )?;
                    return Err(e).context("refused a restore asking for keys");
                }
                Err(e) => return Err(e).context("decoding the joining device's request"),
            };
            refuse_if_closed(channel, &request.name, still_open)?;
            let admission = admit(&request).or_else(|e| refused(channel, &request.name, e))?;
            (
                request.name.clone(),
                HostOutcome::Paired {
                    machine_id: request.machine_id,
                    name: request.name,
                },
                HostReply::Admitted(Box::new(admission)),
            )
        }
        Serve::HandOver(hand_over) => {
            let request: KeyRequest = match serde_json::from_slice(first) {
                Ok(request) => request,
                Err(e) if serde_json::from_slice::<JoinRequest>(first).is_ok() => {
                    refuse(
                        channel,
                        "this device hands over keys to restore a backup and adds no device; \
                         run `sb pair` on it to pair",
                    )?;
                    return Err(e).context("refused a join while handing over keys");
                }
                Err(e) => return Err(e).context("decoding the restoring device's request"),
            };
            refuse_if_closed(channel, &request.name, still_open)?;
            let handover = hand_over(&request).or_else(|e| refused(channel, &request.name, e))?;
            (
                request.name.clone(),
                HostOutcome::HandedOver { name: request.name },
                HostReply::KeysHandedOver(Box::new(handover)),
            )
        }
    };
    channel.send_json(&reply)?;
    channel.set_read_timeout(ACK_WAIT)?;
    match channel.recv_json::<JoinerAck>()? {
        JoinerAck::Joined => Ok(on_ack),
        JoinerAck::Failed { reason } => {
            anyhow::bail!("{name} could not store what it was sent: {reason}")
        }
    }
}

fn refuse(channel: &mut Channel, reason: &str) -> Result<()> {
    channel.send_json(&HostReply::Refused {
        reason: reason.into(),
    })
}

fn refuse_if_closed(
    channel: &mut Channel,
    name: &str,
    still_open: &dyn Fn() -> bool,
) -> Result<()> {
    if still_open() {
        return Ok(());
    }
    refuse(
        channel,
        "pairing on that device was closed or ran out; run `sb pair` there again",
    )?;
    anyhow::bail!("refused {name}: pairing had closed")
}

fn refused<T>(channel: &mut Channel, name: &str, error: anyhow::Error) -> Result<T> {
    let reason = format!("{error:#}");
    refuse(channel, &reason)?;
    anyhow::bail!("refused {name}: {reason}")
}

fn wrong_try(shared: &Shared, tried: &Arc<HostSecrets>, peer: SocketAddr) {
    let mut state = shared.lock();
    if !Arc::ptr_eq(&state.secrets, tried) {
        return;
    }
    state.wrong_tries += 1;
    tracing::warn!(
        "pairing: a wrong code from {peer} ({} of {MAX_WRONG_TRIES})",
        state.wrong_tries
    );
    if state.wrong_tries >= MAX_WRONG_TRIES {
        state.secrets = Arc::new(HostSecrets::generate());
        state.wrong_tries = 0;
        state.retired += 1;
        tracing::warn!("pairing: the code was retired after {MAX_WRONG_TRIES} wrong tries");
    }
}