igniter 0.5.0 → 0.5.1

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Igniter
+  module Cluster
+    module Events
+      Envelope = Struct.new(
+        :event_id,
+        :topic,
+        :type,
+        :source,
+        :entity_type,
+        :entity_id,
+        :payload,
+        :metadata,
+        :timestamp,
+        keyword_init: true
+      ) do
+        def self.build(type:, source:, topic: nil, entity_type: nil, entity_id: nil, payload: {}, metadata: {}, timestamp: nil, event_id: nil)
+          new(
+            event_id: event_id || SecureRandom.uuid,
+            topic: normalize_topic(topic || type),
+            type: type.to_s,
+            source: source.to_s,
+            entity_type: entity_type&.to_s,
+            entity_id: entity_id&.to_s,
+            payload: stringify_keys(payload),
+            metadata: stringify_keys(metadata),
+            timestamp: timestamp || Time.now.utc
+          )
+        end
+
+        def self.from_h(data)
+          build(
+            event_id: value_from(data, :event_id),
+            topic: value_from(data, :topic),
+            type: value_from(data, :type),
+            source: value_from(data, :source),
+            entity_type: value_from(data, :entity_type),
+            entity_id: value_from(data, :entity_id),
+            payload: value_from(data, :payload) || {},
+            metadata: value_from(data, :metadata) || {},
+            timestamp: parse_timestamp(value_from(data, :timestamp))
+          )
+        end
+
+        def self.from_runtime_event(event, source:, topic: "runtime", metadata: {})
+          build(
+            type: event.type,
+            topic: topic,
+            source: source,
+            entity_type: "execution",
+            entity_id: event.execution_id,
+            payload: event.as_json,
+            metadata: metadata
+          )
+        end
+
+        def to_h
+          {
+            event_id: event_id,
+            topic: topic,
+            type: type,
+            source: source,
+            entity_type: entity_type,
+            entity_id: entity_id,
+            payload: payload,
+            metadata: metadata,
+            timestamp: timestamp
+          }
+        end
+
+        def as_json(*)
+          serialize_value(to_h)
+        end
+
+        private
+
+        def self.value_from(data, key)
+          data[key] || data[key.to_s]
+        end
+
+        def self.normalize_topic(value)
+          value.to_s.strip
+        end
+
+        def self.parse_timestamp(value)
+          case value
+          when Time
+            value
+          when String
+            Time.iso8601(value)
+          else
+            value
+          end
+        end
+
+        def self.stringify_keys(hash)
+          hash.each_with_object({}) do |(key, value), memo|
+            memo[key.to_s] = stringify_nested(value)
+          end
+        end
+
+        def self.stringify_nested(value)
+          case value
+          when Hash
+            stringify_keys(value)
+          when Array
+            value.map { |item| stringify_nested(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+
+        def serialize_value(value)
+          case value
+          when Time
+            value.iso8601
+          when Hash
+            value.each_with_object({}) { |(key, nested), memo| memo[key] = serialize_value(nested) }
+          when Array
+            value.map { |item| serialize_value(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Events
+      module HookSupport
+        private
+
+        def run_before_hooks(hooks, context)
+          hooks.each { |hook| invoke_hook(hook, context) }
+        end
+
+        def run_after_hooks(hooks, context)
+          hooks.each { |hook| invoke_hook(hook, context) }
+        end
+
+        def run_around_hooks(hooks, context, &block)
+          hooks.reverse.reduce(block) do |inner, hook|
+            lambda do
+              invoke_hook(hook, context.merge(proceed: inner))
+            end
+          end.call
+        end
+
+        def invoke_hook(hook, context)
+          hook.call(**context)
+        rescue ArgumentError
+          hook.call(context)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "envelope"
+
+module Igniter
+  module Cluster
+    module Events
+      class Log
+        include HookSupport
+
+        def initialize(store:, collection: "igniter_cluster_events", before_publish: [], after_publish: [], around_publish: [])
+          @store = store
+          @collection = collection.to_s
+          @subscribers = []
+          @before_publish = before_publish.dup
+          @after_publish = after_publish.dup
+          @around_publish = around_publish.dup
+        end
+
+        def publish(type: nil, source:, topic: nil, entity_type: nil, entity_id: nil, payload: {}, metadata: {}, envelope: nil)
+          event = envelope || Envelope.build(
+            type: type,
+            source: source,
+            topic: topic,
+            entity_type: entity_type,
+            entity_id: entity_id,
+            payload: payload,
+            metadata: metadata
+          )
+
+          context = { log: self, event: event, collection: @collection }
+          run_before_hooks(@before_publish, context)
+          result = run_around_hooks(@around_publish, context) { persist_and_notify(event) }
+          run_after_hooks(@after_publish, context.merge(result: result))
+          result
+        end
+
+        def publish_runtime_event(event, source:, topic: "runtime", metadata: {})
+          publish(
+            source: source,
+            envelope: Envelope.from_runtime_event(event, source: source, topic: topic, metadata: metadata)
+          )
+        end
+
+        def all(topic: nil)
+          events = active_store.all(collection: @collection).values.map { |entry| Envelope.from_h(entry) }
+          events = events.select { |event| event.topic == topic.to_s } if topic
+          events.sort_by { |event| [event.timestamp.to_f, event.event_id] }
+        end
+
+        def since(timestamp: nil, event_id: nil, topic: nil)
+          all(topic: topic).select do |event|
+            newer_than_timestamp = timestamp.nil? || event.timestamp > timestamp
+            same_timestamp_but_newer_id = !timestamp.nil? && event.timestamp == timestamp && event.event_id > event_id.to_s
+            newer_than_timestamp || same_timestamp_but_newer_id
+          end
+        end
+
+        def subscribe(subscriber = nil, &block)
+          @subscribers << (subscriber || block)
+        end
+
+        def before_publish(callable = nil, &block)
+          @before_publish << (callable || block)
+          self
+        end
+
+        def after_publish(callable = nil, &block)
+          @after_publish << (callable || block)
+          self
+        end
+
+        def around_publish(callable = nil, &block)
+          @around_publish << (callable || block)
+          self
+        end
+
+        private
+
+        def active_store
+          @store.respond_to?(:call) ? @store.call : @store
+        end
+
+        def persist_and_notify(event)
+          active_store.put(collection: @collection, key: key_for(event), value: event.as_json)
+          @subscribers.each { |subscriber| subscriber.call(event) }
+          event
+        end
+
+        def key_for(event)
+          "#{format_timestamp(event.timestamp)}-#{event.event_id}"
+        end
+
+        def format_timestamp(timestamp)
+          seconds = timestamp.to_i
+          micros = timestamp.usec
+          format("%010d%06d", seconds, micros)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    module Events
+      class ProjectionFeed
+        include HookSupport
+
+        def initialize(name:, log:, projector:, store:, checkpoint_collection: "igniter_cluster_projection_feed_checkpoints",
+                       before_process: [], after_process: [], around_process: [])
+          @name = name.to_s
+          @log = log
+          @projector = projector
+          @store = store
+          @checkpoint_collection = checkpoint_collection.to_s
+          @before_process = before_process.dup
+          @after_process = after_process.dup
+          @around_process = around_process.dup
+        end
+
+        def start!
+          @log.subscribe { |event| process(event) }
+          self
+        end
+
+        def replay!(topic: nil)
+          checkpoint = checkpoint_data
+          events = @log.since(
+            timestamp: checkpoint && Time.iso8601(checkpoint.fetch("timestamp")),
+            event_id: checkpoint && checkpoint.fetch("event_id"),
+            topic: topic
+          )
+          events.each { |event| process(event) }
+          events
+        end
+
+        def process(event)
+          context = { feed: self, event: event, name: @name }
+          run_before_hooks(@before_process, context)
+          result = run_around_hooks(@around_process, context) { project_and_checkpoint(event) }
+          run_after_hooks(@after_process, context.merge(result: result))
+          result
+        end
+
+        def checkpoint
+          checkpoint_data&.dup
+        end
+
+        def before_process(callable = nil, &block)
+          @before_process << (callable || block)
+          self
+        end
+
+        def after_process(callable = nil, &block)
+          @after_process << (callable || block)
+          self
+        end
+
+        def around_process(callable = nil, &block)
+          @around_process << (callable || block)
+          self
+        end
+
+        private
+
+        def active_store
+          @store.respond_to?(:call) ? @store.call : @store
+        end
+
+        def checkpoint_data
+          active_store.get(collection: @checkpoint_collection, key: @name)
+        end
+
+        def write_checkpoint(event)
+          active_store.put(
+            collection: @checkpoint_collection,
+            key: @name,
+            value: {
+              "name" => @name,
+              "event_id" => event.event_id,
+              "timestamp" => event.timestamp.iso8601,
+              "topic" => event.topic,
+              "updated_at" => Time.now.utc.iso8601
+            }
+          )
+        end
+
+        def project_and_checkpoint(event)
+          @projector.call(event)
+          write_checkpoint(event)
+          event
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../projection_store"
+
+module Igniter
+  module Cluster
+    module Events
+      class ReadModelProjector
+        def initialize(store:, collection:, primary_key: "id", transform:)
+          @projection_store = ProjectionStore.new(
+            store: store,
+            collection: collection,
+            primary_key: primary_key
+          )
+          @transform = transform
+        end
+
+        def call(event)
+          result = @transform.call(event)
+          return nil unless result
+
+          if result.is_a?(Array)
+            record, metadata = result
+            @projection_store.project(record, metadata: metadata || {})
+          else
+            @projection_store.project(result)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "events/hook_support"
+require_relative "events/envelope"
+require_relative "events/log"
+require_relative "events/projection_feed"
+require_relative "events/read_model_projector"
+
+module Igniter
+  module Cluster
+    module Events
+      class << self
+        attr_reader :store
+
+        def configure
+          yield self
+        end
+
+        def store=(store)
+          @store = store
+          @log = nil
+        end
+
+        def log_collection=(collection)
+          @log_collection = collection.to_s
+          @log = nil
+        end
+
+        def checkpoint_collection=(collection)
+          @checkpoint_collection = collection.to_s
+        end
+
+        def log
+          @log ||= build_log
+        end
+
+        def build_log(collection: nil)
+          Log.new(
+            store: ensure_store!,
+            collection: collection || @log_collection || "igniter_cluster_events",
+            before_publish: before_publish_hooks.dup,
+            after_publish: after_publish_hooks.dup,
+            around_publish: around_publish_hooks.dup
+          )
+        end
+
+        def build_projection_feed(name:, projector:, log: self.log, store: nil, checkpoint_collection: nil)
+          ProjectionFeed.new(
+            name: name,
+            log: log,
+            projector: projector,
+            store: store || ensure_store!,
+            checkpoint_collection: checkpoint_collection || @checkpoint_collection || "igniter_cluster_projection_feed_checkpoints",
+            before_process: before_process_hooks.dup,
+            after_process: after_process_hooks.dup,
+            around_process: around_process_hooks.dup
+          )
+        end
+
+        def before_publish(callable = nil, &block)
+          before_publish_hooks << (callable || block)
+        end
+
+        def after_publish(callable = nil, &block)
+          after_publish_hooks << (callable || block)
+        end
+
+        def around_publish(callable = nil, &block)
+          around_publish_hooks << (callable || block)
+        end
+
+        def before_process(callable = nil, &block)
+          before_process_hooks << (callable || block)
+        end
+
+        def after_process(callable = nil, &block)
+          after_process_hooks << (callable || block)
+        end
+
+        def around_process(callable = nil, &block)
+          around_process_hooks << (callable || block)
+        end
+
+        def reset!
+          @store = nil
+          @log = nil
+          @log_collection = nil
+          @checkpoint_collection = nil
+          @before_publish_hooks = []
+          @after_publish_hooks = []
+          @around_publish_hooks = []
+          @before_process_hooks = []
+          @after_process_hooks = []
+          @around_process_hooks = []
+        end
+
+        private
+
+        def ensure_store!
+          return @store unless @store.nil?
+
+          raise ArgumentError, "Igniter::Cluster::Events.store is not configured"
+        end
+
+        def before_publish_hooks
+          @before_publish_hooks ||= []
+        end
+
+        def after_publish_hooks
+          @after_publish_hooks ||= []
+        end
+
+        def around_publish_hooks
+          @around_publish_hooks ||= []
+        end
+
+        def before_process_hooks
+          @before_process_hooks ||= []
+        end
+
+        def after_process_hooks
+          @after_process_hooks ||= []
+        end
+
+        def around_process_hooks
+          @around_process_hooks ||= []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    module Governance
+      # Typed result of AdmissionWorkflow#request_admission and related methods.
+      #
+      # Outcomes:
+      #   :admitted         — peer is now in the TrustStore; immediately trusted
+      #   :rejected         — request was refused by policy or operator
+      #   :pending_approval — enqueued; awaits explicit operator approval
+      #   :already_trusted  — peer's node_id was already in the TrustStore
+      AdmissionDecision = ::Data.define(:request, :outcome, :rationale, :decided_at) do
+        def self.build(request:, outcome:, rationale: nil, decided_at: Time.now.utc.iso8601)
+          new(
+            request:    request,
+            outcome:    outcome.to_sym,
+            rationale:  rationale&.to_s,
+            decided_at: decided_at.to_s
+          )
+        end
+
+        def admitted?;        outcome == :admitted;         end
+        def rejected?;        outcome == :rejected;         end
+        def pending_approval?; outcome == :pending_approval; end
+        def already_trusted?; outcome == :already_trusted;  end
+
+        def to_h
+          {
+            request:    request.to_h,
+            outcome:    outcome,
+            rationale:  rationale,
+            decided_at: decided_at
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Governance
+      # Declarative policy that governs how new peer admission requests are evaluated.
+      #
+      # Evaluation order (first match wins):
+      #   1. Peer's node_id already in TrustStore            → :already_trusted
+      #   2. Request carries a forbidden capability           → :rejected
+      #   3. Peer's fingerprint matches a known_key entry     → :admitted (auto)
+      #   4. require_approval: true (default)                 → :pending_approval
+      #   5. require_approval: false                          → :admitted (open)
+      #
+      # Usage:
+      #   policy = AdmissionPolicy.new(
+      #     known_keys:          { "node-a" => "abc123fingerprint" },
+      #     require_approval:    true,
+      #     forbidden_capabilities: [:admin]
+      #   )
+      class AdmissionPolicy
+        attr_reader :known_keys, :require_approval, :forbidden_capabilities, :max_pending_ttl
+
+        # @param known_keys           [Hash<node_id → fingerprint>]  auto-admit these nodes
+        # @param require_approval     [Boolean]  default true — unknown peers queue for approval
+        # @param forbidden_capabilities [Array<Symbol>]  immediate rejection if present
+        # @param max_pending_ttl      [Integer]  seconds before a pending request expires (default 3600)
+        def initialize(known_keys: {}, require_approval: true, forbidden_capabilities: [], max_pending_ttl: 3600)
+          @known_keys             = Hash(known_keys).transform_keys(&:to_s).freeze
+          @require_approval       = require_approval
+          @forbidden_capabilities = Array(forbidden_capabilities).map(&:to_sym).freeze
+          @max_pending_ttl        = max_pending_ttl.to_i
+        end
+
+        # Evaluate the request against this policy given the current TrustStore.
+        #
+        # @param request    [AdmissionRequest]
+        # @param trust_store [Trust::TrustStore]
+        # @return [Symbol]  :admitted | :rejected | :pending_approval | :already_trusted
+        def evaluate(request, trust_store)
+          return :already_trusted if trust_store.known?(request.node_id)
+
+          if forbidden_capabilities.any? { |cap| request.capabilities.include?(cap) }
+            return :rejected
+          end
+
+          expected_fp = known_keys[request.node_id]
+          if expected_fp && expected_fp.to_s == request.fingerprint
+            return :admitted
+          end
+
+          require_approval ? :pending_approval : :admitted
+        end
+
+        def to_h
+          {
+            known_keys:             known_keys,
+            require_approval:       require_approval,
+            forbidden_capabilities: forbidden_capabilities,
+            max_pending_ttl:        max_pending_ttl
+          }
+        end
+      end
+    end
+  end
+end