igniter 0.5.0 → 0.5.2

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class RoutePolicy
+      attr_reader :name, :honor_preferred_peer, :require_capabilities, :allow_first_available, :metadata
+
+      def initialize(name:, honor_preferred_peer: true, require_capabilities: true, allow_first_available: true,
+                     metadata: {})
+        @name = name.to_sym
+        @honor_preferred_peer = honor_preferred_peer == true
+        @require_capabilities = require_capabilities == true
+        @allow_first_available = allow_first_available == true
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def self.capability(metadata: {})
+        new(name: :capability, metadata: metadata)
+      end
+
+      def route_mode_for(query)
+        return :pinned if honor_preferred_peer && query.pinned?
+        return :capability if query.capability_constraints? || query.topology_constraints?
+        return :first_available if allow_first_available
+
+        :unroutable
+      end
+
+      def select_peer(query:, candidates:)
+        Array(candidates).find do |peer|
+          matches_peer?(query, peer)
+        end
+      end
+
+      def explanation_for(query:, peer:)
+        mode = route_mode_for(query)
+
+        case mode
+        when :pinned
+          DecisionExplanation.new(
+            code: :pinned_route,
+            message: "pinned route to #{peer.name}",
+            metadata: {
+              peer: peer.name,
+              preferred_peer: query.preferred_peer,
+              policy: name
+            }
+          )
+        when :capability
+          explanation_code, explanation_message = capability_explanation_for(query, peer)
+          DecisionExplanation.new(
+            code: explanation_code,
+            message: explanation_message,
+            metadata: {
+              peer: peer.name,
+              required_capabilities: query.required_capabilities,
+              required_traits: query.required_traits,
+              required_labels: query.required_labels,
+              preferred_region: query.preferred_region,
+              preferred_zone: query.preferred_zone,
+              policy: name
+            }
+          )
+        else
+          DecisionExplanation.new(
+            code: :first_available_route,
+            message: "first available peer #{peer.name}",
+            metadata: {
+              peer: peer.name,
+              policy: name
+            }
+          )
+        end
+      end
+
+      def to_h
+        {
+          name: name,
+          honor_preferred_peer: honor_preferred_peer,
+          require_capabilities: require_capabilities,
+          allow_first_available: allow_first_available,
+          metadata: metadata.dup
+        }
+      end
+
+      private
+
+      def matches_peer?(query, peer)
+        query.matches_peer?(
+          peer,
+          honor_preferred_peer: honor_preferred_peer,
+          require_capabilities: require_capabilities
+        )
+      end
+
+      def capability_explanation_for(query, peer)
+        return [:capability_route, "capability route to #{peer.name}"] unless query.topology_constraints? || !query.required_traits.empty?
+
+        [:intent_route, "intent route to #{peer.name}"]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class RouteRequest
+      attr_reader :session_id, :kind, :operation_name, :query, :metadata, :profile_fingerprint
+
+      def initialize(attributes)
+        @session_id = attributes.fetch(:session_id).to_s
+        @kind = attributes.fetch(:kind).to_sym
+        @operation_name = attributes.fetch(:operation_name).to_sym
+        @query = attributes.fetch(:query)
+        @metadata = attributes.fetch(:metadata).dup.freeze
+        @profile_fingerprint = attributes.fetch(:profile_fingerprint)
+        freeze
+      end
+
+      def self.from_transport_request(request, capability_catalog: nil)
+        new(attributes_from_transport_request(request, capability_catalog: capability_catalog))
+      end
+
+      def to_h
+        {
+          session_id: session_id,
+          kind: kind,
+          operation_name: operation_name,
+          query: query.to_h,
+          metadata: metadata.dup,
+          profile_fingerprint: profile_fingerprint
+        }
+      end
+
+      def capabilities
+        query.required_capabilities
+      end
+
+      def pinned_peer
+        query.preferred_peer
+      end
+
+      class << self
+        private
+
+        def routing_metadata(request)
+          request.metadata.fetch(:routing, request.metadata.fetch("routing", {}))
+        end
+
+        def attributes_from_transport_request(request, capability_catalog:)
+          {
+            session_id: request.session_id,
+            kind: request.kind,
+            operation_name: request.operation_name,
+            query: CapabilityQuery.from_routing(routing_metadata(request), capability_catalog: capability_catalog),
+            metadata: request.metadata,
+            profile_fingerprint: request.profile_fingerprint
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class TopologyPolicy
+      attr_reader :name, :preferred_region, :preferred_zone, :required_labels,
+                  :max_destinations, :metadata
+
+      def initialize(name:, preferred_region: nil, preferred_zone: nil, required_labels: {}, max_destinations: nil,
+                     metadata: {})
+        @name = name.to_sym
+        @preferred_region = preferred_region&.to_s
+        @preferred_zone = preferred_zone&.to_s
+        @required_labels = normalize_labels(required_labels)
+        @max_destinations = max_destinations.nil? ? nil : Integer(max_destinations)
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def self.locality_aware(metadata: {})
+        new(name: :locality_aware, metadata: metadata)
+      end
+
+      def destinations_for(peers:, query:)
+        limited_destinations(select_destinations(peers, query))
+      end
+
+      def plan(peers:, query:, metadata: {})
+        destinations = destinations_for(peers: peers, query: query)
+        sources = select_sources(peers, destinations)
+
+        if destinations.empty?
+          return RebalancePlan.new(
+            mode: :unsatisfied,
+            moves: [],
+            metadata: plan_metadata(query, sources, destinations, metadata),
+            explanation: DecisionExplanation.new(
+              code: :unsatisfied_topology,
+              message: "no topology-compliant destinations available",
+              metadata: plan_metadata(query, sources, destinations, metadata)
+            )
+          )
+        end
+
+        if sources.empty?
+          return RebalancePlan.new(
+            mode: :stable,
+            moves: [],
+            metadata: plan_metadata(query, sources, destinations, metadata),
+            explanation: DecisionExplanation.new(
+              code: :stable_topology,
+              message: "cluster already satisfies topology policy #{name}",
+              metadata: plan_metadata(query, sources, destinations, metadata)
+            )
+          )
+        end
+
+        moves = build_moves(sources, destinations, query)
+        RebalancePlan.new(
+          mode: :rebalance,
+          moves: moves,
+          metadata: plan_metadata(query, sources, destinations, metadata),
+          explanation: DecisionExplanation.new(
+            code: :topology_rebalance,
+            message: "rebalance #{moves.length} source peer(s) toward #{destinations.length} destination peer(s)",
+            metadata: plan_metadata(query, sources, destinations, metadata)
+          )
+        )
+      end
+
+      def to_h
+        {
+          name: name,
+          preferred_region: preferred_region,
+          preferred_zone: preferred_zone,
+          required_labels: required_labels.dup,
+          max_destinations: max_destinations,
+          metadata: metadata.dup
+        }
+      end
+
+      private
+
+      def normalize_labels(labels)
+        labels.each_with_object({}) do |(key, value), memo|
+          memo[key.to_sym] = value
+        end.freeze
+      end
+
+      def select_destinations(peers, query)
+        effective_query = effective_query_for(query)
+        Array(peers).select do |peer|
+          effective_query.matches_topology?(peer)
+        end
+      end
+
+      def limited_destinations(destinations)
+        return destinations if max_destinations.nil?
+
+        destinations.first(max_destinations)
+      end
+
+      def select_sources(peers, destinations)
+        destination_names = destinations.map(&:name)
+        Array(peers).reject { |peer| destination_names.include?(peer.name) }
+      end
+
+      def build_moves(sources, destinations, query)
+        sources.each_with_index.map do |source, index|
+          destination = destinations[index % destinations.length]
+          RebalanceMove.new(
+            source: source,
+            destination: destination,
+            metadata: {
+              policy: name,
+              query: query.to_h
+            },
+            reason: DecisionExplanation.new(
+              code: :topology_move,
+              message: "move workload from #{source.name} to #{destination.name}",
+              metadata: {
+                source: source.name,
+                destination: destination.name,
+                policy: name
+              }
+            )
+          )
+        end
+      end
+
+      def plan_metadata(query, sources, destinations, extra_metadata)
+        {
+          policy: to_h,
+          query: effective_query_for(query).to_h,
+          source_names: sources.map(&:name),
+          destination_names: destinations.map(&:name)
+        }.merge(extra_metadata)
+      end
+
+      def effective_query_for(query)
+        CapabilityQuery.new(
+          required_capabilities: query.required_capabilities,
+          required_traits: query.required_traits,
+          required_labels: required_labels.merge(query.required_labels),
+          preferred_peer: query.preferred_peer,
+          preferred_region: query.preferred_region || preferred_region,
+          preferred_zone: query.preferred_zone || preferred_zone,
+          metadata: query.metadata,
+          capability_catalog: query.capability_catalog
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class TransportAdapter
+      attr_reader :diagnostics_executor
+
+      def initialize(diagnostics_executor: ClusterDiagnosticsExecutor.new(metadata: { scope: :transport }))
+        @diagnostics_executor = diagnostics_executor
+        freeze
+      end
+
+      def call(route:, request:, placement:, admission:)
+        response = route.peer.transport.call(request: request)
+        ensure_transport_response!(route, response)
+
+        Igniter::Application::TransportResponse.new(
+          result: response.result,
+          metadata: response.metadata.merge(cluster: cluster_metadata(placement, route, admission))
+        )
+      end
+
+      private
+
+      def ensure_transport_response!(route, response)
+        return if response.is_a?(Igniter::Application::TransportResponse)
+
+        raise Error,
+              "cluster transport for #{route.peer.name} must return " \
+              "Igniter::Application::TransportResponse"
+      end
+
+      def cluster_metadata(placement, route, admission)
+        diagnostics_report = diagnostics_executor.execute_transport(
+          query: route.metadata[:query],
+          placement: placement.to_h,
+          route: route.to_h,
+          projection_report: route.projection_report&.to_h || placement.projection_report&.to_h,
+          admission: admission.to_h
+        )
+
+        {
+          query: route.metadata[:query],
+          placement: placement.to_h,
+          route: route.to_h,
+          projection_report: route.projection_report&.to_h || placement.projection_report&.to_h,
+          admission: admission.to_h,
+          diagnostics_report: diagnostics_report.to_h
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "igniter/errors"
+require "igniter/application"
+
+require_relative "cluster/errors"
+require_relative "cluster/capability_definition"
+require_relative "cluster/capability_catalog"
+require_relative "cluster/peer_topology"
+require_relative "cluster/peer_health"
+require_relative "cluster/peer_profile"
+require_relative "cluster/peer"
+require_relative "cluster/peer_view"
+require_relative "cluster/projection_stage"
+require_relative "cluster/projection_policy"
+require_relative "cluster/projection_report"
+require_relative "cluster/projection_executor"
+require_relative "cluster/cluster_diagnostics_report"
+require_relative "cluster/cluster_diagnostics_executor"
+require_relative "cluster/memory_peer_registry"
+require_relative "cluster/capability_query"
+require_relative "cluster/decision_explanation"
+require_relative "cluster/rebalance_move"
+require_relative "cluster/rebalance_plan"
+require_relative "cluster/ownership_claim"
+require_relative "cluster/ownership_plan"
+require_relative "cluster/lease_grant"
+require_relative "cluster/lease_plan"
+require_relative "cluster/failover_step"
+require_relative "cluster/failover_plan"
+require_relative "cluster/remediation_step"
+require_relative "cluster/remediation_plan"
+require_relative "cluster/plan_action_result"
+require_relative "cluster/plan_execution_report"
+require_relative "cluster/plan_executor"
+require_relative "cluster/mesh_execution_request"
+require_relative "cluster/mesh_execution_response"
+require_relative "cluster/mesh_execution_attempt"
+require_relative "cluster/mesh_execution_trace"
+require_relative "cluster/discovery_feed"
+require_relative "cluster/membership_feed"
+require_relative "cluster/membership_delta"
+require_relative "cluster/membership_projection"
+require_relative "cluster/membership_snapshot"
+require_relative "cluster/mesh_membership_event"
+require_relative "cluster/mesh_membership"
+require_relative "cluster/mesh_membership_source"
+require_relative "cluster/registry_membership_source"
+require_relative "cluster/peer_discovery"
+require_relative "cluster/mesh_retry_policy"
+require_relative "cluster/mesh_admission_result"
+require_relative "cluster/mesh_trust_policy"
+require_relative "cluster/mesh_admission"
+require_relative "cluster/mesh_executor"
+require_relative "cluster/route_policy"
+require_relative "cluster/policy_router"
+require_relative "cluster/admission_policy"
+require_relative "cluster/policy_admission"
+require_relative "cluster/placement_policy"
+require_relative "cluster/policy_placement"
+require_relative "cluster/topology_policy"
+require_relative "cluster/ownership_policy"
+require_relative "cluster/lease_policy"
+require_relative "cluster/health_policy"
+require_relative "cluster/remediation_policy"
+require_relative "cluster/capability_router"
+require_relative "cluster/permissive_admission"
+require_relative "cluster/route_request"
+require_relative "cluster/placement_decision"
+require_relative "cluster/direct_placement"
+require_relative "cluster/route"
+require_relative "cluster/admission_result"
+require_relative "cluster/cluster_event"
+require_relative "cluster/cluster_event_log"
+require_relative "cluster/operator_timeline"
+require_relative "cluster/cluster_incident"
+require_relative "cluster/incident_entry"
+require_relative "cluster/incident_action"
+require_relative "cluster/incident_workflow"
+require_relative "cluster/active_incident_set"
+require_relative "cluster/memory_incident_registry"
+require_relative "cluster/recovery_timeline"
+require_relative "cluster/incident_executor"
+require_relative "cluster/transport_adapter"
+require_relative "cluster/kernel_seams"
+require_relative "cluster/kernel"
+require_relative "cluster/profile"
+require_relative "cluster/environment"
+
+module Igniter
+  module Cluster
+    class << self
+      def build_kernel(*packs)
+        kernel = Kernel.new
+        packs.flatten.compact.each { |pack| kernel.install_pack(pack) }
+        kernel
+      end
+
+      def build_profile(*packs)
+        build_kernel(*packs).finalize
+      end
+
+      def with(*packs)
+        Environment.new(profile: build_profile(*packs))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "igniter/cluster"