igniter 0.4.5 → 0.5.1

data/packages/igniter-cluster/lib/igniter/cluster/identity/node_identity.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "time"
+
+module Igniter
+  module Cluster
+    module Identity
+      class NodeIdentity
+        DEFAULT_ALGORITHM = "rsa-sha256"
+
+        attr_reader :node_id, :algorithm, :created_at
+
+        def self.generate(node_id:, created_at: Time.now.utc.iso8601)
+          key = OpenSSL::PKey::RSA.generate(2048)
+          new(
+            node_id: node_id,
+            public_key_pem: key.public_key.to_pem,
+            private_key_pem: key.to_pem,
+            algorithm: DEFAULT_ALGORITHM,
+            created_at: created_at
+          )
+        end
+
+        def initialize(node_id:, public_key_pem:, private_key_pem:, algorithm: DEFAULT_ALGORITHM, created_at: nil)
+          @node_id = node_id.to_s.freeze
+          @public_key_pem = public_key_pem.to_s.freeze
+          @private_key_pem = private_key_pem.to_s.freeze
+          @algorithm = algorithm.to_s.freeze
+          @created_at = (created_at || Time.now.utc.iso8601).to_s.freeze
+          freeze
+        end
+
+        def sign(payload)
+          encoded = canonical_json(payload)
+          Base64.strict_encode64(private_key.sign(OpenSSL::Digest::SHA256.new, encoded))
+        end
+
+        def verify(payload, signature:)
+          public_key.verify(
+            OpenSSL::Digest::SHA256.new,
+            Base64.strict_decode64(signature.to_s),
+            canonical_json(payload)
+          )
+        rescue OpenSSL::PKey::PKeyError, ArgumentError
+          false
+        end
+
+        def public_key_pem
+          @public_key_pem
+        end
+
+        def private_key_pem
+          @private_key_pem
+        end
+
+        def fingerprint
+          OpenSSL::Digest::SHA256.hexdigest(public_key.to_der)[0, 24]
+        end
+
+        def to_h(include_private: false)
+          payload = {
+            node_id: node_id,
+            algorithm: algorithm,
+            public_key: public_key_pem,
+            fingerprint: fingerprint,
+            created_at: created_at
+          }
+          payload[:private_key] = private_key_pem if include_private
+          payload
+        end
+
+        private
+
+        def public_key
+          OpenSSL::PKey.read(@public_key_pem)
+        end
+
+        def private_key
+          OpenSSL::PKey.read(@private_key_pem)
+        end
+
+        def canonical_json(value)
+          JSON.generate(deep_sort(value))
+        end
+
+        def deep_sort(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.to_s] = deep_sort(nested)
+            end.sort.to_h
+          when Array
+            value.map { |item| deep_sort(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/identity.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "identity/node_identity"
+require_relative "identity/capability_attestation"
+require_relative "identity/manifest"

data/packages/igniter-cluster/lib/igniter/cluster/mesh/announcer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Announces this node's identity to seed nodes at startup and withdraws
+    # the registration on graceful shutdown.
+    #
+    # All network errors are swallowed — a seed being temporarily down must
+    # not prevent the local node from starting. The background Poller will
+    # re-register once the seed recovers.
+    class Announcer
+      def initialize(config)
+        @config = config
+      end
+
+      # POST self-manifest to every configured seed. No-op if peer_name or
+      # local_url are not configured.
+      def announce_all
+        return unless announceable?
+
+        @config.seeds.each { |url| announce_to(url) }
+      end
+
+      # DELETE self from every configured seed. Best-effort — errors are ignored.
+      def deannounce_all
+        return unless @config.peer_name
+
+        @config.seeds.each { |url| deannounce_from(url) }
+      end
+
+      private
+
+      def announceable?
+        @config.peer_name && !@config.peer_name.to_s.strip.empty? &&
+          @config.local_url && !@config.local_url.to_s.strip.empty?
+      end
+
+      def announce_to(seed_url)
+        metadata = PeerMetadata.authoritative(@config.local_metadata, origin: @config.peer_name)
+        checkpoint = @config.governance_checkpoint(limit: 10)
+        metadata = metadata.merge(
+          mesh_governance: {
+            node_id: checkpoint.node_id,
+            peer_name: checkpoint.peer_name,
+            fingerprint: checkpoint.fingerprint,
+            checkpointed_at: checkpoint.checkpointed_at,
+            crest_digest: checkpoint.crest_digest,
+            checkpoint: checkpoint.to_h,
+            trust: Igniter::Cluster::Trust::Verifier.assess_governance_checkpoint(
+              checkpoint,
+              trust_store: @config.trust_store
+            ).to_h
+          }
+        )
+
+        state = @config.local_state
+        metadata = metadata.merge(mesh_state: state) if state && !state.empty?
+
+        locality = @config.local_locality
+        metadata = metadata.merge(mesh_locality: locality) if locality && !locality.empty?
+
+        manifest = Igniter::Cluster::Identity::Manifest.build(
+          identity: @config.ensure_identity!,
+          peer_name: @config.peer_name,
+          url: @config.local_url,
+          capabilities: @config.local_capabilities,
+          tags: @config.local_tags,
+          metadata: metadata,
+          contracts: []
+        )
+
+        Igniter::Server::Client.new(seed_url, timeout: 5).register_peer(
+          manifest: manifest
+        )
+      rescue Igniter::Server::Client::ConnectionError
+        nil
+      end
+
+      def deannounce_from(seed_url)
+        Igniter::Server::Client.new(seed_url, timeout: 5).unregister_peer(@config.peer_name)
+      rescue Igniter::Server::Client::ConnectionError
+        nil
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/mesh/checkpoint_gossip.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Shared helper: accepts a governance checkpoint embedded in a peer's
+      # metadata (received during Poller seed-fetch or GossipRound peer-exchange)
+      # and persists it locally when it is newer than the current local checkpoint.
+      #
+      # Called after every peer registration in both Poller and GossipRound.
+      # No-op when config.checkpoint_store is nil.
+      #
+      # Security: the remote checkpoint's RSA/ECDSA signature is verified before
+      # the checkpoint is accepted. Tampered or unsigned payloads are silently
+      # dropped.
+      #
+      # Governance trail: records :checkpoint_replicated when a newer checkpoint
+      # is saved, allowing operators to audit the replication history.
+      module CheckpointGossip
+        module_function
+
+        # @param peer_metadata [Hash]  symbol-keyed metadata from PeerIdentityEnvelope
+        # @param config        [Mesh::Config]
+        # @param source        [Symbol]  :poller or :gossip (for trail attribution)
+        def sync(peer_metadata, config:, source: :discovery)
+          store = config.checkpoint_store
+          return unless store
+
+          checkpoint_hash = peer_metadata.dig(:mesh_governance, :checkpoint)
+          return unless checkpoint_hash.is_a?(Hash)
+
+          remote_cp = Igniter::Cluster::Governance::Checkpoint.from_h(checkpoint_hash)
+          return unless remote_cp&.verify_signature
+
+          local_cp = store.load
+          if local_cp
+            remote_time = Time.parse(remote_cp.checkpointed_at)
+            local_time  = Time.parse(local_cp.checkpointed_at)
+            return if local_time >= remote_time
+          end
+
+          store.save(remote_cp)
+          config.governance_trail&.record(
+            :checkpoint_replicated,
+            source:  source,
+            payload: {
+              from_peer:       peer_metadata.dig(:mesh_governance, :peer_name),
+              crest_digest:    remote_cp.crest_digest,
+              checkpointed_at: remote_cp.checkpointed_at
+            }
+          )
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/mesh/config.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Configuration for the local mesh node: registered peers and local identity.
+    class Config
+      attr_accessor :peer_name, :local_capabilities, :local_tags, :local_metadata,
+                    :local_state, :local_locality,
+                    :seeds, :discovery_interval, :auto_announce, :local_url, :gossip_fanout,
+                    :identity, :trust_store, :governance_trail, :auto_self_heal,
+                    :self_heal_interval, :self_heal_limit, :self_heal_report_provider,
+                    :ownership_registry, :checkpoint_store,
+                    :knowledge_shard,
+                    :admission_policy, :admission_queue,
+                    :workload_tracker
+      attr_reader   :peers, :peer_registry
+
+      def initialize
+        @peer_name          = nil
+        @local_capabilities = []
+        @local_tags         = []
+        @local_metadata     = {}
+        @local_state        = {}
+        @local_locality     = {}
+        @peers              = []
+        @peer_registry      = PeerRegistry.new
+        @seeds              = []
+        @discovery_interval = 30
+        @auto_announce      = true
+        @local_url          = nil
+        @gossip_fanout      = 3
+        @identity           = nil
+        @trust_store        = Igniter::Cluster::Trust::TrustStore.new
+        @governance_trail   = Igniter::Cluster::Governance::Trail.new
+        @auto_self_heal     = false
+        @self_heal_interval = 15
+        @self_heal_limit    = nil
+        @self_heal_report_provider = nil
+        @ownership_registry = nil
+        @checkpoint_store   = nil
+        @knowledge_shard    = nil
+        @admission_policy   = nil
+        @admission_queue    = nil
+        @workload_tracker   = nil
+        @last_routing_report = nil
+      end
+
+      def ensure_identity!
+        @identity ||= Igniter::Cluster::Identity::NodeIdentity.generate(node_id: @peer_name || "anonymous-node")
+      end
+
+      def governance_log(path, archive: nil, retain_events: nil, retention_policy: nil)
+        @governance_trail = Igniter::Cluster::Governance::Trail.new(
+          store: Igniter::Cluster::Governance::Stores::FileStore.new(
+            path: path,
+            max_events: retain_events,
+            archive_path: archive,
+            retention_policy: retention_policy
+          )
+        )
+        self
+      end
+
+      def reload_governance_trail!
+        return @governance_trail unless @governance_trail&.store
+
+        @governance_trail = Igniter::Cluster::Governance::Trail.new(store: @governance_trail.store)
+      end
+
+      def governance_checkpoint(limit: 10, checkpointed_at: Time.now.utc.iso8601)
+        identity = ensure_identity!
+        Igniter::Cluster::Governance::Checkpoint.build(
+          identity: identity,
+          peer_name: @peer_name || identity.node_id,
+          trail: @governance_trail,
+          limit: limit,
+          checkpointed_at: checkpointed_at
+        )
+      end
+
+      def record_routing_report!(target)
+        @last_routing_report = normalize_routing_report(target)
+      end
+
+      def current_routing_report
+        provided = @self_heal_report_provider&.call
+        report = normalize_routing_report(provided)
+        return report if report
+
+        @last_routing_report
+      rescue StandardError
+        @last_routing_report
+      end
+
+      # Register a remote peer by name.
+      #
+      #   Igniter::Cluster::Mesh.configure do |c|
+      #     c.add_peer "orders-node", url: "http://orders.internal:4567",
+      #                               capabilities: [:orders, :inventory]
+      #   end
+      def add_peer(name, url:, capabilities: [], tags: [], metadata: {})
+        @peers << Peer.new(name: name, url: url, capabilities: capabilities, tags: tags, metadata: metadata)
+        self
+      end
+
+      # All static peers that advertise a given capability.
+      def peers_with_capability(capability)
+        @peers.select { |p| p.capable?(capability) }
+      end
+
+      # All static peers matching a capability query.
+      def peers_matching_query(query)
+        @peers.select { |p| p.matches_query?(query) }
+      end
+
+      # Find a static peer by its registered name. Returns nil if not found.
+      def peer_named(name)
+        @peers.find { |p| p.name == name.to_s }
+      end
+
+      private
+
+      def normalize_routing_report(target)
+        return nil if target.nil?
+
+        report =
+          if target.respond_to?(:diagnostics)
+            target.diagnostics.to_h
+          elsif target.is_a?(Hash)
+            target
+          elsif target.respond_to?(:to_h)
+            target.to_h
+          end
+
+        return nil unless report.is_a?(Hash)
+        return nil unless report.dig(:routing, :plans).is_a?(Array)
+
+        report
+      rescue StandardError
+        nil
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/mesh/discovery.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Orchestrates the full dynamic-discovery lifecycle:
+    #
+    #   1. Announce self to all seeds (POST /v1/mesh/peers).
+    #   2. Immediately poll all seeds for their known peer list (GET /v1/mesh/peers).
+    #   3. Start the background Poller to keep the registry up to date.
+    #
+    # On #stop:
+    #   1. Deannounce self from all seeds (DELETE /v1/mesh/peers/:name), best-effort.
+    #   2. Stop the background Poller.
+    class Discovery
+      def initialize(config)
+        @config    = config
+        @announcer = Announcer.new(config)
+        @poller    = Poller.new(config)
+        @repair_loop = RepairLoop.new(config)
+      end
+
+      def start
+        @announcer.announce_all
+        @poller.poll_once
+        @poller.start
+        @repair_loop.start if @config.auto_self_heal
+        self
+      end
+
+      def stop
+        @announcer.deannounce_all
+        @poller.stop
+        @repair_loop.stop
+        self
+      end
+
+      def running?
+        @poller.running? || @repair_loop.running?
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/mesh/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Raised when a capability-routed remote node has no alive peers.
+    # Inherits from PendingDependencyError so the resolver transitions
+    # the node to :pending (same as await/distributed workflow nodes).
+    class DeferredCapabilityError < Igniter::PendingDependencyError
+      attr_reader :capability, :query, :explanation
+
+      def initialize(capability, deferred_result, message = nil, query: nil, explanation: nil)
+        @capability  = capability
+        @query       = query
+        @explanation = explanation
+        label       = query ? query.inspect : ":#{capability}"
+        super(deferred_result, message || "No alive peer matching capability #{label}")
+      end
+    end
+
+    # Raised when a pinned_to peer is unavailable.
+    # Inherits from ResolutionError so the resolver transitions the node
+    # to :failed and surfaces it as an operational incident requiring
+    # manual intervention.
+    class IncidentError < Igniter::ResolutionError
+      attr_reader :peer_name
+
+      def initialize(peer_name, message = nil, context: {})
+        @peer_name = peer_name
+        super(message || "Pinned peer '#{peer_name}' is unreachable — manual intervention required",
+              context: context)
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/mesh/gossip.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Executes a single peer-to-peer gossip round.
+    #
+    # Picks up to config.gossip_fanout random peers from the local PeerRegistry
+    # (excluding self), fetches their GET /v1/mesh/peers lists, and registers
+    # any newly discovered peers. This decentralises topology exchange: once seeds
+    # bootstrap the registry, peers continue spreading topology information among
+    # themselves even if seeds become unavailable.
+    #
+    # Errors from individual peers are swallowed — a dead peer must not abort
+    # the round for the remaining candidates.
+    class GossipRound
+      def initialize(config)
+        @config = config
+      end
+
+      def run
+        pick_candidates.each { |peer| exchange_with(peer) }
+      end
+
+      private
+
+      def pick_candidates
+        @config.peer_registry.all
+               .reject { |p| p.url == @config.local_url }
+               .sample(@config.gossip_fanout)
+      end
+
+      def exchange_with(peer) # rubocop:disable Metrics/AbcSize
+        peers = Igniter::Server::Client.new(peer.url, timeout: 5).list_peers
+        peers.each do |pd|
+          attributes = PeerIdentityEnvelope.build(
+            source: pd,
+            trust_store: @config.trust_store,
+            relayed_by: peer.name
+          )
+          next if attributes[:name].nil? || attributes[:url].nil?
+          next if attributes[:name] == @config.peer_name
+
+          @config.peer_registry.register(
+            Peer.new(
+              name: attributes[:name],
+              url: attributes[:url],
+              capabilities: attributes[:capabilities] || [],
+              tags: attributes[:tags] || [],
+              metadata: attributes[:metadata] || {}
+            )
+          )
+
+          CheckpointGossip.sync(attributes[:metadata] || {}, config: @config, source: :gossip)
+        end
+      rescue Igniter::Server::Client::ConnectionError
+        nil
+      end
+    end
+    end
+  end
+end