igniter 0.5.0 → 0.5.2

data/lib/igniter/saga/executor.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Saga
-    # Runs declared compensations for all successfully completed nodes,
-    # in reverse topological order.
-    #
-    # A node is eligible for compensation if:
-    #   1. Its state in the cache is `succeeded?`
-    #   2. A compensation is declared for it, via one of:
-    #      a. Contract-level `compensate :node_name do ... end`  (takes precedence)
-    #      b. Built-in compensation defined on the Igniter::Effect adapter class
-    #
-    # Compensation failures are captured as failed CompensationRecords and
-    # do NOT halt the rollback of other nodes.
-    class Executor
-      def initialize(contract)
-        @contract = contract
-        @graph    = contract.execution.compiled_graph
-        @cache    = contract.execution.cache
-      end
-
-      # @return [Array<CompensationRecord>]
-      def run_compensations
-        eligible_nodes_reversed.filter_map do |node|
-          compensation = find_compensation(node)
-          next unless compensation
-
-          attempt(compensation, node)
-        end
-      end
-
-      # Find the first node whose state is :failed in the cache.
-      # @return [Symbol, nil]
-      def failed_node_name
-        @cache.to_h.find { |_name, state| state.failed? }&.first
-      end
-
-      private
-
-      # Resolve the compensation to use for a node, if any.
-      #
-      # Contract-level `compensate :node_name` takes precedence over built-in
-      # compensation declared on an Igniter::Effect subclass.
-      #
-      # @return [Igniter::Saga::Compensation, nil]
-      def find_compensation(node)
-        declared = @contract.class.compensations
-        return declared[node.name] if declared.key?(node.name)
-
-        return nil unless node.kind == :effect
-
-        built_in = node.adapter_class.built_in_compensation
-        return nil unless built_in
-
-        Compensation.new(node.name, &built_in)
-      end
-
-      # Nodes that succeeded, in reverse resolution order.
-      def eligible_nodes_reversed
-        @graph.resolution_order
-              .select { |node| @cache.fetch(node.name)&.succeeded? }
-              .reverse
-      end
-
-      def attempt(compensation, node)
-        inputs = extract_inputs(node)
-        value  = @cache.fetch(node.name)&.value
-
-        compensation.run(inputs: inputs, value: value)
-        CompensationRecord.new(node_name: compensation.node_name, success: true)
-      rescue StandardError => e
-        CompensationRecord.new(node_name: compensation.node_name, success: false, error: e)
-      end
-
-      # Gather the resolved values of the node's direct dependencies.
-      def extract_inputs(node)
-        node.dependencies.each_with_object({}) do |dep_name, acc|
-          state = @cache.fetch(dep_name)
-          acc[dep_name.to_sym] = state&.value
-        end
-      end
-    end
-  end
-end

data/lib/igniter/saga/formatter.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Saga
-    # Formats a SagaResult as a human-readable text block.
-    #
-    # Example:
-    #
-    #   Contract: OrderWorkflow
-    #   Status:   FAILED
-    #   Error:    Insufficient funds
-    #   At node:  :charge_card
-    #
-    #   COMPENSATIONS (1):
-    #     [ok]    :reserve_stock
-    #
-    module Formatter
-      class << self
-        def format(result)
-          lines = []
-          lines << "Contract: #{result.contract.class.name}"
-          lines << "Status:   #{result.success? ? "SUCCESS" : "FAILED"}"
-
-          if result.failed?
-            lines << "Error:    #{result.error&.message}"
-            lines << "At node:  :#{result.failed_node}" if result.failed_node
-          end
-
-          append_compensations(result, lines)
-          lines.join("\n")
-        end
-
-        private
-
-        def append_compensations(result, lines)
-          return if result.compensations.empty?
-
-          lines << ""
-          lines << "COMPENSATIONS (#{result.compensations.size}):"
-          result.compensations.each do |rec|
-            tag = rec.success? ? "[ok]   " : "[fail] "
-            lines << "  #{tag} :#{rec.node_name}"
-            lines << "    error: #{rec.error.message}" if rec.failed?
-          end
-        end
-      end
-    end
-  end
-end

