igniter 0.5.0 → 0.5.2

data/lib/igniter/consensus/cluster.rb

@@ -1,183 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,43 +0,0 @@
-# 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

@@ -1,320 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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

@@ -1,58 +0,0 @@
-# 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