axn 0.1.0.pre.alpha.2.7.1 → 0.1.0.pre.alpha.2.8

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "action/core/flow/handlers"
+require "action/core/flow/handlers/resolvers/callback_resolver"
 
 module Action
   module Core
@@ -17,9 +18,13 @@ module Action
         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
+            resolver = Action::Core::Flow::Handlers::Resolvers::CallbackResolver.new(
+              _callbacks_registry,
+              event_type,
+              action:,
+              exception:,
+            )
+            resolver.execute_callbacks
           end
 
           # ONLY raised exceptions (i.e. NOT fail!).
@@ -39,14 +44,23 @@ module Action
 
           def _add_callback(event_type, handler: nil, block: nil, **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} cannot be called with both a block and a handler" if block && handler
             raise ArgumentError, "on_#{event_type} must be called with a block or symbol" unless block || handler
 
-            callback_handler = block || handler
-            matcher = condition.nil? ? nil : Action::Core::Flow::Handlers::Matcher.new(condition, invert: kwargs.key?(:unless))
-            entry = Action::Core::Flow::Handlers::CallbackHandler.new(matcher:, handler: callback_handler)
+            # If handler is already a descriptor, use it directly
+            entry = if handler.is_a?(Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+                      raise ArgumentError, "Cannot pass additional configuration with prebuilt descriptor" if kwargs.any? || block
+
+                      handler
+                    else
+                      Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor.build(
+                        handler: handler || block,
+                        **kwargs,
+                      )
+                    end
+
             self._callbacks_registry = _callbacks_registry.register(event_type:, entry:)
+            true
           end
         end
       end

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

@@ -33,6 +33,8 @@ module Action
           def _with_exception_handling
             yield
           rescue StandardError => e
+            @__context.__record_exception(e)
+
             # on_error handlers run for both unhandled exceptions and fail!
             self.class._dispatch_callbacks(:error, action: self, exception: e)
 
@@ -42,12 +44,7 @@ module Action
             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

data/lib/action/core/flow/handlers/{base_handler.rb → base_descriptor.rb}

@@ -8,15 +8,15 @@ module Action
       # "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
+        class BaseDescriptor
           def initialize(matcher: nil, handler: nil)
             @matcher = matcher
             @handler = handler
           end
 
-          attr_reader :handler
+          attr_reader :handler, :matcher
 
-          def static? = @matcher.nil?
+          def static? = @matcher.nil? || @matcher.static?
 
           def matches?(action:, exception:)
             return true if static?
@@ -24,7 +24,10 @@ module Action
             @matcher.call(exception:, action:)
           end
 
-          # Subclasses should implement `apply(action:, exception:)`
+          def self.build(handler: nil, if: nil, unless: nil, **)
+            matcher = Matcher.build(if:, unless:)
+            new(matcher:, handler:)
+          end
         end
       end
     end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/base_descriptor"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        module Descriptors
+          # Data structure for callback configuration - no behavior, just data
+          class CallbackDescriptor < BaseDescriptor
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/base_descriptor"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        module Descriptors
+          # Data structure for message configuration - no behavior, just data
+          class MessageDescriptor < BaseDescriptor
+            attr_reader :prefix
+
+            def initialize(matcher:, handler:, prefix: nil)
+              super(matcher:, handler:)
+              @prefix = prefix
+            end
+
+            def self.build(handler: nil, if: nil, unless: nil, prefix: nil, from: nil, **)
+              new(
+                handler:,
+                prefix:,
+                matcher: _build_matcher(if:, unless:, from:),
+              )
+            end
+
+            def self._build_matcher(if:, unless:, from:)
+              rules = [
+                binding.local_variable_get(:if),
+                binding.local_variable_get(:unless),
+                _build_rule_for_from_condition(from),
+              ].compact
+
+              Action::Core::Flow::Handlers::Matcher.new(rules, invert: !!binding.local_variable_get(:unless))
+            end
+
+            def self._build_rule_for_from_condition(from_class)
+              return nil unless from_class
+
+              if from_class.is_a?(String)
+                lambda { |exception:, **|
+                  exception.is_a?(Action::Failure) && exception.source&.class&.name == from_class
+                }
+              else
+                ->(exception:, **) { exception.is_a?(Action::Failure) && exception.source.is_a?(from_class) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,14 +6,15 @@ module Action
   module Core
     module Flow
       module Handlers
-        class Matcher
+        class SingleRuleMatcher
           def initialize(rule, invert: false)
             @rule = rule
             @invert = invert
           end
 
           def call(exception:, action:)
-            @invert ? !matches?(exception:, action:) : matches?(exception:, action:)
+            result = matches?(exception:, action:)
+            @invert ? !result : result
           rescue StandardError => e
             Axn::Util.piping_error("determining if handler applies to exception", action:, exception: e)
           end
@@ -79,6 +80,44 @@ module Action
             false
           end
         end
+
+        class Matcher
+          # NOTE: invert means it's an unless rather than an if.  This will apply to ALL rules (sufficient for current use case,
+          # but flagging if we ever extend this for complex matching)
+          def initialize(rules, invert: false)
+            @rules = Array(rules).compact
+            @invert = invert
+          end
+
+          def call(exception:, action:)
+            matches?(exception:, action:)
+          rescue StandardError => e
+            Axn::Util.piping_error("determining if handler applies to exception", action:, exception: e)
+          end
+
+          def static? = @rules.empty?
+          def invert? = !!@invert
+
+          # Class method to build matcher from kwargs
+          def self.build(if: nil, unless: nil)
+            if_condition = binding.local_variable_get(:if)
+            unless_condition = binding.local_variable_get(:unless)
+
+            raise Action::UnsupportedArgument, "providing both :if and :unless" if if_condition && unless_condition
+
+            new(Array(if_condition || unless_condition).compact, invert: !!unless_condition)
+          end
+
+          private
+
+          def matches?(exception:, action:)
+            return true if @rules.empty?
+
+            @rules.all? do |rule|
+              SingleRuleMatcher.new(rule, invert: @invert).call(exception:, action:)
+            end
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        module Resolvers
+          class BaseResolver
+            def initialize(registry, event_type, action:, exception:)
+              @registry = registry
+              @event_type = event_type
+              @action = action
+              @exception = exception
+            end
+
+            protected
+
+            attr_reader :registry, :event_type, :action, :exception
+
+            def candidate_entries = registry.for(event_type)
+            def matching_entries = candidate_entries.select { |descriptor| descriptor.matches?(action:, exception:) }
+            def static_entries = candidate_entries.select(&:static?)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        module Resolvers
+          # Internal: resolves and executes callbacks
+          class CallbackResolver < BaseResolver
+            def execute_callbacks
+              matching_entries.each do |descriptor|
+                execute_callback(descriptor)
+              end
+            end
+
+            private
+
+            # Executes a specific callback descriptor
+            def execute_callback(descriptor)
+              Invoker.call(operation: "executing callback", action:, handler: descriptor.handler, exception:)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "action/core/flow/handlers/invoker"
+
+module Action
+  module Core
+    module Flow
+      module Handlers
+        module Resolvers
+          # Internal: resolves messages with different strategies
+          class MessageResolver < BaseResolver
+            DEFAULT_ERROR = "Something went wrong"
+            DEFAULT_SUCCESS = "Action completed successfully"
+
+            def resolve_message
+              descriptor = matching_entries.detect { |d| message_from(d) }
+              message_from(descriptor) || fallback_message
+            end
+
+            def resolve_default_message
+              message_from(default_descriptor) || fallback_message
+            end
+
+            private
+
+            def default_descriptor
+              # NOTE: descriptor.handler check avoids returning a prefix-only descriptor (which
+              # needs to look up a default handler via this method to return a message)
+              static_entries.detect { |descriptor| descriptor.handler && message_from(descriptor) }
+            end
+
+            def message_from(descriptor)
+              message = resolved_message_body(descriptor)
+              return nil unless message.present?
+
+              descriptor.prefix ? "#{descriptor.prefix}#{message}" : message
+            end
+
+            def resolved_message_body(descriptor)
+              return nil unless descriptor
+
+              if descriptor.handler
+                invoke_handler(descriptor.handler)
+              elsif exception
+                exception.message
+              elsif descriptor.prefix
+                # For prefix-only success messages, find a default message from other descriptors
+                invoke_handler(default_descriptor&.handler)
+              end
+            end
+
+            def invoke_handler(handler) = handler ? Invoker.call(operation: "determining message callable", action:, handler:, exception:).presence : nil
+            def fallback_message = event_type == :success ? DEFAULT_SUCCESS : DEFAULT_ERROR
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -9,9 +9,12 @@ module Action
   end
 end
 
+require "action/core/flow/handlers/base_descriptor"
+require "action/core/flow/handlers/matcher"
+require "action/core/flow/handlers/resolvers/base_resolver"
+require "action/core/flow/handlers/descriptors/message_descriptor"
+require "action/core/flow/handlers/descriptors/callback_descriptor"
 require "action/core/flow/handlers/invoker"
+require "action/core/flow/handlers/resolvers/callback_resolver"
 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"
+require "action/core/flow/handlers/resolvers/message_resolver"

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

@@ -11,64 +11,38 @@ module Action
             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 Action::UnsupportedArgument, "calling #{kind} with both :if and :unless" if kwargs.key?(:if) && kwargs.key?(:unless)
+            raise Action::UnsupportedArgument, "Combining from: with if: or unless:" if kwargs.key?(:from) && (kwargs.key?(:if) || kwargs.key?(: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?
+            raise ArgumentError, "Provide a message, block, or prefix" unless message || block_given? || kwargs[:prefix]
+            raise ArgumentError, "from: only applies to error messages" if kwargs.key?(:from) && kind != :error
 
-            handler = block_given? ? block : message
+            # If message is already a descriptor, use it directly
+            entry = if message.is_a?(Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
+                      raise ArgumentError, "Cannot pass additional configuration with prebuilt descriptor" if kwargs.any? || block_given?
+
+                      message
+                    else
+                      Action::Core::Flow::Handlers::Descriptors::MessageDescriptor.build(
+                        handler: block_given? ? block : message,
+                        **kwargs,
+                      )
+                    end
 
-            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

data/lib/action/core/nesting_tracking.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module NestingTracking
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        def _nested_in_another_axn?
+          NestingTracking._current_axn_stack.any?
+        end
+      end
+
+      def _tracking_nesting(axn)
+        NestingTracking._current_axn_stack.push(axn)
+        yield
+      ensure
+        NestingTracking._current_axn_stack.pop
+      end
+
+      # Shared method for both class and instance access
+      def self._current_axn_stack
+        ActiveSupport::IsolatedExecutionState[:_axn_stack] ||= []
+      end
+    end
+  end
+end

data/lib/action/core/timing.rb

@@ -32,7 +32,7 @@ module Action
           yield
         ensure
           elapsed_mils = Core::Timing.elapsed_ms(timing_start)
-          @__context.elapsed_time = elapsed_mils
+          @__context.send(:elapsed_time=, elapsed_mils)
         end
       end
     end

data/lib/action/core.rb

@@ -5,11 +5,12 @@ require "action/context"
 require "action/strategies"
 require "action/core/hooks"
 require "action/core/logging"
-require "action/core/hoist_errors"
 require "action/core/flow"
 require "action/core/automatic_logging"
 require "action/core/use_strategy"
+require "action/core/timing"
 require "action/core/tracing"
+require "action/core/nesting_tracking"
 
 # CONSIDER: make class names match file paths?
 require "action/core/validation/validators/model_validator"
@@ -19,7 +20,6 @@ require "action/core/validation/validators/validate_validator"
 require "action/core/contract_validation"
 require "action/core/contract"
 require "action/core/contract_for_subfields"
-require "action/core/timing"
 
 module Action
   module Core
@@ -37,8 +37,8 @@ module Action
         include Core::ContractValidation
         include Core::Contract
         include Core::ContractForSubfields
+        include Core::NestingTracking
 
-        include Core::HoistErrors
         include Core::UseStrategy
       end
     end
@@ -52,7 +52,11 @@ module Action
         result = call(**)
         return result if result.ok?
 
-        raise result.exception || Action::Failure.new(result.error)
+        # When we're nested, we want to raise a failure that includes the source action to support
+        # the error message generation's `from` filter
+        raise Action::Failure.new(result.error, source: result.__action__), cause: result.exception if _nested_in_another_axn?
+
+        raise result.exception
       end
     end
 
@@ -62,13 +66,15 @@ module Action
 
     # Main entry point for action execution
     def _run
-      _with_tracing do
-        _with_logging do
-          _with_timing do
-            _with_exception_handling do # Exceptions stop here; outer wrappers access result status (and must not introduce another exception layer)
-              _with_contract do # Library internals -- any failures (e.g. contract violations) *should* fail the Action::Result
-                _with_hooks do # User hooks -- any failures here *should* fail the Action::Result
-                  call
+      _tracking_nesting(self) do
+        _with_tracing do
+          _with_logging do
+            _with_timing do
+              _with_exception_handling do # Exceptions stop here; outer wrappers access result status (and must not introduce another exception layer)
+                _with_contract do # Library internals -- any failures (e.g. contract violations) *should* fail the Action::Result
+                  _with_hooks do # User hooks -- any failures here *should* fail the Action::Result
+                    call
+                  end
                 end
               end
             end
@@ -82,7 +88,9 @@ module Action
     # User-defined action logic - override this method in your action classes
     def call; end
 
-    delegate :fail!, to: :@__context
+    def fail!(message = nil)
+      raise Action::Failure, message
+    end
 
     private
 

data/lib/action/exceptions.rb

@@ -5,15 +5,20 @@ module Action
   class Failure < StandardError
     DEFAULT_MESSAGE = "Execution was halted"
 
-    def initialize(message = nil, **)
+    attr_reader :source
+
+    def initialize(message = nil, source: nil)
+      @source = source
       @message = message
-      super(**)
+      super(message)
     end
 
     def message
       @message.presence || DEFAULT_MESSAGE
     end
 
+    def default_message? = message == DEFAULT_MESSAGE
+
     def inspect = "#<#{self.class.name} '#{message}'>"
   end
 
@@ -56,4 +61,17 @@ module Action
 
   class InboundValidationError < ValidationError; end
   class OutboundValidationError < ValidationError; end
+
+  class UnsupportedArgument < ArgumentError
+    def initialize(feature)
+      @feature = feature
+      super()
+    end
+
+    def message
+      "#{@feature} is not currently supported.\n\n" \
+        "Implementation is technically possible but very complex. " \
+        "Please submit a Github Issue if you have a real-world need for this functionality."
+    end
+  end
 end