igniter 0.5.1 → 0.5.2

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class AdmissionResult
+      attr_reader :code, :metadata, :reason
+
+      def initialize(allowed:, code:, metadata: {}, explanation: nil, reason: nil)
+        @allowed = allowed == true
+        @code = code.to_sym
+        @metadata = metadata.dup.freeze
+        @reason = DecisionExplanation.normalize(
+          reason || explanation,
+          default_code: @code,
+          metadata: @metadata
+        )
+        freeze
+      end
+
+      def self.allowed(code: :allowed, metadata: {}, explanation: nil, reason: nil)
+        new(allowed: true, code: code, metadata: metadata, explanation: explanation, reason: reason)
+      end
+
+      def self.denied(code: :denied, metadata: {}, explanation: nil, reason: nil)
+        new(allowed: false, code: code, metadata: metadata, explanation: explanation, reason: reason)
+      end
+
+      def allowed?
+        @allowed
+      end
+
+      def explanation
+        reason&.message
+      end
+
+      def to_h
+        {
+          allowed: allowed?,
+          code: code,
+          metadata: metadata.dup,
+          reason: reason&.to_h,
+          explanation: explanation
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class CapabilityCatalog
+      def initialize(definitions: [])
+        @definitions = {}
+        Array(definitions).each { |definition| register(definition) }
+      end
+
+      def register(definition)
+        ensure_mutable!
+        normalized = normalize_definition(definition)
+        @definitions[normalized.name] = normalized
+        self
+      end
+
+      def fetch(name)
+        @definitions.fetch(name.to_sym)
+      end
+
+      def capability?(name)
+        @definitions.key?(name.to_sym)
+      end
+
+      def resolve(names)
+        Array(names).filter_map do |name|
+          @definitions[name.to_sym]
+        end
+      end
+
+      def with_traits(traits)
+        required_traits = Array(traits).map(&:to_sym)
+        return [] if required_traits.empty?
+
+        definitions.select do |definition|
+          required_traits.all? { |trait| definition.traits.include?(trait) }
+        end
+      end
+
+      def definitions
+        @definitions.values.sort_by(&:name)
+      end
+
+      def to_h
+        {
+          definitions: definitions.map(&:to_h)
+        }
+      end
+
+      private
+
+      def ensure_mutable!
+        return unless frozen?
+
+        raise FrozenError, "can't modify frozen capability catalog"
+      end
+
+      def normalize_definition(definition)
+        return definition if definition.is_a?(CapabilityDefinition)
+
+        CapabilityDefinition.new(**definition)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class CapabilityDefinition
+      attr_reader :name, :traits, :description, :labels, :metadata
+
+      def initialize(name:, traits: [], description: nil, labels: {}, metadata: {})
+        @name = name.to_sym
+        @traits = Array(traits).map(&:to_sym).uniq.sort.freeze
+        @description = description
+        @labels = normalize_labels(labels)
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def tagged?(name, value = nil)
+        return labels.key?(name.to_sym) if value.nil?
+
+        labels[name.to_sym] == value
+      end
+
+      def to_h
+        {
+          name: name,
+          traits: traits.dup,
+          description: description,
+          labels: labels.dup,
+          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
+    end
+  end
+end

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

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class CapabilityQuery
+      attr_reader :required_capabilities, :required_traits, :required_labels, :preferred_peer,
+                  :preferred_region, :preferred_zone, :metadata, :capability_catalog
+
+      def initialize(required_capabilities: [], required_traits: [], required_labels: {}, preferred_peer: nil,
+                     preferred_region: nil, preferred_zone: nil, metadata: {}, capability_catalog: nil)
+        @required_capabilities = Array(required_capabilities).map(&:to_sym).uniq.sort.freeze
+        @required_traits = Array(required_traits).map(&:to_sym).uniq.sort.freeze
+        @required_labels = normalize_labels(required_labels)
+        @preferred_peer = preferred_peer&.to_sym
+        @preferred_region = preferred_region&.to_s
+        @preferred_zone = preferred_zone&.to_s
+        @metadata = metadata.dup.freeze
+        @capability_catalog = capability_catalog
+        freeze
+      end
+
+      def self.from_routing(routing = nil, capability_catalog: nil, **keyword_routing)
+        routing ||= keyword_routing
+        new(
+          required_capabilities: routing_capabilities(routing),
+          required_traits: routing_traits(routing),
+          required_labels: routing_labels(routing),
+          preferred_peer: routing_peer(routing),
+          preferred_region: routing_region(routing),
+          preferred_zone: routing_zone(routing),
+          metadata: routing_metadata(routing),
+          capability_catalog: capability_catalog
+        )
+      end
+
+      def pinned?
+        !preferred_peer.nil?
+      end
+
+      def empty?
+        !pinned? && !capability_constraints? && !topology_constraints?
+      end
+
+      def routing_mode
+        return :pinned if pinned?
+        return :capability if capability_constraints? || topology_constraints?
+
+        :first_available
+      end
+
+      def capability_constraints?
+        !required_capabilities.empty? || !required_traits.empty?
+      end
+
+      def topology_constraints?
+        !required_labels.empty? || !preferred_region.nil? || !preferred_zone.nil?
+      end
+
+      def matches_peer?(peer, honor_preferred_peer: true, require_capabilities: true)
+        return false if honor_preferred_peer && pinned? && peer.name != preferred_peer
+
+        return false unless matches_topology?(peer)
+        return true unless require_capabilities
+
+        matches_capabilities?(peer)
+      end
+
+      def matches_capabilities?(peer)
+        peer.supports_capabilities?(required_capabilities) &&
+          peer.supports_traits?(required_traits)
+      end
+
+      def matches_topology?(peer)
+        peer.matches_labels?(required_labels) &&
+          peer.matches_region?(preferred_region) &&
+          peer.matches_zone?(preferred_zone)
+      end
+
+      def capability_definitions
+        return [] if capability_catalog.nil?
+
+        capability_catalog.resolve(required_capabilities)
+      end
+
+      def required_trait_definitions
+        return [] if capability_catalog.nil?
+
+        capability_catalog.with_traits(required_traits)
+      end
+
+      def to_h
+        {
+          required_capabilities: required_capabilities.dup,
+          required_capability_definitions: capability_definitions.map(&:to_h),
+          required_traits: required_traits.dup,
+          required_trait_definitions: required_trait_definitions.map(&:to_h),
+          required_labels: required_labels.dup,
+          preferred_peer: preferred_peer,
+          preferred_region: preferred_region,
+          preferred_zone: preferred_zone,
+          metadata: metadata.dup
+        }
+      end
+
+      class << self
+        private
+
+        def routing_capabilities(routing)
+          routing.fetch(:required_capabilities, routing.fetch("required_capabilities", legacy_capabilities(routing)))
+        end
+
+        def routing_traits(routing)
+          routing.fetch(:required_traits, routing.fetch("required_traits", []))
+        end
+
+        def routing_labels(routing)
+          routing.fetch(:required_labels, routing.fetch("required_labels", {}))
+        end
+
+        def routing_peer(routing)
+          routing.fetch(:preferred_peer, routing.fetch("preferred_peer", legacy_peer(routing)))
+        end
+
+        def routing_region(routing)
+          routing.fetch(:preferred_region, routing.fetch("preferred_region", legacy_region(routing)))
+        end
+
+        def routing_zone(routing)
+          routing.fetch(:preferred_zone, routing.fetch("preferred_zone", legacy_zone(routing)))
+        end
+
+        def routing_metadata(routing)
+          routing.fetch(:metadata, routing.fetch("metadata", {}))
+        end
+
+        def legacy_capabilities(routing)
+          routing.fetch(:all_of, routing.fetch("all_of", []))
+        end
+
+        def legacy_peer(routing)
+          routing[:peer] || routing["peer"]
+        end
+
+        def legacy_region(routing)
+          routing[:region] || routing["region"]
+        end
+
+        def legacy_zone(routing)
+          routing[:zone] || routing["zone"]
+        end
+      end
+
+      private
+
+      def normalize_labels(labels)
+        labels.each_with_object({}) do |(key, value), memo|
+          memo[key.to_sym] = value
+        end.freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class CapabilityRouter < PolicyRouter
+      def initialize(policy: RoutePolicy.capability)
+        super(policy: policy)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class ClusterDiagnosticsExecutor
+      attr_reader :metadata
+
+      def initialize(metadata: {})
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def execute_transport(query:, placement:, route:, projection_report:, admission:, metadata: {})
+        resolved_status = admission.fetch(:allowed, false) ? :completed : :failed
+        event_log = build_transport_event_log(
+          placement: placement,
+          route: route,
+          projection_report: projection_report,
+          admission: admission,
+          metadata: metadata
+        )
+        operator_timeline = build_timeline(
+          kind: :transport,
+          status: resolved_status,
+          event_log: event_log,
+          metadata: metadata
+        )
+
+        ClusterDiagnosticsReport.new(
+          kind: :transport,
+          status: resolved_status,
+          query: query,
+          placement: placement,
+          route: route,
+          projection_report: projection_report,
+          admission: admission,
+          event_log: event_log,
+          operator_timeline: operator_timeline,
+          metadata: self.metadata.merge(metadata),
+          explanation: DecisionExplanation.new(
+            code: :transport_diagnostics,
+            message: "transport diagnostics resolved #{route.fetch(:peer)}",
+            metadata: {
+              peer: route.fetch(:peer),
+              route_mode: route.fetch(:mode),
+              placement_mode: placement.fetch(:mode)
+            }
+          )
+        )
+      end
+
+      def execute_mesh(query:, projection_report:, mesh:, status:, metadata: {})
+        event_log = build_mesh_event_log(
+          projection_report: projection_report,
+          mesh: mesh,
+          metadata: metadata
+        )
+        operator_timeline = build_timeline(
+          kind: :mesh,
+          status: status,
+          event_log: event_log,
+          metadata: metadata
+        )
+
+        ClusterDiagnosticsReport.new(
+          kind: :mesh,
+          status: status,
+          query: query,
+          projection_report: projection_report,
+          mesh: mesh,
+          event_log: event_log,
+          operator_timeline: operator_timeline,
+          metadata: self.metadata.merge(metadata),
+          explanation: DecisionExplanation.new(
+            code: :mesh_diagnostics,
+            message: "mesh diagnostics captured #{mesh.fetch(:attempt_count)} attempt(s)",
+            metadata: {
+              trace_id: mesh.fetch(:trace_id),
+              plan_kind: mesh.fetch(:plan_kind),
+              attempt_count: mesh.fetch(:attempt_count)
+            }
+          )
+        )
+      end
+
+      private
+
+      def build_transport_event_log(placement:, route:, projection_report:, admission:, metadata:)
+        ClusterEventLog.new(
+          events: [
+            ClusterEvent.new(
+              kind: :placement,
+              status: :resolved,
+              metadata: {
+                mode: placement.fetch(:mode),
+                candidate_names: placement.fetch(:candidates)
+              }
+            ),
+            ClusterEvent.new(
+              kind: :projection,
+              status: projection_report.fetch(:status),
+              metadata: {
+                mode: projection_report.fetch(:mode),
+                candidate_names: projection_report.fetch(:candidate_names)
+              }
+            ),
+            ClusterEvent.new(
+              kind: :route,
+              status: :resolved,
+              metadata: {
+                peer: route.fetch(:peer),
+                mode: route.fetch(:mode)
+              }
+            ),
+            ClusterEvent.new(
+              kind: :admission,
+              status: admission.fetch(:allowed) ? :allowed : :denied,
+              metadata: {
+                code: admission.fetch(:code),
+                peer: route.fetch(:peer)
+              }
+            )
+          ],
+          metadata: self.metadata.merge(metadata)
+        )
+      end
+
+      def build_mesh_event_log(projection_report:, mesh:, metadata:)
+        attempt_events = Array(mesh[:attempt_statuses]).each_with_index.map do |attempt_status, index|
+          ClusterEvent.new(
+            kind: :mesh_attempt,
+            status: attempt_status,
+            metadata: {
+              sequence: index + 1,
+              plan_kind: mesh.fetch(:plan_kind)
+            }
+          )
+        end
+
+        ClusterEventLog.new(
+          events: [
+            ClusterEvent.new(
+              kind: :projection,
+              status: projection_report.fetch(:status),
+              metadata: {
+                mode: projection_report.fetch(:mode),
+                candidate_names: projection_report.fetch(:candidate_names)
+              }
+            ),
+            *attempt_events,
+            ClusterEvent.new(
+              kind: :mesh,
+              status: mesh.fetch(:attempt_statuses).last || :failed,
+              metadata: {
+                trace_id: mesh.fetch(:trace_id),
+                plan_kind: mesh.fetch(:plan_kind),
+                attempt_count: mesh.fetch(:attempt_count)
+              }
+            )
+          ],
+          metadata: self.metadata.merge(metadata)
+        )
+      end
+
+      def build_timeline(kind:, status:, event_log:, metadata:)
+        OperatorTimeline.new(
+          kind: kind,
+          status: status,
+          event_log: event_log,
+          metadata: self.metadata.merge(metadata),
+          explanation: DecisionExplanation.new(
+            code: :operator_timeline,
+            message: "#{kind} timeline captured #{event_log.event_count} event(s)",
+            metadata: {
+              kind: kind,
+              status: status,
+              event_count: event_log.event_count
+            }
+          )
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class ClusterDiagnosticsReport
+      attr_reader :kind, :status, :query, :placement, :route, :projection_report,
+                  :admission, :mesh, :event_log, :operator_timeline, :metadata, :explanation
+
+      def initialize(kind:, status:, query: nil, placement: nil, route: nil, projection_report: nil,
+                     admission: nil, mesh: nil, event_log: nil, operator_timeline: nil, metadata: {},
+                     explanation: nil)
+        @kind = kind.to_sym
+        @status = status.to_sym
+        @query = query&.dup&.freeze
+        @placement = placement&.dup&.freeze
+        @route = route&.dup&.freeze
+        @projection_report = projection_report&.dup&.freeze
+        @admission = admission&.dup&.freeze
+        @mesh = mesh&.dup&.freeze
+        @event_log = event_log
+        @operator_timeline = operator_timeline
+        @metadata = metadata.dup.freeze
+        @explanation = DecisionExplanation.normalize(
+          explanation,
+          default_code: @status,
+          metadata: @metadata
+        )
+        freeze
+      end
+
+      def to_h
+        {
+          kind: kind,
+          status: status,
+          query: query&.dup,
+          placement: placement&.dup,
+          route: route&.dup,
+          projection_report: projection_report&.dup,
+          admission: admission&.dup,
+          mesh: mesh&.dup,
+          event_log: event_log&.to_h,
+          operator_timeline: operator_timeline&.to_h,
+          metadata: metadata.dup,
+          explanation: explanation&.to_h
+        }.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    class ClusterEvent
+      attr_reader :at, :kind, :status, :metadata, :explanation
+
+      def initialize(kind:, status:, at: Time.now.utc, metadata: {}, explanation: nil)
+        @at = at.utc
+        @kind = kind.to_sym
+        @status = status.to_sym
+        @metadata = metadata.dup.freeze
+        @explanation = DecisionExplanation.normalize(
+          explanation,
+          default_code: @kind,
+          metadata: @metadata
+        )
+        freeze
+      end
+
+      def to_h
+        {
+          at: at.iso8601,
+          kind: kind,
+          status: status,
+          metadata: metadata.dup,
+          explanation: explanation&.to_h
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class ClusterEventLog
+      attr_reader :events, :metadata
+
+      def initialize(events:, metadata: {})
+        @events = Array(events).freeze
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def event_count
+        events.length
+      end
+
+      def to_h
+        {
+          event_count: event_count,
+          events: events.map(&:to_h),
+          metadata: metadata.dup
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class ClusterIncident
+      attr_reader :kind, :status, :severity, :targets, :source_names, :destination_names,
+                  :owner_names, :metadata, :explanation
+
+      def initialize(kind:, status:, severity:, targets: [], source_names: [], destination_names: [], owner_names: [],
+                     metadata: {}, explanation: nil)
+        @kind = kind.to_sym
+        @status = status.to_sym
+        @severity = severity.to_sym
+        @targets = Array(targets).map(&:to_s).freeze
+        @source_names = Array(source_names).map(&:to_sym).freeze
+        @destination_names = Array(destination_names).map(&:to_sym).freeze
+        @owner_names = Array(owner_names).map(&:to_sym).freeze
+        @metadata = metadata.dup.freeze
+        @explanation = DecisionExplanation.normalize(
+          explanation,
+          default_code: @kind,
+          metadata: @metadata
+        )
+        freeze
+      end
+
+      def to_h
+        {
+          kind: kind,
+          status: status,
+          severity: severity,
+          targets: targets.dup,
+          source_names: source_names.dup,
+          destination_names: destination_names.dup,
+          owner_names: owner_names.dup,
+          metadata: metadata.dup,
+          explanation: explanation&.to_h
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class DecisionExplanation
+      attr_reader :code, :message, :metadata
+
+      def initialize(code:, message:, metadata: {})
+        @code = code.to_sym
+        @message = message.to_s
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def self.normalize(value, default_code:, metadata: {})
+        return value if value.is_a?(self)
+        return nil if value.nil?
+
+        new(code: default_code, message: value, metadata: metadata)
+      end
+
+      def to_h
+        {
+          code: code,
+          message: message,
+          metadata: metadata.dup
+        }
+      end
+    end
+  end
+end