igniter 0.5.1 → 0.5.2

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class IncidentEntry
+      attr_reader :id, :sequence, :incident_key, :plan_kind, :status, :resolution,
+                  :incident, :recovery_timeline, :metadata, :explanation
+
+      def self.from_report(report, sequence:, metadata: {})
+        incident = report.incident
+        raise ArgumentError, "plan execution report does not include incident artifacts" if incident.nil?
+
+        resolution = resolve_resolution(report.recovery_timeline)
+        details = metadata.merge(
+          sequence: sequence,
+          plan_kind: report.plan_kind,
+          report_status: report.status,
+          incident_kind: incident.kind,
+          resolution: resolution
+        )
+
+        new(
+          id: build_id(incident, sequence),
+          sequence: sequence,
+          incident_key: build_incident_key(incident),
+          plan_kind: report.plan_kind,
+          status: report.status,
+          resolution: resolution,
+          incident: incident,
+          recovery_timeline: report.recovery_timeline,
+          metadata: details,
+          explanation: DecisionExplanation.new(
+            code: :incident_entry,
+            message: "recorded #{incident.kind} incident entry",
+            metadata: details
+          )
+        )
+      end
+
+      def self.resolve_resolution(recovery_timeline)
+        recovery_timeline&.event_log&.events&.last&.status&.to_sym || :unknown
+      end
+
+      def self.build_id(incident, sequence)
+        "#{incident.kind}/#{sequence}"
+      end
+
+      def self.build_incident_key(incident)
+        [
+          incident.kind,
+          Array(incident.targets).sort.join(","),
+          Array(incident.source_names).sort.join(","),
+          Array(incident.destination_names).sort.join(","),
+          Array(incident.owner_names).sort.join(",")
+        ].join("|")
+      end
+
+      def initialize(id:, sequence:, incident_key:, plan_kind:, status:, resolution:, incident:, recovery_timeline: nil,
+                     metadata: {}, explanation: nil)
+        @id = id.to_s.freeze
+        @sequence = Integer(sequence)
+        @incident_key = incident_key.to_s.freeze
+        @plan_kind = plan_kind.to_sym
+        @status = status.to_sym
+        @resolution = resolution.to_sym
+        @incident = incident
+        @recovery_timeline = recovery_timeline
+        @metadata = metadata.dup.freeze
+        @explanation = DecisionExplanation.normalize(
+          explanation,
+          default_code: :incident_entry,
+          metadata: @metadata
+        )
+        freeze
+      end
+
+      def active?
+        !%i[recovered stable].include?(resolution)
+      end
+
+      def to_h
+        {
+          id: id,
+          sequence: sequence,
+          incident_key: incident_key,
+          plan_kind: plan_kind,
+          status: status,
+          resolution: resolution,
+          active: active?,
+          incident: incident.to_h,
+          recovery_timeline: recovery_timeline&.to_h,
+          metadata: metadata.dup,
+          explanation: explanation&.to_h
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class IncidentExecutor
+      attr_reader :metadata
+
+      def initialize(metadata: {})
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def execute(plan_kind:, plan:, action_results:, status:, metadata: {})
+        incident = build_incident(plan_kind: plan_kind, plan: plan, status: status, metadata: metadata)
+        recovery_timeline = build_recovery_timeline(
+          incident: incident,
+          plan_kind: plan_kind,
+          action_results: action_results,
+          status: status,
+          metadata: metadata
+        )
+
+        {
+          incident: incident,
+          recovery_timeline: recovery_timeline
+        }
+      end
+
+      private
+
+      def build_incident(plan_kind:, plan:, status:, metadata:)
+        kind = incident_kind_for(plan_kind)
+        details = self.metadata.merge(metadata).merge(
+          plan_kind: plan_kind,
+          plan_mode: plan.mode
+        )
+
+        ClusterIncident.new(
+          kind: kind,
+          status: status,
+          severity: severity_for(kind, status),
+          targets: plan.respond_to?(:targets) ? plan.targets : [],
+          source_names: plan.respond_to?(:source_names) ? plan.source_names : [],
+          destination_names: plan.respond_to?(:destination_names) ? plan.destination_names : [],
+          owner_names: plan.respond_to?(:owner_names) ? plan.owner_names : [],
+          metadata: details,
+          explanation: DecisionExplanation.new(
+            code: :"#{kind}_incident",
+            message: incident_message(kind, status),
+            metadata: details
+          )
+        )
+      end
+
+      def build_recovery_timeline(incident:, plan_kind:, action_results:, status:, metadata:)
+        event_log = ClusterEventLog.new(
+          events: [
+            ClusterEvent.new(
+              kind: :incident_detected,
+              status: incident.status,
+              metadata: {
+                incident: incident.to_h,
+                plan_kind: plan_kind
+              }
+            ),
+            *Array(action_results).map.with_index do |action_result, index|
+              ClusterEvent.new(
+                kind: action_result.action_type,
+                status: action_result.status,
+                metadata: {
+                  sequence: index + 1,
+                  subject: action_result.subject,
+                  explanation: action_result.explanation&.to_h
+                }
+              )
+            end,
+            ClusterEvent.new(
+              kind: :recovery_outcome,
+              status: recovery_status_for(status),
+              metadata: {
+                incident_kind: incident.kind,
+                plan_kind: plan_kind,
+                action_count: Array(action_results).length
+              }
+            )
+          ],
+          metadata: self.metadata.merge(metadata)
+        )
+
+        RecoveryTimeline.new(
+          kind: incident.kind,
+          status: status,
+          event_log: event_log,
+          metadata: self.metadata.merge(metadata),
+          explanation: DecisionExplanation.new(
+            code: :recovery_timeline,
+            message: "recovery timeline captured #{event_log.event_count} event(s) for #{incident.kind}",
+            metadata: {
+              incident_kind: incident.kind,
+              plan_kind: plan_kind,
+              event_count: event_log.event_count
+            }
+          )
+        )
+      end
+
+      def incident_kind_for(plan_kind)
+        case plan_kind.to_sym
+        when :ownership
+          :ownership_shift
+        when :lease
+          :lease
+        when :failover
+          :degraded_health
+        else
+          :rebalance
+        end
+      end
+
+      def severity_for(kind, status)
+        return :critical if status.to_sym == :failed && kind == :degraded_health
+        return :high if kind == :degraded_health
+        return :high if kind == :lease && status.to_sym == :failed
+        return :medium if %i[ownership_shift lease].include?(kind)
+
+        :low
+      end
+
+      def incident_message(kind, status)
+        "#{kind} incident is #{status}"
+      end
+
+      def recovery_status_for(status)
+        case status.to_sym
+        when :completed
+          :recovered
+        when :failed
+          :unresolved
+        else
+          :stable
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class IncidentWorkflow
+      attr_reader :incident_key, :entries, :actions, :metadata, :explanation
+
+      def initialize(incident_key:, entries:, actions:, metadata: {}, explanation: nil)
+        @incident_key = incident_key.to_s.freeze
+        @entries = Array(entries).sort_by(&:sequence).freeze
+        @actions = Array(actions).sort_by(&:sequence).freeze
+        @metadata = metadata.dup.freeze
+        @explanation = DecisionExplanation.normalize(
+          explanation,
+          default_code: :incident_workflow,
+          metadata: @metadata
+        )
+        freeze
+      end
+
+      def latest_entry
+        entries.last
+      end
+
+      def latest_action
+        actions.last
+      end
+
+      def state
+        return latest_action.kind if latest_action
+        return :active if latest_entry&.active?
+
+        :inactive
+      end
+
+      def active?
+        return false if %i[resolved closed].include?(state)
+
+        latest_entry&.active? == true
+      end
+
+      def action_kinds
+        actions.map(&:kind).freeze
+      end
+
+      def to_h
+        {
+          incident_key: incident_key,
+          state: state,
+          active: active?,
+          entry_count: entries.length,
+          action_count: actions.length,
+          latest_entry: latest_entry&.to_h,
+          latest_action: latest_action&.to_h,
+          action_kinds: action_kinds,
+          entries: entries.map(&:to_h),
+          actions: actions.map(&:to_h),
+          metadata: metadata.dup,
+          explanation: explanation&.to_h
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class Kernel
+      include KernelSeams
+
+      attr_reader :application_kernel, :cluster_packs, :transport_seam, :router_seam,
+                  :admission_seam, :placement_seam, :peer_registry_seam, :incident_registry_seam
+
+      def initialize(application_kernel: Igniter::Application.build_kernel)
+        @application_kernel = application_kernel
+        @cluster_packs = []
+        initialize_defaults
+      end
+
+      def install_pack(pack)
+        if pack.respond_to?(:install_into_cluster_kernel)
+          pack.install_into_cluster_kernel(self)
+          @cluster_packs |= [pack]
+        else
+          install_dependent_pack(pack)
+        end
+
+        self
+      end
+
+      def register_peer(name, capabilities:, transport:, metadata: {}, roles: [], labels: {}, region: nil, zone: nil,
+                        health: nil, health_status: :healthy, health_checks: {})
+        peer_registry_seam.register(
+          Peer.new(
+            name: name,
+            capabilities: capabilities,
+            transport: transport,
+            metadata: metadata,
+            roles: roles,
+            labels: labels,
+            region: region,
+            zone: zone,
+            capability_catalog: capability_catalog,
+            health: health,
+            health_status: health_status,
+            health_checks: health_checks
+          )
+        )
+        self
+      end
+
+      def finalize
+        Profile.new(
+          application_profile: application_kernel.finalize,
+          cluster_packs: cluster_packs,
+          names: profile_names,
+          seams: profile_seams,
+          policies: profile_policies,
+          capability_catalog: CapabilityCatalog.new(definitions: capability_catalog.definitions).freeze
+        )
+      end
+
+      private
+
+      def install_dependent_pack(pack)
+        if pack.respond_to?(:install_into_application_kernel) || pack.respond_to?(:install_into)
+          application_kernel.install_pack(pack)
+          return
+        end
+
+        raise ArgumentError,
+              "cluster pack #{pack.inspect} must implement " \
+              "install_into_cluster_kernel, install_into_application_kernel, " \
+              "or install_into"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module KernelSeams
+      def capability(name = nil, definition: nil, **attributes)
+        return capability_catalog.fetch(name) if definition_query?(name, definition, attributes)
+
+        capability_catalog.register(
+          definition || CapabilityDefinition.new(name: name, **attributes)
+        )
+        self
+      end
+
+      def capability_catalog(catalog = nil)
+        return @capability_catalog if catalog.nil?
+
+        @capability_catalog = catalog
+        self
+      end
+
+      def route_policy(name = nil, policy: nil, **attributes)
+        return @route_policy if policy_query?(name, policy, attributes)
+
+        @route_policy = policy || RoutePolicy.new(name: name || :route_policy, **attributes)
+        configure_default_seam(:router, @route_policy.name, PolicyRouter.new(policy: @route_policy))
+        self
+      end
+
+      def admission_policy(name = nil, policy: nil, **attributes)
+        return @admission_policy if policy_query?(name, policy, attributes)
+
+        @admission_policy = policy || AdmissionPolicy.new(name: name || :admission_policy, **attributes)
+        configure_default_seam(:admission, @admission_policy.name, PolicyAdmission.new(policy: @admission_policy))
+        self
+      end
+
+      def placement_policy(name = nil, policy: nil, **attributes)
+        return @placement_policy if policy_query?(name, policy, attributes)
+
+        @placement_policy = policy || PlacementPolicy.new(name: name || :placement_policy, **attributes)
+        configure_default_seam(:placement, @placement_policy.name, PolicyPlacement.new(policy: @placement_policy))
+        self
+      end
+
+      def topology_policy(name = nil, policy: nil, **attributes)
+        return @topology_policy if policy_query?(name, policy, attributes)
+
+        @topology_policy = policy || TopologyPolicy.new(name: name || :topology_policy, **attributes)
+        self
+      end
+
+      def ownership_policy(name = nil, policy: nil, **attributes)
+        return @ownership_policy if policy_query?(name, policy, attributes)
+
+        @ownership_policy = policy || OwnershipPolicy.new(name: name || :ownership_policy, **attributes)
+        self
+      end
+
+      def lease_policy(name = nil, policy: nil, **attributes)
+        return @lease_policy if policy_query?(name, policy, attributes)
+
+        @lease_policy = policy || LeasePolicy.new(name: name || :lease_policy, **attributes)
+        self
+      end
+
+      def health_policy(name = nil, policy: nil, **attributes)
+        return @health_policy if policy_query?(name, policy, attributes)
+
+        @health_policy = policy || HealthPolicy.new(name: name || :health_policy, **attributes)
+        self
+      end
+
+      def remediation_policy(name = nil, policy: nil, **attributes)
+        return @remediation_policy if policy_query?(name, policy, attributes)
+
+        @remediation_policy = policy || RemediationPolicy.new(name: name || :remediation_policy, **attributes)
+        self
+      end
+
+      def transport(name = nil, seam: nil, &block)
+        return @transport_name if seam_query?(name, seam, block)
+
+        configure_named_seam(:transport, name, seam, block, %i[call])
+        self
+      end
+
+      def router(name = nil, seam: nil, &block)
+        return @router_name if seam_query?(name, seam, block)
+
+        configure_named_seam(:router, name, seam, block, %i[route])
+        @route_policy = nil if seam || block
+        self
+      end
+
+      def admission(name = nil, seam: nil, &block)
+        return @admission_name if seam_query?(name, seam, block)
+
+        configure_named_seam(:admission, name, seam, block, %i[admit])
+        @admission_policy = nil if seam || block
+        self
+      end
+
+      def placement(name = nil, seam: nil, &block)
+        return @placement_name if seam_query?(name, seam, block)
+
+        configure_named_seam(:placement, name, seam, block, %i[place])
+        @placement_policy = nil if seam || block
+        self
+      end
+
+      def peer_registry(name = nil, seam: nil, &block)
+        return @peer_registry_name if seam_query?(name, seam, block)
+
+        configure_named_seam(:peer_registry, name, seam, block, %i[register fetch peers])
+        self
+      end
+
+      def incident_registry(name = nil, seam: nil, &block)
+        return @incident_registry_name if seam_query?(name, seam, block)
+
+        configure_named_seam(
+          :incident_registry,
+          name,
+          seam,
+          block,
+          %i[record fetch entries active_set record_action workflow workflows]
+        )
+        self
+      end
+
+      def initialize_defaults
+        @capability_catalog = CapabilityCatalog.new
+        configure_default_seam(:transport, :direct, TransportAdapter.new)
+        @route_policy = RoutePolicy.capability
+        configure_default_seam(:router, @route_policy.name, PolicyRouter.new(policy: @route_policy))
+        @admission_policy = AdmissionPolicy.permissive
+        configure_default_seam(:admission, @admission_policy.name, PolicyAdmission.new(policy: @admission_policy))
+        @placement_policy = PlacementPolicy.direct
+        configure_default_seam(:placement, @placement_policy.name, PolicyPlacement.new(policy: @placement_policy))
+        @topology_policy = TopologyPolicy.locality_aware
+        @ownership_policy = OwnershipPolicy.distributed
+        @lease_policy = LeasePolicy.ephemeral
+        @health_policy = HealthPolicy.availability_aware
+        @remediation_policy = RemediationPolicy.default
+        configure_default_seam(:peer_registry, :memory, MemoryPeerRegistry.new)
+        configure_default_seam(:incident_registry, :memory, MemoryIncidentRegistry.new)
+      end
+
+      def profile_names
+        {
+          transport: transport,
+          router: router,
+          admission: admission,
+          placement: placement,
+          peer_registry: peer_registry,
+          incident_registry: incident_registry
+        }
+      end
+
+      def profile_seams
+        {
+          transport: transport_seam,
+          router: router_seam,
+          admission: admission_seam,
+          placement: placement_seam,
+          peer_registry: peer_registry_seam,
+          incident_registry: incident_registry_seam
+        }
+      end
+
+      def profile_policies
+        {
+          route: @route_policy,
+          admission: @admission_policy,
+          placement: @placement_policy,
+          topology: @topology_policy,
+          ownership: @ownership_policy,
+          lease: @lease_policy,
+          health: @health_policy,
+          remediation: @remediation_policy
+        }
+      end
+
+      private
+
+      def definition_query?(name, definition, attributes)
+        !name.nil? && definition.nil? && attributes.empty?
+      end
+
+      def policy_query?(name, policy, attributes)
+        name.nil? && policy.nil? && attributes.empty?
+      end
+
+      def seam_query?(name, seam, block)
+        name.nil? && seam.nil? && !block
+      end
+
+      def configure_default_seam(type, name, seam)
+        instance_variable_set(seam_name_ivar(type), name)
+        instance_variable_set(seam_object_ivar(type), seam)
+      end
+
+      def configure_named_seam(type, next_name, explicit_seam, block, required_methods)
+        current_seam = instance_variable_get(seam_object_ivar(type))
+        instance_variable_set(seam_name_ivar(type), normalize_seam_name(type, next_name))
+        instance_variable_set(
+          seam_object_ivar(type),
+          resolved_seam(type, explicit_seam, block, current_seam, required_methods)
+        )
+      end
+
+      def normalize_seam_name(type, next_name)
+        current_name = instance_variable_get(seam_name_ivar(type))
+        next_name.nil? ? current_name : next_name.to_sym
+      end
+
+      def seam_name_ivar(type)
+        "@#{type}_name"
+      end
+
+      def seam_object_ivar(type)
+        "@#{type}_seam"
+      end
+
+      def seam_label(type)
+        type.to_s.tr("_", " ")
+      end
+
+      def resolved_seam(type, explicit_seam, block, current_seam, required_methods)
+        resolve_seam(
+          explicit_seam,
+          block,
+          current: current_seam,
+          required_methods: required_methods,
+          label: seam_label(type)
+        )
+      end
+
+      def resolve_seam(explicit_seam, block, current:, required_methods:, label:)
+        resolved = explicit_seam || block || current
+        missing = required_methods.reject { |method_name| resolved.respond_to?(method_name) }
+        return resolved if missing.empty?
+
+        raise ArgumentError, "#{label} seam #{resolved.inspect} must respond to: #{required_methods.join(", ")}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    class LeaseGrant
+      attr_reader :target, :owner, :ttl_seconds, :renewable, :issued_at, :expires_at, :metadata, :reason
+
+      def initialize(target:, owner:, ttl_seconds:, renewable:, issued_at:, expires_at:, metadata: {}, reason: nil)
+        @target = target.to_s
+        @owner = owner
+        @ttl_seconds = Integer(ttl_seconds)
+        @renewable = renewable == true
+        @issued_at = issued_at
+        @expires_at = expires_at
+        @metadata = metadata.dup.freeze
+        @reason = DecisionExplanation.normalize(
+          reason,
+          default_code: :lease_grant,
+          metadata: @metadata
+        )
+        freeze
+      end
+
+      def to_h
+        {
+          target: target,
+          owner: owner.name,
+          ttl_seconds: ttl_seconds,
+          renewable: renewable,
+          issued_at: issued_at.iso8601,
+          expires_at: expires_at.iso8601,
+          metadata: metadata.dup,
+          reason: reason&.to_h
+        }
+      end
+    end
+  end
+end