igniter 0.5.0 → 0.5.2

data/packages/igniter-embed/lib/igniter/embed/config.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    class Config
+      ContractRegistration = Struct.new(:definition, :name, keyword_init: true)
+
+      attr_reader :name, :packs, :contract_registrations,
+                  :contractable_configs, :discovery_pattern
+      attr_accessor :cache, :capture_exceptions, :executor_name
+
+      UNSET = Object.new.freeze
+
+      def initialize(name:)
+        @name = name.to_sym
+        @cache = true
+        @root = nil
+        @owner = nil
+        @packs = []
+        @contract_registrations = []
+        @contractable_configs = []
+        @discovery_enabled = false
+        @discovery_pattern = "**/*_contract.rb"
+        @capture_exceptions = false
+        @executor_name = :inline
+      end
+
+      def pack(pack)
+        packs << pack
+        self
+      end
+
+      def owner(value = UNSET)
+        return @owner if value.equal?(UNSET)
+
+        @owner = value
+        self
+      end
+
+      def owner=(value)
+        owner(value)
+      end
+
+      def contract(definition, as: nil)
+        contract_registrations << ContractRegistration.new(definition: definition, name: as)
+        self
+      end
+
+      def contractable(config)
+        raise DuplicateContractError, "contractable #{config.name} is already configured" if contractable_registered?(config.name)
+
+        contractable_configs << config
+        self
+      end
+
+      def contractable_config(name)
+        key = name.to_sym
+        contractable_configs.find { |contractable_config| contractable_config.name == key }
+      end
+
+      def contracts(&block)
+        builder = ContractsBuilder.new(config: self)
+        evaluate_builder_block(builder, &block) if block
+        self
+      end
+
+      def root(path = nil)
+        return @root if path.nil?
+
+        @root = File.expand_path(path.to_s)
+        self
+      end
+
+      def root=(path)
+        root(path)
+      end
+
+      def path(value = nil)
+        return root if value.nil?
+
+        root(resolve_path(value))
+      end
+
+      def path=(value)
+        path(value)
+      end
+
+      def sugar_expansion
+        SugarExpansion.new(config: self)
+      end
+
+      def discover!(pattern: "**/*_contract.rb")
+        @discovery_enabled = true
+        @discovery_pattern = pattern
+        self
+      end
+
+      def cache?
+        !!cache
+      end
+
+      def discovery_enabled?
+        !!@discovery_enabled
+      end
+
+      def capture_exceptions?
+        !!capture_exceptions
+      end
+
+      private
+
+      def contractable_registered?(name)
+        contractable_configs.any? { |contractable_config| contractable_config.name == name }
+      end
+
+      def resolve_path(value)
+        if value.is_a?(Array)
+          raise SugarError, "path requires exactly one path in this implementation slice" unless value.length == 1
+
+          value = value.first
+        end
+
+        raise SugarError, "path entries must be strings or path-like objects" unless path_like?(value)
+
+        path_value = value.respond_to?(:to_path) ? value.to_path : value.to_s
+        return path_value if absolute_path?(path_value)
+
+        owner_root = resolved_owner_root
+        owner_root ? File.join(owner_root, path_value) : path_value
+      end
+
+      def absolute_path?(path)
+        File.absolute_path(path) == path
+      end
+
+      def resolved_owner_root
+        return nil unless @owner.respond_to?(:root)
+
+        @owner.root.to_s
+      end
+
+      def path_like?(value)
+        value.is_a?(String) || value.respond_to?(:to_path)
+      end
+
+      def evaluate_builder_block(builder, &block)
+        if block.arity.zero?
+          builder.instance_eval(&block)
+        else
+          block.call(builder)
+        end
+      end
+    end
+  end
+end

