blockworx/log/

command.rs

//! The command vocabulary: the only things that can change a document.
//!
//! Every variant reduces to an LWW register write, a create, or a tombstone —
//! the three primitives the convergence argument covers. A command type that
//! does not reduce to them breaks the merge, so this is the place that
//! constraint is enforced.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use crate::document::{
    BlockLabel, GridPos, GridRect, LinearDistance, Lock, PinSide, PinType, TagVisibility, Waypoint,
};
use crate::log::id::{AssetId, ElementId};

/// What kind of thing an element is. Fixed at creation and never written
/// again, so it is not a register.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Serialize, Deserialize)]
pub enum ElementKind {
    Block,
    Pin,
    Route,
    Text,
    Comment,
    Image,
    /// A block's foreground badge. Distinct from [`Image`](Self::Image), which
    /// is a free-floating background annotation, because the two differ in
    /// selectability and paint order rather than in content.
    Icon,
    RouteLabel,
}

/// A pin's location designator and whether it is drawn. One value because the
/// flag governs the text — hiding a tag is not the same as clearing it.
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
pub struct TagLabel {
    pub text: String,
    pub visibility: TagVisibility,
}

/// Where a pin sits on its owner's edge.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
pub struct PinPlacement {
    pub side: PinSide,
    pub offset: u32,
}

