axn 0.1.0.pre.alpha.2.6 → 0.1.0.pre.alpha.2.7

data/lib/action/core/context/internal.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "action/core/context/facade"
+
+module Action
+  # Inbound / Internal ContextFacade
+  class InternalContext < ContextFacade
+    # Available for use from within message callables
+    def default_error
+      msg = action.class._static_message_for(:error, action:, exception: @context.exception || Action::Failure.new)
+      [@context.error_prefix, msg.presence || "Something went wrong"].compact.join(" ").squeeze(" ")
+    end
+
+    def default_success
+      msg = action.class._static_message_for(:success, action:, exception: nil)
+      msg.presence || "Action completed successfully"
+    end
+
+    private
+
+    def context_data_source = @context.provided_data
+
+    def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)
+      if @context.__combined_data.key?(method_name.to_sym)
+        msg = <<~MSG
+          Method ##{method_name} is not available on Action::InternalContext!
+
+          #{action_name} may be missing a line like:
+            expects :#{method_name}
+        MSG
+
+        raise Action::ContractViolation::MethodNotAllowed, msg
+      end
+
+      super
+    end
+  end
+end

data/lib/action/core/contract.rb

@@ -4,7 +4,8 @@ require "active_support/core_ext/enumerable"
 require "active_support/core_ext/module/delegation"
 
 require "action/core/validation/fields"
-require "action/core/context_facade"
+require "action/result"
+require "action/core/context/internal"
 
 module Action
   module Core
@@ -70,13 +71,13 @@ module Action
         private
 
         RESERVED_FIELD_NAMES_FOR_EXPECTATIONS = %w[
-          fail! success? ok?
+          fail! ok?
           inspect default_error
           each_pair
         ].freeze
 
         RESERVED_FIELD_NAMES_FOR_EXPOSURES = %w[
-          fail! success? ok?
+          fail! ok?
           inspect each_pair default_error
           ok error success message
         ].freeze
@@ -114,13 +115,15 @@ module Action
           define_method(field) { internal_context.public_send(field) }
         end
 
-        def _define_model_reader(field, klass)
+        def _define_model_reader(field, klass, &id_extractor)
           name = field.to_s.delete_suffix("_id")
           raise ArgumentError, "Model validation expects to be given a field ending in _id (given: #{field})" unless field.to_s.end_with?("_id")
           raise ArgumentError, "Failed to define model reader - #{name} is already defined" if method_defined?(name)
 
+          id_extractor ||= -> { public_send(field) }
+
           define_memoized_reader_method(name) do
-            Validators::ModelValidator.instance_for(field:, klass:, id: public_send(field))
+            Validators::ModelValidator.instance_for(field:, klass:, id: instance_exec(&id_extractor))
           end
         end
 
@@ -166,23 +169,37 @@ module Action
           kwargs.each do |key, value|
             raise Action::ContractViolation::UnknownExposure, key unless result.respond_to?(key)
 
-            @context.public_send("#{key}=", value)
+            @__context.exposed_data[key] = value
           end
         end
 
         def context_for_logging(direction = nil)
-          inspection_filter.filter(@context.to_h.slice(*_declared_fields(direction)))
+          inspection_filter.filter(@__context.__combined_data.slice(*_declared_fields(direction)))
         end
 
         private
 
+        def _with_contract
+          _apply_inbound_preprocessing!
+          _apply_defaults!(:inbound)
+          _validate_contract!(:inbound)
+
+          yield
+
+          _apply_defaults!(:outbound)
+          _validate_contract!(:outbound)
+
+          # TODO: improve location of this triggering
+          _trigger_on_success if respond_to?(:_trigger_on_success)
+        end
+
         def _build_context_facade(direction)
           raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
 
           klass = direction == :inbound ? Action::InternalContext : Action::Result
           implicitly_allowed_fields = direction == :inbound ? _declared_fields(:outbound) : []
 
