igniter 0.3.0 → 0.4.0

data/examples/ringcentral_routing.rb

@@ -104,29 +104,26 @@ class CallConnectedContract < Igniter::Contract
       active_calls.any?
     end
 
-    map :call_inputs, from: :active_calls do |active_calls:|
-      active_calls.map do |call|
-        {
-          session_id: call.fetch("telephonySessionId"),
-          direction: call.fetch("direction"),
-          from: call.fetch("from"),
-          to: call.fetch("to"),
-          start_time: call.fetch("startTime")
-        }
-      end
-    end
-
     collection :calls,
-      with: :call_inputs,
+      with: :active_calls,
       each: CallEventContract,
       key: :session_id,
-      mode: :collect
+      mode: :collect,
+      map_inputs: lambda { |item:|
+        {
+          session_id: item.fetch("telephonySessionId"),
+          direction: item.fetch("direction"),
+          from: item.fetch("from"),
+          to: item.fetch("to"),
+          start_time: item.fetch("startTime")
+        }
+      }
 
     compute :call_summaries, with: :calls do |calls:|
       calls.successes.values.map { |item| item.result.summary }
     end
 
-    compute :routing_summary, with: %i[calls call_summaries extension_id telephony_status has_calls] do |calls:, call_summaries:, extension_id:, telephony_status:, has_calls:|
+    aggregate :routing_summary, with: %i[calls call_summaries extension_id telephony_status has_calls] do |calls:, call_summaries:, extension_id:, telephony_status:, has_calls:|
       has_calls
       {
         extension_id: extension_id,
@@ -204,28 +201,22 @@ class RingcentralWebhookContract < Igniter::Contract
     input :payload
 
     scope :parse do
-      map :body, from: :payload do |payload:|
-        payload.fetch("body", {})
-      end
-
-      map :telephony_status, from: :body do |body:|
-        body["telephonyStatus"]
-      end
-
-      map :extension_id, from: :body do |body:|
-        body["extensionId"]
-      end
-
-      map :active_calls, from: :body do |body:|
-        body["activeCalls"] || []
-      end
+      project :body, from: :payload, key: :body, default: {}
+      project :telephony_status, from: :body, key: "telephonyStatus"
+      project :extension_id, from: :body, key: "extensionId"
+      project :active_calls, from: :body, key: "activeCalls", default: []
     end
 
-    branch :status_route, with: :telephony_status, inputs: {
-      extension_id: :extension_id,
-      telephony_status: :telephony_status,
-      active_calls: :active_calls
-    } do
+    branch :status_route,
+      with: :telephony_status,
+      depends_on: %i[extension_id active_calls],
+      map_inputs: lambda { |selector:, extension_id:, active_calls:|
+        {
+          extension_id: extension_id,
+          telephony_status: selector,
+          active_calls: active_calls
+        }
+      } do
       on "CallConnected", contract: CallConnectedContract
       on "NoCall", contract: NoCallContract
       on "Ringing", contract: RingingContract

data/lib/igniter/compiler/compiled_graph.rb

@@ -49,6 +49,10 @@ module Igniter
         raise KeyError, "Unknown dependency '#{name}'"
       end
 
+      def await_nodes
+        @nodes.select { |n| n.kind == :await }
+      end
+
       def to_h
         {
           name: name,
@@ -66,16 +70,21 @@ module Igniter
             end
             if node.kind == :branch
               base[:selector] = node.selector_dependency
+              base[:depends_on] = node.context_dependencies if node.context_dependencies.any?
               base[:cases] = node.cases.map { |entry| { match: entry[:match], contract: entry[:contract].name } }
               base[:default_contract] = node.default_contract.name
               base[:inputs] = node.input_mapping
+              base[:mapper] = node.input_mapper.to_s if node.input_mapper?
             end
             if node.kind == :collection
               base[:with] = node.source_dependency
+              base[:depends_on] = node.context_dependencies if node.context_dependencies.any?
               base[:each] = node.contract_class.name
               base[:key] = node.key_name
               base[:mode] = node.mode
+              base[:mapper] = node.input_mapper.to_s if node.input_mapper?
             end
+            base[:event] = node.event_name if node.kind == :await
             base
           end,
           outputs: outputs.map do |output|
@@ -113,11 +122,20 @@ module Igniter
               metadata: node.metadata.reject { |key, _| key == :source_location }
             }
           end,
+          awaits: nodes.select { |node| node.kind == :await }.map do |node|
+            {
+              name: node.name,
+              event: node.event_name,
+              metadata: node.metadata.reject { |key, _| key == :source_location }
+            }
+          end,
           branches: nodes.select { |node| node.kind == :branch }.map do |node|
             {
               name: node.name,
               with: node.selector_dependency,
+              depends_on: node.context_dependencies,
               inputs: node.input_mapping,
+              map_inputs: (node.input_mapper if node.input_mapper?),
               cases: node.cases.map { |entry| { on: entry[:match], contract: entry[:contract] } },
               default: node.default_contract,
               metadata: node.metadata.reject { |key, _| key == :source_location }
@@ -127,9 +145,11 @@ module Igniter
             {
               name: node.name,
               with: node.source_dependency,
+              depends_on: node.context_dependencies,
               each: node.contract_class,
               key: node.key_name,
               mode: node.mode,
+              map_inputs: (node.input_mapper if node.input_mapper?),
               metadata: node.metadata.reject { |key, _| key == :source_location }
             }
           end,

data/lib/igniter/compiler/validation_pipeline.rb

@@ -8,7 +8,9 @@ module Igniter
         Validators::OutputsValidator,
         Validators::DependenciesValidator,
         Validators::TypeCompatibilityValidator,
-        Validators::CallableValidator
+        Validators::CallableValidator,
+        Validators::AwaitValidator,
+        Validators::RemoteValidator
       ].freeze
 
       def self.call(context, validators: DEFAULT_VALIDATORS)

data/lib/igniter/compiler/validators/await_validator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    module Validators
+      class AwaitValidator
+        def self.call(context)
+          new(context).call
+        end
+
+        def initialize(context)
+          @context = context
+        end
+
+        def call
+          await_nodes = @context.runtime_nodes.select { |n| n.kind == :await }
+          return if await_nodes.empty?
+
+          validate_correlation_keys_as_inputs!(await_nodes)
+          validate_unique_event_names!(await_nodes)
+        end
+
+        private
+
+        def validate_correlation_keys_as_inputs!(await_nodes) # rubocop:disable Metrics/AbcSize
+          correlation_keys = @context.graph.metadata[:correlation_keys] || []
+          return if correlation_keys.empty?
+
+          input_names = @context.runtime_nodes.select { |n| n.kind == :input }.map(&:name)
+          missing = correlation_keys.reject { |key| input_names.include?(key.to_sym) }
+          return if missing.empty?
+
+          raise @context.validation_error(
+            await_nodes.first,
+            "Correlation keys #{missing.inspect} must be declared as inputs"
+          )
+        end
+
+        def validate_unique_event_names!(await_nodes)
+          event_names = await_nodes.map(&:event_name)
+          duplicates = event_names.select { |e| event_names.count(e) > 1 }.uniq
+          return if duplicates.empty?
+
+          node = await_nodes.find { |n| duplicates.include?(n.event_name) }
+          raise @context.validation_error(
+            node,
+            "Duplicate await event names: #{duplicates.inspect}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/igniter/compiler/validators/dependencies_validator.rb

@@ -12,8 +12,10 @@ module Igniter
           @context = context
         end
 
-        def call
+        def call # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
           @context.runtime_nodes.each do |node|
+            next if node.kind == :await
+
             validate_composition_node!(node) if node.kind == :composition
             validate_branch_node!(node) if node.kind == :branch
             validate_collection_node!(node) if node.kind == :collection
@@ -40,6 +42,7 @@ module Igniter
           end
 
           validate_composition_input_mapping!(node, contract_class.compiled_graph)
+          validate_composition_cycle!(node)
         end
 
         def validate_composition_input_mapping!(node, child_graph)
@@ -100,6 +103,8 @@ module Igniter
         end
 
         def validate_branch_input_mapping!(node, child_graph)
+          return if node.input_mapper?
+
           child_input_nodes = child_graph.nodes.select { |child_node| child_node.kind == :input }
           child_input_names = child_input_nodes.map(&:name)
 
@@ -124,6 +129,43 @@ module Igniter
           )
         end
 
+        def validate_composition_cycle!(node)
+          child_contract = node.contract_class
+          return unless child_contract.respond_to?(:compiled_graph) && child_contract.compiled_graph
+
+          current_name = @context.graph.name
+          # Skip anonymous contracts to avoid false positives when multiple
+          # anonymous contracts share the same name "AnonymousContract"
+          return if current_name == "AnonymousContract"
+
+          validate_direct_cycle!(node, child_contract, current_name)
+          validate_grandchild_cycles!(node, child_contract, current_name)
+        end
+
+        def validate_direct_cycle!(node, child_contract, current_name)
+          return unless child_contract.compiled_graph.name == current_name
+
+          raise @context.validation_error(
+            node,
+            "Composition cycle: '#{node.name}' composes '#{child_contract.name}' " \
+            "which is the same contract ('#{current_name}')"
+          )
+        end
+
+        def validate_grandchild_cycles!(node, child_contract, current_name) # rubocop:disable Metrics/AbcSize
+          child_contract.compiled_graph.nodes.select { |n| n.kind == :composition }.each do |grandchild|
+            next unless grandchild.contract_class.respond_to?(:compiled_graph)
+            next unless grandchild.contract_class.compiled_graph
+            next unless grandchild.contract_class.compiled_graph.name == current_name
+
+            raise @context.validation_error(
+              node,
+              "Composition cycle: '#{node.name}' -> '#{child_contract.name}' -> " \
+              "'#{grandchild.contract_class.name}' loops back to '#{current_name}'"
+            )
+          end
+        end
+
         def validate_collection_node!(node)
           unless node.contract_class.is_a?(Class) && node.contract_class <= Igniter::Contract
             raise @context.validation_error(node, "Collection '#{node.name}' must reference an Igniter::Contract subclass")

data/lib/igniter/compiler/validators/remote_validator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    module Validators
+      class RemoteValidator
+        def self.call(context)
+          new(context).call
+        end
+
+        def initialize(context)
+          @context = context
+        end
+
+        def call
+          @context.runtime_nodes.each do |node|
+            next unless node.kind == :remote
+
+            validate_url!(node)
+            validate_contract_name!(node)
+            validate_dependencies!(node)
+          end
+        end
+
+        private
+
+        def validate_url!(node)
+          return if node.node_url.start_with?("http://", "https://")
+
+          raise @context.validation_error(
+            node,
+            "remote :#{node.name} has invalid node: URL '#{node.node_url}'. Must start with http:// or https://"
+          )
+        end
+
+        def validate_contract_name!(node)
+          return unless node.contract_name.strip.empty?
+
+          raise @context.validation_error(
+            node,
+            "remote :#{node.name} requires a non-empty contract: name"
+          )
+        end
+
+        def validate_dependencies!(node)
+          node.dependencies.each do |dep_name|
+            next if @context.dependency_resolvable?(dep_name)
+
+            raise @context.validation_error(
+              node,
+              "remote :#{node.name} depends on '#{dep_name}' which is not defined in the graph"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/compiler.rb

@@ -8,6 +8,8 @@ require_relative "compiler/validators/outputs_validator"
 require_relative "compiler/validators/dependencies_validator"
 require_relative "compiler/validators/callable_validator"
 require_relative "compiler/validators/type_compatibility_validator"
+require_relative "compiler/validators/await_validator"
+require_relative "compiler/validators/remote_validator"
 require_relative "compiler/validation_pipeline"
 require_relative "compiler/validator"
 require_relative "compiler/graph_compiler"

data/lib/igniter/contract.rb

@@ -3,8 +3,20 @@
 module Igniter
   class Contract
     class << self
+      def correlate_by(*keys)
+        @correlation_keys = keys.map(&:to_sym).freeze
+      end
+
+      def correlation_keys
+        @correlation_keys || []
+      end
+
       def define(&block)
-        @compiled_graph = DSL::ContractBuilder.compile(name: contract_name, &block)
+        @compiled_graph = DSL::ContractBuilder.compile(
+          name: contract_name,
+          correlation_keys: correlation_keys,
+          &block
+        )
       end
 
       def run_with(runner:, max_workers: nil)
@@ -28,6 +40,45 @@ module Igniter
         @compiled_graph = DSL::SchemaBuilder.compile(schema, name: contract_name)
       end
 
+      def start(inputs = {}, store: nil, **keyword_inputs)
+        resolved_store = store || Igniter.execution_store
+        all_inputs = inputs.merge(keyword_inputs)
+
+        instance = new(all_inputs, runner: :store, store: resolved_store)
+        instance.resolve_all
+
+        correlation = correlation_keys.each_with_object({}) do |key, hash|
+          hash[key] = all_inputs[key] || all_inputs[key.to_s]
+        end
+
+        resolved_store.save(instance.snapshot, correlation: correlation.compact, graph: contract_name)
+        instance
+      end
+
+      def deliver_event(event_name, correlation:, payload:, store: nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        resolved_store = store || Igniter.execution_store
+        execution_id = resolved_store.find_by_correlation(
+          graph: contract_name,
+          correlation: correlation.transform_keys(&:to_sym)
+        )
+        unless execution_id
+          raise ResolutionError,
+                "No pending execution found for #{contract_name} with given correlation"
+        end
+
+        instance = restore_from_store(execution_id, store: resolved_store)
+
+        await_node = instance.execution.compiled_graph.await_nodes
+                             .find { |n| n.event_name == event_name.to_sym }
+        raise ResolutionError, "No await node found for event '#{event_name}' in #{contract_name}" unless await_node
+
+        instance.execution.resume(await_node.name, value: payload)
+        instance.resolve_all
+
+        resolved_store.save(instance.snapshot, correlation: correlation.transform_keys(&:to_sym), graph: contract_name)
+        instance
+      end
+
       def restore(snapshot)
         instance = new(
           snapshot[:inputs] || snapshot["inputs"] || {},
@@ -103,6 +154,13 @@ module Igniter
         react_to(:execution_failed, once_per_execution: true, &terminal_hook)
       end
 
+      def present(output_name, with: nil, &block)
+        raise CompileError, "present requires a block or `with:`" unless block || with
+        raise CompileError, "present cannot use both a block and `with:`" if block && with
+
+        own_output_presenters[output_name.to_sym] = with || block
+      end
+
       def compiled_graph
         @compiled_graph || superclass_compiled_graph
       end
@@ -116,8 +174,17 @@ module Igniter
         @execution_options || superclass_execution_options || {}
       end
 
+      def output_presenters
+        inherited = superclass.respond_to?(:output_presenters) ? superclass.output_presenters : {}
+        inherited.merge(own_output_presenters)
+      end
+
       private
 
+      def own_output_presenters
+        @output_presenters ||= {}
+      end
+
       def contract_name
         name || "AnonymousContract"
       end
@@ -143,9 +210,9 @@ module Igniter
       end
     end
 
-    attr_reader :execution, :result
+    attr_reader :execution, :result, :reactive
 
-    def initialize(inputs = nil, runner: nil, max_workers: nil, **keyword_inputs)
+    def initialize(inputs = nil, runner: nil, max_workers: nil, store: nil, **keyword_inputs)
       graph = self.class.compiled_graph
       raise CompileError, "#{self.class.name} has no compiled graph. Use `define`." unless graph
 
@@ -159,7 +226,7 @@ module Igniter
         end
 
       execution_options = self.class.execution_options.merge(
-        { runner: runner, max_workers: max_workers }.compact
+        { runner: runner, max_workers: max_workers, store: store }.compact
       )
       execution_options[:store] ||= Igniter.execution_store if execution_options[:runner]&.to_sym == :store
 
@@ -204,10 +271,6 @@ module Igniter
       execution.audit.snapshot
     end
 
-    def reactive
-      @reactive
-    end
-
     def subscribe(subscriber = nil, &block)
       execution.events.subscribe(subscriber, &block)
       self
@@ -245,5 +308,9 @@ module Igniter
     def failed?
       execution.failed?
     end
+
+    def pending?
+      execution.pending?
+    end
   end
 end

data/lib/igniter/diagnostics/report.rb

@@ -32,7 +32,7 @@ module Igniter
         lines << "Diagnostics #{report[:graph]}"
         lines << "Execution #{report[:execution_id]}"
         lines << "Status: #{report[:status]}"
-        lines << format_outputs(report[:outputs])
+        lines << format_outputs(presented_outputs)
         lines << format_nodes(report[:nodes])
         lines << format_collection_nodes(report[:collection_nodes])
         lines << format_errors(report[:errors])
@@ -47,7 +47,7 @@ module Igniter
         lines << ""
         lines << "- Execution: `#{report[:execution_id]}`"
         lines << "- Status: `#{report[:status]}`"
-        lines << "- Outputs: #{inline_hash(report[:outputs])}"
+        lines << "- Outputs: #{inline_hash(presented_outputs)}"
         lines << "- Nodes: total=#{report[:nodes][:total]}, succeeded=#{report[:nodes][:succeeded]}, failed=#{report[:nodes][:failed]}, stale=#{report[:nodes][:stale]}"
         unless report[:collection_nodes].empty?
           lines << "- Collections: #{report[:collection_nodes].map { |node| "#{node[:node_name]} total=#{node[:total]} succeeded=#{node[:succeeded]} failed=#{node[:failed]} status=#{node[:status]}" }.join('; ')}"
@@ -170,6 +170,13 @@ module Igniter
         "Outputs: #{inline_hash(outputs)}"
       end
 
+      def presented_outputs
+        @presented_outputs ||= execution.compiled_graph.outputs.each_with_object({}) do |output_node, memo|
+          raw_value = to_h[:outputs][output_node.name]
+          memo[output_node.name] = present_output(output_node.name, raw_value)
+        end
+      end
+
       def format_nodes(nodes)
         line = "Nodes: total=#{nodes[:total]}, succeeded=#{nodes[:succeeded]}, failed=#{nodes[:failed]}, stale=#{nodes[:stale]}"
         line = "Nodes: total=#{nodes[:total]}, succeeded=#{nodes[:succeeded]}, failed=#{nodes[:failed]}, pending=#{nodes[:pending]}, stale=#{nodes[:stale]}"
@@ -203,7 +210,27 @@ module Igniter
       end
 
       def inline_hash(hash)
-        hash.map { |key, value| "#{key}=#{value.inspect}" }.join(", ")
+        hash.map { |key, value| "#{key}=#{inline_value(value)}" }.join(", ")
+      end
+
+      def present_output(output_name, raw_value)
+        presenter = execution.contract_instance.class.output_presenters[output_name.to_sym]
+        return raw_value unless presenter
+
+        if presenter.is_a?(Symbol) || presenter.is_a?(String)
+          execution.contract_instance.public_send(
+            presenter,
+            value: raw_value,
+            contract: execution.contract_instance,
+            execution: execution
+          )
+        else
+          presenter.call(
+            value: raw_value,
+            contract: execution.contract_instance,
+            execution: execution
+          )
+        end
       end
 
       def serialize_value(value)
@@ -221,6 +248,78 @@ module Igniter
         end
       end
 
+      def inline_value(value)
+        case value
+        when Hash
+          return summarize_serialized_collection_hash(value) if serialized_collection_hash?(value)
+          return summarize_serialized_collection_items_hash(value) if serialized_collection_items_hash?(value)
+
+          "{#{value.map { |key, nested| "#{key}: #{inline_value(nested)}" }.join(', ')}}"
+        when Array
+          "[#{value.map { |item| inline_value(item) }.join(', ')}]"
+        when Runtime::Result
+          summarize_nested_result(value)
+        when Runtime::CollectionResult
+          summarize_collection_result(value)
+        else
+          value.inspect
+        end
+      end
+
+      def summarize_nested_result(result)
+        outputs = result.to_h.keys
+        "{graph=#{result.execution.compiled_graph.name.inspect}, status=#{nested_result_status(result).inspect}, outputs=#{outputs.inspect}}"
+      end
+
+      def summarize_collection_result(result)
+        summary = result.summary
+        failed_keys = result.failures.keys
+        "{mode=#{result.mode.inspect}, total=#{summary[:total]}, succeeded=#{summary[:succeeded]}, failed=#{summary[:failed]}, status=#{summary[:status].inspect}, keys=#{result.keys.inspect}, failed_keys=#{failed_keys.inspect}}"
+      end
+
+      def serialized_collection_hash?(value)
+        value.key?(:mode) && value.key?(:summary) && value.key?(:items)
+      end
+
+      def summarize_serialized_collection_hash(value)
+        summary = value[:summary] || {}
+        items = value[:items] || {}
+        failed_keys = items.each_with_object([]) do |(key, item), memo|
+          memo << key if item[:status] == :failed || item["status"] == :failed
+        end
+
+        "{mode=#{value[:mode].inspect}, total=#{summary[:total]}, succeeded=#{summary[:succeeded]}, failed=#{summary[:failed]}, status=#{summary[:status].inspect}, keys=#{items.keys.inspect}, failed_keys=#{failed_keys.inspect}}"
+      end
+
+      def serialized_collection_items_hash?(value)
+        return false if value.empty?
+
+        value.values.all? do |item|
+          item.is_a?(Hash) && (item.key?(:key) || item.key?("key")) && (item.key?(:status) || item.key?("status"))
+        end
+      end
+
+      def summarize_serialized_collection_items_hash(value)
+        failed_keys = value.each_with_object([]) do |(key, item), memo|
+          status = item[:status] || item["status"]
+          memo << key if status == :failed || status == "failed"
+        end
+
+        total = value.size
+        failed = failed_keys.size
+        succeeded = total - failed
+        status = failed.zero? ? :succeeded : :partial_failure
+
+        "{mode=:collect, total=#{total}, succeeded=#{succeeded}, failed=#{failed}, status=#{status.inspect}, keys=#{value.keys.inspect}, failed_keys=#{failed_keys.inspect}}"
+      end
+
+      def nested_result_status(result)
+        return :failed if result.failed?
+        return :pending if result.pending?
+
+        :succeeded
+      end
+
       def summarize_collection_nodes
         execution.cache.values.filter_map do |state|
           next unless state.value.is_a?(Runtime::CollectionResult)