merge_machines 0.2.0

data/ext/merge_machines_native/core/src/lib.rs

@@ -0,0 +1,221 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+
+//! Conflict-free replicated data types and the clocks they need.
+//!
+//! Every type here has a [`Merge::merge`] that is commutative, associative and
+//! idempotent, so replicas that have seen the same updates hold the same state
+//! no matter what order the updates arrived in, or how many times.
+//!
+//! Nothing here talks to a network and nothing here reads a clock. The caller
+//! owns the transport, the replica ids, the tags, and every clock reading.
+//!
+//! # Which clock
+//!
+//! [`LogicalClock`] counts events. [`HybridClock`] pairs a wall-clock reading
+//! with a counter, where a wall-clock reading means physical time that two
+//! machines can compare: nanoseconds since the Unix epoch, which jumps
+//! backwards when the host's clock is corrected. That is not the monotonic
+//! reading you measure elapsed time with, and no deadline, timeout or budget
+//! may be derived from it. Those belong to a monotonic clock, which this crate
+//! does not have and does not want.
+//!
+//! State is fixed-size: capacities are const generics, and a state with no free
+//! slot left reports [`CapacityError`] rather than allocating. A clock whose
+//! counter has run out reports [`ClockExhausted`] rather than reissuing the
+//! timestamp it last gave away.
+//!
+//! # Putting state on a wire
+//!
+//! Every state encodes to a fixed-length frame of its own
+//! `ENCODED_LEN` bytes, led by a tag naming the structure and, where there is
+//! one, a field naming the const generic. `decode` and `decode_into` reject a
+//! short buffer, another structure's tag, and a frame written at another shape.
+
+#[cfg(feature = "alloc")]
+extern crate alloc;
+
+/// Compiles and runs the README's examples as doctests.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+struct ReadmeDoctests;
+
+pub mod gcounter;
+pub mod gset;
+pub mod hybrid;
+pub mod logical;
+pub mod lww;
+pub mod orset;
+pub mod pncounter;
+
+pub use gcounter::GCounter;
+pub use gset::GSet;
+pub use hybrid::{HybridClock, HybridTimestamp};
+pub use logical::LogicalClock;
+pub use lww::{LwwRegister, STAMP_HYBRID, STAMP_LOGICAL, Stamp};
+pub use orset::{OrSet, Tag, Tagged};
+pub use pncounter::PNCounter;
+
+/// Which replica an update came from.
+pub type ReplicaId = u64;
+
+/// A state that can absorb another replica's state.
+pub trait Merge {
+    /// Why this state could not absorb the other one.
+    type Error;
+
+    /// Folds `other` into this state.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`CapacityError`] when the union needs more slots than this
+    /// state has. Nothing is rolled back: whatever fit stayed, and merging
+    /// again after raising the capacity completes the job.
+    fn merge(&mut self, other: &Self) -> Result<(), Self::Error>;
+}
+
+/// The union needed a slot and there was none left.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CapacityError;
+
+/// A clock has issued the last timestamp its counter can hold.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ClockExhausted;
+
+impl core::fmt::Display for ClockExhausted {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.write_str("no timestamp left")
+    }
+}
+
+impl core::error::Error for ClockExhausted {}
+
+impl core::fmt::Display for CapacityError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.write_str("no free slot")
+    }
+}
+
+impl core::error::Error for CapacityError {}
+
+/// Why a state could not be read from or written to a byte buffer.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CodecError {
+    /// The buffer is shorter than the encoded form needs.
+    Truncated,
+    /// The leading byte names a different structure.
+    Tag,
+    /// The encoded shape does not match the target type's.
+    Parameters,
+}
+
+impl core::fmt::Display for CodecError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.write_str(match self {
+            Self::Truncated => "buffer too short",
+            Self::Tag => "wrong structure tag",
+            Self::Parameters => "shape mismatch",
+        })
+    }
+}
+
+impl core::error::Error for CodecError {}
+
+pub(crate) const TAG_LOGICAL_CLOCK: u8 = 0x51;
+pub(crate) const TAG_HYBRID_CLOCK: u8 = 0x52;
+pub(crate) const TAG_GCOUNTER: u8 = 0x61;
+pub(crate) const TAG_PNCOUNTER: u8 = 0x62;
+pub(crate) const TAG_LWW_REGISTER: u8 = 0x71;
+pub(crate) const TAG_GSET: u8 = 0x81;
+pub(crate) const TAG_ORSET: u8 = 0x82;
+
+/// Where a frame's leading structure tag sits.
+pub(crate) const TAG: usize = 0;
+
+/// Bytes a frame spends on its leading structure tag.
+pub(crate) const TAG_LEN: usize = 1;
+
+/// Bytes a frame spends naming the shape it was written at.
+pub(crate) const SHAPE_LEN: usize = 2;
+
+/// Bytes a frame spends saying how many of its slot records carry a slot.
+pub(crate) const COUNT_LEN: usize = 2;
+
+/// Bytes a frame spends on one 64-bit field.
+pub(crate) const FIELD_LEN: usize = 8;
+
+/// A frame's 64-bit field, read from `field`, which is [`FIELD_LEN`] long.
+pub(crate) const fn read_u64(field: &[u8]) -> u64 {
+    let mut bytes = [0_u8; FIELD_LEN];
+    bytes.copy_from_slice(field);
+    u64::from_le_bytes(bytes)
+}
+
+/// The low two bytes of `value`, as a frame's shape or count field.
+pub(crate) const fn small_field(value: usize) -> [u8; SHAPE_LEN] {
+    let [low, high, ..] = value.to_le_bytes();
+    [low, high]
+}
+
+/// A frame's shape or count field, read from `field`, which is [`SHAPE_LEN`]
+/// long.
+pub(crate) fn read_small(field: &[u8]) -> usize {
+    let mut bytes = [0_u8; SHAPE_LEN];
+    bytes.copy_from_slice(field);
+    usize::from(u16::from_le_bytes(bytes))
+}
+
+/// Writes a frame of `len` bytes at the front of `out` through `fill`,
+/// returning the number of bytes written.
+pub(crate) fn write_into(
+    out: &mut [u8],
+    len: usize,
+    fill: impl FnOnce(&mut [u8]),
+) -> Result<usize, CodecError> {
+    let Some(frame) = out.get_mut(..len) else {
+        return Err(CodecError::Truncated);
+    };
+    fill(frame);
+    Ok(len)
+}
+
+/// A frame of exactly `len` bytes, filled by `fill`.
+#[cfg(feature = "alloc")]
+pub(crate) fn boxed_frame(len: usize, fill: impl FnOnce(&mut [u8])) -> alloc::boxed::Box<[u8]> {
+    let mut frame = alloc::vec![0_u8; len].into_boxed_slice();
+    fill(&mut frame);
+    frame
+}
+
+/// The `len`-byte frame `bytes` leads with, which `tag` has to name.
+pub(crate) fn tagged_frame(bytes: &[u8], len: usize, tag: u8) -> Result<&[u8], CodecError> {
+    let Some(frame) = bytes.get(..len) else {
+        return Err(CodecError::Truncated);
+    };
+    if frame[TAG] != tag {
+        return Err(CodecError::Tag);
+    }
+    Ok(frame)
+}
+
+/// Whether two slot arrays hold the same elements, ignoring where in the array
+/// each one sits.
+pub(crate) fn same_elements<T: PartialEq>(left: &[Option<T>], right: &[Option<T>]) -> bool {
+    let contained =
+        |haystack: &[Option<T>], needle: &T| haystack.iter().flatten().any(|held| held == needle);
+
+    left.iter()
+        .flatten()
+        .all(|element| contained(right, element))
+        && right
+            .iter()
+            .flatten()
+            .all(|element| contained(left, element))
+}
+
+/// Index of the first slot nothing has claimed yet.
+pub(crate) fn free_slot<T>(slots: &[Option<T>]) -> Option<usize> {
+    slots.iter().position(Option::is_none)
+}
+
+#[cfg(test)]
+mod tests;

