axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/lib/{action → axn}/core/flow/handlers/descriptors/callback_descriptor.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers/base_descriptor"
+require "axn/core/flow/handlers/base_descriptor"
 
-module Action
+module Axn
   module Core
     module Flow
       module Handlers

data/lib/{action → axn}/core/flow/handlers/descriptors/message_descriptor.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers/base_descriptor"
+require "axn/core/flow/handlers/base_descriptor"
 
-module Action
+module Axn
   module Core
     module Flow
       module Handlers
@@ -12,8 +12,8 @@ module Action
             attr_reader :prefix
 
             def initialize(matcher:, handler:, prefix: nil)
-              super(matcher:, handler:)
               @prefix = prefix
+              super(matcher:, handler:)
             end
 
             def self.build(handler: nil, if: nil, unless: nil, prefix: nil, from: nil, **)
@@ -31,19 +31,31 @@ module Action
                 _build_rule_for_from_condition(from),
               ].compact
 
-              Action::Core::Flow::Handlers::Matcher.new(rules, invert: !!binding.local_variable_get(:unless))
+              Axn::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
+              # Special case: `from: true` means "from any child action"
+              return ->(exception:, **) { exception.is_a?(Axn::Failure) && exception.source } if from_class == true
+
+              from_classes = Array(from_class)
+              lambda { |exception:, **|
+                return false unless exception.is_a?(Axn::Failure) && exception.source
+
+                source = exception.source
+                from_classes.any? do |cls|
+                  if cls.is_a?(String)
+                    # rubocop:disable Style/ClassEqualityComparison
+                    # We're comparing class name strings, not classes themselves
+                    source.class.name == cls
+                    # rubocop:enable Style/ClassEqualityComparison
+                  else
+                    source.is_a?(cls)
+                  end
+                end
+              }
             end
           end
         end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Axn
+  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::Internal::Logging.piping_error(operation, action:, exception: e)
+          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, true)
+              action.warn("Ignoring apparently-invalid symbol #{symbol.inspect} -- action does not respond to method")
+              return nil
+            end
+
+            method = action.method(symbol)
+            filtered_args, filtered_kwargs = Axn::Util::Callable.only_requested_params_for_exception(method, exception)
+            action.send(symbol, *filtered_args, **filtered_kwargs)
+          end
+
+          def call_callable_handler(action:, callable:, exception: nil)
+            filtered_args, filtered_kwargs = Axn::Util::Callable.only_requested_params_for_exception(callable, exception)
+            action.instance_exec(*filtered_args, **filtered_kwargs, &callable)
+          end
+
+          def literal_value(value) = value
+        end
+      end
+    end
+  end
+end

data/lib/{action → axn}/core/flow/handlers/matcher.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers/invoker"
+require "axn/core/flow/handlers/invoker"
 
-module Action
+module Axn
   module Core
     module Flow
       module Handlers
@@ -16,7 +16,7 @@ module Action
             result = matches?(exception:, action:)
             @invert ? !result : result
           rescue StandardError => e
-            Axn::Util.piping_error("determining if handler applies to exception", action:, exception: e)
+            Axn::Internal::Logging.piping_error("determining if handler applies to exception", action:, exception: e)
           end
 
           private
@@ -36,25 +36,15 @@ module Action
           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
+            filtered_args, filtered_kwargs = Axn::Util::Callable.only_requested_params_for_exception(@rule, exception)
+            !!action.instance_exec(*filtered_args, **filtered_kwargs, &@rule)
           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
+              filtered_args, filtered_kwargs = Axn::Util::Callable.only_requested_params_for_exception(method, exception)
+              !!action.public_send(@rule, *filtered_args, **filtered_kwargs)
             else
               begin
                 klass = Object.const_get(@rule.to_s)
@@ -92,7 +82,7 @@ module Action
           def call(exception:, action:)
             matches?(exception:, action:)
           rescue StandardError => e
-            Axn::Util.piping_error("determining if handler applies to exception", action:, exception: e)
+            Axn::Internal::Logging.piping_error("determining if handler applies to exception", action:, exception: e)
           end
 
           def static? = @rules.empty?
@@ -103,7 +93,7 @@ module Action
             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
+            raise Axn::UnsupportedArgument, "providing both :if and :unless" if if_condition && unless_condition
 
             new(Array(if_condition || unless_condition).compact, invert: !!unless_condition)
           end