data/lib/igniter/saga/result.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Saga
-    # Immutable result of a saga execution (resolve_saga call).
-    #
-    # Attributes:
-    #   contract      — the contract instance that was executed
-    #   error         — Igniter::Error that caused failure (nil on success)
-    #   failed_node   — Symbol name of the first node that failed (nil on success)
-    #   compensations — Array<CompensationRecord> for all attempted compensations
-    class Result
-      attr_reader :contract, :error, :failed_node, :compensations
-
-      def initialize(success:, contract:, error: nil, failed_node: nil, compensations: [])
-        @success       = success
-        @contract      = contract
-        @error         = error
-        @failed_node   = failed_node
-        @compensations = compensations.freeze
-        freeze
-      end
-
-      def success? = @success
-      def failed?  = !@success
-
-      # Human-readable saga report.
-      def explain
-        Formatter.format(self)
-      end
-
-      alias to_s explain
-
-      # Structured (serialisable) representation.
-      def to_h
-        {
-          success: success?,
-          failed_node: failed_node,
-          error: error&.message,
-          compensations: compensations.map do |rec|
-            { node: rec.node_name, success: rec.success?, error: rec.error&.message }
-          end
-        }
-      end
-    end
-  end
-end

data/lib/igniter/saga.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "errors"
-require_relative "saga/compensation"
-require_relative "saga/compensation_record"
-require_relative "saga/formatter"
-require_relative "saga/result"
-require_relative "saga/executor"
-
-module Igniter
-  # Saga pattern — compensating transactions for Igniter contracts.
-  #
-  # When a contract execution fails partway through, the saga system
-  # automatically runs the compensating actions for all previously
-  # SUCCEEDED nodes, in reverse topological order.
-  #
-  # Usage:
-  #
-  #   require "igniter/extensions/saga"
-  #
-  #   class OrderWorkflow < Igniter::Contract
-  #     define do
-  #       input  :order_id
-  #       input  :amount
-  #
-  #       compute :reserve_stock, depends_on: :order_id do |order_id:|
-  #         InventoryService.reserve(order_id)
-  #       end
-  #
-  #       compute :charge_card, depends_on: %i[order_id amount reserve_stock] do |amount:, **|
-  #         raise "Declined" if amount > 1000
-  #         PaymentService.charge(amount)
-  #       end
-  #
-  #       output :charge_card
-  #     end
-  #
-  #     compensate :charge_card do |inputs:, value:|
-  #       PaymentService.refund(value[:charge_id])
-  #     end
-  #
-  #     compensate :reserve_stock do |inputs:, value:|
-  #       InventoryService.release(value[:reservation_id])
-  #     end
-  #   end
-  #
-  #   result = OrderWorkflow.new(order_id: "x1", amount: 1500).resolve_saga
-  #   result.success?            # => false
-  #   result.failed_node         # => :charge_card
-  #   result.compensations.map(&:node_name)  # => [:reserve_stock]
-  #   puts result.explain
-  #
-  module Saga
-    class SagaError < Igniter::Error; end
-  end
-end

data/lib/igniter/server/client.rb