/// Declares the document's registers once, and derives from that single list:
///
/// - [`PropTag`] — which register, and the wire code identifying it;
/// - [`PropWrite`] — a register's *value*, which is what state stores;
/// - [`PropChange`] — a register's *transition*, which is what a command
///   records.
///
/// The point is that the three cannot disagree. A transition is one variant
/// carrying one type for both sides, so an edit whose old and new name
/// different registers is unrepresentable rather than rejected — there is no
/// tag to store beside the values and no constructor that has to check them.
/// Adding a register is one line here.
///
/// Codes are persisted. They may be deprecated but never renumbered or reused.
macro_rules! registers {
    ($( $(#[$doc:meta])* $name:ident($ty:ty) = $code:literal ),+ $(,)?) => {
        /// Which register a write targets.
        #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Serialize, Deserialize)]
        #[repr(u16)]
        pub enum PropTag {
            $( $(#[$doc])* $name = $code, )+
        }

        impl PropTag {
            pub const fn code(self) -> u16 {
                self as u16
            }

            pub const fn from_code(code: u16) -> Option<Self> {
                match code {
                    $( $code => Some(Self::$name), )+
                    _ => None,
                }
            }
        }

        /// One register's value.
        ///
        /// No variant wraps an `Option`: "this block has no accent" is a
        /// register holding nothing, not an `Accent(None)`. One state, one
        /// representation.
        #[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
        pub enum PropWrite {
            $( $(#[$doc])* $name($ty), )+
        }

        impl PropWrite {
            pub fn tag(&self) -> PropTag {
                match self {
                    $( Self::$name(_) => PropTag::$name, )+
                }
            }
        }

        /// What one register went from and to.
        ///
        /// `None` on a side means the register held nothing there — undo of a
        /// first-time write clears rather than writing an "empty" value, which
        /// is what makes it restore the document exactly.
        #[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
        pub enum PropChange {
            $( $(#[$doc])* $name { old: Option<$ty>, new: Option<$ty> }, )+
        }

        impl PropChange {
            pub fn tag(&self) -> PropTag {
                match self {
                    $( Self::$name { .. } => PropTag::$name, )+
                }
            }

            /// The value the author saw. Not needed to replay — it is here so a
            /// command is self-contained for undo, for describing an edit, and
            /// for noticing that someone else had already overwritten it.
            pub fn old(&self) -> Option<PropWrite> {
                match self {
                    $( Self::$name { old, .. } => old.clone().map(PropWrite::$name), )+
                }
            }

            /// The value to write.
            pub fn new_value(&self) -> Option<PropWrite> {
                match self {
                    $( Self::$name { new, .. } => new.clone().map(PropWrite::$name), )+
                }
            }

            /// Swapping the sides is the whole of undo for a property edit.
            pub fn inverted(&self) -> Self {
                match self {
                    $( Self::$name { old, new } => Self::$name {
                        old: new.clone(),
                        new: old.clone(),
                    }, )+
                }
            }
        }
    };
}

registers! {
    /// The containment edge. A move is one write to this register, which is
    /// why identity survives a move.
    Parent(ElementId) = 1,
    /// Block, comment, image and port geometry.
    Rect(GridRect) = 2,
    /// A text box's position. It has no size of its own — its extent is
    /// whatever the text needs, which makes the extent derived, not authored.
    Anchor(GridPos) = 3,
    Title(BlockLabel) = 4,
    TypeLabel(BlockLabel) = 5,
    /// A pin's or route's primary label.
    Name(String) = 6,
    /// A pin's secondary label, drawn under its name.
    TypeName(String) = 7,
    Tag(TagLabel) = 8,
    Placement(PinPlacement) = 9,
    PinKind(PinType) = 10,
    PortOrientation(PinSide) = 11,
    /// Route endpoints are two registers rather than one keyed by which end,
    /// so a change may repoint both ends without the second write landing on
    /// the first.
    RouteStart(ElementId) = 12,
    RouteFinish(ElementId) = 13,
    /// The whole polyline as one value: concurrent edits to a wire's shape
    /// resolve as a unit rather than merging element-wise.
    Waypoints(Vec<Waypoint>) = 14,
    /// A route label's position along its wire.
    Along(LinearDistance) = 15,
    /// A text box's content.
    Body(String) = 16,
    Accent(u8) = 17,
    Locked(Lock) = 18,
    /// Content-derived, so referencing it from a command is legal.
    Asset(AssetId) = 19,
    DocumentName(String) = 20,
}

impl PropWrite {
    /// The element this value points at, if it points at one. The repair pass
    /// sweeps these for references to elements that are gone.
    pub fn reference(&self) -> Option<ElementId> {
        match self {
            Self::Parent(id) | Self::RouteStart(id) | Self::RouteFinish(id) => Some(*id),
            _ => None,
        }
    }
}

/// An element's initial registers. A map rather than a list so one create
/// cannot carry two writes to the same register — they would share a
/// [`WriteOrder`](crate::log::id::WriteOrder) and be unordered.
#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
#[serde(into = "Vec<PropWrite>", try_from = "Vec<PropWrite>")]
pub struct PropSet(BTreeMap<PropTag, PropWrite>);

impl From<PropSet> for Vec<PropWrite> {
    fn from(set: PropSet) -> Self {
        set.0.into_values().collect()
    }
}

impl TryFrom<Vec<PropWrite>> for PropSet {
    type Error = &'static str;

    /// Refuses rather than repairs: collecting would silently drop a duplicate
    /// register, which is the same "one value, many encodings" hazard as
    /// unsorted parents.
    fn try_from(writes: Vec<PropWrite>) -> Result<Self, Self::Error> {
        let mut set = BTreeMap::new();
        for write in writes {
            if set.insert(write.tag(), write).is_some() {
                return Err("a create names one register twice");
            }
        }
        Ok(Self(set))
    }
}

impl PropSet {
    pub fn new() -> Self {
        Self::default()
    }

    /// Later writes to a register replace earlier ones.
    pub fn with(mut self, write: PropWrite) -> Self {
        self.insert(write);
        self
    }

    pub fn insert(&mut self, write: PropWrite) -> Option<PropWrite> {
        self.0.insert(write.tag(), write)
    }

    pub fn get(&self, tag: PropTag) -> Option<&PropWrite> {
        self.0.get(&tag)
    }

    pub fn len(&self) -> usize {
        self.0.len()
    }

    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Ordered by tag, so two replicas encode the same set to the same bytes.
    pub fn iter(&self) -> impl Iterator<Item = &PropWrite> {
        self.0.values()
    }
}

impl FromIterator<PropWrite> for PropSet {
    fn from_iter<I: IntoIterator<Item = PropWrite>>(iter: I) -> Self {
        Self(iter.into_iter().map(|w| (w.tag(), w)).collect())
    }
}

/// One primitive edit.
///
/// A high-level operation — align thirty blocks, duplicate a subtree — is
/// recorded as the primitives it produced, with identities already minted and
/// references already remapped. Replay must never re-run the logic that
/// decided them, or two replicas replaying the same log could decide
/// differently.
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
pub enum Command {
    Create {
        id: ElementId,
        kind: ElementKind,
        parent: ElementId,
        init: PropSet,
    },
    SetProp {
        id: ElementId,
        change: PropChange,
    },
    /// Tombstone. The element and its id persist so a restore can bring it
    /// back, and so a late edit naming it can be reported rather than dropped.
    Delete {
        id: ElementId,
    },
    Restore {
        id: ElementId,
    },
}

impl Command {
    pub fn target(&self) -> ElementId {
        match self {
            Self::Create { id, .. }
            | Self::SetProp { id, .. }
            | Self::Delete { id }
            | Self::Restore { id } => *id,
        }
    }

    /// The inverse edit. Every command inverts from its own fields alone,
    /// which is what lets undo be an append rather than a rewind.
    pub fn inverted(&self) -> Self {
        match self {
            Self::Delete { id } => Self::Restore { id: *id },
            Self::Create { id, .. } | Self::Restore { id } => Self::Delete { id: *id },
            Self::SetProp { id, change } => Self::SetProp {
                id: *id,
                change: change.inverted(),
            },
        }
    }
}

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

    /// The property the macro exists for. There is no way to write an edit
    /// whose two sides name different registers — `PropChange::Accent { old:
    /// Some(1), new: Some(PropWrite::Name(..)) }` does not typecheck — so
    /// nothing has to check for it, at construction or on decode.
    #[test]
    fn a_property_edit_names_one_register_by_construction() {
        let change = PropChange::Accent {
            old: Some(1),
            new: Some(3),
        };
        assert_eq!(change.tag(), PropTag::Accent);
        assert_eq!(change.old(), Some(PropWrite::Accent(1)));
        assert_eq!(change.new_value(), Some(PropWrite::Accent(3)));
    }

    #[test]
    fn inverting_a_prop_change_swaps_its_sides() {
        let change = PropChange::Accent {
            old: Some(1),
            new: Some(3),
        };
        let back = change.inverted();
        assert_eq!(back.old(), change.new_value());
        assert_eq!(back.new_value(), change.old());
        assert_eq!(back.inverted(), change);
    }

    /// Giving a register its first value inverts into taking it away again,
    /// not into writing an "empty" one. Both sides still name the register, so
    /// the fold knows which one to clear.
    #[test]
    fn setting_a_first_value_inverts_into_clearing_it() {
        let set = PropChange::Accent {
            old: None,
            new: Some(3),
        };
        let undo = set.inverted();

        assert_eq!(undo.new_value(), None);
        assert_eq!(undo.old(), Some(PropWrite::Accent(3)));
        assert_eq!(
            undo.tag(),
            PropTag::Accent,
            "a cleared register still names the register it clears"
        );
        assert_eq!(undo.inverted(), set);
    }

    #[test]
    fn a_prop_set_holds_one_write_per_register() {
        let set: PropSet = [
            PropWrite::Name("first".into()),
            PropWrite::Accent(1),
            PropWrite::Name("second".into()),
        ]
        .into_iter()
        .collect();

        assert_eq!(
            set.len(),
            2,
            "the duplicate register must not be kept twice"
        );
        assert_eq!(
            set.get(PropTag::Name),
            Some(&PropWrite::Name("second".into())),
            "the later write should win"
        );
    }

    /// The set is encoded in iteration order, so that order has to be a
    /// function of content alone.
    #[test]
    fn a_prop_set_iterates_in_tag_order_whatever_the_build_order() {
        let forwards: PropSet = [PropWrite::Parent(ElementId::DOCUMENT), PropWrite::Accent(1)]
            .into_iter()
            .collect();
        let backwards: PropSet = [PropWrite::Accent(1), PropWrite::Parent(ElementId::DOCUMENT)]
            .into_iter()
            .collect();

        let tags = |s: &PropSet| s.iter().map(PropWrite::tag).collect::<Vec<_>>();
        assert_eq!(tags(&forwards), tags(&backwards));
        assert_eq!(tags(&forwards), vec![PropTag::Parent, PropTag::Accent]);
    }

    /// Guards the deprecate-never-renumber rule. The macro generates the codes
    /// and `from_code` from one list, so they cannot disagree — what this
    /// checks is that nobody renumbered the list itself.
    #[test]
    fn every_tag_round_trips_through_its_code() {
        for code in 1..=20u16 {
            let tag = PropTag::from_code(code).expect("codes 1..=20 are all assigned");
            assert_eq!(tag.code(), code);
        }
        assert!(PropTag::from_code(0).is_none());
        assert!(PropTag::from_code(21).is_none());
    }

    #[test]
    fn creates_and_deletes_invert_into_each_other() {
        let id = ElementId::new();
        let create = Command::Create {
            id,
            kind: ElementKind::Block,
            parent: ElementId::DOCUMENT,
            init: PropSet::new(),
        };
        assert_eq!(create.inverted(), Command::Delete { id });
        assert_eq!(
            Command::Delete { id }.inverted(),
            Command::Restore { id },
            "undoing a delete restores rather than recreating, so identity survives"
        );
    }
}