axn 0.1.0.pre.alpha.2.7 → 0.1.0.pre.alpha.2.8

data/lib/action/context.rb

@@ -11,28 +11,24 @@ module Action
       # Framework-managed fields
       @failure = false
       @exception = nil
-      @error_from_user = nil
-      @error_prefix = nil
       @elapsed_time = nil
     end
 
-    def fail!(message = nil)
-      @error_from_user = message if message.present?
-      raise Action::Failure, message
-    end
-
-    # INTERNAL: base for further filtering (for logging) or providing user with usage hints
-    def __combined_data = @provided_data.merge(@exposed_data)
-
     # Framework state methods
     def ok? = !@failure
     def failed? = @failure || false
 
     # Framework field accessors
-    attr_accessor :exception, :error_from_user, :error_prefix, :elapsed_time
+    attr_accessor :elapsed_time
+    attr_reader :exception
+    private :elapsed_time=
 
-    # Internal failure state setter (for framework use)
-    attr_writer :failure
-    private :failure=
+    # INTERNAL: base for further filtering (for logging) or providing user with usage hints
+    def __combined_data = @provided_data.merge(@exposed_data)
+
+    def __record_exception(e)
+      @exception = e
+      @failure = true
+    end
   end
 end

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

@@ -15,7 +15,7 @@ module Action
 
       (@declared_fields + Array(implicitly_allowed_fields)).each do |field|
         singleton_class.define_method(field) do
-          context_data_source[field]
+          _context_data_source[field]
         end
       end
     end
@@ -34,6 +34,15 @@ module Action
 
     def action_name = @action.class.name.presence || "The action"
 
-    def context_data_source = raise NotImplementedError
+    def _context_data_source = raise NotImplementedError
+
+    def _msg_resolver(event_type, exception:)
+      Action::Core::Flow::Handlers::Resolvers::MessageResolver.new(
+        action._messages_registry,
+        event_type,
+        action:,
+        exception:,
+      )
+    end
   end
 end

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

@@ -22,8 +22,9 @@ module Action
       return unless facade.is_a?(Action::Result)
 
       return "[OK]" if context.ok?
-      unless context.exception
-        return context.error_from_user.present? ? "[failed with '#{context.error_from_user}']" : "[failed]"
+
+      if context.exception.is_a?(Action::Failure)
+        return context.exception.message.present? ? "[failed with '#{context.exception.message}']" : "[failed]"
       end
 
       %([failed with #{context.exception.class.name}: '#{context.exception.message}'])

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

@@ -5,20 +5,12 @@ 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
+    def default_error = _msg_resolver(:error, exception: Action::Failure.new).resolve_default_message
+    def default_success = _msg_resolver(:success, exception: nil).resolve_default_message
 
     private
 
-    def context_data_source = @context.provided_data
+    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)

data/lib/action/core/contract_validation.rb

@@ -13,7 +13,7 @@ module Action
           new_value = config.preprocess.call(initial_value)
           @__context.provided_data[config.field] = new_value
         rescue StandardError => e
-          raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}"
+          raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}", cause: e
         end
       end
 

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,35 +18,49 @@ 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!).
-          def on_exception(**, &block) = _add_callback(:exception, **, block:)
+          def on_exception(handler = nil, **, &block) = _add_callback(:exception, handler:, **, block:)
 
           # ONLY raised on fail! (i.e. NOT unhandled exceptions).
-          def on_failure(**, &block) = _add_callback(:failure, **, block:)
+          def on_failure(handler = nil, **, &block) = _add_callback(:failure, handler:, **, block:)
 
           # Handles both fail! and unhandled exceptions
-          def on_error(**, &block) = _add_callback(:error, **, block:)
+          def on_error(handler = nil, **, &block) = _add_callback(:error, handler:, **, 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:)
+          def on_success(handler = nil, **, &block) = _add_callback(:success, handler:, **, block:)
 
           private
 
-          def _add_callback(event_type, block:, **kwargs)
+          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)
+            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
 
-            condition = kwargs.key?(:if) ? kwargs[:if] : kwargs[:unless]
-            raise ArgumentError, "on_#{event_type} must be called with a block" unless block
+            # 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
 
-            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:)
+            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