data/packages/igniter-embed/lib/igniter/embed/container.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    class Container
+      attr_reader :config, :registry
+
+      def initialize(config:)
+        @config = config
+        @registry = Registry.new
+        @compiled_contracts = {}
+        @contractable_runners = {}
+        register_configured_contracts
+        discover_configured_contracts
+      end
+
+      def profile
+        @profile ||= Igniter::Contracts.build_profile(config.packs)
+      end
+
+      def register(name_or_definition, definition = nil, as: nil, &block)
+        name, contract_definition = normalize_registration(name_or_definition, definition, as: as, block: block)
+        raise ArgumentError, "contract definition is required" unless contract_definition
+
+        registry.register(name, contract_definition)
+        compiled_contracts.delete(name)
+        ContractHandle.new(name: name, container: self)
+      end
+
+      def fetch(name)
+        registry.fetch(name)
+        ContractHandle.new(name: name, container: self)
+      end
+
+      def compile(name = nil, &block)
+        return compile_block(&block) if block
+
+        compile_registered(name)
+      end
+
+      def call(name, inputs = {}, **keyword_inputs)
+        normalized_inputs = inputs.merge(keyword_inputs)
+        compiled_graph = compile_registered(name)
+        result = Igniter::Contracts.execute_with(
+          config.executor_name,
+          compiled_graph,
+          inputs: normalized_inputs,
+          profile: profile
+        )
+        ExecutionEnvelope.new(name: name, inputs: normalized_inputs, result: result)
+      rescue StandardError => e
+        raise unless config.capture_exceptions?
+
+        ExecutionEnvelope.new(
+          name: name,
+          inputs: normalized_inputs || {},
+          errors: [e],
+          metadata: { captured_exception: true }
+        )
+      end
+
+      def contractable(name)
+        key = name.to_sym
+        return contractable_runners.fetch(key) if contractable_runners.key?(key)
+
+        contractable_config = config.contractable_config(key)
+        raise UnknownContractableError, "unknown contractable #{key}" unless contractable_config
+
+        contractable_runners[key] = Contractable::Runner.new(config: contractable_config)
+      end
+      alias fetch_contractable contractable
+
+      def contractable_names
+        config.contractable_configs.map(&:name)
+      end
+
+      def clear_cache
+        compiled_contracts.clear
+        contractable_runners.clear
+        @profile = nil
+        self
+      end
+
+      def reload!
+        clear_cache
+      end
+
+      def sugar_expansion
+        config.sugar_expansion
+      end
+
+      private
+
+      attr_reader :compiled_contracts, :contractable_runners
+
+      def discover_configured_contracts
+        return unless config.discovery_enabled?
+
+        root = config.root
+        raise DiscoveryError, "config.root is required when discovery is enabled" unless root
+        raise DiscoveryError, "contract discovery root does not exist: #{root}" unless Dir.exist?(root)
+
+        before = contract_classes
+        Dir[File.join(root, config.discovery_pattern)].sort.each { |path| require path }
+        discovered_contract_classes = (contract_classes - before).select { |klass| discoverable_contract_class?(klass) }
+        discovered_by_name = discovered_contract_classes.group_by { |klass| ContractNaming.infer_contract_name(klass) }
+        duplicates = discovered_by_name.select { |_name, classes| classes.length > 1 }
+        unless duplicates.empty?
+          duplicate_names = duplicates.keys.sort.map { |name| ":#{name}" }.join(", ")
+          raise DiscoveryError,
+                "discovered duplicate contract names #{duplicate_names}; use explicit config.contract registrations"
+        end
+
+        discovered_by_name.keys.sort.each do |name|
+          next if registry.key?(name)
+
+          register(discovered_by_name.fetch(name).first, as: name)
+        end
+      end
+
+      def contract_classes
+        ObjectSpace.each_object(Class).select { |klass| ContractNaming.contract_class?(klass) }
+      end
+
+      def discoverable_contract_class?(contract_class)
+        !contract_class.name.nil?
+      end
+
+      def register_configured_contracts
+        config.contract_registrations.each do |registration|
+          register(registration.definition, as: registration.name)
+        end
+      end
+
+      def normalize_registration(name_or_definition, definition, as:, block:)
+        if ContractNaming.contract_class?(name_or_definition)
+          name = ContractNaming.normalize_contract_name(as || ContractNaming.infer_contract_name(name_or_definition))
+          return [name, name_or_definition]
+        end
+
+        name = ContractNaming.normalize_contract_name(as || name_or_definition)
+        [name, definition || block]
+      end
+
+      def compile_block(&block)
+        Igniter::Contracts.compile(profile: profile, &block)
+      end
+
+      def compile_registered(name)
+        key = name.to_sym
+        return compiled_contracts.fetch(key) if config.cache? && compiled_contracts.key?(key)
+
+        compiled = compile_registration(registry.fetch(key))
+        compiled_contracts[key] = compiled if config.cache?
+        compiled
+      end
+
+      def compile_registration(registration)
+        return compile_block(&registration.definition) if registration.block?
+
+        registration.definition.compile(profile: profile)
+      end
+    end
+  end
+end

data/packages/igniter-embed/lib/igniter/embed/contract_handle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    class ContractHandle
+      attr_reader :name, :container
+
+      def initialize(name:, container:)
+        @name = name.to_sym
+        @container = container
+        freeze
+      end
+
+      def compile
+        container.compile(name)
+      end
+
+      def call(inputs = {}, **keyword_inputs)
+        container.call(name, inputs.merge(keyword_inputs))
+      end
+    end
+  end
+end

