consensus_machines 0.1.4

data/ext/consensus_machines_native/ffi/src/lib.rs

@@ -0,0 +1,251 @@
+//! Native Ruby bridge for a bounded Raft model, not a consensus service.
+mod init;
+mod model;
+mod values;
+use consensus_machines::{AppendRequest, Entry, Position, Role, Vote, VoteRequest, VoteResponse};
+use magnus::{Error, RArray, Ruby, Value, prelude::*, typed_data::Obj};
+use std::{cell::RefCell, sync::Arc};
+use values::{Id, index};
+
+struct State {
+    node: Box<dyn model::Model>,
+    revision: u64,
+}
+#[magnus::wrap(class = "ConsensusMachines::Checkpoint", free_immediately, size)]
+struct Saved {
+    owner: Arc<()>,
+    revision: u64,
+    checkpoint: Box<dyn model::Durable>,
+}
+#[magnus::wrap(class = "ConsensusMachines::Raft", free_immediately, size)]
+struct Wrapper {
+    owner: Arc<()>,
+    state: RefCell<State>,
+}
+const fn role(role: Role) -> &'static str {
+    match role {
+        Role::Follower => "follower",
+        Role::Candidate => "candidate",
+        Role::Leader => "leader",
+        _ => "unknown",
+    }
+}
+impl Wrapper {
+    fn new(ruby: &Ruby, members: RArray, own: Id) -> Result<Self, Error> {
+        let count = members.len();
+        if !(1..=9).contains(&count) {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "membership must contain 1..9 actual members",
+            ));
+        }
+        let mut ids = [0; 9];
+        for (offset, id) in ids[..count].iter_mut().enumerate() {
+            *id = members.entry::<Id>(offset.cast_signed())?.0;
+        }
+        let node = model::new(&ids[..count], index(ruby, own)?).ok_or_else(|| {
+            Error::new(
+                ruby.exception_arg_error(),
+                "members must be unique and own index must be in membership",
+            )
+        })?;
+        Ok(Self {
+            owner: Arc::new(()),
+            state: RefCell::new(State { node, revision: 0 }),
+        })
+    }
+    fn next_revision(&self, ruby: &Ruby) -> Result<u64, Error> {
+        let revision = self.state.borrow().revision.checked_add(1);
+        revision.ok_or_else(|| Error::new(ruby.exception_range_error(), "revision exhausted"))
+    }
+    /// Runs `step` against the node under the next revision, which stales every
+    /// checkpoint taken before it.
+    fn advance<T>(
+        &self,
+        ruby: &Ruby,
+        step: impl FnOnce(&mut dyn model::Model) -> T,
+    ) -> Result<T, Error> {
+        let revision = self.next_revision(ruby)?;
+        let mut state = self.state.borrow_mut();
+        state.revision = revision;
+        Ok(step(state.node.as_mut()))
+    }
+    fn role(&self) -> &'static str {
+        role(self.state.borrow().node.role())
+    }
+    fn term(&self) -> u64 {
+        self.state.borrow().node.term()
+    }
+    fn committed(&self) -> usize {
+        self.state.borrow().node.committed()
+    }
+    fn last(&self) -> (usize, u64) {
+        let last = self.state.borrow().node.last();
+        (last.index, last.term)
+    }
+    fn entry(ruby: &Ruby, rb_self: &Self, position: Id) -> Result<Option<(u64, u64)>, Error> {
+        let index = index(ruby, position)?;
+        Ok(rb_self
+            .state
+            .borrow()
+            .node
+            .entry(index)
+            .map(|entry| (entry.term, entry.command)))
+    }
+    fn begin_election(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+    ) -> Result<Option<(usize, u64, usize, u64)>, Error> {
+        rb_self.check_frozen()?;
+        let request = rb_self.advance(ruby, |node| node.begin_election())?;
+        Ok(request.map(|request| {
+            (
+                request.candidate,
+                request.term,
+                request.last.index,
+                request.last.term,
+            )
+        }))
+    }
+    fn request_vote(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        candidate: Id,
+        term: Id,
+        last_index: Id,
+        last_term: Id,
+    ) -> Result<(u64, bool), Error> {
+        rb_self.check_frozen()?;
+        let request = VoteRequest {
+            candidate: index(ruby, candidate)?,
+            term: term.0,
+            last: Position {
+                index: index(ruby, last_index)?,
+                term: last_term.0,
+            },
+        };
+        let response = rb_self.advance(ruby, |node| node.request_vote(request))?;
+        Ok((response.term, response.vote == Vote::Granted))
+    }
+    fn receive_vote(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        peer: Id,
+        term: Id,
+        ballot: Id,
+    ) -> Result<&'static str, Error> {
+        rb_self.check_frozen()?;
+        let peer = index(ruby, peer)?;
+        let vote = match ballot.0 {
+            0 => Vote::Denied,
+            1 => Vote::Granted,
+            _ => {
+                return Err(Error::new(
+                    ruby.exception_arg_error(),
+                    "ballot must be Integer 0 or 1",
+                ));
+            }
+        };
+        let result = rb_self.advance(ruby, |node| {
+            node.receive_vote(peer, VoteResponse { term: term.0, vote })
+        })?;
+        Ok(role(result))
+    }
+    fn propose(ruby: &Ruby, rb_self: Obj<Self>, command: Id) -> Result<Option<usize>, Error> {
+        rb_self.check_frozen()?;
+        rb_self.advance(ruby, |node| node.propose(command.0))
+    }
+    // Mirrors AppendEntries metadata without Ruby policy objects.
+    #[allow(clippy::too_many_arguments)]
+    fn append_entries(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        leader: Id,
+        term: Id,
+        previous_index: Id,
+        previous_term: Id,
+        committed: Id,
+        entries: RArray,
+    ) -> Result<(u64, Option<usize>), Error> {
+        rb_self.check_frozen()?;
+        let count = entries.len();
+        if count > 64 {
+            return Err(Error::new(ruby.exception_arg_error(), "at most 64 entries"));
+        }
+        let mut decoded = [Entry {
+            term: 0,
+            command: 0,
+        }; 64];
+        for (offset, entry) in decoded[..count].iter_mut().enumerate() {
+            // RArray::try_convert can invoke to_ary, permitting reentrant input
+            // mutation or freezing. Nested entries must already be Arrays.
+            let value = entries.entry::<Value>(offset.cast_signed())?;
+            let pair = RArray::from_value(value)
+                .ok_or_else(|| Error::new(ruby.exception_type_error(), "entry must be an Array"))?;
+            if pair.len() != 2 {
+                return Err(Error::new(
+                    ruby.exception_arg_error(),
+                    "entry must be [term, command_id]",
+                ));
+            }
+            *entry = Entry {
+                term: pair.entry::<Id>(0)?.0,
+                command: pair.entry::<Id>(1)?.0,
+            };
+        }
+        let request = AppendRequest {
+            leader: index(ruby, leader)?,
+            term: term.0,
+            previous: Position {
+                index: index(ruby, previous_index)?,
+                term: previous_term.0,
+            },
+            committed: index(ruby, committed)?,
+        };
+        rb_self.check_frozen()?;
+        let response =
+            rb_self.advance(ruby, |node| node.append_entries(request, &decoded[..count]))?;
+        Ok((response.term, response.matched))
+    }
+    fn acknowledge(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        peer: Id,
+        term: Id,
+        position: Id,
+    ) -> Result<bool, Error> {
+        rb_self.check_frozen()?;
+        let peer = index(ruby, peer)?;
+        let position = index(ruby, position)?;
+        rb_self.advance(ruby, |node| node.acknowledge(peer, term.0, position))
+    }
+    fn checkpoint(&self) -> Saved {
+        let (checkpoint, revision) = {
+            let state = self.state.borrow();
+            (state.node.checkpoint(), state.revision)
+        };
+        Saved {
+            owner: Arc::clone(&self.owner),
+            revision,
+            checkpoint,
+        }
+    }
+    fn restore(ruby: &Ruby, rb_self: Obj<Self>, saved: &Saved) -> Result<bool, Error> {
+        rb_self.check_frozen()?;
+        if !Arc::ptr_eq(&rb_self.owner, &saved.owner)
+            || rb_self.state.borrow().revision != saved.revision
+        {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "cross-instance or stale checkpoint",
+            ));
+        }
+        let revision = rb_self.next_revision(ruby)?;
+        let node = saved
+            .checkpoint
+            .restore()
+            .ok_or_else(|| Error::new(ruby.exception_arg_error(), "invalid checkpoint"))?;
+        *rb_self.state.borrow_mut() = State { node, revision };
+        Ok(true)
+    }
+}