@@ -1,166 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "json"
-require "uri"
-
-module Igniter
-  module Server
-    # HTTP client for calling remote igniter-server nodes.
-    # Uses only stdlib (Net::HTTP + JSON), no external gems required.
-    class Client # rubocop:disable Metrics/ClassLength
-      class Error < Igniter::Server::Error; end
-      class ConnectionError < Error; end
-      class RemoteError < Error; end
-
-      def initialize(base_url, timeout: 30)
-        @base_url = base_url.chomp("/")
-        @timeout  = timeout
-      end
-
-      # Execute a contract on the remote node synchronously.
-      #
-      # Returns a symbolized hash:
-      #   { status: :succeeded, execution_id: "uuid", outputs: { result: 42 } }
-      #   { status: :failed,    execution_id: "uuid", error: { message: "..." } }
-      #   { status: :pending,   execution_id: "uuid", waiting_for: ["event"] }
-      def execute(contract_name, inputs: {})
-        response = post(
-          "/v1/contracts/#{uri_encode(contract_name)}/execute",
-          { inputs: inputs }
-        )
-        symbolize_response(response)
-      end
-
-      # Deliver an event to a pending distributed workflow on the remote node.
-      def deliver_event(contract_name, event:, correlation:, payload: {})
-        response = post(
-          "/v1/contracts/#{uri_encode(contract_name)}/events",
-          { event: event, correlation: correlation, payload: payload }
-        )
-        symbolize_response(response)
-      end
-
-      # Fetch execution status by ID.
-      def status(execution_id)
-        symbolize_response(get("/v1/executions/#{uri_encode(execution_id)}"))
-      end
-
-      # Check remote node health.
-      def health
-        get("/v1/health")
-      end
-
-      # Fetch peer manifest: peer_name, capabilities, contracts, url.
-      def manifest
-        response = get("/v1/manifest")
-        {
-          peer_name: response["peer_name"],
-          capabilities: (response["capabilities"] || []).map(&:to_sym),
-          contracts: response["contracts"] || [],
-          url: response["url"]
-        }
-      end
-
-      # Fetch the list of all peers known to the remote node.
-      # Returns an Array of hashes with :name, :url, :capabilities (Array<Symbol>).
-      def list_peers
-        Array(get("/v1/mesh/peers")).map do |p|
-          {
-            name: p["name"],
-            url: p["url"],
-            capabilities: Array(p["capabilities"]).map(&:to_sym)
-          }
-        end
-      end
-
-      # Register this node as a peer on the remote node.
-      def register_peer(name:, url:, capabilities: [])
-        post("/v1/mesh/peers",
-             { "name" => name, "url" => url, "capabilities" => capabilities.map(&:to_s) })
-      end
-
-      # Remove a peer registration from the remote node. Best-effort.
-      def unregister_peer(name)
-        delete_request("/v1/mesh/peers/#{uri_encode(name)}")
-      end
-
-      private
-
-      def post(path, body)
-        uri  = build_uri(path)
-        http = build_http(uri)
-        req  = Net::HTTP::Post.new(uri.path, json_headers)
-        req.body = JSON.generate(body)
-        parse_response(http.request(req))
-      rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
-        raise ConnectionError, "Cannot connect to #{@base_url}: #{e.message}"
-      end
-
-      def get(path)
-        uri  = build_uri(path)
-        http = build_http(uri)
-        req  = Net::HTTP::Get.new(uri.path, json_headers)
-        parse_response(http.request(req))
-      rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
-        raise ConnectionError, "Cannot connect to #{@base_url}: #{e.message}"
-      end
-
-      def delete_request(path)
-        uri  = build_uri(path)
-        http = build_http(uri)
-        req  = Net::HTTP::Delete.new(uri.path, json_headers)
-        parse_response(http.request(req))
-      rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
-        raise ConnectionError, "Cannot connect to #{@base_url}: #{e.message}"
-      end
-
-      def build_uri(path)
-        URI.parse("#{@base_url}#{path}")
-      end
-
-      def build_http(uri)
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl      = uri.scheme == "https"
-        http.read_timeout = @timeout
-        http.open_timeout = 10
-        http
-      end
-
-      def json_headers
-        { "Content-Type" => "application/json", "Accept" => "application/json" }
-      end
-
-      def parse_response(response)
-        body = begin
-          JSON.parse(response.body.to_s)
-        rescue JSON::ParserError
-          {}
-        end
-        raise RemoteError, "Remote error #{response.code}: #{body["error"]}" unless response.is_a?(Net::HTTPSuccess)
-
-        body
-      end
-
-      def symbolize_response(hash)
-        {
-          status: hash["status"]&.to_sym,
-          execution_id: hash["execution_id"],
-          outputs: symbolize_keys(hash["outputs"] || {}),
-          waiting_for: hash["waiting_for"] || [],
-          error: hash["error"]
-        }
-      end
-
-      def symbolize_keys(hash)
-        return hash unless hash.is_a?(Hash)
-
-        hash.each_with_object({}) { |(k, v), memo| memo[k.to_sym] = v }
-      end
-
-      def uri_encode(str)
-        URI.encode_uri_component(str.to_s)
-      end
-    end
-  end
-end