data/packages/igniter-embed/lib/igniter/embed/contract_naming.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    module ContractNaming
+      module_function
+
+      def contract_class?(value)
+        value.is_a?(Class) && value < Igniter::Contract
+      end
+
+      def infer_contract_name(contract_class)
+        class_name = contract_class.name
+        unless class_name
+          raise InvalidContractRegistrationError,
+                "anonymous contract classes must be registered with as:"
+        end
+
+        basename = class_name.split("::").last.sub(/Contract\z/, "")
+        snake_case(basename).to_sym
+      end
+
+      def normalize_contract_name(name)
+        raise InvalidContractRegistrationError, "contract name is required" unless name
+
+        name.to_sym
+      end
+
+      def snake_case(value)
+        value
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr("-", "_")
+          .downcase
+      end
+    end
+  end
+end

data/packages/igniter-embed/lib/igniter/embed/contractable/acceptance.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    module Contractable
+      module Acceptance
+        module_function
+
+        def evaluate(policy:, report:, candidate:, options:)
+          case policy.to_sym
+          when :exact
+            result(policy: :exact, failures: report.match? ? [] : ["differential mismatch"])
+          when :completed
+            completed = candidate.fetch(:status) != :error && candidate.fetch(:error).nil?
+            result(policy: :completed, failures: completed ? [] : ["candidate did not complete"])
+          when :shape
+            failures = shape_failures(candidate.fetch(:outputs), options.fetch(:outputs, {}))
+            result(policy: :shape, failures: failures)
+          else
+            raise ArgumentError, "unknown contractable acceptance policy #{policy}"
+          end
+        end
+
+        def result(policy:, failures:)
+          {
+            policy: policy,
+            accepted: failures.empty?,
+            failures: failures
+          }
+        end
+
+        def shape_failures(outputs, expected, path = [])
+          expected.flat_map do |key, matcher|
+            current_path = path + [key]
+            next ["#{current_path.join(".")} is missing"] unless outputs.key?(key)
+
+            value = outputs.fetch(key)
+            if matcher.is_a?(Hash)
+              value.is_a?(Hash) ? shape_failures(value, matcher, current_path) : ["#{current_path.join(".")} is not a hash"]
+            elsif matcher.is_a?(Class) || matcher.is_a?(Module)
+              value.is_a?(matcher) ? [] : ["#{current_path.join(".")} is not a #{matcher}"]
+            elsif matcher.respond_to?(:call)
+              matcher.call(value) ? [] : ["#{current_path.join(".")} did not satisfy predicate"]
+            else
+              value == matcher ? [] : ["#{current_path.join(".")} did not equal #{matcher.inspect}"]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-embed/lib/igniter/embed/contractable/adapters.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    module Contractable
+      module Adapters
+        class InlineAsync
+          def enqueue(name:, inputs:, metadata:, handoff: nil, &block) # rubocop:disable Lint/UnusedMethodArgument
+            block.call
+          end
+        end
+
+        class ThreadAsync
+          def enqueue(name:, inputs:, metadata:, handoff: nil, &block) # rubocop:disable Lint/UnusedMethodArgument
+            Thread.new { block.call }
+          end
+        end
+
+        class MemoryStore
+          attr_reader :observations
+
+          def initialize
+            @observations = []
+          end
+
+          def record(observation)
+            observations << observation
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-embed/lib/igniter/embed/contractable/config.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    module Contractable
+      class Config
+        EventHandler = Struct.new(:event, :handler, :source, keyword_init: true)
+        CapabilityAttachment = Struct.new(:name, :target, :kind, keyword_init: true)
+
+        FAILURE_EVENTS = %i[primary_error candidate_error acceptance_failure store_error].freeze
+        SUPPORTED_EVENTS = (
+          %i[primary_success primary_error candidate_success candidate_error divergence acceptance_failure store_error observation] +
+          [:failure]
+        ).freeze
+
+        attr_reader :name, :event_handlers, :capability_attachments
+        attr_accessor :primary_callable, :candidate_callable,
+                      :primary_normalizer, :candidate_normalizer,
+                      :store_adapter, :observation_callback,
+                      :acceptance_policy, :acceptance_options, :clock_callable,
+                      :redaction_input_policy
+
+        def initialize(name:)
+          @name = name.to_sym
+          @role = nil
+          @stage = :captured
+          @stage_explicit = false
+          @async_enabled = true
+          @sample_value = 1.0
+          @async_adapter = nil
+          @metadata_value = {}
+          @input_redactor = ->(*, **) { {} }
+          @redaction_input_policy = :custom
+          @acceptance_policy = :exact
+          @acceptance_options = {}
+          @event_handlers = []
+          @capability_attachments = []
+          @clock_callable = Time
+        end
+
+        def primary(callable = nil)
+          return primary_callable unless callable
+
+          self.primary_callable = callable
+          apply_core_contractable_defaults(callable)
+        end
+
+        def candidate(callable = nil)
+          return candidate_callable unless callable
+
+          self.candidate_callable = callable
+          apply_core_contractable_defaults(callable)
+        end
+
+        def normalize_primary(callable = nil, &block)
+          return primary_normalizer unless callable || block
+
+          self.primary_normalizer = callable || block
+        end
+
+        def normalize_candidate(callable = nil, &block)
+          return candidate_normalizer unless callable || block
+
+          self.candidate_normalizer = callable || block
+        end
+
+        def role(value = nil)
+          return @role || inferred_role unless value
+
+          @role = value.to_sym
+        end
+
+        def stage(value = nil)
+          return @stage unless value
+
+          @stage = value.to_sym
+          @stage_explicit = true
+        end
+
+        def async(value = nil)
+          return @async_enabled if value.nil?
+
+          @async_enabled = !!value
+        end
+
+        def sample(value = nil)
+          return @sample_value if value.nil?
+
+          @sample_value = value
+        end
+
+        def store(value = nil)
+          return store_adapter unless value
+
+          self.store_adapter = value
+        end
+
+        def async_adapter(value = nil)
+          return @async_adapter || default_async_adapter unless value
+
+          @async_adapter = value
+        end
+
+        def redact_inputs(callable = nil, &block)
+          return @input_redactor unless callable || block
+
+          @input_redactor = callable || block
+        end
+
+        def metadata(value = nil, &block)
+          return @metadata_value unless value || block
+
+          @metadata_value = block || value
+        end
+
+        def on_observation(callable = nil, &block)
+          return observation_callback unless callable || block
+
+          self.observation_callback = callable || block
+        end
+
+        def on(event, callable = nil, &block)
+          handler = callable || block
+          raise SugarError, "on :#{event} requires a block or callable" unless handler
+
+          normalized_event = event.to_sym
+          raise SugarError, "unsupported event :#{event}" unless SUPPORTED_EVENTS.include?(normalized_event)
+
+          event_names(normalized_event).each do |event_name|
+            event_handlers << EventHandler.new(event: event_name, handler: handler, source: normalized_event)
+          end
+          self
+        end
+
+        def handlers_for(event)
+          event_handlers.select { |handler| handler.event == event.to_sym }
+        end
+
+        def capability(name, target)
+          capability_name = name.to_sym
+          raise SugarError, "capability :#{capability_name} is already configured" if capability_configured?(capability_name)
+
+          capability_attachments << CapabilityAttachment.new(
+            name: capability_name,
+            target: target,
+            kind: capability_kind(target)
+          )
+          self
+        end
+
+        def accept(policy = nil, **options)
+          return acceptance_policy unless policy
+
+          self.acceptance_policy = policy.to_sym
+          self.acceptance_options = options
+        end
+
+        def validate!
+          raise ArgumentError, "contractable #{name} requires a primary callable" unless primary_callable
+          raise ArgumentError, "contractable #{name} requires normalize_primary" unless primary_normalizer
+
+          return if observed_service?
+          raise ArgumentError, "contractable #{name} requires normalize_candidate when candidate is configured" unless candidate_normalizer
+        end
+
+        def observed_service?
+          candidate_callable.nil?
+        end
+
+        def sampled?
+          value = sample_value
+          value = value.call if value.respond_to?(:call)
+          value.to_f >= 1.0 || rand < value.to_f
+        end
+
+        def normalize_inputs(args, kwargs)
+          input_redactor.call(*args, **kwargs)
+        end
+
+        def metadata_payload
+          metadata_value.respond_to?(:call) ? metadata_value.call : metadata_value
+        end
+
+        def now
+          clock_callable.respond_to?(:now) ? clock_callable.now : clock_callable.call
+        end
+
+        private
+
+        attr_reader :sample_value, :input_redactor, :metadata_value
+
+        def event_names(event)
+          event == :failure ? FAILURE_EVENTS : [event]
+        end
+
+        def capability_kind(target)
+          ContractNaming.contract_class?(target) ? :contract : :callable_adapter
+        end
+
+        def capability_configured?(name)
+          capability_attachments.any? { |attachment| attachment.name == name }
+        end
+
+        def inferred_role
+          observed_service? ? :observed_service : :migration_candidate
+        end
+
+        def default_async_adapter
+          async ? Adapters::ThreadAsync.new : Adapters::InlineAsync.new
+        end
+
+        def apply_core_contractable_defaults(callable)
+          return unless Igniter::Contracts::Contractable.contractable?(callable)
+
+          definition = contractable_definition(callable)
+          @role ||= definition.role
+          @stage = definition.stage if definition.stage && !@stage_explicit
+          merge_core_contractable_metadata(definition.metadata)
+        end
+
+        def contractable_definition(callable)
+          klass = callable.is_a?(Class) ? callable : callable.class
+          klass.contractable_definition
+        end
+
+        def merge_core_contractable_metadata(metadata)
+          return if metadata.empty? || !@metadata_value.is_a?(Hash)
+
+          @metadata_value = metadata.merge(@metadata_value)
+        end
+      end
+    end
+  end
+end