axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.3

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

@@ -2,14 +2,24 @@
 
 require "active_model"
 
-module Action
+module Axn
   module Validators
     class ValidateValidator < ActiveModel::EachValidator
+      def self.apply_syntactic_sugar(value, _fields)
+        return value if value.is_a?(Hash)
+
+        { with: value }
+      end
+
+      def check_validity!
+        raise ArgumentError, "must supply :with" if options[:with].nil?
+      end
+
       def validate_each(record, attribute, value)
         msg = begin
           options[:with].call(value)
         rescue StandardError => e
-          Axn::Util.piping_error("applying custom validation on field '#{attribute}'", exception: e)
+          Axn::Internal::Logging.piping_error("applying custom validation on field '#{attribute}'", exception: e)
 
           "failed validation: #{e.message}"
         end

data/lib/axn/core.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "axn/internal/logging"
+
+require "axn/context"
+
+require "axn/strategies"
+require "axn/core/hooks"
+require "axn/core/logging"
+require "axn/core/flow"
+require "axn/core/automatic_logging"
+require "axn/core/use_strategy"
+require "axn/core/timing"
+require "axn/core/tracing"
+require "axn/core/profiling"
+require "axn/core/nesting_tracking"
+
+# CONSIDER: make class names match file paths?
+require "axn/core/validation/validators/model_validator"
+require "axn/core/validation/validators/type_validator"
+require "axn/core/validation/validators/validate_validator"
+
+require "axn/core/field_resolvers"
+require "axn/core/contract_validation"
+require "axn/core/contract_validation_for_subfields"
+require "axn/core/contract"
+require "axn/core/contract_for_subfields"
+
+module Axn
+  module Core
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        include Core::Hooks
+        include Core::Logging
+        include Core::AutomaticLogging
+        include Core::Tracing
+        include Core::Timing
+        include Core::Profiling
+
+        include Core::Flow
+
+        include Core::ContractValidation
+        include Core::ContractValidationForSubfields
+        include Core::Contract
+        include Core::ContractForSubfields
+        include Core::NestingTracking
+
+        include Core::UseStrategy
+      end
+    end
+
+    module ClassMethods
+      def call(**)
+        new(**).tap(&:_run).result
+      end
+
+      def call!(**)
+        result = call(**)
+        return result if result.ok?
+
+        # 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 Axn::Failure.new(result.error, source: result.__action__), cause: result.exception if _nested_in_another_axn?
+
+        raise result.exception
+      end
+    end
+
+    def initialize(**)
+      @__context = Axn::Context.new(**)
+    end
+
+    # Main entry point for action execution
+    def _run
+      _tracking_nesting(self) do
+        _with_profiling 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
+            end
+          end
+        end
+      end
+    ensure
+      _emit_metrics
+    end
+
+    # User-defined action logic - override this method in your action classes
+    def call; end
+
+    def fail!(message = nil, **exposures)
+      expose(**exposures) if exposures.any?
+      raise Axn::Failure, message
+    end
+
+    def done!(message = nil, **exposures)
+      expose(**exposures) if exposures.any?
+      raise Axn::Internal::EarlyCompletion, message
+    end
+
+    private
+
+    def _emit_metrics
+      return unless Axn.config.emit_metrics
+
+      Axn.config.emit_metrics.call(
+        self.class.name || "AnonymousClass",
+        result,
+      )
+    rescue StandardError => e
+      Axn::Internal::Logging.piping_error("running metrics hook", action: self, exception: e)
+    end
+  end
+end

data/lib/{action → axn}/exceptions.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
-module Action
-  # Raised internally when fail! is called
+module Axn
+  module Internal
+    # Internal only -- rescued before Axn::Result is returned
+    class EarlyCompletion < StandardError; end
+  end
+
+  # Raised when fail! is called
   class Failure < StandardError
     DEFAULT_MESSAGE = "Execution was halted"
 
@@ -22,6 +27,10 @@ module Action
     def inspect = "#<#{self.class.name} '#{message}'>"
   end
 
+  module Mountable
+    class MountingError < ArgumentError; end
+  end
+
   class ContractViolation < StandardError
     class ReservedAttributeError < ContractViolation
       def initialize(name)
@@ -34,6 +43,7 @@ module Action
 
     class MethodNotAllowed < ContractViolation; end
     class PreprocessingError < ContractViolation; end