data/lib/igniter/server/config.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Server
-    class Config
-      attr_accessor :host, :port, :store, :logger,
-                    :metrics_collector, :log_format, :drain_timeout,
-                    :peer_name, :peer_capabilities
-      attr_reader   :registry
-
-      def initialize
-        @host              = "0.0.0.0"
-        @port              = 4567
-        @store             = Igniter::Runtime::Stores::MemoryStore.new
-        @registry          = Registry.new
-        @logger            = nil
-        @metrics_collector = nil
-        @log_format        = :text
-        @drain_timeout     = 30
-        @peer_name         = nil
-        @peer_capabilities = []
-      end
-
-      def register(name, contract_class)
-        @registry.register(name, contract_class)
-        self
-      end
-
-      def contracts=(hash)
-        hash.each { |name, klass| register(name.to_s, klass) }
-      end
-    end
-  end
-end

data/lib/igniter/server/handlers/base.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Igniter
-  module Server
-    module Handlers
-      class Base
-        def initialize(registry, store)
-          @registry = registry
-          @store    = store
-        end
-
-        def call(params:, body:)
-          handle(params: params, body: body)
-        rescue Igniter::Server::Registry::RegistryError => e
-          json_error(e.message, status: 404)
-        rescue Igniter::Error => e
-          json_error(e.message, status: 422)
-        rescue StandardError => e
-          json_error("Internal server error: #{e.message}", status: 500)
-        end
-
-        private
-
-        def handle(params:, body:)
-          raise NotImplementedError, "#{self.class}#handle must be implemented"
-        end
-
-        def json_ok(data)
-          { status: 200, body: JSON.generate(data), headers: json_ct }
-        end
-
-        def json_error(message, status: 422)
-          { status: status, body: JSON.generate({ error: message }), headers: json_ct }
-        end
-
-        def json_ct
-          { "Content-Type" => "application/json" }
-        end
-
-        # Serialize a contract execution result into the standard API response hash.
-        # Reads the cache directly to avoid calling contract.pending?/failed? which
-        # internally re-invoke resolve_all and would re-raise on failed nodes.
-        def serialize_execution(contract, contract_class) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-          execution_id = contract.execution.events.execution_id
-          cache_values = contract.execution.cache.values
-
-          if cache_values.any?(&:pending?)
-            pending_nodes = cache_values.select(&:pending?)
-            waiting_for   = pending_nodes.filter_map { |s| s.value.payload[:event]&.to_s }
-            { execution_id: execution_id, status: "pending", waiting_for: waiting_for }
-          elsif cache_values.any?(&:failed?)
-            error_state = cache_values.find(&:failed?)
-            { execution_id: execution_id, status: "failed",
-              error: serialize_error(error_state&.error) }
-          else
-            outputs = serialize_outputs(contract, contract_class)
-            { execution_id: execution_id, status: "succeeded", outputs: outputs }
-          end
-        end
-
-        def serialize_outputs(contract, contract_class)
-          contract_class.compiled_graph.outputs.each_with_object({}) do |output, memo|
-            memo[output.name] = to_json_value(contract.result.public_send(output.name))
-          rescue StandardError
-            nil
-          end
-        end
-
-        def serialize_error(error)
-          return { message: "Unknown error" } unless error
-
-          {
-            type: error.class.name,
-            message: error.message,
-            node: error.context[:node_name]
-          }
-        end
-
-        # Recursively convert a value into JSON-safe primitives.
-        def to_json_value(value) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
-          case value
-          when Hash
-            value.each_with_object({}) { |(k, v), h| h[k.to_s] = to_json_value(v) }
-          when Array
-            value.map { |v| to_json_value(v) }
-          when String, Integer, Float, TrueClass, FalseClass, NilClass
-            value
-          when Symbol
-            value.to_s
-          else
-            value.respond_to?(:to_h) ? to_json_value(value.to_h) : value.to_s
-          end
-        end
-
-        def symbolize_inputs(hash)
-          return {} unless hash.is_a?(Hash)
-
-          hash.each_with_object({}) { |(k, v), memo| memo[k.to_sym] = v }
-        end
-      end
-    end
-  end
-end

