igniter 0.4.5 → 0.5.0

data/lib/igniter/consensus/cluster.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Consensus
+    # Manages a consensus cluster: node lifecycle, leader discovery,
+    # high-level read/write, quorum checks, and Igniter::Contract integration.
+    #
+    # == Quick start (default KV state machine)
+    #
+    #   cluster = Igniter::Consensus::Cluster.start(nodes: %i[n1 n2 n3 n4 n5])
+    #   cluster.wait_for_leader
+    #   cluster.write(key: :price, value: 99)
+    #   cluster.read(:price)   # => 99
+    #   cluster.stop!
+    #
+    # == Custom state machine
+    #
+    #   class OrderBook < Igniter::Consensus::StateMachine
+    #     apply :add    do |state, cmd| state.merge(cmd[:id] => cmd[:data]) end
+    #     apply :cancel do |state, cmd| state.reject { |k, _| k == cmd[:id] } end
+    #   end
+    #
+    #   cluster = Igniter::Consensus::Cluster.start(
+    #     nodes: %i[n1 n2 n3 n4 n5],
+    #     state_machine: OrderBook,
+    #   )
+    #   cluster.write(type: :add, id: "o1", data: { price: 42 })
+    #   cluster.read("o1")   # => { price: 42 }
+    #
+    # == Contract integration
+    #
+    #   q = cluster.read_contract(key: :price)
+    #   q.resolve_all
+    #   q.result.value   # => 99
+    class Cluster
+      attr_reader :node_ids, :state_machine_class
+
+      # Start a cluster. Does NOT wait for leader election.
+      # Call +wait_for_leader+ if you need a leader before proceeding.
+      #
+      # @param nodes          [Array<Symbol>] Registry names for each node
+      # @param state_machine  [Class]         StateMachine subclass (default: StateMachine)
+      # @param verbose        [Boolean]       print Raft events to stdout
+      def self.start(nodes:, state_machine: nil, verbose: false)
+        new(nodes: nodes, state_machine: state_machine, verbose: verbose).tap(&:start!)
+      end
+
+      def initialize(nodes:, state_machine: nil, verbose: false)
+        @node_ids            = nodes.freeze
+        @state_machine_class = state_machine || StateMachine
+        @verbose             = verbose
+      end
+
+      # Start all nodes.
+      def start!
+        @node_ids.each do |nid|
+          Node.start(
+            name:          nid,
+            peers:         @node_ids.reject { |id| id == nid },
+            state_machine: @state_machine_class,
+            verbose:       @verbose,
+          )
+        end
+        self
+      end
+
+      # Stop all nodes gracefully.
+      def stop!(timeout: 2)
+        @node_ids.each do |nid|
+          begin
+            Igniter::Registry.find(nid)&.stop(timeout: timeout)
+            Igniter::Registry.unregister(nid)
+          rescue StandardError
+            nil
+          end
+        end
+        self
+      end
+
+      # Returns the Ref for the current leader, or +nil+ if none is available.
+      def leader
+        @node_ids.each do |nid|
+          ref = Igniter::Registry.find(nid)
+          next unless ref&.alive?
+          return ref if ref.state[:role] == :leader
+        end
+        nil
+      end
+
+      # Block until a leader is elected or +timeout+ seconds elapse.
+      #
+      # @param timeout [Float] seconds to wait (default: ~2s, covers max election jitter)
+      # @return [Agent::Ref] the leader Ref
+      # @raise [NoLeaderError] if no leader is elected within the timeout
+      def wait_for_leader(timeout: ELECTION_TIMEOUT_BASE + ELECTION_TIMEOUT_JITTER + 0.5)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          ref = leader
+          return ref if ref
+
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise NoLeaderError, "No leader elected within #{timeout}s — cluster may lack quorum" if remaining <= 0
+
+          sleep 0.05
+        end
+      end
+
+      # Submit a command to the consensus log via the current leader.
+      #
+      # Default KV protocol:   +cluster.write(key: :x, value: 42)+
+      # Custom state machine:  +cluster.write(type: :add_order, id: "o1", data: {...})+
+      #
+      # @raise [NoLeaderError] if no leader is currently available
+      def write(command = {})
+        ref = leader
+        raise NoLeaderError, "No leader available — cluster may be electing or lacks quorum" unless ref
+        ref.send(:client_write, command: command)
+        self
+      end
+
+      # Read a key from the current leader's committed state machine.
+      #
+      # @raise [NoLeaderError] if no leader is available
+      def read(key)
+        ref = leader
+        raise NoLeaderError, "No leader available" unless ref
+        ref.state[:state_machine][key]
+      end
+
+      # Return a snapshot of the full state machine from the current leader.
+      #
+      # @raise [NoLeaderError] if no leader is available
+      def state_machine_snapshot
+        ref = leader
+        raise NoLeaderError, "No leader available" unless ref
+        ref.state[:state_machine].dup
+      end
+
+      # Number of alive nodes.
+      def alive_count
+        @node_ids.count { |nid| Igniter::Registry.find(nid)&.alive? }
+      end
+
+      # Minimum votes required for any Raft decision (⌊N/2⌋ + 1).
+      def quorum_size
+        (@node_ids.size / 2) + 1
+      end
+
+      # Returns +true+ if enough nodes are alive to elect a leader.
+      def has_quorum?
+        alive_count >= quorum_size
+      end
+
+      # Returns a +ReadQuery+ contract pre-configured for this cluster and key.
+      # Resolve it like any Igniter::Contract:
+      #
+      #   q = cluster.read_contract(key: :price)
+      #   q.resolve_all
+      #   q.result.value   # => 99
+      def read_contract(key:)
+        ReadQuery.new(cluster: self, key: key)
+      end
+
+      # Status snapshot for every alive node in the cluster.
+      # @return [Array<Hash>] one hash per alive node
+      def status
+        @node_ids.filter_map do |nid|
+          ref = Igniter::Registry.find(nid)
+          next unless ref&.alive?
+          s = ref.state
+          {
+            node_id:      s[:node_id],
+            role:         s[:role],
+            term:         s[:term],
+            commit_index: s[:commit_index],
+            log_size:     s[:log].size,
+            state_machine: s[:state_machine],
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/consensus/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Consensus
+    # Base class for all consensus errors.
+    class Error < Igniter::Error; end
+
+    # Raised when no leader is available — cluster may be electing or lacks quorum.
+    class NoLeaderError < Error; end
+
+    # Raised when the cluster loses quorum mid-operation.
+    class QuorumLostError < Error; end
+  end
+end

data/lib/igniter/consensus/executors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Consensus
+    # Finds the current leader in a Cluster.
+    # Raises +Igniter::ResolutionError+ if no leader is available —
+    # the Resolver will enrich the error with graph/node context.
+    class FindLeader < Igniter::Executor
+      def call(cluster:)
+        ref = cluster.leader
+        raise Igniter::ResolutionError, "No leader in cluster — retry later" unless ref
+        s = ref.state
+        { ref: ref, term: s[:term], node_id: s[:node_id] }
+      end
+    end
+
+    # Reads a single key from the leader's committed state machine.
+    class ReadValue < Igniter::Executor
+      def call(leader:, key:)
+        leader[:ref].state[:state_machine][key]
+      end
+    end
+
+    # Submits an arbitrary command to the consensus log and returns the command.
+    # Useful for fan-out patterns (e.g., multiple parallel writes in a Contract).
+    #
+    # Receives +cluster:+ plus any additional named keyword arguments; those
+    # extra kwargs become the command body:
+    #
+    #   compute :write1, with: [:cluster, :cmd1], call: SubmitCommand
+    #
+    # The executor forwards +:cluster+ as the Cluster ref and treats all other
+    # keyword arguments as the command payload.
+    class SubmitCommand < Igniter::Executor
+      def call(cluster:, **command_kwargs)
+        ref = cluster.leader
+        raise Igniter::ResolutionError, "No leader — cannot submit command" unless ref
+        ref.send(:client_write, command: command_kwargs)
+        command_kwargs
+      end
+    end
+  end
+end

data/lib/igniter/consensus/node.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Consensus
+    # Value objects for sync-reply handlers.
+    # Must be non-Hash so the Agent runner sends them as replies rather than
+    # treating them as new state.
+    NodeStatus = Struct.new(:node_id, :role, :term, :commit_index,
+                            :log_size, :state_machine, :leader, keyword_init: true)
+    NodeReadResult = Struct.new(:data, keyword_init: true)
+
+    # Timing constants — 1:20 heartbeat-to-election ratio for Ruby scheduling jitter.
+    ELECTION_CHECK_INTERVAL = 0.05   # how often to poll for timeout (s)
+    ELECTION_TIMEOUT_BASE   = 1.0    # minimum idle time before election (s)
+    ELECTION_TIMEOUT_JITTER = 0.5    # random addition to prevent split votes (s)
+    HEARTBEAT_INTERVAL      = 0.05   # leader heartbeat cadence (s)
+
+    # Raft consensus agent — internal implementation.
+    # Users should interact with +Cluster+ rather than +Node+ directly.
+    #
+    # The full Raft protocol (leader election, log replication, quorum-based
+    # commit) is encapsulated here. The user-defined state machine is stored in
+    # the agent state as +:state_machine_class+ and invoked on every commit.
+    class Node < Igniter::Agent
+      mailbox_size 2000
+      mailbox_overflow :drop_oldest
+
+      # Convenience factory — builds the correct initial_state automatically.
+      #
+      # @param name          [Symbol]       Registry key for this node
+      # @param peers         [Array<Symbol>] Registry keys of all other nodes
+      # @param state_machine [Class]        StateMachine subclass (default: StateMachine)
+      # @param verbose       [Boolean]      print protocol events to stdout
+      def self.start(name:, peers:, state_machine: StateMachine, verbose: false)
+        super(
+          name: name,
+          initial_state: {
+            node_id:             name,
+            peers:               peers,
+            state_machine_class: state_machine,
+            verbose:             verbose,
+            role:                :follower,
+            term:                0,
+            voted_for:           nil,
+            log:                 [],
+            commit_index:        -1,
+            last_applied:        -1,
+            votes_received:      [],
+            state_machine:       {},
+            next_index:          {},
+            match_index:         {},
+            current_leader:      nil,
+            last_heartbeat_at:   Process.clock_gettime(Process::CLOCK_MONOTONIC),
+            election_timeout:    ELECTION_TIMEOUT_BASE + rand * ELECTION_TIMEOUT_JITTER,
+          }
+        )
+      end
+
+      # Minimum votes required for a decision in a cluster of +size+ nodes.
+      def self.quorum(size) = (size / 2) + 1
+
+      # ── Internal helpers (called from schedule/on blocks) ────────────────────
+
+      def self.find_peer(id) = Igniter::Registry.find(id)
+
+      def self.log_msg(state, msg)
+        $stdout.puts "  [#{state[:node_id]}] #{msg}" if state[:verbose]
+      end
+
+      # Apply committed log entries to the state machine and return the updated
+      # state_machine hash + last_applied index.
+      def self.apply_entries(sm, last_applied, log, commit_index, sm_class)
+        sm = sm.dup
+        while last_applied < commit_index
+          last_applied += 1
+          cmd = log[last_applied]&.dig(:command)
+          sm = sm_class.call(sm, cmd) if cmd
+        end
+        [sm, last_applied]
+      end
+
+      # ── Timer: election check ──────────────────────────────────────────────
+      schedule :election_check, every: ELECTION_CHECK_INTERVAL do |state:|
+        next state if state[:role] == :leader
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - state[:last_heartbeat_at]
+        next state if elapsed < state[:election_timeout]
+
+        new_term = state[:term] + 1
+        nid      = state[:node_id]
+        lli      = state[:log].size - 1
+        llt      = state[:log].empty? ? -1 : state[:log].last[:term]
+
+        Node.log_msg(state, "timeout #{elapsed.round(2)}s → Candidate term=#{new_term}")
+
+        state[:peers].each do |pid|
+          Node.find_peer(pid)&.send(:request_vote, {
+            term: new_term, candidate_id: nid,
+            last_log_index: lli, last_log_term: llt,
+          })
+        end
+
+        state.merge(
+          role: :candidate, term: new_term,
+          voted_for: nid, votes_received: [nid],
+          last_heartbeat_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+          election_timeout: ELECTION_TIMEOUT_BASE + rand * ELECTION_TIMEOUT_JITTER,
+        )
+      end
+
+      # ── Timer: heartbeat (leader only) ────────────────────────────────────
+      schedule :heartbeat, every: HEARTBEAT_INTERVAL do |state:|
+        next state unless state[:role] == :leader
+
+        state[:peers].each do |pid|
+          peer = Node.find_peer(pid)
+          next unless peer
+
+          mi        = state[:match_index][pid] || -1
+          next_idx  = mi + 1
+          prev_idx  = next_idx - 1
+          prev_term = state[:log][prev_idx]&.dig(:term) || -1
+          entries   = state[:log][next_idx..] || []
+
+          peer.send(:append_entries, {
+            term: state[:term], leader_id: state[:node_id],
+            prev_log_index: prev_idx, prev_log_term: prev_term,
+            entries: entries, leader_commit: state[:commit_index],
+          })
+        end
+
+        state
+      end
+
+      # ── RequestVote ──────────────────────────────────────────────────────
+      on :request_vote do |state:, payload:|
+        msg  = payload
+        base = msg[:term] > state[:term] ?
+          state.merge(term: msg[:term], role: :follower, voted_for: nil) : state
+
+        our_lt = base[:log].empty? ? -1 : base[:log].last[:term]
+        our_li = base[:log].size - 1
+        log_ok = msg[:last_log_term] > our_lt ||
+                 (msg[:last_log_term] == our_lt && msg[:last_log_index] >= our_li)
+
+        can_vote = msg[:term] >= base[:term] && log_ok &&
+                   (base[:voted_for].nil? || base[:voted_for] == msg[:candidate_id])
+
+        sender = Node.find_peer(msg[:candidate_id])
+
+        if can_vote
+          Node.log_msg(state, "votes for #{msg[:candidate_id]} (term #{msg[:term]})")
+          sender&.send(:vote_response, {
+            term: msg[:term], vote_granted: true, voter_id: state[:node_id],
+          })
+          base.merge(
+            voted_for: msg[:candidate_id],
+            last_heartbeat_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+          )
+        else
+          sender&.send(:vote_response, {
+            term: base[:term], vote_granted: false, voter_id: state[:node_id],
+          })
+          base
+        end
+      end
+
+      # ── VoteResponse ────────────────────────────────────────────────────
+      on :vote_response do |state:, payload:|
+        msg = payload
+        next state unless state[:role] == :candidate && msg[:term] == state[:term]
+
+        if msg[:term] > state[:term]
+          next state.merge(role: :follower, term: msg[:term], voted_for: nil)
+        end
+        next state unless msg[:vote_granted]
+
+        votes  = (state[:votes_received] + [msg[:voter_id]]).uniq
+        quorum = Node.quorum(state[:peers].size + 1)  # full cluster = peers + self
+
+        if votes.size >= quorum
+          ni = state[:peers].each_with_object({}) { |p, h| h[p] = state[:log].size }
+          mi = state[:peers].each_with_object({}) { |p, h| h[p] = -1 }
+          Node.log_msg(state, "*** LEADER (term=#{state[:term]}, votes=#{votes.size}/#{state[:peers].size + 1}) ***")
+          state.merge(role: :leader, votes_received: votes,
+                      next_index: ni, match_index: mi)
+        else
+          state.merge(votes_received: votes)
+        end
+      end
+
+      # ── AppendEntries ───────────────────────────────────────────────────
+      on :append_entries do |state:, payload:|
+        msg    = payload
+        sender = Node.find_peer(msg[:leader_id])
+
+        if msg[:term] < state[:term]
+          sender&.send(:append_entries_response, {
+            term: state[:term], success: false,
+            follower_id: state[:node_id], match_index: -1,
+          })
+          next state
+        end
+
+        s = state.merge(
+          term:              [state[:term], msg[:term]].max,
+          role:              :follower,
+          voted_for:         state[:term] == msg[:term] ? state[:voted_for] : nil,
+          current_leader:    msg[:leader_id],
+          last_heartbeat_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+        )
+
+        if msg[:prev_log_index] >= 0
+          ok = s[:log].size > msg[:prev_log_index] &&
+               s[:log][msg[:prev_log_index]]&.dig(:term) == msg[:prev_log_term]
+          unless ok
+            sender&.send(:append_entries_response, {
+              term: s[:term], success: false,
+              follower_id: state[:node_id], match_index: s[:log].size - 1,
+            })
+            next s
+          end
+        end
+
+        new_log    = s[:log].take(msg[:prev_log_index] + 1).concat(msg[:entries])
+        new_commit = [[msg[:leader_commit], new_log.size - 1].min, s[:commit_index]].max
+
+        sm, la = Node.apply_entries(s[:state_machine], s[:last_applied],
+                                    new_log, new_commit, s[:state_machine_class])
+
+        sender&.send(:append_entries_response, {
+          term: s[:term], success: true,
+          follower_id: state[:node_id], match_index: new_log.size - 1,
+        })
+
+        s.merge(log: new_log, commit_index: new_commit,
+                last_applied: la, state_machine: sm)
+      end
+
+      # ── AppendEntriesResponse (leader) ──────────────────────────────────
+      on :append_entries_response do |state:, payload:|
+        msg = payload
+        next state unless state[:role] == :leader
+
+        if msg[:term] > state[:term]
+          next state.merge(role: :follower, term: msg[:term], voted_for: nil)
+        end
+
+        pid    = msg[:follower_id]
+        new_mi = state[:match_index].dup
+        new_ni = state[:next_index].dup
+
+        if msg[:success]
+          new_mi[pid] = [new_mi[pid] || -1, msg[:match_index]].max
+          new_ni[pid] = new_mi[pid] + 1
+        else
+          new_ni[pid] = [(new_ni[pid] || 1) - 1, 0].max
+        end
+
+        new_log    = state[:log]
+        new_commit = state[:commit_index]
+        quorum     = Node.quorum(state[:peers].size + 1)
+
+        ((new_commit + 1)...new_log.size).each do |n|
+          next unless new_log[n][:term] == state[:term]
+          replicated = new_mi.values.count { |m| m >= n } + 1  # +1 for leader
+          new_commit = n if replicated >= quorum
+        end
+
+        sm, la = Node.apply_entries(state[:state_machine], state[:last_applied],
+                                    new_log, new_commit, state[:state_machine_class])
+
+        if new_commit > state[:commit_index]
+          Node.log_msg(state, "committed idx=#{new_commit} → #{sm.inspect}")
+        end
+
+        state.merge(match_index: new_mi, next_index: new_ni,
+                    commit_index: new_commit, last_applied: la, state_machine: sm)
+      end
+
+      # ── client_write — appends to log (leader) or forwards ──────────────
+      on :client_write do |state:, payload:|
+        unless state[:role] == :leader
+          ref = state[:current_leader] && Node.find_peer(state[:current_leader])
+          if ref
+            ref.send(:client_write, payload)
+          else
+            Node.log_msg(state, "no leader known — write dropped")
+          end
+          next state
+        end
+
+        entry   = { term: state[:term], command: payload[:command] }
+        new_log = state[:log] + [entry]
+        Node.log_msg(state, "Leader appends log[#{new_log.size - 1}]: #{payload[:command].inspect}")
+        state.merge(log: new_log)
+      end
+
+      # ── Sync query: status ───────────────────────────────────────────────
+      # Returns NodeStatus (non-Hash) → runner sends as sync reply, NOT new state.
+      on :status do |state:, payload:|
+        NodeStatus.new(
+          node_id:       state[:node_id],
+          role:          state[:role],
+          term:          state[:term],
+          commit_index:  state[:commit_index],
+          log_size:      state[:log].size,
+          state_machine: state[:state_machine],
+          leader:        state[:current_leader],
+        )
+      end
+
+      # ── Sync query: read full state machine snapshot ─────────────────────
+      # Returns NodeReadResult (non-Hash) so the runner sends it as sync reply.
+      on :read do |state:, payload:|
+        NodeReadResult.new(data: state[:state_machine].dup)
+      end
+    end
+  end
+end

data/lib/igniter/consensus/read_query.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Consensus
+    # Built-in single-shot read Contract. Dependency graph: find_leader → read_value.
+    #
+    # Prefer +Cluster#read_contract+ for convenience:
+    #
+    #   q = cluster.read_contract(key: :price)
+    #   q.resolve_all
+    #   q.result.value   # => 99
+    #
+    # Or instantiate directly:
+    #
+    #   q = Igniter::Consensus::ReadQuery.new(cluster: my_cluster, key: :price)
+    #   q.resolve_all
+    #   q.result.value   # => 99
+    class ReadQuery < Igniter::Contract
+      define do
+        input :cluster   # Igniter::Consensus::Cluster
+        input :key       # key to read from the state machine
+
+        compute :leader, with: :cluster,        call: FindLeader
+        compute :value,  with: [:leader, :key], call: ReadValue
+
+        output :value
+      end
+    end
+  end
+end

data/lib/igniter/consensus/state_machine.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Consensus
+    # Base class for user-defined consensus state machines.
+    #
+    # Subclass and declare command handlers with +apply+. Each handler receives
+    # the current state (Hash) and a command Hash and must return the NEW state —
+    # without mutating the original.
+    #
+    #   class PriceStore < Igniter::Consensus::StateMachine
+    #     apply :set    do |state, cmd| state.merge(cmd[:key] => cmd[:value]) end
+    #     apply :delete do |state, cmd| state.reject { |k, _| k == cmd[:key] } end
+    #   end
+    #
+    # Passing no subclass to Cluster uses the default KV protocol:
+    # +{ key:, value: }+ sets a key; +{ key:, op: :delete }+ removes it.
+    class StateMachine
+      class << self
+        # Declare a reducer for a named command type.
+        # The block receives +(state, command)+ and must return the new state Hash.
+        def apply(type, &block)
+          reducers[type.to_sym] = block
+        end
+
+        # @api private
+        def reducers
+          @reducers ||= {}
+        end
+
+        # Apply +command+ to +state+ and return the resulting state.
+        # Dispatches to the registered reducer for +command[:type]+, or falls back
+        # to the built-in KV protocol when no reducer is found.
+        #
+        # @param state   [Hash] current state machine snapshot
+        # @param command [Hash, nil] command to apply
+        # @return [Hash] new state
+        def call(state, command)
+          return state unless command
+
+          type = command[:type]&.to_sym
+          if type && (reducer = reducers[type])
+            reducer.call(state, command)
+          else
+            # Default KV protocol: { key:, value: } → set; { key:, op: :delete } → remove
+            return state unless command.key?(:key)
+
+            if command[:op] == :delete
+              state.reject { |k, _| k == command[:key] }
+            else
+              state.merge(command[:key] => command[:value])
+            end
+          end
+        end
+      end
+    end
+  end
+end