data/lib/{action → axn}/core/flow/handlers/registry.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   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.
+        #
+        # NOTE: serves different need than user-mutable e.g. Axn::Async::Adapters
         class Registry
           def self.empty = new({})
 

data/lib/{action → axn}/core/flow/handlers/resolvers/base_resolver.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Core
     module Flow
       module Handlers

data/lib/{action → axn}/core/flow/handlers/resolvers/callback_resolver.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers/invoker"
+require "axn/core/flow/handlers/invoker"
 
-module Action
+module Axn
   module Core
     module Flow
       module Handlers

data/lib/{action → axn}/core/flow/handlers/resolvers/message_resolver.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers/invoker"
+require "axn/core/flow/handlers/invoker"
 
-module Action
+module Axn
   module Core
     module Flow
       module Handlers
@@ -33,7 +33,7 @@ module Action
               message = resolved_message_body(descriptor)
               return nil unless message.present?
 
-              descriptor.prefix ? "#{descriptor.prefix}#{message}" : message
+              "#{resolved_prefix(descriptor)}#{message}"
             end
 
             def resolved_message_body(descriptor)
@@ -49,6 +49,15 @@ module Action
               end
             end
 
+            def resolved_prefix(descriptor)
+              return nil unless descriptor.prefix
+              return descriptor.prefix if descriptor.prefix.is_a?(String)
+
+              Invoker.call(action:, handler: descriptor.prefix, exception:, operation: "determining prefix callable")
+            rescue StandardError
+              nil
+            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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module Flow
+      module Handlers
+      end
+    end
+  end
+end
+
+require "axn/core/flow/handlers/base_descriptor"
+require "axn/core/flow/handlers/matcher"
+require "axn/core/flow/handlers/resolvers/base_resolver"
+require "axn/core/flow/handlers/descriptors/message_descriptor"
+require "axn/core/flow/handlers/descriptors/callback_descriptor"
+require "axn/core/flow/handlers/invoker"
+require "axn/core/flow/handlers/resolvers/callback_resolver"
+require "axn/core/flow/handlers/registry"
+require "axn/core/flow/handlers/resolvers/message_resolver"

data/lib/{action → axn}/core/flow/messages.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-require "action/core/flow/handlers"
+require "axn/core/flow/handlers"
 
-module Action
+module Axn
   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
+            class_attribute :_messages_registry, default: Axn::Core::Flow::Handlers::Registry.empty
 
             extend ClassMethods
           end
@@ -21,19 +21,19 @@ module Action
           private
 
           def _add_message(kind, message:, **kwargs, &block)
-            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 Axn::UnsupportedArgument, "calling #{kind} with both :if and :unless" if kwargs.key?(:if) && kwargs.key?(:unless)
+            raise Axn::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, block, or prefix" unless message || block_given? || kwargs[:prefix]
+            raise ArgumentError, "Provide a message, block, or prefix" unless message || block_given? || kwargs[:prefix] || kwargs[:from]
             raise ArgumentError, "from: only applies to error messages" if kwargs.key?(:from) && kind != :error
 
             # If message is already a descriptor, use it directly