-          klass.new(action: self, context: @context, declared_fields: _declared_fields(direction), implicitly_allowed_fields:)
+          klass.new(action: self, context: @__context, declared_fields: _declared_fields(direction), implicitly_allowed_fields:)
         end
 
         def inspection_filter

data/lib/action/core/contract_for_subfields.rb

@@ -86,7 +86,7 @@ module Action
             Action::Validation::Subfields.extract(field, public_send(on))
           end
 
-          _define_model_reader(field, validations[:model]) if validations.key?(:model)
+          _define_model_reader(field, validations[:model]) { Action::Validation::Subfields.extract(field, public_send(on)) } if validations.key?(:model)
         end
       end
 

data/lib/action/core/contract_validation.rb

@@ -9,9 +9,9 @@ module Action
         internal_field_configs.each do |config|
           next unless config.preprocess
 
-          initial_value = @context.public_send(config.field)
+          initial_value = @__context.provided_data[config.field]
           new_value = config.preprocess.call(initial_value)
-          @context.public_send("#{config.field}=", new_value)
+          @__context.provided_data[config.field] = new_value
         rescue StandardError => e
           raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}"
         end
@@ -33,17 +33,28 @@ module Action
       def _apply_defaults!(direction)
         raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
 
+        if direction == :outbound
+          # For outbound defaults, first copy values from provided_data for fields that are both expected and exposed
+          external_field_configs.each do |config|
+            field = config.field
+            next if @__context.exposed_data[field].present? # Already has a value
+
+            @__context.exposed_data[field] = @__context.provided_data[field] if @__context.provided_data[field].present?
+          end
+        end
+
         configs = direction == :inbound ? internal_field_configs : external_field_configs
         defaults_mapping = configs.each_with_object({}) do |config, hash|
           hash[config.field] = config.default
         end.compact
 
         defaults_mapping.each do |field, default_value_getter|
-          next if @context.public_send(field).present?
+          data_hash = direction == :inbound ? @__context.provided_data : @__context.exposed_data
+          next if data_hash[field].present?
 
           default_value = default_value_getter.respond_to?(:call) ? instance_exec(&default_value_getter) : default_value_getter
 
-          @context.public_send("#{field}=", default_value)
+          data_hash[field] = default_value
         end
       end
     end