data/ext/merge_machines_native/core/src/logical.rs

@@ -0,0 +1,139 @@
+//! Lamport's logical clock: ordering events without reading a clock.
+
+#[cfg(feature = "alloc")]
+use crate::boxed_frame;
+use crate::{
+    ClockExhausted, CodecError, FIELD_LEN, TAG, TAG_LEN, TAG_LOGICAL_CLOCK, read_u64, tagged_frame,
+    write_into,
+};
+
+/// Where the counter sits in a frame.
+const COUNTER: core::ops::Range<usize> = TAG_LEN..TAG_LEN + FIELD_LEN;
+
+/// A counter that orders events across replicas, with no clock involved.
+///
+/// ```
+/// use merge_machines::{ClockExhausted, LogicalClock};
+///
+/// let mut sender = LogicalClock::new();
+/// let mut receiver = LogicalClock::new();
+///
+/// let sent_at = sender.tick()?;
+/// assert_eq!(sent_at, 1);
+///
+/// receiver.tick()?;
+/// receiver.tick()?;
+///
+/// // Receiving is stamped after both the local history and the send.
+/// assert_eq!(receiver.observe(sent_at), Ok(3));
+/// assert_eq!(receiver.observe(99), Ok(100));
+///
+/// // A counter with nothing left reports it instead of repeating itself.
+/// assert_eq!(receiver.observe(u64::MAX), Err(ClockExhausted));
+/// assert_eq!(receiver.now(), 100);
+/// # Ok::<(), ClockExhausted>(())
+/// ```
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct LogicalClock {
+    counter: u64,
+}
+
+impl LogicalClock {
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { counter: 0 }
+    }
+
+    /// The last timestamp this clock issued.
+    #[must_use]
+    pub const fn now(&self) -> u64 {
+        self.counter
+    }
+
+    /// Stamps a local event.
+    ///
+    /// # Errors
+    ///
+    /// [`ClockExhausted`] when the counter holds its highest value, which
+    /// leaves the clock where it was.
+    pub const fn tick(&mut self) -> Result<u64, ClockExhausted> {
+        self.issue(self.counter)
+    }
+
+    /// Stamps the receipt of `observed`, a timestamp from another replica.
+    ///
+    /// # Errors
+    ///
+    /// The same as [`tick`](Self::tick), and the observed timestamp is not
+    /// adopted either.
+    pub const fn observe(&mut self, observed: u64) -> Result<u64, ClockExhausted> {
+        self.issue(if observed > self.counter {
+            observed
+        } else {
+            self.counter
+        })
+    }
+
+    /// Issues the timestamp that follows `base`.
+    const fn issue(&mut self, base: u64) -> Result<u64, ClockExhausted> {
+        let Some(next) = base.checked_add(1) else {
+            return Err(ClockExhausted);
+        };
+        self.counter = next;
+        Ok(next)
+    }
+
+    /// Length of the [`encode`](Self::encode) frame.
+    pub const ENCODED_LEN: usize = TAG_LEN + FIELD_LEN;
+
+    /// Writes the clock into `out`, returning the number of bytes written.
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `out` is shorter than
+    /// [`ENCODED_LEN`](Self::ENCODED_LEN).
+    pub fn encode(&self, out: &mut [u8]) -> Result<usize, CodecError> {
+        write_into(out, Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// The clock's frame, exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    #[cfg(feature = "alloc")]
+    #[must_use]
+    pub fn encoded(&self) -> alloc::boxed::Box<[u8]> {
+        boxed_frame(Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// Fills a frame of exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    fn write_frame(self, frame: &mut [u8]) {
+        frame[TAG] = TAG_LOGICAL_CLOCK;
+        frame[COUNTER].copy_from_slice(&self.counter.to_le_bytes());
+    }
+
+    /// Reads a clock written by [`encode`](Self::encode).
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `bytes` is too short, [`CodecError::Tag`]
+    /// when it holds another structure.
+    pub fn decode(bytes: &[u8]) -> Result<Self, CodecError> {
+        let mut clock = Self::new();
+        clock.decode_into(bytes)?;
+        Ok(clock)
+    }
+
+    /// Reads a frame over a clock the caller already holds.
+    ///
+    /// The clock is untouched when the frame is rejected.
+    ///
+    /// # Errors
+    ///
+    /// The same as [`decode`](Self::decode).
+    pub fn decode_into(&mut self, bytes: &[u8]) -> Result<(), CodecError> {
+        let frame = tagged_frame(bytes, Self::ENCODED_LEN, TAG_LOGICAL_CLOCK)?;
+        self.counter = read_u64(&frame[COUNTER]);
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/merge_machines_native/core/src/lww.rs

@@ -0,0 +1,213 @@
+//! Last writer wins, with the replica id as the tie-break.
+
+#[cfg(feature = "alloc")]
+use crate::boxed_frame;
+use crate::{
+    CodecError, FIELD_LEN, Merge, ReplicaId, SHAPE_LEN, TAG, TAG_LEN, TAG_LWW_REGISTER, read_small,
+    read_u64, small_field, tagged_frame, write_into,
+};
+use core::convert::Infallible;
+
+/// A stamp naming one 64-bit counter, as [`LogicalClock`](crate::LogicalClock)
+/// issues.
+pub const STAMP_LOGICAL: u8 = 0x01;
+
+/// A stamp naming a wall-clock reading and its counter, as
+/// [`HybridClock`](crate::HybridClock) issues.
+pub const STAMP_HYBRID: u8 = 0x02;
+
+/// A stamp a register's frame can carry.
+pub trait Stamp: Copy + Default + Ord {
+    /// Byte naming this stamp in a register frame.
+    const KIND: u8;
+
+    /// Bytes this stamp occupies in a register frame.
+    const ENCODED_LEN: usize;
+
+    /// Writes this stamp into `field`, which is
+    /// [`ENCODED_LEN`](Self::ENCODED_LEN) long.
+    fn write(self, field: &mut [u8]);
+
+    /// Reads a stamp from `field`, which is
+    /// [`ENCODED_LEN`](Self::ENCODED_LEN) long.
+    fn read(field: &[u8]) -> Self;
+}
+
+impl Stamp for u64 {
+    const KIND: u8 = STAMP_LOGICAL;
+    const ENCODED_LEN: usize = FIELD_LEN;
+
+    fn write(self, field: &mut [u8]) {
+        field.copy_from_slice(&self.to_le_bytes());
+    }
+
+    fn read(field: &[u8]) -> Self {
+        read_u64(field)
+    }
+}
+
+/// Where the stamp kind sits in a frame.
+const STAMP_KIND: core::ops::Range<usize> = TAG_LEN..TAG_LEN + SHAPE_LEN;
+
+/// Where the value sits in a frame.
+const VALUE: core::ops::Range<usize> = STAMP_KIND.end..STAMP_KIND.end + FIELD_LEN;
+
+/// Where the writing replica sits in a frame.
+const REPLICA: core::ops::Range<usize> = VALUE.end..VALUE.end + FIELD_LEN;
+
+/// One value, held by whichever write was stamped last.
+///
+/// ```
+/// use merge_machines::{LwwRegister, Merge};
+///
+/// let mut left = LwwRegister::new(10_u32, 4_u64, 1);
+/// let right = LwwRegister::new(20, 9, 2);
+///
+/// assert_eq!(left.merge(&right), Ok(()));
+/// assert_eq!(*left.value(), 20);
+///
+/// // A stamp from before the current one changes nothing.
+/// left.set(30, 1, 1);
+/// assert_eq!(*left.value(), 20);
+///
+/// // Equal stamps go to the higher replica id, from either side.
+/// let mut low = LwwRegister::new(1_u32, 5_u64, 1);
+/// let high = LwwRegister::new(2, 5, 2);
+/// assert_eq!(low.merge(&high), Ok(()));
+/// assert_eq!(*low.value(), 2);
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct LwwRegister<T, S> {
+    value: T,
+    stamp: S,
+    replica: ReplicaId,
+}
+
+impl<T: Clone, S: Ord + Copy> LwwRegister<T, S> {
+    #[must_use]
+    pub const fn new(value: T, stamp: S, replica: ReplicaId) -> Self {
+        Self {
+            value,
+            stamp,
+            replica,
+        }
+    }
+
+    /// Writes `value` if `(stamp, replica)` beats the write already held.
+    pub fn set(&mut self, value: T, stamp: S, replica: ReplicaId) {
+        if (stamp, replica) > (self.stamp, self.replica) {
+            self.value = value;
+            self.stamp = stamp;
+            self.replica = replica;
+        }
+    }
+
+    #[must_use]
+    pub const fn value(&self) -> &T {
+        &self.value
+    }
+
+    /// The stamp of the write being held.
+    #[must_use]
+    pub const fn stamp(&self) -> &S {
+        &self.stamp
+    }
+
+    /// The replica that wrote what is being held.
+    #[must_use]
+    pub const fn replica(&self) -> ReplicaId {
+        self.replica
+    }
+}
+
+impl<S: Stamp> LwwRegister<u64, S> {
+    /// Length of the [`encode`](Self::encode) frame.
+    pub const ENCODED_LEN: usize = REPLICA.end + S::ENCODED_LEN;
+
+    /// Where the stamp sits in a frame.
+    const STAMP: core::ops::Range<usize> = REPLICA.end..Self::ENCODED_LEN;
+
+    /// A register holding nothing, for [`decode`](Self::decode) to read a frame
+    /// over.
+    fn empty() -> Self {
+        Self {
+            value: 0,
+            stamp: S::default(),
+            replica: 0,
+        }
+    }
+
+    /// Writes the register into `out`, returning the number of bytes written.
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `out` is shorter than
+    /// [`ENCODED_LEN`](Self::ENCODED_LEN).
+    pub fn encode(&self, out: &mut [u8]) -> Result<usize, CodecError> {
+        write_into(out, Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// The register's frame, exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    #[cfg(feature = "alloc")]
+    #[must_use]
+    pub fn encoded(&self) -> alloc::boxed::Box<[u8]> {
+        boxed_frame(Self::ENCODED_LEN, |frame| self.write_frame(frame))
+    }
+
+    /// Fills a frame of exactly [`ENCODED_LEN`](Self::ENCODED_LEN) bytes.
+    fn write_frame(&self, frame: &mut [u8]) {
+        frame[TAG] = TAG_LWW_REGISTER;
+        frame[STAMP_KIND].copy_from_slice(&small_field(usize::from(S::KIND)));
+        frame[VALUE].copy_from_slice(&self.value.to_le_bytes());
+        frame[REPLICA].copy_from_slice(&self.replica.to_le_bytes());
+        self.stamp.write(&mut frame[Self::STAMP]);
+    }
+
+    /// Reads a register written by [`encode`](Self::encode).
+    ///
+    /// # Errors
+    ///
+    /// [`CodecError::Truncated`] when `bytes` is too short, [`CodecError::Tag`]
+    /// when it holds another structure, [`CodecError::Parameters`] when it was
+    /// written with another kind of stamp.
+    pub fn decode(bytes: &[u8]) -> Result<Self, CodecError> {
+        let mut register = Self::empty();
+        register.decode_into(bytes)?;
+        Ok(register)
+    }
+
+    /// Reads a frame over a register the caller already holds.
+    ///
+    /// The register is untouched when the frame is rejected.
+    ///
+    /// # Errors
+    ///
+    /// The same as [`decode`](Self::decode).
+    pub fn decode_into(&mut self, bytes: &[u8]) -> Result<(), CodecError> {
+        let frame = tagged_frame(bytes, Self::ENCODED_LEN, TAG_LWW_REGISTER)?;
+        if read_small(&frame[STAMP_KIND]) != usize::from(S::KIND) {
+            return Err(CodecError::Parameters);
+        }
+
+        self.value = read_u64(&frame[VALUE]);
+        self.replica = read_u64(&frame[REPLICA]);
+        self.stamp = S::read(&frame[Self::STAMP]);
+        Ok(())
+    }
+}
+
+impl<T: Clone, S: Ord + Copy> Merge for LwwRegister<T, S> {
+    type Error = Infallible;
+
+    fn merge(&mut self, other: &Self) -> Result<(), Self::Error> {
+        if (other.stamp, other.replica) > (self.stamp, self.replica) {
+            self.value.clone_from(&other.value);
+            self.stamp = other.stamp;
+            self.replica = other.replica;
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests;