blockworx/

collab.rs

//! [`LocalHost`]: a [`Host`] and the [`ClientSession`] that edits it, wired
//! together in this process. The editor's only link to an authority now
//! that the server and its wire are gone (`docs/single-author-playbook.md`,
//! D5 step one).

use blockworx_doc::{
    commit::Commit,
    document::FoldError,
    rev::Rev,
    session::{ClientSession, Host, Nonce, SessionError, UndoRefusal},
};

/// One step over the session's undo/redo journal. A fn pointer rather than
/// a flag: the two steps are the session's own methods, and naming them at
/// the call site keeps the link from re-deciding which is which.
type JournalStep = fn(&mut ClientSession, Nonce) -> Result<Nonce, UndoRefusal>;

/// Why a log would not seed a [`LocalHost`].
#[derive(Debug, thiserror::Error)]
pub enum SeedError {
    #[error("the seed log does not fold: {0}")]
    Refused(#[from] FoldError),
    #[error("the host's own welcome did not land: {0}")]
    Welcome(#[from] SessionError),
}

/// The authority, in this process: a [`Host`] and the [`ClientSession`]
/// that edits it, wired loopback. A submission's answer is delivered before
/// `submit` returns, so the queue is empty at every call boundary.
///
/// `Default` is the empty document, which is also what [`Self::new`]
/// reaches from an empty log (asserted, not assumed).
#[derive(Default)]
pub struct LocalHost {
    host: Host,
    session: ClientSession,
    /// Ordinary edits submitted since the editor last drained this. Not
    /// undo/redo submissions: those are steps the editor's own stack is
    /// already taking, and recording them would make a step of a step.
    submitted: Vec<Nonce>,
}

impl LocalHost {
    /// Fold `commits` into the host, then welcome the session from its log.
    ///
    /// # Errors
    /// A commit the fold refuses; or, unreachably, a welcome the session
    /// will not take.
    pub fn new(commits: Vec<Commit>) -> Result<Self, SeedError> {
        let mut host = Host::default();
        for commit in commits {
            host.ingest(&commit)?;
        }
        let session = ClientSession::welcome(host.commits_after(Rev::ZERO))?;
        Ok(Self {
            host,
            session,
            submitted: Vec::new(),
        })
    }

    /// Seal, predict, and answer.
    ///
    /// # Errors
    /// The fold's refusal, checked against the prediction — the host would
    /// refuse it too, so it is never sequenced.
    pub fn submit(&mut self, commit: Commit) -> Result<Nonce, FoldError> {
        let nonce = self.session.submit(commit)?;
        self.submitted.push(nonce);
        self.ship();
        Ok(nonce)
    }

    fn drain_submitted(&mut self) -> Vec<Nonce> {
        std::mem::take(&mut self.submitted)
    }

    /// # Errors
    /// The refusal, as [`ClientSession::undo`].
    fn journal(&mut self, edit: Nonce, step: JournalStep) -> Result<Nonce, UndoRefusal> {
        let nonce = step(&mut self.session, edit)?;
        self.ship();
        Ok(nonce)
    }

    /// Sequence whatever the session just queued and hand the answer back
    /// to it, all before the caller returns.
    fn ship(&mut self) {
        let Some((nonce, outbound)) = self
            .session
            .last_submission()
            .map(|(nonce, commit)| (nonce, commit.clone()))
        else {
            return;
        };
        let answered = match self.host.accept(outbound) {
            Ok(accepted) => {
                let rev = self.host.publish(accepted);
                self.session.committed(nonce, rev)
            }
            // Unreachable by construction: the session folds every
            // submission against its prediction first, and with the answer
            // delivered before `submit` returns, that prediction *is* the
            // host's document. Mirrored rather than asserted anyway — the
            // session already knows how to revert a rejection, and dying
            // over a broken invariant would cost the user the drawing.
            Err(refusal) => {
                tracing::error!("the in-process host refused a predicted commit: {refusal}");
                self.session.rejected(nonce)
            }
        };
        if let Err(refusal) = answered {
            tracing::error!("the local session and its own host disagree: {refusal}");
        }
    }

    pub fn session(&self) -> &ClientSession {
        &self.session
    }
}

/// The editor's link to the authority that sequences its commits. One
/// variant since the transport left: callers read
/// [`session`](Self::session) and never ask what is behind it.
///
/// Boxed because it carries a whole session, which every `App` would
/// otherwise hold inline.
pub enum Link {
    Local(Box<LocalHost>),
}

impl Link {
    pub fn local(host: LocalHost) -> Self {
        Link::Local(Box::new(host))
    }

    /// # Errors
    /// The fold's refusal, as [`LocalHost::submit`].
    pub fn submit(&mut self, commit: Commit) -> Result<Nonce, FoldError> {
        match self {
            Link::Local(local) => local.submit(commit),
        }
    }

    /// Undo the last edit: the session builds the inverse and this ships it
    /// as an ordinary commit, so the log cannot tell an undo from an edit.
    /// Availability is [`ClientSession::can_undo`].
    ///
    /// # Errors
    /// The inverse's refusal, as [`Self::submit`].
    pub fn undo(&mut self, edit: Nonce) -> Result<Nonce, UndoRefusal> {
        self.journal(edit, ClientSession::undo)
    }

    /// # Errors
    /// As [`Self::undo`].
    pub fn redo(&mut self, edit: Nonce) -> Result<Nonce, UndoRefusal> {
        self.journal(edit, ClientSession::redo)
    }

    fn journal(&mut self, edit: Nonce, step: JournalStep) -> Result<Nonce, UndoRefusal> {
        match self {
            Link::Local(local) => local.journal(edit, step),
        }
    }

    /// The ordinary edits submitted since the last drain — what the editor's
    /// undo stack owes a step each.
    pub fn drain_submitted(&mut self) -> Vec<Nonce> {
        match self {
            Link::Local(local) => local.drain_submitted(),
        }
    }

    pub fn session(&self) -> &ClientSession {
        match self {
            Link::Local(local) => local.session(),
        }
    }

    /// What the window title says about the link. The document is the
    /// session, so where the session's commits go is what the title is
    /// *for*.
    pub fn summary(&self) -> String {
        match self {
            // D5's marker, true as of the flag day: the in-process host
            // lives and dies with the process, and the container save path
            // that used to share this title is gone (F5/F6).
            Link::Local(_) => "nothing persisted".into(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use blockworx_doc::{
        block_model::{BlockInit, BlockUpdate, Icon, LabelInit},
        fixtures::{block_id, commit},
        geometry::{FracVal, GridPoint, GridRect, GridSize},
        opcode::{Crud, OpCodes},
        values::{LabelSide, Role},
    };

    fn rect(x: i32, y: i32) -> GridRect {
        GridRect {
            top_left: GridPoint { x, y },
            size: GridSize { w: 4, h: 4 },
        }
    }

    fn block_create(byte: u8) -> OpCodes {
        OpCodes::Block(
            block_id(byte),
            Crud::Create(BlockInit {
                parent: Scope::Root.wire_id(),
                rect: rect(0, 0),
                locked: false,
                role: Role::default(),
                title: LabelInit {
                    name: format!("b{byte}"),
                    side: LabelSide::default(),
                    offset: FracVal::default(),
                    hidden: false,
                },
                type_label: LabelInit {
                    name: String::new(),
                    side: LabelSide::default(),
                    offset: FracVal::default(),
                    hidden: false,
                },
                icon: Icon::default(),
            }),
        )
    }

    fn resize(byte: u8, to: GridRect) -> OpCodes {
        OpCodes::Block(block_id(byte), Crud::Update(BlockUpdate::Rect(to)))
    }

    /// Nothing in flight, and the session's confirmed document is the
    /// host's — the whole convergence claim, for a host of one.
    fn assert_converged(local: &LocalHost) {
        assert!(
            local.session.last_submission().is_none(),
            "the queue drains before submit returns",
        );
        assert_eq!(
            local.session.confirmed().content_hash(),
            local.host.state().content_hash(),
            "the session's confirmed document is the host's, byte for byte",
        );
        assert_eq!(
            local.session.optimistic().content_hash(),
            local.session.confirmed().content_hash(),
            "with nothing pending, the prediction is the confirmed document",
        );
        assert_eq!(local.session.rev(), local.host.rev());
    }

    #[test]
    fn an_empty_seed_is_the_default_host() {
        let seeded = LocalHost::new(Vec::new()).expect("an empty log seeds");
        let default = LocalHost::default();
        assert_eq!(
            seeded.session.confirmed().content_hash(),
            default.session.confirmed().content_hash(),
        );
        assert_eq!(seeded.session.rev(), Rev::ZERO);
        assert_converged(&seeded);
        assert_converged(&default);
    }

    #[test]
    fn a_seeded_log_welcomes_the_session_at_its_head() {
        let log = vec![
            commit("Added a block", vec![block_create(1)]),
            commit("Added another", vec![block_create(2)]),
        ];
        assert_eq!(log.len(), 2, "precondition: the seed log is not empty");

        let local = LocalHost::new(log).expect("the seed log folds");
        assert_eq!(
            local.session.rev().get(),
            2,
            "the welcome's head is the log's length",
        );
        assert_converged(&local);
        assert!(
            local.session.confirmed().block(&block_id(2)).is_some(),
            "the seeded blocks are in the session's document",
        );
    }

    /// A submission is accepted, sequenced, and acknowledged inside the
    /// call — and the next one stacks on top of it.
    #[test]
    fn a_submission_is_acked_before_it_returns() {
        let mut local =
            LocalHost::new(vec![commit("Added a block", vec![block_create(1)])]).expect("it folds");
        let seeded = local.session.rev();

        local
            .submit(commit("Moved it", vec![resize(1, rect(5, 5))]))
            .expect("the edit folds");
        assert_eq!(local.session.rev(), seeded.next(), "one commit, one rev");
        assert_converged(&local);
        assert_eq!(
            *local
                .session
                .confirmed()
                .block(&block_id(1))
                .expect("the block is confirmed")
                .as_ref()
                .rect
                .as_ref(),
            rect(5, 5),
        );

        local
            .submit(commit("Moved it again", vec![resize(1, rect(9, 9))]))
            .expect("the second edit folds on the first");
        assert_eq!(local.session.rev(), seeded.next().next());
        assert_converged(&local);
        assert_eq!(
            *local
                .session
                .confirmed()
                .block(&block_id(1))
                .expect("the block is confirmed")
                .as_ref()
                .rect
                .as_ref(),
            rect(9, 9),
        );
    }

    /// The prediction check is the client's, and it fires before anything
    /// reaches the host: a refused edit sequences nothing and journals
    /// nothing.
    #[test]
    fn an_edit_the_fold_refuses_never_reaches_the_host() {
        let mut local = LocalHost::default();
        let before = local.host.rev();

        assert!(
            local
                .submit(commit("Moved a stranger", vec![resize(9, rect(1, 1))]))
                .is_err(),
            "the target is not in the document",
        );
        assert_eq!(local.host.rev(), before, "a refusal mints no rev");
        assert_converged(&local);
    }

    /// The title says what the in-process host costs: the session is the
    /// document, and it goes with the process (D5, true as of the flag day).
    #[test]
    fn a_local_link_says_in_the_title_that_nothing_is_persisted() {
        let link = Link::local(LocalHost::default());
        assert_eq!(link.session().rev(), Rev::ZERO);
        assert_eq!(link.summary(), "nothing persisted");
    }

    /// The block the journal tests move, as the session confirmed it.
    fn block_rect(link: &Link) -> GridRect {
        *link
            .session()
            .confirmed()
            .block(&block_id(1))
            .expect("the block is confirmed")
            .as_ref()
            .rect
            .as_ref()
    }

    /// Undo and redo reach the document through the *link*, and travel as
    /// ordinary commits: each one takes a rev, so the authority sequenced
    /// it exactly as it sequences an edit.
    #[test]
    fn a_link_undoes_and_redoes_through_the_session_journal() {
        let mut link = Link::local(
            LocalHost::new(vec![commit("Added a block", vec![block_create(1)])]).expect("it folds"),
        );
        let (placed, moved) = (rect(0, 0), rect(5, 5));
        assert_eq!(block_rect(&link), placed, "precondition: the seeded rect");
        assert!(
            !link.session().can_undo(),
            "precondition: a welcome journals nothing",
        );

        link.submit(commit("Moved it", vec![resize(1, moved)]))
            .expect("the edit folds");
        assert_eq!(block_rect(&link), moved);
        assert_eq!(link.session().rev().get(), 2);
        assert!(link.session().can_undo());
        assert!(!link.session().can_redo());

        let edit = link.session().next_undo().expect("the edit is journalled");
        link.undo(edit).expect("the inverse folds");
        assert_eq!(block_rect(&link), placed, "undo put the block back");
        assert_eq!(link.session().rev().get(), 3, "the inverse took a rev");
        assert!(link.session().can_redo());
        assert!(!link.session().can_undo(), "the past is spent");

        let undone = link.session().next_redo().expect("the undo is journalled");
        link.redo(undone).expect("the edit re-applies");
        assert_eq!(block_rect(&link), moved, "redo moved it again");
        assert_eq!(link.session().rev().get(), 4);
        assert!(link.session().can_undo());
        assert!(!link.session().can_redo(), "the future is spent");
    }

    /// An empty stack has no edit to name, so the editor never asks — and if
    /// it did, the session says so rather than inventing a commit.
    #[test]
    fn an_empty_journal_has_no_step_to_name() {
        let mut link = Link::local(LocalHost::default());
        assert!(!link.session().can_undo() && !link.session().can_redo());
        assert_eq!(link.session().next_undo(), None);
        assert_eq!(link.session().next_redo(), None);

        // An edit from another session, so the nonce names nothing here.
        let mut elsewhere = Link::local(LocalHost::default());
        let foreign = elsewhere
            .submit(commit("Placed it", vec![block_create(1)]))
            .expect("the edit folds");
        assert!(link.undo(foreign).is_err(), "nothing stands ready");
        assert!(link.redo(foreign).is_err());
        assert_eq!(link.session().rev(), Rev::ZERO, "no commit was sequenced");
    }

    /// The editor's stack names the edit it made, so a submission's nonce has
    /// to reach it. Undo and redo submissions must not: they are steps the
    /// editor's stack is already taking, and a step of a step would leave the
    /// two disagreeing about how many edits stand ready.
    #[test]
    fn only_ordinary_edits_are_reported_to_the_editor() {
        let mut link = Link::local(LocalHost::default());
        let placed = link
            .submit(commit("Placed it", vec![block_create(1)]))
            .expect("the edit folds");
        assert_eq!(
            link.drain_submitted(),
            vec![placed],
            "the edit is reported once, by name",
        );
        assert!(
            link.drain_submitted().is_empty(),
            "and draining is what makes it a frame's worth",
        );

        link.undo(placed).expect("the inverse folds");
        assert!(
            link.drain_submitted().is_empty(),
            "the undo's own submission is not a new edit to remember",
        );
    }
}