igniter 0.5.0 → 0.5.2

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

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class PlanExecutor
+      attr_reader :environment, :incident_executor
+
+      def initialize(environment:)
+        @environment = environment
+        @incident_executor = IncidentExecutor.new(metadata: { scope: :plan_execution })
+      end
+
+      def execute(plan, handler: nil, metadata: {})
+        case plan
+        when RebalancePlan
+          execute_rebalance(plan, handler: handler, metadata: metadata)
+        when OwnershipPlan
+          execute_ownership(plan, handler: handler, metadata: metadata)
+        when LeasePlan
+          execute_lease(plan, handler: handler, metadata: metadata)
+        when FailoverPlan
+          execute_failover(plan, handler: handler, metadata: metadata)
+        when RemediationPlan
+          execute_remediation(plan, handler: handler, metadata: metadata)
+        else
+          raise ArgumentError, "unsupported cluster plan #{plan.class}"
+        end
+      end
+
+      def execute_rebalance(plan, handler: nil, metadata: {})
+        execute_action_plan(
+          plan_kind: :rebalance,
+          plan: plan,
+          actions: plan.moves,
+          handler: handler,
+          metadata: metadata
+        )
+      end
+
+      def execute_ownership(plan, handler: nil, metadata: {})
+        execute_action_plan(
+          plan_kind: :ownership,
+          plan: plan,
+          actions: plan.claims,
+          handler: handler,
+          metadata: metadata
+        )
+      end
+
+      def execute_lease(plan, handler: nil, metadata: {})
+        execute_action_plan(
+          plan_kind: :lease,
+          plan: plan,
+          actions: plan.grants,
+          handler: handler,
+          metadata: metadata
+        )
+      end
+
+      def execute_failover(plan, handler: nil, metadata: {})
+        execute_action_plan(
+          plan_kind: :failover,
+          plan: plan,
+          actions: plan.steps,
+          handler: handler,
+          metadata: metadata
+        )
+      end
+
+      def execute_remediation(plan, handler: nil, metadata: {})
+        report = execute_action_plan(
+          plan_kind: :remediation,
+          plan: plan,
+          actions: plan.steps,
+          handler: handler,
+          metadata: metadata,
+          record_incident: false
+        )
+        persist_remediation_workflow_actions(report)
+        report
+      end
+
+      private
+
+      def execute_action_plan(plan_kind:, plan:, actions:, handler:, metadata:, record_incident: true)
+        action_results = Array(actions).map do |action|
+          resolve_action_result(plan_kind: plan_kind, action: action, handler: handler)
+        end
+
+        status = derive_status(action_results)
+        details = {
+          plan_mode: plan.mode,
+          action_count: action_results.length,
+          cluster_profile: environment.profile.to_h
+        }.merge(metadata)
+        incident_artifacts = incident_artifacts_for(
+          record_incident: record_incident,
+          plan_kind: plan_kind,
+          plan: plan,
+          action_results: action_results,
+          status: status,
+          metadata: metadata
+        )
+
+        report = PlanExecutionReport.new(
+          plan_kind: plan_kind,
+          status: status,
+          plan: plan,
+          action_results: action_results,
+          incident: incident_artifacts.fetch(:incident),
+          recovery_timeline: incident_artifacts.fetch(:recovery_timeline),
+          metadata: details,
+          explanation: DecisionExplanation.new(
+            code: :"#{plan_kind}_execution",
+            message: execution_message(plan_kind, status, action_results.length),
+            metadata: details
+          )
+        )
+        persist_incident_entry(report, details) if record_incident
+        report
+      end
+
+      def resolve_action_result(plan_kind:, action:, handler:)
+        return default_action_result(plan_kind: plan_kind, action: action) if handler.nil?
+
+        resolved = handler.call(plan_kind: plan_kind, action: action, environment: environment)
+        return resolved if resolved.is_a?(PlanActionResult)
+
+        metadata =
+          case resolved
+          when Hash
+            resolved
+          else
+            { handler_result: resolved }
+          end
+
+        PlanActionResult.new(
+          action_type: action_type_for(plan_kind),
+          status: :completed,
+          subject: subject_for(plan_kind, action),
+          metadata: metadata.merge(simulated: false, action: action.to_h),
+          explanation: DecisionExplanation.new(
+            code: :"#{plan_kind}_action_executed",
+            message: execution_action_message(plan_kind, action),
+            metadata: metadata
+          )
+        )
+      rescue StandardError => e
+        PlanActionResult.new(
+          action_type: action_type_for(plan_kind),
+          status: :failed,
+          subject: subject_for(plan_kind, action),
+          metadata: {
+            simulated: false,
+            action: action.to_h,
+            error: {
+              class: e.class.name,
+              message: e.message
+            }
+          },
+          explanation: DecisionExplanation.new(
+            code: :"#{plan_kind}_action_failed",
+            message: "failed to execute #{plan_kind} action",
+            metadata: {
+              error_class: e.class.name
+            }
+          )
+        )
+      end
+
+      def default_action_result(plan_kind:, action:)
+        PlanActionResult.new(
+          action_type: action_type_for(plan_kind),
+          status: action.to_h.empty? ? :skipped : :completed,
+          subject: subject_for(plan_kind, action),
+          metadata: {
+            simulated: true,
+            action: action.to_h
+          },
+          explanation: DecisionExplanation.new(
+            code: :"#{plan_kind}_action_simulated",
+            message: execution_action_message(plan_kind, action),
+            metadata: {
+              simulated: true
+            }
+          )
+        )
+      end
+
+      def action_type_for(plan_kind)
+        :"#{plan_kind}_action"
+      end
+
+      def derive_status(action_results)
+        return :skipped if action_results.empty?
+        return :failed if action_results.any?(&:failed?)
+        return :skipped if action_results.all?(&:skipped?)
+
+        :completed
+      end
+
+      def execution_message(plan_kind, status, count)
+        case status
+        when :completed
+          "executed #{count} #{plan_kind} action(s)"
+        when :failed
+          "failed while executing #{plan_kind} actions"
+        else
+          "no #{plan_kind} actions executed"
+        end
+      end
+
+      def execution_action_message(plan_kind, action)
+        case plan_kind
+        when :rebalance
+          "rebalance #{action.source.name} to #{action.destination.name}"
+        when :ownership
+          "assign #{action.target} to #{action.owner.name}"
+        when :lease
+          "grant lease for #{action.target} to #{action.owner.name}"
+        when :failover
+          "fail over #{action.target} from #{action.source.name} to #{action.destination.name}"
+        when :remediation
+          "run #{action.action} for #{action.incident_kind} on #{action.target}"
+        else
+          "execute #{plan_kind} action"
+        end
+      end
+
+      def subject_for(plan_kind, action)
+        case plan_kind
+        when :rebalance
+          {
+            source: action.source.name,
+            destination: action.destination.name
+          }
+        when :ownership
+          {
+            target: action.target,
+            owner: action.owner.name
+          }
+        when :lease
+          {
+            target: action.target,
+            owner: action.owner.name
+          }
+        when :failover
+          {
+            target: action.target,
+            source: action.source.name,
+            destination: action.destination.name
+          }
+        when :remediation
+          {
+            incident_id: action.incident_id,
+            incident_kind: action.incident_kind,
+            target: action.target,
+            action: action.action
+          }
+        else
+          action.to_h
+        end
+      end
+
+      def incident_artifacts_for(record_incident:, plan_kind:, plan:, action_results:, status:, metadata:)
+        return { incident: nil, recovery_timeline: nil } unless record_incident
+
+        incident_executor.execute(
+          plan_kind: plan_kind,
+          plan: plan,
+          action_results: action_results,
+          status: status,
+          metadata: metadata
+        )
+      end
+
+      def persist_incident_entry(report, details)
+        return report if report.incident.nil?
+
+        environment.incident_registry.record(report, metadata: details)
+        report
+      end
+
+      def persist_remediation_workflow_actions(report)
+        report.action_results.each do |result|
+          subject = result.subject
+          next unless subject.is_a?(Hash) && subject[:incident_id]
+
+          environment.incident_registry.record_action(
+            subject.fetch(:incident_id),
+            kind: remediation_action_kind(result.status),
+            status: result.status,
+            metadata: {
+              remediation_action: subject[:action],
+              remediation_target: subject[:target],
+              action_result: result.to_h
+            }
+          )
+        end
+      end
+
+      def remediation_action_kind(status)
+        case status.to_sym
+        when :completed
+          :remediation_completed
+        when :failed
+          :remediation_failed
+        else
+          :remediation_skipped
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class PolicyAdmission
+      attr_reader :policy
+
+      def initialize(policy:)
+        @policy = policy
+        freeze
+      end
+
+      def admit(request:, route:)
+        policy.admit(request: request, route: route)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class PolicyPlacement
+      attr_reader :policy, :projection_policy, :projection_executor
+
+      def initialize(policy:)
+        @policy = policy
+        @projection_policy = ProjectionPolicy.new(name: :"placement_#{policy.name}")
+        @projection_executor = ProjectionExecutor.new(metadata: { scope: :placement })
+        freeze
+      end
+
+      def place(request:, peers:)
+        projection = build_projection(request: request, peers: peers)
+        selected_peers = projection.candidates
+        PlacementDecision.new(
+          mode: policy.mode_for(request.query),
+          candidates: selected_peers,
+          projection: projection,
+          projection_report: projection_executor.execute(projection, metadata: { policy: policy.to_h }),
+          metadata: {
+            policy: policy.to_h,
+            projection_policy: projection_policy.to_h,
+            query: request.query.to_h,
+            membership_projection: projection.to_h,
+            candidate_peer_views: projection.candidate_views.map(&:to_h),
+            candidate_profiles: selected_peers.map { |peer| peer.profile.to_h }
+          },
+          explanation: policy.explanation_for(query: request.query, candidates: selected_peers)
+        )
+      end
+
+      private
+
+      def build_projection(request:, peers:)
+        selected_peers = policy.select_candidates(query: request.query, peers: peers)
+        stages = projection_policy.project_placement(query: request.query, peers: peers, placement_policy: policy)
+        peer_views = Array(peers).map do |peer|
+          PeerView.new(
+            peer: peer,
+            query: request.query,
+            included: selected_peers.include?(peer),
+            metadata: {
+              source: :peer_registry,
+              policy: policy.to_h
+            }
+          )
+        end
+        candidate_views = peer_views.select(&:included?)
+
+        MembershipProjection.new(
+          mode: policy.mode_for(request.query),
+          query: request.query,
+          peer_views: peer_views,
+          candidate_views: candidate_views,
+          stages: stages,
+          metadata: {
+            source: :peer_registry,
+            policy: policy.to_h,
+            projection_policy: projection_policy.to_h
+          },
+          explanation: policy.explanation_for(query: request.query, candidates: selected_peers)
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class PolicyRouter
+      attr_reader :policy
+
+      def initialize(policy:)
+        @policy = policy
+        @projection_executor = ProjectionExecutor.new(metadata: { scope: :route })
+        freeze
+      end
+
+      def route(request:, placement:)
+        candidates = placement.candidates
+        raise RoutingError, "no peers available for #{request.session_id}" if candidates.empty?
+
+        selected_peer = policy.select_peer(query: request.query, candidates: candidates)
+        raise RoutingError, missing_route_message(request) if selected_peer.nil?
+
+        selected_peer_view = placement.projection&.candidate_views&.find { |view| view.peer == selected_peer }
+
+        Route.new(
+          peer: selected_peer,
+          peer_view: selected_peer_view,
+          projection_report: projection_executor.execute(
+            placement.projection,
+            mode: policy.route_mode_for(request.query),
+            selected_peer_view: selected_peer_view,
+            metadata: { policy: policy.to_h }
+          ),
+          mode: policy.route_mode_for(request.query),
+          metadata: route_metadata(request, placement, candidates, selected_peer, selected_peer_view),
+          explanation: policy.explanation_for(query: request.query, peer: selected_peer)
+        )
+      end
+
+      private
+
+      attr_reader :projection_executor
+
+      def route_metadata(request, placement, candidates, selected_peer, selected_peer_view)
+        {
+          policy: policy.to_h,
+          query: request.query.to_h,
+          candidate_names: candidates.map(&:name),
+          membership_projection: placement.projection&.to_h,
+          projection_report: placement.projection_report&.to_h,
+          route_projection_report: projection_executor.execute(
+            placement.projection,
+            mode: policy.route_mode_for(request.query),
+            selected_peer_view: selected_peer_view,
+            metadata: { policy: policy.to_h }
+          ).to_h,
+          selected_peer_view: selected_peer_view&.to_h,
+          selected_capabilities: selected_peer.capabilities,
+          selected_peer_profile: selected_peer.profile.to_h
+        }
+      end
+
+      def missing_route_message(request)
+        [
+          "no route for #{request.session_id}",
+          "query=#{request.query.to_h.inspect}",
+          "policy=#{policy.to_h.inspect}"
+        ].join(" ")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class Profile
+      NAME_KEYS = %i[transport router admission placement peer_registry incident_registry].freeze
+      SEAM_KEYS = NAME_KEYS.dup.freeze
+
+      attr_reader :application_profile, :cluster_packs, :transport_name, :router_name,
+                  :admission_name, :placement_name, :peer_registry_name, :incident_registry_name,
+                  :transport_seam, :router_seam, :admission_seam, :placement_seam,
+                  :peer_registry_seam, :incident_registry_seam, :route_policy, :admission_policy, :placement_policy,
+                  :topology_policy, :ownership_policy, :lease_policy, :health_policy, :remediation_policy,
+                  :capability_catalog
+
+      def initialize(application_profile:, cluster_packs:, names:, seams:, policies:, capability_catalog:)
+        @application_profile = application_profile
+        @cluster_packs = cluster_packs.dup.freeze
+        @capability_catalog = capability_catalog
+        assign_names!(names)
+        assign_seams!(seams)
+        assign_policies!(policies)
+        freeze
+      end
+
+      def cluster_pack_names
+        cluster_packs.map { |pack| pack.respond_to?(:name) ? pack.name.to_s : pack.inspect }
+      end
+
+      def peers
+        peer_registry_seam.peers
+      end
+
+      def incidents
+        incident_registry_seam.entries
+      end
+
+      def active_incidents
+        incident_registry_seam.active_set
+      end
+
+      def incident_workflows
+        incident_registry_seam.workflows
+      end
+
+      def to_h
+        {
+          application_profile: application_profile.to_h,
+          cluster_packs: cluster_pack_names,
+          transport: transport_name,
+          router: router_name,
+          route_policy: route_policy&.to_h,
+          admission: admission_name,
+          admission_policy: admission_policy&.to_h,
+          placement: placement_name,
+          placement_policy: placement_policy&.to_h,
+          topology_policy: topology_policy&.to_h,
+          ownership_policy: ownership_policy&.to_h,
+          lease_policy: lease_policy&.to_h,
+          health_policy: health_policy&.to_h,
+          remediation_policy: remediation_policy&.to_h,
+          peer_registry: peer_registry_name,
+          incident_registry: incident_registry_name,
+          capability_catalog: capability_catalog.to_h,
+          peers: peers.map(&:to_h),
+          active_incidents: active_incidents.to_h,
+          incident_workflows: incident_workflows.map(&:to_h)
+        }
+      end
+
+      private
+
+      def assign_names!(names)
+        NAME_KEYS.each do |name_key|
+          instance_variable_set("@#{name_key}_name", names.fetch(name_key).to_sym)
+        end
+      end
+
+      def assign_seams!(seams)
+        SEAM_KEYS.each do |seam_key|
+          instance_variable_set("@#{seam_key}_seam", seams.fetch(seam_key))
+        end
+      end
+
+      def assign_policies!(policies)
+        @route_policy = policies[:route]
+        @admission_policy = policies[:admission]
+        @placement_policy = policies[:placement]
+        @topology_policy = policies[:topology]
+        @ownership_policy = policies[:ownership]
+        @lease_policy = policies[:lease]
+        @health_policy = policies[:health]
+        @remediation_policy = policies[:remediation]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class ProjectionExecutor
+      attr_reader :metadata
+
+      def initialize(metadata: {})
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def execute(projection, mode: nil, selected_peer_view: nil, metadata: {})
+        resolved_mode = mode || projection.mode
+
+        ProjectionReport.new(
+          mode: resolved_mode,
+          status: projection.candidate_names.empty? ? :empty : :resolved,
+          projection: projection,
+          selected_peer_view: selected_peer_view,
+          metadata: self.metadata.merge(metadata),
+          explanation: DecisionExplanation.new(
+            code: :projection_report,
+            message: projection_message(resolved_mode, projection, selected_peer_view),
+            metadata: {
+              candidate_names: projection.candidate_names,
+              selected_peer: selected_peer_view&.name
+            }
+          )
+        )
+      end
+
+      private
+
+      def projection_message(mode, projection, selected_peer_view)
+        return "#{mode} projection resolved #{projection.candidate_names.length} candidate peer(s)" if selected_peer_view.nil?
+
+        "#{mode} projection selected #{selected_peer_view.name} from #{projection.candidate_names.length} candidate peer(s)"
+      end
+    end
+  end
+end