data/ext/consensus_machines_native/ffi/src/model.rs

@@ -0,0 +1,84 @@
+//! Exact-membership type erasure; all transitions delegate to the core.
+use consensus_machines::{
+    AppendRequest, AppendResponse, Checkpoint, Entry, Position, Raft, Role, VoteRequest,
+    VoteResponse,
+};
+
+pub trait Durable: Send {
+    fn restore(&self) -> Option<Box<dyn Model>>;
+}
+pub trait Model: Send {
+    fn role(&self) -> Role;
+    fn term(&self) -> u64;
+    fn committed(&self) -> usize;
+    fn last(&self) -> Position;
+    fn entry(&self, index: usize) -> Option<Entry>;
+    fn begin_election(&mut self) -> Option<VoteRequest>;
+    fn request_vote(&mut self, request: VoteRequest) -> VoteResponse;
+    fn receive_vote(&mut self, peer: usize, response: VoteResponse) -> Role;
+    fn propose(&mut self, command: u64) -> Option<usize>;
+    fn append_entries(&mut self, request: AppendRequest, entries: &[Entry]) -> AppendResponse;
+    fn acknowledge(&mut self, peer: usize, term: u64, index: usize) -> bool;
+    fn checkpoint(&self) -> Box<dyn Durable>;
+}
+impl<const N: usize> Durable for Checkpoint<N, 64> {
+    fn restore(&self) -> Option<Box<dyn Model>> {
+        Raft::restore(self.clone()).map(|node| Box::new(node) as Box<dyn Model>)
+    }
+}
+impl<const N: usize> Model for Raft<N, 64> {
+    fn role(&self) -> Role {
+        self.role()
+    }
+    fn term(&self) -> u64 {
+        self.term()
+    }
+    fn committed(&self) -> usize {
+        self.committed()
+    }
+    fn last(&self) -> Position {
+        self.last()
+    }
+    fn entry(&self, index: usize) -> Option<Entry> {
+        self.entry(index)
+    }
+    fn begin_election(&mut self) -> Option<VoteRequest> {
+        self.begin_election()
+    }
+    fn request_vote(&mut self, request: VoteRequest) -> VoteResponse {
+        self.request_vote(request)
+    }
+    fn receive_vote(&mut self, peer: usize, response: VoteResponse) -> Role {
+        self.receive_vote(peer, response)
+    }
+    fn propose(&mut self, command: u64) -> Option<usize> {
+        self.propose(command)
+    }
+    fn append_entries(&mut self, request: AppendRequest, entries: &[Entry]) -> AppendResponse {
+        self.append_entries(request, entries)
+    }
+    fn acknowledge(&mut self, peer: usize, term: u64, index: usize) -> bool {
+        self.acknowledge(peer, term, index)
+    }
+    fn checkpoint(&self) -> Box<dyn Durable> {
+        Box::new(self.checkpoint())
+    }
+}
+fn sized<const N: usize>(members: &[u64], own: usize) -> Option<Box<dyn Model>> {
+    let members: [u64; N] = members.try_into().ok()?;
+    Raft::<N, 64>::new(members, own).map(|node| Box::new(node) as Box<dyn Model>)
+}
+pub fn new(members: &[u64], own: usize) -> Option<Box<dyn Model>> {
+    match members.len() {
+        1 => sized::<1>(members, own),
+        2 => sized::<2>(members, own),
+        3 => sized::<3>(members, own),
+        4 => sized::<4>(members, own),
+        5 => sized::<5>(members, own),
+        6 => sized::<6>(members, own),
+        7 => sized::<7>(members, own),
+        8 => sized::<8>(members, own),
+        9 => sized::<9>(members, own),
+        _ => None,
+    }
+}