data/lib/action/core/flow/callbacks.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers"
+
+module Action
+  module Core
+    module Flow
+      module Callbacks
+        def self.included(base)
+          base.class_eval do
+            class_attribute :_callbacks_registry, default: Action::Core::Flow::Handlers::Registry.empty
+
+            extend ClassMethods
+          end
+        end
+
+        module ClassMethods
+          # Internal dispatcher
+          def _dispatch_callbacks(event_type, action:, exception: nil)
+            _callbacks_registry.for(event_type).each do |handler|
+              handler.apply(action:, exception:)
+            end
+          end
+
+          # ONLY raised exceptions (i.e. NOT fail!).
+          def on_exception(**, &block) = _add_callback(:exception, **, block:)
+
+          # ONLY raised on fail! (i.e. NOT unhandled exceptions).
+          def on_failure(**, &block) = _add_callback(:failure, **, block:)
+
+          # Handles both fail! and unhandled exceptions
+          def on_error(**, &block) = _add_callback(:error, **, block:)
+
+          # Executes when the action completes successfully (after all after hooks complete successfully)
+          # Runs in child-first order (child handlers before parent handlers)
+          def on_success(**, &block) = _add_callback(:success, **, block:)
+
+          private
+
+          def _add_callback(event_type, block:, **kwargs)
+            raise ArgumentError, "on_#{event_type} cannot be called with both :if and :unless" if kwargs.key?(:if) && kwargs.key?(:unless)
+
+            condition = kwargs.key?(:if) ? kwargs[:if] : kwargs[:unless]
+            raise ArgumentError, "on_#{event_type} must be called with a block" unless block
+
+            matcher = condition.nil? ? nil : Action::Core::Flow::Handlers::Matcher.new(condition, invert: kwargs.key?(:unless))
+            entry = Action::Core::Flow::Handlers::CallbackHandler.new(matcher:, handler: block)
+            self._callbacks_registry = _callbacks_registry.register(event_type:, entry:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/exception_execution.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module ExceptionExecution
+        def self.included(base)
+          base.class_eval do
+            include InstanceMethods
+
+            def _trigger_on_exception(exception)
+              # Call any handlers registered on *this specific action* class
+              self.class._dispatch_callbacks(:exception, action: self, exception:)
+
+              # Call any global handlers
+              Action.config.on_exception(exception, action: self, context: context_for_logging)
+            rescue StandardError => e
+              # No action needed -- downstream #on_exception implementation should ideally log any internal failures, but
+              # we don't want exception *handling* failures to cascade and overwrite the original exception.
+              Axn::Util.piping_error("executing on_exception hooks", action: self, exception: e)
+            end
+
+            def _trigger_on_success
+              # Call success handlers in child-first order (like after hooks)
+              self.class._dispatch_callbacks(:success, action: self, exception: nil)
+            end
+          end
+        end
+
+        module InstanceMethods
+          private
+
+          def _with_exception_handling
+            yield
+          rescue StandardError => e
+            # on_error handlers run for both unhandled exceptions and fail!
+            self.class._dispatch_callbacks(:error, action: self, exception: e)
+
+            # on_failure handlers run ONLY for fail!
+            if e.is_a?(Action::Failure)
+              self.class._dispatch_callbacks(:failure, action: self, exception: e)
+            else
+              # on_exception handlers run for ONLY for unhandled exceptions.
+              _trigger_on_exception(e)
+
+              @__context.exception = e
+            end
+
+            # Set failure state using accessor method
+            @__context.send(:failure=, true)
+          end
+
+          def try
+            yield
+          rescue Action::Failure => e
+            # NOTE: re-raising so we can still fail! from inside the block
+            raise e
+          rescue StandardError => e
+            _trigger_on_exception(e)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/base_handler.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/matcher"
+
+module Action
+  module Core
+    module Flow
+      # "Handlers" doesn't feel like *quite* the right name for this, but basically things in this namespace
+      # relate to conditionally-invoked code blocks (e.g. callbacks, messages, etc.)
+      module Handlers
+        class BaseHandler
+          def initialize(matcher: nil, handler: nil)
+            @matcher = matcher
+            @handler = handler
+          end
+
+          attr_reader :handler
+
+          def static? = @matcher.nil?
+
+          def matches?(action:, exception:)
+            return true if static?
+
+            @matcher.call(exception:, action:)
+          end
+
+          # Subclasses should implement `apply(action:, exception:)`
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/callback_handler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/base_handler"
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        class CallbackHandler < BaseHandler
+          def apply(action:, exception:)
+            return false unless matches?(action:, exception:)
+
+            Invoker.call(action:, handler:, exception:, operation: "executing handler")
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/invoker.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        # Shared block evaluation with consistent arity handling and error piping
+        module Invoker
+          extend self
+
+          def call(action:, handler:, exception: nil, operation: "executing handler")
+            return call_symbol_handler(action:, symbol: handler, exception:) if symbol?(handler)
+            return call_callable_handler(action:, callable: handler, exception:) if callable?(handler)
+
+            literal_value(handler)
+          rescue StandardError => e
+            Axn::Util.piping_error(operation, action:, exception: e)
+          end
+
+          # Shared introspection helpers
+          def accepts_exception_keyword?(callable_or_method)
+            return false unless callable_or_method.respond_to?(:parameters)
+
+            params = callable_or_method.parameters
+            params.any? { |type, name| %i[keyreq key].include?(type) && name == :exception } ||
+              params.any? { |type, _| type == :keyrest }
+          end
+
+          def accepts_positional_exception?(callable_or_method)
+            return false unless callable_or_method.respond_to?(:arity)
+
+            arity = callable_or_method.arity
+            arity == 1 || arity.negative?
+          end
+
+          private
+
+          def symbol?(value) = value.is_a?(Symbol)
+
+          def callable?(value) = value.respond_to?(:arity)
+
+          def call_symbol_handler(action:, symbol:, exception: nil)
+            unless action.respond_to?(symbol)
+              action.warn("Ignoring apparently-invalid symbol #{symbol.inspect} -- action does not respond to method")
+              return nil
+            end
+
+            method = action.method(symbol)
+            if exception && accepts_exception_keyword?(method)
+              action.public_send(symbol, exception:)
+            elsif exception && accepts_positional_exception?(method)
+              action.public_send(symbol, exception)
+            else
+              action.public_send(symbol)
+            end
+          end
+
+          def call_callable_handler(action:, callable:, exception: nil)
+            if exception && accepts_exception_keyword?(callable)
+              action.instance_exec(exception:, &callable)
+            elsif exception && accepts_positional_exception?(callable)
+              action.instance_exec(exception, &callable)
+            else
+              action.instance_exec(&callable)
+            end
+          end
+
+          def literal_value(value) = value
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/matcher.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        class Matcher
+          def initialize(rule, invert: false)
+            @rule = rule
+            @invert = invert
+          end
+
+          def call(exception:, action:)
+            @invert ? !matches?(exception:, action:) : matches?(exception:, action:)
+          rescue StandardError => e
+            Axn::Util.piping_error("determining if handler applies to exception", action:, exception: e)
+          end
+
+          private
+
+          def matches?(exception:, action:)
+            return apply_callable(action:, exception:) if callable?
+            return apply_symbol(action:, exception:) if symbol?
+            return apply_string(exception:) if string?
+            return apply_exception_class(exception:) if exception_class?
+
+            handle_invalid(action:)
+          end
+
+          def callable? = @rule.respond_to?(:call)
+          def symbol? = @rule.is_a?(Symbol)
+          def string? = @rule.is_a?(String)
+          def exception_class? = @rule.is_a?(Class) && @rule <= Exception
+
+          def apply_callable(action:, exception:)
+            if exception && Invoker.accepts_exception_keyword?(@rule)
+              !!action.instance_exec(exception:, &@rule)
+            elsif exception && Invoker.accepts_positional_exception?(@rule)
+              !!action.instance_exec(exception, &@rule)
+            else
+              !!action.instance_exec(&@rule)
+            end
+          end
+
+          def apply_symbol(action:, exception:)
+            if action.respond_to?(@rule)
+              method = action.method(@rule)
+              if exception && Invoker.accepts_exception_keyword?(method)
+                !!action.public_send(@rule, exception:)
+              elsif exception && Invoker.accepts_positional_exception?(method)
+                !!action.public_send(@rule, exception)
+              else
+                !!action.public_send(@rule)
+              end
+            else
+              begin
+                klass = Object.const_get(@rule.to_s)
+                klass && exception.is_a?(klass)
+              rescue NameError
+                action.warn("Ignoring apparently-invalid matcher #{@rule.inspect} -- neither action method nor constant found")
+                false
+              end
+            end
+          end
+
+          def apply_string(exception:)
+            klass = Object.const_get(@rule.to_s)
+            klass && exception.is_a?(klass)
+          end
+
+          def apply_exception_class(exception:)
+            exception.is_a?(@rule)
+          end
+
+          def handle_invalid(action:)
+            action.warn("Ignoring apparently-invalid matcher #{@rule.inspect} -- could not find way to apply it")
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/message_handler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/base_handler"
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        class MessageHandler < BaseHandler
+          # Returns a string (truthy) when it applies and yields a non-blank message; otherwise nil
+          def apply(action:, exception:)
+            return nil unless matches?(action:, exception:)
+
+            value =
+              if handler.is_a?(Symbol) || handler.respond_to?(:call)
+                Invoker.call(action:, handler:, exception:, operation: "determining message callable")
+              else
+                handler
+              end
+            value.respond_to?(:presence) ? value.presence : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers/registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        # Small, immutable, copy-on-write registry keyed by event_type.
+        # Stores arrays of entries (handlers/interceptors) in insertion order.
+        class Registry
+          def self.empty = new({})
+
+          def initialize(index)
+            # Freeze arrays and the index for immutability
+            @index = index.transform_values { |arr| Array(arr).freeze }.freeze
+          end
+
+          # Always register most-recent-first (last-defined wins). Simpler mental model.
+          def register(event_type:, entry:)
+            key = event_type.to_sym
+            existing = Array(@index[key])
+            updated = [entry] + existing
+            self.class.new(@index.merge(key => updated.freeze))
+          end
+
+          def for(event_type)
+            Array(@index[event_type.to_sym])
+          end
+
+          def empty?
+            @index.empty?
+          end
+
+          protected
+
+          attr_reader :index
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow/handlers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+      end
+    end
+  end
+end
+
+require "action/core/flow/handlers/invoker"
+require "action/core/flow/handlers/registry"
+require "action/core/flow/handlers/matcher"
+require "action/core/flow/handlers/base_handler"
+require "action/core/flow/handlers/callback_handler"
+require "action/core/flow/handlers/message_handler"

data/lib/action/core/flow/messages.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers"
+
+module Action
+  module Core
+    module Flow
+      module Messages
+        def self.included(base)
+          base.class_eval do
+            class_attribute :_messages_registry, default: Action::Core::Flow::Handlers::Registry.empty
+
+            extend ClassMethods
+            include InstanceMethods
+          end
+        end
+
+        module ClassMethods
+          # Internal: resolve a message for the given event (conditional first, then static)
+          def _message_for(event_type, action:, exception: nil)
+            _conditional_message_for(event_type, action:, exception:) ||
+              _static_message_for(event_type, action:, exception:)
+          end
+
+          def _conditional_message_for(event_type, action:, exception: nil)
+            _messages_registry.for(event_type).each do |handler|
+              next if handler.respond_to?(:static?) && handler.static?
+
+              msg = handler.apply(action:, exception:)
+              return msg if msg.present?
+            end
+            nil
+          end
+
+          def _static_message_for(event_type, action:, exception: nil)
+            _messages_registry.for(event_type).each do |handler|
+              next unless handler.respond_to?(:static?) && handler.static?
+
+              msg = handler.apply(action:, exception:)
+              return msg if msg.present?
+            end
+            nil
+          end
+
+          def success(message = nil, **, &) = _add_message(:success, message:, **, &)
+          def error(message = nil, **, &) = _add_message(:error, message:, **, &)
+
+          def default_error = new.internal_context.default_error
+          def default_success = new.internal_context.default_success
+
+          private
+
+          def _add_message(kind, message:, **kwargs, &block)
+            raise ArgumentError, "#{kind} cannot be called with both :if and :unless" if kwargs.key?(:if) && kwargs.key?(:unless)
+
+            condition = kwargs.key?(:if) ? kwargs[:if] : kwargs[:unless]
+            raise ArgumentError, "Provide either a message or a block, not both" if message && block_given?
+            raise ArgumentError, "Provide a message or a block" unless message || block_given?
+
+            handler = block_given? ? block : message
+
+            matcher = condition.nil? ? nil : Action::Core::Flow::Handlers::Matcher.new(condition, invert: kwargs.key?(:unless))
+            entry = Action::Core::Flow::Handlers::MessageHandler.new(matcher:, handler:)
+            self._messages_registry = _messages_registry.register(event_type: kind, entry:)
+            true
+          end
+        end
+
+        module InstanceMethods
+          delegate :default_error, :default_success, to: :internal_context
+        end
+      end
+    end
+  end
+end