+    class DefaultAssignmentError < ContractViolation; end
 
     class UnknownExposure < ContractViolation
       def initialize(key)

data/lib/axn/factory.rb

@@ -5,10 +5,15 @@ module Axn
     class << self
       # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
       def build(
+        callable = nil,
         # Builder-specific options
-        name: nil,
         superclass: nil,
-        expose_return_as: :nil,
+        expose_return_as: nil,
+
+        # Module inclusion options
+        include: [],
+        extend: [],
+        prepend: [],
 
         # Expose standard class-level options
         exposes: [],
@@ -30,19 +35,27 @@ module Axn
         # Strategies
         use: [],
 
+        # Async configuration
+        async: nil,
+
         &block
       )
-        args = block.parameters.each_with_object(_hash_with_default_array) { |(type, field), hash| hash[type] << field }
+        raise ArgumentError, "[Axn::Factory] Cannot receive both a callable and a block" if callable.present? && block_given?
+
+        executable = callable || block
+        raise ArgumentError, "[Axn::Factory] Must provide either a callable or a block" unless executable
+
+        args = executable.parameters.each_with_object(_hash_with_default_array) { |(type, field), hash| hash[type] << field }
 
         if args[:opt].present? || args[:req].present? || args[:rest].present?
           raise ArgumentError,
-                "[Axn::Factory] Cannot convert block to action: block expects positional arguments"
+                "[Axn::Factory] Cannot convert callable to action: callable expects positional arguments"
         end
-        raise ArgumentError, "[Axn::Factory] Cannot convert block to action: block expects a splat of keyword arguments" if args[:keyrest].present?
+        raise ArgumentError, "[Axn::Factory] Cannot convert callable to action: callable expects a splat of keyword arguments" if args[:keyrest].present?
 
         if args[:key].present?
           raise ArgumentError,
-                "[Axn::Factory] Cannot convert block to action: block expects keyword arguments with defaults (ruby does not allow introspecting)"
+                "[Axn::Factory] Cannot convert callable to action: callable expects keyword arguments with defaults (ruby does not allow introspecting)"
         end
 
         expects = _hydrate_hash(expects)
@@ -53,25 +66,7 @@ module Axn
         end
 
         # NOTE: inheriting from wrapping class, so we can set default values (e.g. for HTTP headers)
-        Class.new(superclass || Object) do
-          include Action unless self < Action
-
-          define_singleton_method(:name) do
-            [
-              superclass&.name.presence || "AnonymousAction",
-              name,
-            ].compact.join("#")
-          end
-
-          define_method(:call) do
-            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |field, hash|
-              hash[field] = public_send(field)
-            end
-
-            retval = instance_exec(**unwrapped_kwargs, &block)
-            expose(expose_return_as => retval) if expose_return_as.present?
-          end
-        end.tap do |axn|
+        _build_axn_class(superclass:, args:, executable:, expose_return_as:, include:, extend:, prepend:).tap do |axn|
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end
@@ -81,8 +76,8 @@ module Axn
           end
 
           # Apply success and error handlers