data/lib/igniter/server/handlers/contracts_handler.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Server
-    module Handlers
-      class ContractsHandler < Base
-        private
-
-        def handle(params:, body:) # rubocop:disable Lint/UnusedMethodArgument
-          json_ok(@registry.introspect)
-        end
-      end
-    end
-  end
-end

data/lib/igniter/server/handlers/event_handler.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Server
-    module Handlers
-      class EventHandler < Base
-        def initialize(registry, store, collector: nil) # rubocop:disable Lint/UnusedMethodArgument
-          super(registry, store)
-        end
-
-        private
-
-        def handle(params:, body:) # rubocop:disable Metrics/MethodLength
-          contract_class = @registry.fetch(params[:name])
-          event       = body["event"]&.to_sym
-          correlation = symbolize_inputs(body["correlation"] || {})
-          payload     = body["payload"] || {}
-
-          raise Igniter::Error, "event name is required" unless event
-
-          contract = contract_class.deliver_event(event,
-                                                  correlation: correlation,
-                                                  payload: payload,
-                                                  store: @store)
-          contract.resolve_all unless contract.success? || contract.failed?
-
-          json_ok(serialize_execution(contract, contract_class))
-        end
-      end
-    end
-  end
-end

data/lib/igniter/server/handlers/execute_handler.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Server
-    module Handlers
-      class ExecuteHandler < Base
-        def initialize(registry, store, collector: nil)
-          super(registry, store)
-          @collector = collector
-        end
-
-        private
-
-        def handle(params:, body:)
-          contract_class = @registry.fetch(params[:name])
-          inputs = symbolize_inputs(body["inputs"] || {})
-          contract = run_contract(contract_class, inputs)
-          json_ok(serialize_execution(contract, contract_class))
-        end
-
-        def run_contract(contract_class, inputs) # rubocop:disable Metrics/MethodLength
-          if use_distributed_start?(contract_class)
-            contract_class.start(inputs, store: @store)
-          else
-            contract = contract_class.new(inputs)
-            contract.execution.events.subscribe(@collector) if @collector
-            begin
-              contract.resolve_all
-            rescue Igniter::Error
-              nil # failed state is already written to cache; serialize_execution handles it
-            end
-            contract
-          end
-        end
-
-        # Use .start for contracts that declare correlate_by (distributed workflows).
-        def use_distributed_start?(contract_class)
-          contract_class.respond_to?(:correlation_keys) && !contract_class.correlation_keys.empty?
-        end
-      end
-    end
-  end
-end

data/lib/igniter/server/handlers/health_handler.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Server
-    module Handlers
-      class HealthHandler < Base
-        def initialize(registry, store, node_url: nil)
-          super(registry, store)
-          @node_url = node_url
-        end
-
-        private
-
-        def handle(params:, body:) # rubocop:disable Lint/UnusedMethodArgument,Metrics/MethodLength
-          pending_count = begin
-            @store.list_pending.size
-          rescue StandardError
-            0
-          end
-
-          json_ok({
-                    status: "ok",
-                    node: @node_url,
-                    contracts: @registry.names,
-                    store: @store.class.name.split("::").last,
-                    pending: pending_count
-                  })
-        end
-      end
-    end
-  end
-end

data/lib/igniter/server/handlers/liveness_handler.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Server
-    module Handlers
-      # GET /v1/live — Kubernetes liveness probe.
-      #
-      # Returns 200 as long as the process is running. This endpoint should
-      # NEVER return a non-200 status unless the process is truly broken (e.g.
-      # deadlocked). A failing liveness probe causes K8s to restart the pod.
-      class LivenessHandler < Base
-        private
-
-        def handle(params:, body:) # rubocop:disable Lint/UnusedMethodArgument
-          json_ok({ status: "alive", pid: Process.pid })
-        end
-      end
-    end
-  end
-end