igniter 0.5.1 → 0.5.2

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

@@ -1,306 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Cluster
-    module Mesh
-    require_relative "../replication/capability_query"
-
-    # Thread-safe capability router with a short-lived health cache.
-    #
-    # Resolves the URL to call for a given routing mode:
-    #   - :capability  → round-robin among alive peers that advertise the capability;
-    #                    raises DeferredCapabilityError when no alive peer is found.
-    #   - :pinned      → asserts the named peer is alive and returns its URL;
-    #                    raises IncidentError when the peer is unknown or unreachable.
-    #
-    # Peer pool = static peers (Config#peers) + dynamic peers (Config#peer_registry).
-    # Static peers take precedence when a name appears in both sets.
-    class Router
-      HEALTH_CACHE_TTL = 5 # seconds
-
-      def initialize(config)
-        @config       = config
-        @health_cache = {}
-        @mutex        = Mutex.new
-        @round_robin  = Hash.new(0)
-      end
-
-      # Find an alive peer advertising +capability+.
-      # Returns the peer URL. Raises DeferredCapabilityError when none are alive.
-      def find_peer_for(capability, deferred_result)
-        find_peer_for_query({ all_of: [capability.to_sym] }, deferred_result, round_robin_key: capability.to_sym)
-      end
-
-      # Return a structured explanation of how capability routing would resolve.
-      # Does not mutate round-robin state.
-      def explain_peer_for(capability)
-        explain_peer_for_query({ all_of: [capability.to_sym] }, round_robin_key: capability.to_sym)
-      end
-
-      # Find an alive peer matching a full capability query.
-      # Returns the peer URL. Raises DeferredCapabilityError when none are alive.
-      def find_peer_for_query(query, deferred_result, round_robin_key: nil)
-        normalized = Igniter::Cluster::Replication::CapabilityQuery.normalize(query)
-        candidates = all_matching_peers(normalized).select { |peer| alive?(peer) }
-
-        if candidates.empty?
-          raise DeferredCapabilityError.new(
-            normalized.name || normalized.all_of.first,
-            deferred_result,
-            query: normalized.to_h,
-            explanation: explain_peer_for_query(normalized, round_robin_key: round_robin_key)
-          )
-        end
-
-        url_for_round_robin(round_robin_key || normalized.to_h, top_ranked_candidates(normalized, candidates))
-      end
-
-      # Return a structured explanation of how a full capability query resolves.
-      # Does not mutate round-robin state.
-      def explain_peer_for_query(query, round_robin_key: nil)
-        normalized = Igniter::Cluster::Replication::CapabilityQuery.normalize(query)
-        peers = all_known_peers
-        evaluations = peers.map { |peer| evaluate_peer(normalized, peer) }
-        eligible_evaluations = evaluations.select { |entry| entry[:eligible] }
-        top_tier = top_ranked_candidates(normalized, eligible_evaluations.map { |entry| entry[:peer] })
-        top_tier_names = top_tier.map(&:name)
-        selected_peer, round_robin_index = preview_round_robin_candidate(round_robin_key || normalized.to_h, top_tier)
-
-        {
-          routing_mode: :capability,
-          query: normalized.to_h,
-          peer_count: peers.size,
-          matched_count: evaluations.count { |entry| entry[:matched] },
-          eligible_count: eligible_evaluations.size,
-          top_tier_count: top_tier.size,
-          selected_url: selected_peer&.url,
-          selected_peer: selected_peer&.name,
-          round_robin_index: round_robin_index,
-          peers: evaluations.map do |entry|
-            peer = entry[:peer]
-            {
-              name: peer.name,
-              url: peer.url,
-              matched: entry[:matched],
-              alive: entry[:alive],
-              eligible: entry[:eligible],
-              match_details: entry[:match_details],
-              top_tier: top_tier_names.include?(peer.name),
-              selected: selected_peer&.name == peer.name,
-              ranking_fingerprint: entry[:ranking_fingerprint],
-              reasons: evaluation_reasons(entry, top_tier_names, selected_peer)
-            }
-          end
-        }
-      end
-
-      # Resolve the URL of a pinned peer by name.
-      # Raises IncidentError if the peer is unknown or unreachable.
-      def resolve_pinned(peer_name)
-        peer = find_named_peer(peer_name)
-
-        unless peer
-          raise IncidentError.new(
-            peer_name,
-            "Pinned peer '#{peer_name}' is not registered in Igniter::Cluster::Mesh",
-            context: { routing_trace: explain_pinned(peer_name) }
-          )
-        end
-
-        unless alive?(peer)
-          raise IncidentError.new(
-            peer_name,
-            nil,
-            context: { routing_trace: explain_pinned(peer_name) }
-          )
-        end
-
-        peer.url
-      end
-
-      # Return a structured explanation of pinned routing resolution.
-      def explain_pinned(peer_name)
-        peer = find_named_peer(peer_name)
-
-        {
-          routing_mode: :pinned,
-          peer_name: peer_name.to_s,
-          known: !peer.nil?,
-          selected_url: peer&.url,
-          reachable: peer ? alive?(peer) : false,
-          reasons: pinned_reasons(peer)
-        }
-      end
-
-      # Expire a peer's cached health status (e.g., after a successful or failed request).
-      def invalidate_health!(url)
-        @mutex.synchronize { @health_cache.delete(url) }
-      end
-
-      private
-
-      # Combined static + dynamic peer pool for capability-query lookup.
-      # Static peers take precedence over same-named dynamic peers.
-      def all_matching_peers(query)
-        merge_peers(
-          @config.peers_matching_query(query),
-          @config.peer_registry.peers_matching_query(query)
-        )
-      end
-
-      def all_known_peers
-        merge_peers(@config.peers, @config.peer_registry.all)
-      end
-
-      # Lookup peer by name across static and dynamic pools.
-      def find_named_peer(name)
-        @config.peer_named(name) || @config.peer_registry.peer_named(name)
-      end
-
-      # Merge static and dynamic peer lists; static names win on collision.
-      def merge_peers(static, dynamic)
-        seen = static.each_with_object({}) { |p, h| h[p.name] = true }
-        static + dynamic.reject { |p| seen[p.name] }
-      end
-
-      def url_for_round_robin(capability, candidates)
-        peer, = pick_round_robin_candidate(capability, candidates)
-        peer.url
-      end
-
-      def top_ranked_candidates(query, candidates)
-        return candidates if candidates.empty?
-        return trust_ranked_candidates(candidates) unless query.ordered? || query.decisioned?
-
-        ranked = candidates.sort do |left, right|
-          comparison = query.compare_profiles(left.profile, right.profile)
-          next comparison unless comparison.zero?
-
-          compare_trust_profiles(left.profile, right.profile)
-        end
-        best_fingerprint = routing_fingerprint(query, ranked.first.profile)
-        ranked.select { |peer| routing_fingerprint(query, peer.profile) == best_fingerprint }
-      end
-
-      def evaluate_peer(query, peer)
-        match_details = query.explain_profile(peer.profile)
-        matched = match_details[:matched]
-        alive = matched ? alive?(peer) : nil
-        eligible = matched && alive
-
-        {
-          peer: peer,
-          matched: matched,
-          alive: alive,
-          eligible: eligible,
-          match_details: match_details,
-          ranking_fingerprint: eligible ? routing_fingerprint(query, peer.profile) : nil
-        }
-      end
-
-      def routing_fingerprint(query, profile)
-        Array(query.ranking_fingerprint(profile)) + trust_fingerprint(profile)
-      end
-
-      def trust_ranked_candidates(candidates)
-        ranked = candidates.sort do |left, right|
-          compare_trust_profiles(left.profile, right.profile)
-        end
-        best_fingerprint = trust_fingerprint(ranked.first.profile)
-        ranked.select { |peer| trust_fingerprint(peer.profile) == best_fingerprint }
-      end
-
-      def compare_trust_profiles(left, right)
-        left_fingerprint = trust_fingerprint(left)
-        right_fingerprint = trust_fingerprint(right)
-
-        left_fingerprint <=> right_fingerprint
-      end
-
-      def trust_fingerprint(profile)
-        metadata = profile.metadata || {}
-        identity_trust = metadata.dig(:mesh_trust, :status)
-        attestation_trust = metadata.dig(:mesh_capabilities, :trust, :status)
-        attestation_freshness = metadata.dig(:mesh_capabilities, :freshness_seconds)
-        governance_trust = metadata.dig(:mesh_governance, :trust, :status)
-        governance_freshness = metadata.dig(:mesh_governance, :freshness_seconds)
-        governance_blocked_events = metadata.dig(:mesh_governance, :blocked_events)
-        governance_applied_events = metadata.dig(:mesh_governance, :applied_events)
-
-        [
-          trust_priority(identity_trust, missing_rank: 1, invalid_rank: 2),
-          trust_priority(attestation_trust, missing_rank: 2, invalid_rank: 3),
-          attestation_freshness.nil? ? 1_000_000_000 : attestation_freshness.to_i,
-          trust_priority(governance_trust, missing_rank: 2, invalid_rank: 3),
-          governance_freshness.nil? ? 1_000_000_000 : governance_freshness.to_i,
-          governance_blocked_events.nil? ? 1_000_000_000 : governance_blocked_events.to_i,
-          governance_applied_events.nil? ? 1_000_000_000 : -governance_applied_events.to_i
-        ]
-      end
-
-      def trust_priority(status, missing_rank:, invalid_rank:)
-        case status&.to_sym
-        when :trusted
-          0
-        when nil, :unknown
-          missing_rank
-        else
-          invalid_rank
-        end
-      end
-
-      def evaluation_reasons(entry, top_tier_names, selected_peer)
-        return [:query_mismatch] unless entry[:matched]
-        return [:unreachable] unless entry[:alive]
-        return [:lower_ranked] if entry[:eligible] && !top_tier_names.include?(entry[:peer].name)
-        return [:selected] if selected_peer&.name == entry[:peer].name
-
-        [:not_selected_this_turn]
-      end
-
-      def pick_round_robin_candidate(key, candidates)
-        idx = @mutex.synchronize do
-          i = @round_robin[key] % candidates.size
-          @round_robin[key] = i + 1
-          i
-        end
-        [candidates[idx], idx]
-      end
-
-      def preview_round_robin_candidate(key, candidates)
-        return [nil, nil] if candidates.empty?
-
-        idx = @mutex.synchronize { @round_robin[key] % candidates.size }
-        [candidates[idx], idx]
-      end
-
-      def pinned_reasons(peer)
-        return [:unknown_peer] unless peer
-        return [:unreachable] unless alive?(peer)
-
-        [:selected]
-      end
-
-      def alive?(peer) # rubocop:disable Metrics/MethodLength
-        @mutex.synchronize do
-          entry = @health_cache[peer.url]
-          return entry[:alive] if entry && (Time.now.utc - entry[:checked_at]) < HEALTH_CACHE_TTL
-        end
-
-        alive = begin
-          Igniter::Server::Client.new(peer.url, timeout: 3).health
-          true
-        rescue Igniter::Server::Client::ConnectionError
-          false
-        end
-
-        @mutex.synchronize do
-          @health_cache[peer.url] = { alive: alive, checked_at: Time.now.utc }
-        end
-
-        alive
-      end
-    end
-    end
-  end
-end

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

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Igniter
-  module Cluster
-    module Mesh
-      # A single recorded runtime event for one peer-capability interaction.
-      # Immutable — produced by WorkloadTracker#record.
-      WorkloadSignal = ::Data.define(
-        :peer_name,
-        :capability,
-        :success,
-        :duration_ms,
-        :error_class,
-        :recorded_at
-      ) do
-        def self.build(peer_name:, capability:, success:, duration_ms: nil, error: nil, recorded_at: Time.now.utc.iso8601)
-          new(
-            peer_name:   peer_name.to_s,
-            capability:  capability&.to_sym,
-            success:     success ? true : false,
-            duration_ms: duration_ms&.to_f,
-            error_class: error ? error.class.name : nil,
-            recorded_at: recorded_at.to_s
-          )
-        end
-
-        def failure?
-          !success
-        end
-
-        def to_h
-          {
-            peer_name:   peer_name,
-            capability:  capability,
-            success:     success,
-            duration_ms: duration_ms,
-            error_class: error_class,
-            recorded_at: recorded_at
-          }.compact
-        end
-      end
-    end
-  end
-end

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