-          _apply_handlers(axn, :success, success, Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
-          _apply_handlers(axn, :error, error, Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
+          _apply_handlers(axn, :success, success, Axn::Core::Flow::Handlers::Descriptors::MessageDescriptor)
+          _apply_handlers(axn, :error, error, Axn::Core::Flow::Handlers::Descriptors::MessageDescriptor)
 
           # Hooks
           axn.before(before) if before.present?
@@ -90,10 +85,10 @@ module Axn
           axn.around(around) if around.present?
 
           # Callbacks
-          _apply_handlers(axn, :on_success, on_success, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
-          _apply_handlers(axn, :on_failure, on_failure, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
-          _apply_handlers(axn, :on_error, on_error, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
-          _apply_handlers(axn, :on_exception, on_exception, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_success, on_success, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_failure, on_failure, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_error, on_error, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_exception, on_exception, Axn::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
 
           # Strategies
           Array(use).each do |strategy|
@@ -110,8 +105,19 @@ module Axn
             end
           end
 
+          # Async configuration
+          unless async.nil?
+            async_array = Array(async)
+            # Skip async configuration if adapter is nil (but not if array is empty)
+            if !async_array.empty? && async_array[0].nil?
+              # Do nothing - skip async configuration
+            else
+              _apply_async_config(axn, async_array)
+            end
+          end
+
           # Default exposure
-          axn.exposes(expose_return_as, allow_blank: true) if expose_return_as.present?
+          axn.exposes(expose_return_as, optional: true) if expose_return_as.present?
         end
       end
       # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
@@ -138,16 +144,78 @@ module Axn
         return unless value.present?
 
         # Check if the value itself is a hash (this catches the case where someone passes a hash literal)
-        raise Action::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if value.is_a?(Hash)
+        raise Axn::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if value.is_a?(Hash)
 
         # Wrap in Array() to handle both single values and arrays
         Array(value).each do |handler|
-          raise Action::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if handler.is_a?(Hash)
+          raise Axn::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if handler.is_a?(Hash)
 
           # Both descriptor objects and simple cases (string/proc) can be used directly
           axn.public_send(method_name, handler)
         end
       end
+
+      def _build_axn_class(superclass:, args:, executable:, expose_return_as:, include: nil, extend: nil, prepend: nil)
+        Class.new(superclass || Object) do
+          include Axn unless self < Axn
+
+          Array(include).each { |mod| include mod }
+          Array(extend).each { |mod| extend mod }
+          Array(prepend).each { |mod| prepend mod }
+
+          # Set a default name for anonymous classes to help with debugging
+          define_singleton_method(:name) do
+            "AnonymousAxn_#{object_id}"
+          end
+
+          define_method(:call) do
+            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |field, hash|
+              hash[field] = public_send(field)
+            end
+
+            retval = instance_exec(**unwrapped_kwargs, &executable)
+            expose(expose_return_as => retval) if expose_return_as.present?
+          end
+        end
+      end
+
+      def _apply_async_config(axn, async)
+        raise ArgumentError, "[Axn::Factory] Invalid async configuration" unless _validate_async_config(async)
+
+        adapter, *config_args = async
+
+        # Determine hash config and callable config
+        config = config_args.find { |arg| arg.is_a?(Hash) }
+        block = config_args.find { |arg| arg.respond_to?(:call) }
+
+        # Call async once with the determined values
+        axn.async(adapter, **(config || {}), &block)
+      end
+
+      def _validate_async_config(async_array)
+        return false unless async_array.length.between?(1, 3)
+
+        adapter = async_array[0]
+        second_arg = async_array[1]
+        third_arg = async_array[2]
+
+        # First arg must be adapter (symbol/string), false, or nil
+        return false unless adapter.is_a?(Symbol) || adapter.is_a?(String) || adapter == false || adapter.nil?
+
+        case async_array.length
+        when 1
+          # Pattern A: [:sidekiq], [false], or [nil]
+          true
+        when 2
+          # Pattern B: [:sidekiq, hash_or_callable] or [nil, hash_or_callable]
+          second_arg.is_a?(Hash) || second_arg.respond_to?(:call)
+        when 3
+          # Pattern C: [:sidekiq, hash, callable] or [nil, hash, callable]
+          second_arg.is_a?(Hash) && third_arg.respond_to?(:call)
+        else
+          false
+        end
+      end
     end
   end
 end

data/lib/axn/internal/logging.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Axn
+  module Internal
+    module Logging
+      def self.piping_error(desc, exception:, action: nil)
+        # Extract just filename/line number from backtrace
+        src = exception.backtrace.first.split.first.split("/").last.split(":")[0, 2].join(":")
+
+        message = if Axn.config.env.production?
+                    "Ignoring exception raised while #{desc}: #{exception.class.name} - #{exception.message} (from #{src})"
+                  else
+                    msg = "!! IGNORING EXCEPTION RAISED WHILE #{desc.upcase} !!\n\n" \
+                          "\t* Exception: #{exception.class.name}\n" \
+                          "\t* Message: #{exception.message}\n" \
+                          "\t* From: #{src}"
+                    "#{"⌵" * 30}\n\n#{msg}\n\n#{"^" * 30}"
+                  end
+
+        (action || Axn.config.logger).send(:warn, message)
+
+        nil
+      end
+    end
+  end
+end

data/lib/axn/internal/registry.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module Axn
+  module Internal
+    class Registry
+      class NotFound < StandardError; end
+      class DuplicateError < StandardError; end
+
+      class << self
+        def built_in
+          @built_in ||= begin
+            # Get the directory name from the class name (e.g., "Strategies" -> "strategies")
+            dir_name = name.split("::").last.underscore
+
+            # Load all files from the directory
+            files = ::Dir[File.join(registry_directory, dir_name, "*.rb")]
+            files.each { |file| require file }
+
+            # Get all modules defined within this class
+            constants = self.constants.map { |const| const_get(const) }
+            items = select_constants_to_load(constants)
+
+            # Convert module names to keys
+            items.to_h do |item|
+              name = item.name.split("::").last
+              key = name.underscore.to_sym
+              [key, item]
+            end
+          end
+        end
+
+        def register(name, item)
+          items = all # ensure built_in is initialized
+          key = name.to_sym
+          raise duplicate_error_class, "#{item_type} #{name} already registered" if items.key?(key)
+
+          items[key] = item
+          items
+        end
+
+        def all
+          @items ||= built_in.dup
+        end
+
+        def clear!
+          @items = built_in.dup
+        end
+
+        def find(name)
+          raise not_found_error_class, "#{item_type} name cannot be nil" if name.nil?
+          raise not_found_error_class, "#{item_type} name cannot be empty" if name.to_s.strip.empty?
+
+          all[name.to_sym] or raise not_found_error_class, "#{item_type} '#{name}' not found"
+        end
+
+        private
+
+        def item_type
+          # Subclasses can override this for better error messages
+          "Item"
+        end
+
+        def not_found_error_class
+          # Subclasses can override this to return their specific error class
+          NotFound
+        end
+
+        def duplicate_error_class
+          # Subclasses can override this to return their specific error class
+          DuplicateError
+        end
+
+        def registry_directory
+          # Subclasses must override this to return their directory
+          raise NotImplementedError, "Subclasses must implement registry_directory method"
+        end
+
+        def select_constants_to_load(constants)
+          # Subclasses can override this to select which constants to load
+          constants.select { |const| const.is_a?(Module) }
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/descriptor.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    # Descriptor holds the information needed to mount an action
+    class Descriptor
+      attr_reader :name, :options, :mounted_axn, :mount_strategy, :existing_axn_klass, :block, :raw_kwargs, :kwargs
+
+      def initialize(name:, as:, axn_klass: nil, block: nil, kwargs: {})
+        @mount_strategy = MountingStrategies.find(as)
+        @existing_axn_klass = axn_klass
+
+        @name = name
+        @block = block
+        @raw_kwargs = kwargs
+
+        @kwargs = mount_strategy.preprocess_kwargs(**kwargs.except(*mount_strategy.strategy_specific_kwargs), axn_klass:)
+        @options = kwargs.slice(*mount_strategy.strategy_specific_kwargs)
+
+        @validator = Helpers::Validator.new(self)
+
+        @validator.validate!
+        freeze
+      end
+
+      def mount(target:)
+        validate_before_mount!(target:)
+        mount_strategy.mount(descriptor: self, target:)
+      end
+
+      def mounted_axn_for(target:)
+        # Check if the target already has this action class cached
+        cache_key = "#{@name}_#{object_id}_#{target.object_id}"
+
+        # Use a class variable to store the cache on the target
+        cache_var = :@_axn_cache
+        target.instance_variable_set(cache_var, {}) unless target.instance_variable_defined?(cache_var)
+        cache = target.instance_variable_get(cache_var)
+
+        return cache[cache_key] if cache.key?(cache_key)
+
+        # Check if constant is already registered
+        action_class_builder = Helpers::ClassBuilder.new(self)
+        namespace = Helpers::NamespaceManager.get_or_create_namespace(target)
+        constant_name = action_class_builder.generate_constant_name(@name.to_s)
+        if namespace.const_defined?(constant_name, false)
+          mounted_axn = namespace.const_get(constant_name)
+          cache[cache_key] = mounted_axn
+          return mounted_axn
+        end
+
+        # Build and configure action class
+        mounted_axn = action_class_builder.build_and_configure_action_class(target, @name.to_s, namespace)
+
+        # Cache on the target
+        cache[cache_key] = mounted_axn
+        mounted_axn
+      end
+
+      def mounted? = @mounted_axn.present?
+
+      private
+
+      def method_name = @name.to_s.underscore
+
+      def validate_before_mount!(target:)
+        # Method name collision validation is now handled in mount_axn
+        # This method is kept for potential future validation needs
+      end
+
+      def mounting_type_name
+        mount_strategy.name.split("::").last.underscore.to_s.humanize
+      end
+    end
+  end
+end