data/ext/consensus_machines_native/ffi/src/values.rs

@@ -0,0 +1,19 @@
+//! Strict integer decoding before any state transition.
+use magnus::{Error, Integer, Ruby, TryConvert, Value};
+#[derive(Clone, Copy)]
+pub struct Id(pub u64);
+impl TryConvert for Id {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        if Integer::from_value(value).is_none() {
+            return Err(Error::new(
+                Ruby::get_with(value).exception_type_error(),
+                "expected an Integer",
+            ));
+        }
+        u64::try_convert(value).map(Self)
+    }
+}
+pub fn index(ruby: &Ruby, id: Id) -> Result<usize, Error> {
+    usize::try_from(id.0)
+        .map_err(|_| Error::new(ruby.exception_range_error(), "index outside native range"))
+}

data/lib/consensus_machines/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module ConsensusMachines
+  VERSION = '0.1.4'
+end

data/lib/consensus_machines.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+require_relative 'consensus_machines/version'
+require 'consensus_machines_native/consensus_machines_native'

data/sig/consensus_machines.rbs

@@ -0,0 +1,21 @@
+module ConsensusMachines
+  VERSION: String
+  class Checkpoint
+  end
+  class Raft
+    def self.new: (Array[Integer], Integer) -> Raft
+    def role: () -> String
+    def term: () -> Integer
+    def committed: () -> Integer
+    def last: () -> [Integer, Integer]
+    def entry: (Integer) -> [Integer, Integer]?
+    def begin_election: () -> [Integer, Integer, Integer, Integer]?
+    def request_vote: (Integer, Integer, Integer, Integer) -> [Integer, bool]
+    def receive_vote: (Integer, Integer, Integer) -> String
+    def propose: (Integer) -> Integer?
+    def append_entries: (Integer, Integer, Integer, Integer, Integer, Array[[Integer, Integer]]) -> [Integer, Integer?]
+    def acknowledge: (Integer, Integer, Integer) -> bool
+    def checkpoint: () -> Checkpoint
+    def restore!: (Checkpoint) -> bool
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: consensus_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: A thin bridge to an allocation-free fixed-membership Rust Raft model.
+  Not a production consensus service.
+email:
+- oss@seuros.com
+executables: []
+extensions:
+- ext/consensus_machines_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/consensus_machines_native/core/CHANGELOG.md
+- ext/consensus_machines_native/core/Cargo.toml
+- ext/consensus_machines_native/core/README.md
+- ext/consensus_machines_native/core/src/lib.rs
+- ext/consensus_machines_native/core/src/log.rs
+- ext/consensus_machines_native/extconf.rb
+- ext/consensus_machines_native/ffi/Cargo.toml
+- ext/consensus_machines_native/ffi/extconf.rb
+- ext/consensus_machines_native/ffi/src/init.rs
+- ext/consensus_machines_native/ffi/src/lib.rs
+- ext/consensus_machines_native/ffi/src/model.rs
+- ext/consensus_machines_native/ffi/src/values.rs
+- lib/consensus_machines.rb
+- lib/consensus_machines/version.rb
+- sig/consensus_machines.rbs
+homepage: https://github.com/seuros/consensus_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/consensus_machines
+  bug_tracker_uri: https://github.com/seuros/consensus_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: consensus_machines_native
+  cargo_manifest_path: ext/consensus_machines_native/ffi/Cargo.toml
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Native bounded Raft transition model for Ruby
+test_files: []