@@ -1,215 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Cluster
-    module Mesh
-      # Thread-safe accumulator of runtime workload signals across all peers.
-      #
-      # Each peer-capability pair maintains a sliding window of the most recent
-      # `window_size` WorkloadSignal records. Older signals are dropped when the
-      # window overflows, keeping memory bounded.
-      #
-      # Usage:
-      #   tracker = WorkloadTracker.new(window_size: 100)
-      #   tracker.record("node-a", :database, success: true, duration_ms: 42)
-      #   tracker.record("node-a", :database, success: false, error: e)
-      #
-      #   report = tracker.report_for("node-a")
-      #   report.failure_rate   # => 0.5
-      #   report.degraded?      # => false (threshold is 0.3 by default)
-      #
-      #   tracker.degraded_peers   # => ["node-a"] when any peer exceeds threshold
-      #   tracker.reset_peer!("node-a")  # clear signals for a specific peer
-      class WorkloadTracker
-        DEFAULT_WINDOW_SIZE          = 200
-        DEFAULT_DEGRADED_THRESHOLD   = 0.3   # failure rate above which peer is degraded
-        DEFAULT_OVERLOAD_THRESHOLD_MS = 1000  # avg ms above which peer is overloaded
-
-        attr_reader :window_size, :degraded_threshold, :overload_threshold_ms
-
-        def initialize(window_size: DEFAULT_WINDOW_SIZE,
-                       degraded_threshold: DEFAULT_DEGRADED_THRESHOLD,
-                       overload_threshold_ms: DEFAULT_OVERLOAD_THRESHOLD_MS)
-          @window_size           = window_size
-          @degraded_threshold    = degraded_threshold.to_f
-          @overload_threshold_ms = overload_threshold_ms.to_f
-          @windows               = Hash.new { |h, k| h[k] = [] }
-          @mutex                 = Mutex.new
-        end
-
-        # Record a single workload signal for a peer-capability pair.
-        #
-        # @param peer_name   [String]
-        # @param capability  [Symbol, nil]
-        # @param success     [Boolean]
-        # @param duration_ms [Numeric, nil]
-        # @param error       [Exception, nil]
-        # @return [WorkloadSignal]
-        def record(peer_name, capability = nil, success:, duration_ms: nil, error: nil)
-          signal = WorkloadSignal.build(
-            peer_name:   peer_name,
-            capability:  capability,
-            success:     success,
-            duration_ms: duration_ms,
-            error:       error
-          )
-          @mutex.synchronize do
-            key = window_key(peer_name, capability)
-            window = @windows[key]
-            window << signal
-            window.shift if window.size > @window_size
-          end
-          signal
-        end
-
-        # Compute and return a capacity report for a single peer (all capabilities combined).
-        #
-        # @param peer_name [String]
-        # @return [PeerCapacityReport]
-        def report_for(peer_name)
-          signals   = signals_for_peer(peer_name)
-          caps      = capabilities_seen_for(peer_name)
-          build_report(peer_name, signals, capabilities: caps)
-        end
-
-        # All signals recorded for a peer across all its capabilities.
-        #
-        # @return [Array<WorkloadSignal>]
-        def signals_for_peer(peer_name)
-          @mutex.synchronize do
-            @windows
-              .select { |k, _| k.start_with?("#{peer_name}:") || k == peer_name.to_s }
-              .values.flatten
-          end
-        end
-
-        # Capacity report for a specific peer+capability pair.
-        #
-        # @return [PeerCapacityReport]
-        def report_for_capability(peer_name, capability)
-          key     = window_key(peer_name, capability)
-          signals = @mutex.synchronize { @windows[key].dup }
-          build_report(peer_name, signals, capabilities: [capability&.to_sym].compact)
-        end
-
-        # Aggregated reports for every peer seen so far (snapshot).
-        #
-        # @return [Hash<String, PeerCapacityReport>]
-        def all_reports
-          peer_names = @mutex.synchronize do
-            @windows.keys.map { |k| k.split(":").first }.uniq
-          end
-          peer_names.each_with_object({}) { |name, h| h[name] = report_for(name) }
-        end
-
-        # Peers whose failure_rate exceeds `degraded_threshold`.
-        #
-        # @param threshold [Float, nil]  override for this call
-        # @return [Array<String>]
-        def degraded_peers(threshold: nil)
-          t = (threshold || @degraded_threshold).to_f
-          all_reports.select { |_, r| r.failure_rate >= t }.keys
-        end
-
-        # Peers whose avg_duration_ms exceeds `overload_threshold_ms`.
-        #
-        # @param threshold_ms [Numeric, nil]  override for this call
-        # @return [Array<String>]
-        def overloaded_peers(threshold_ms: nil)
-          t = (threshold_ms || @overload_threshold_ms).to_f
-          all_reports.select { |_, r| r.avg_duration_ms && r.avg_duration_ms >= t }.keys
-        end
-
-        # All peer names with recorded signals.
-        #
-        # @return [Array<String>]
-        def known_peers
-          @mutex.synchronize do
-            @windows.keys.map { |k| k.split(":").first }.uniq
-          end
-        end
-
-        # Clear signals for a specific peer (e.g. after repair).
-        #
-        # @param peer_name [String]
-        # @return [self]
-        def reset_peer!(peer_name)
-          @mutex.synchronize do
-            @windows.reject! { |k, _| k.start_with?("#{peer_name}:") || k == peer_name.to_s }
-          end
-          self
-        end
-
-        # Clear all signals.
-        #
-        # @return [self]
-        def reset!
-          @mutex.synchronize { @windows.clear }
-          self
-        end
-
-        def total_signals
-          @mutex.synchronize { @windows.values.sum(&:size) }
-        end
-
-        # Build the mesh_workload metadata hash for a peer, suitable for merging
-        # into a NodeObservation's metadata. Returns nil if no signals recorded.
-        #
-        # @param peer_name [String]
-        # @return [Hash, nil]
-        def to_metadata_for(peer_name)
-          report = report_for(peer_name)
-          return nil if report.total.zero?
-
-          {
-            mesh_workload: {
-              failure_rate:    report.failure_rate,
-              avg_duration_ms: report.avg_duration_ms,
-              total:           report.total,
-              degraded:        report.degraded?,
-              overloaded:      report.overloaded?
-            }.compact
-          }
-        end
-
-        private
-
-        def window_key(peer_name, capability)
-          capability ? "#{peer_name}:#{capability}" : peer_name.to_s
-        end
-
-        def capabilities_seen_for(peer_name)
-          @mutex.synchronize do
-            @windows
-              .keys
-              .select { |k| k.start_with?("#{peer_name}:") }
-              .map    { |k| k.split(":", 2).last.to_sym }
-          end
-        end
-
-        def build_report(peer_name, signals, capabilities:)
-          total     = signals.size
-          successes = signals.count(&:success)
-          failures  = total - successes
-
-          failure_rate = total.zero? ? 0.0 : failures.to_f / total
-
-          durations    = signals.filter_map(&:duration_ms)
-          avg_ms       = durations.empty? ? nil : durations.sum / durations.size
-
-          PeerCapacityReport.new(
-            peer_name:       peer_name.to_s,
-            total:           total,
-            successes:       successes,
-            failures:        failures,
-            failure_rate:    failure_rate,
-            avg_duration_ms: avg_ms,
-            degraded:        failure_rate >= @degraded_threshold,
-            overloaded:      avg_ms && avg_ms >= @overload_threshold_ms,
-            capabilities:    capabilities
-          )
-        end
-      end
-    end
-  end
-end