-            entry = if message.is_a?(Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
+            entry = if message.is_a?(Axn::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(
+                      Axn::Core::Flow::Handlers::Descriptors::MessageDescriptor.build(
                         handler: block_given? ? block : message,
                         **kwargs,
                       )

data/lib/{action → axn}/core/flow.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require "action/core/flow/messages"
-require "action/core/flow/callbacks"
-require "action/core/flow/exception_execution"
+require "axn/core/flow/messages"
+require "axn/core/flow/callbacks"
+require "axn/core/flow/exception_execution"
 
-module Action
+module Axn
   module Core
     module Flow
       def self.included(base)

data/lib/{action → axn}/core/hooks.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Core
     module Hooks
       def self.included(base)
@@ -68,10 +68,15 @@ module Action
       private
 
       def _with_hooks
-        _run_around_hooks do
-          _run_before_hooks
-          yield
-          _run_after_hooks
+        # Outer is needed in the unlikely case done! is called in around hooks
+        __respecting_early_completion do
+          _run_around_hooks do
+            __respecting_early_completion do
+              _run_before_hooks
+              yield
+              _run_after_hooks
+            end
+          end
         end
       end
 
@@ -118,6 +123,13 @@ module Action
       def _run_hook(hook, *)
         hook.is_a?(Symbol) ? send(hook, *) : instance_exec(*, &hook)
       end
+
+      def __respecting_early_completion
+        yield
+      rescue Axn::Internal::EarlyCompletion => e
+        @__context.__record_early_completion(e.message)
+        raise e
+      end
     end
   end
 end

data/lib/axn/core/logging.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+module Axn
+  module Core
+    module Logging
+      LEVELS = %i[debug info warn error fatal].freeze
+
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+          delegate :log, *LEVELS, to: :class
+        end
+      end
+
+      module ClassMethods
+        def log_level = Axn.config.log_level
+
+        # @param message [String] The message to log
+        # @param level [Symbol] The log level (default: log_level)
+        # @param before [String, nil] Text to prepend to the message
+        # @param after [String, nil] Text to append to the message
+        # @param prefix [String, nil] Override the default prefix (useful for class-level logging)
+        def log(message, level: log_level, before: nil, after: nil, prefix: nil)
+          resolved_prefix = prefix.nil? ? _log_prefix : prefix
+          msg = [resolved_prefix, message].compact_blank.join(" ")
+          msg = [before, msg, after].compact_blank.join if before || after
+
+          Axn.config.logger.send(level, msg)
+        end
+
+        LEVELS.each do |level|
+          define_method(level) do |message, before: nil, after: nil, prefix: nil|
+            log(message, level:, before:, after:, prefix:)
+          end
+        end
+
+        def _log_prefix
+          names = NestingTracking._current_axn_stack.map do |axn|
+            axn.class.name.presence || "Anonymous Class"
+          end
+          "[#{names.join(' > ')}]"
+        end
+      end
+    end
+  end
+end

data/lib/axn/core/memoization.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module Memoization
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        def memo(method_name)
+          if _memo_wise_available?
+            _ensure_memo_wise_prepended
+            memo_wise(method_name)
+          else
+            _memo_minimal(method_name)
+          end
+        end
+
+        private
+
+        def _memo_wise_available?
+          defined?(MemoWise)
+        end
+
+        def _ensure_memo_wise_prepended
+          return if ancestors.include?(MemoWise)
+
+          prepend MemoWise
+        end
+
+        def _memo_minimal(method_name)
+          method = instance_method(method_name)
+          params = method.parameters
+          has_args = params.any? { |type, _name| %i[req opt rest keyreq key keyrest].include?(type) }
+
+          if has_args
+            raise ArgumentError,
+                  "Memoization of methods with arguments requires the 'memo_wise' gem. " \
+                  "Please add 'memo_wise' to your Gemfile or use a method without arguments."
+          end
+
+          # Wrap the method with memoization
+          Axn::Util::Memoization.define_memoized_reader_method(self, method_name) do
+            method.bind(self).call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/{action → axn}/core/nesting_tracking.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Core
     module NestingTracking
       def self.included(base)

data/lib/{action → axn}/core/timing.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Core
     module Timing
       def self.included(base)

data/lib/axn/core/tracing.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Axn
+  module Core
+    module Tracing
+      class << self
+        # Cache the tracer instance to avoid repeated lookups
+        # The tracer provider may cache internally, but we avoid the method call overhead
+        # We check defined?(OpenTelemetry) each time to handle cases where it's loaded lazily
+        def tracer
+          return nil unless defined?(OpenTelemetry)
+
+          # Re-fetch if the tracer provider has changed (e.g., in tests with mocks)
+          current_provider = OpenTelemetry.tracer_provider
+          return @tracer if defined?(@tracer) && defined?(@tracer_provider) && @tracer_provider == current_provider
+
+          @tracer_provider = current_provider
+          @tracer = current_provider.tracer("axn", Axn::VERSION)
+        end
+      end
+
+      private
+
+      def _with_tracing(&)
+        resource = self.class.name || "AnonymousClass"
+        payload = { resource:, action: self }
+
+        update_payload = proc do
+          result = self.result
+          outcome = result.outcome.to_s
+          payload[:outcome] = outcome
+          payload[:result] = result
+          payload[:elapsed_time] = result.elapsed_time
+          payload[:exception] = result.exception if result.exception
+        rescue StandardError => e
+          # Don't raise in ensure block to avoid interfering with existing exceptions
+          Axn::Internal::Logging.piping_error("updating notification payload while tracing axn.call", action: self, exception: e)
+        end
+
+        instrument_block = proc do
+          ActiveSupport::Notifications.instrument("axn.call", payload, &)
+        ensure
+          # Update payload BEFORE instrument completes so subscribers see the changes
+          update_payload.call
+        end
+
+        # NOTE: despite using block form, ActiveSupport explicitly only emits to subscribers when it's finished,
+        # which means it's not suitable for wrapping execution with a span and tracking child spans.
+        # We use OpenTelemetry for that, if available.
+        if defined?(OpenTelemetry)
+          Tracing.tracer.in_span("axn.call", attributes: { "axn.resource" => resource }) do |span|
+            instrument_block.call
+          ensure
+            # Update span with outcome and error status after execution
+            # This ensure runs before the span finishes, so we can still update it
+            begin
+              result = self.result
+              outcome = result.outcome.to_s
+              span.set_attribute("axn.outcome", outcome)
+
+              if %w[failure exception].include?(outcome) && result.exception
+                span.record_exception(result.exception)
+                error_message = result.exception.message || result.exception.class.name
+                span.status = OpenTelemetry::Trace::Status.error(error_message)
+              end
+            rescue StandardError => e
+              # Don't raise in ensure block to avoid interfering with existing exceptions
+              Axn::Internal::Logging.piping_error("updating OTel span while tracing axn.call", action: self, exception: e)
+            end
+          end
+        else
+          instrument_block.call
+        end
+      ensure
+        begin
+          emit_metrics_proc = Axn.config.emit_metrics
+          if emit_metrics_proc
+            result = self.result
+            Axn::Util::Callable.call_with_desired_shape(emit_metrics_proc, kwargs: { resource:, result: })
+          end
+        rescue StandardError => e
+          # Don't raise in ensure block to avoid interfering with existing exceptions
+          Axn::Internal::Logging.piping_error("calling emit_metrics while tracing axn.call", action: self, exception: e)
+        end
+      end
+    end
+  end
+end

data/lib/axn/core/use_strategy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module UseStrategy
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def use(strategy_name, **config, &block)
+          strategy = Axn::Strategies.find(strategy_name)
+          raise ArgumentError, "Strategy #{strategy_name} does not support config" if config.any? && !strategy.respond_to?(:configure)
+
+          # Allow dynamic configuration of strategy (i.e. dynamically define module before returning)
+          if strategy.respond_to?(:configure)
+            configured = strategy.configure(**config, &block)
+            raise ArgumentError, "Strategy #{strategy_name} configure method must return a module" unless configured.is_a?(Module)
+
+            strategy = configured
+          else
+            raise ArgumentError, "Strategy #{strategy_name} does not support config (define #configure method)" if config.any?
+            raise ArgumentError, "Strategy #{strategy_name} does not support blocks (define #configure method)" if block_given?
+          end
+
+          include strategy
+        end
+      end
+    end
+  end
+end

data/lib/{action → axn}/core/validation/fields.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Validation
     class Fields
       include ActiveModel::Validations
@@ -20,9 +20,25 @@ module Action
         @context.public_send(attr)
       end
 
+      def method_missing(method_name, ...)
+        # Delegate method calls to the action instance to support symbol-based validations
+        # like inclusion: { in: :valid_channels_for_number }
+        action = _action_for_validation
+        return super unless action && action.respond_to?(method_name, true) # rubocop:disable Style/SafeNavigation
+
+        action.send(method_name, ...)
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        action = _action_for_validation
+        return super unless action
+
+        action.respond_to?(method_name, include_private) || super
+      end
+
       def self.validate!(validations:, context:, exception_klass:)
         validator = Class.new(self) do
-          def self.name = "Action::Validation::Fields::OneOff"
+          def self.name = "Axn::Validation::Fields::OneOff"
 
           validations.each do |field, field_validations|
             field_validations.each do |key, value|
@@ -35,6 +51,14 @@ module Action
 
         raise exception_klass, validator.errors
       end
+
+      private
+
+      def _action_for_validation
+        return unless @context.respond_to?(:action, true)
+
+        @context.send(:action)
+      end
     end
   end
 end