axn 0.1.0.pre.alpha.2.5.3.1 → 0.1.0.pre.alpha.2.6.1

data/lib/action/core/contract_validation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module ContractValidation
+      private
+
+      def _apply_inbound_preprocessing!
+        internal_field_configs.each do |config|
+          next unless config.preprocess
+
+          initial_value = @__context.provided_data[config.field]
+          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}"
+        end
+      end
+
+      def _validate_contract!(direction)
+        raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
+
+        configs = direction == :inbound ? internal_field_configs : external_field_configs
+        validations = configs.each_with_object({}) do |config, hash|
+          hash[config.field] = config.validations
+        end
+        context = direction == :inbound ? internal_context : result
+        exception_klass = direction == :inbound ? Action::InboundValidationError : Action::OutboundValidationError
+
+        Validation::Fields.validate!(validations:, context:, exception_klass:)
+      end
+
+      def _apply_defaults!(direction)
+        raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
+
+        if direction == :outbound
+          # For outbound defaults, first copy values from provided_data for fields that are both expected and exposed
+          external_field_configs.each do |config|
+            field = config.field
+            next if @__context.exposed_data[field].present? # Already has a value
+
+            @__context.exposed_data[field] = @__context.provided_data[field] if @__context.provided_data[field].present?
+          end
+        end
+
+        configs = direction == :inbound ? internal_field_configs : external_field_configs
+        defaults_mapping = configs.each_with_object({}) do |config, hash|
+          hash[config.field] = config.default
+        end.compact
+
+        defaults_mapping.each do |field, default_value_getter|
+          data_hash = direction == :inbound ? @__context.provided_data : @__context.exposed_data
+          next if data_hash[field].present?
+
+          default_value = default_value_getter.respond_to?(:call) ? instance_exec(&default_value_getter) : default_value_getter
+
+          data_hash[field] = default_value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "action/core/event_handlers"
+
+module Action
+  module Core
+    module Flow
+      module Callbacks
+        def self.included(base)
+          base.class_eval do
+            class_attribute :_error_handlers, default: []
+            class_attribute :_exception_handlers, default: []
+            class_attribute :_failure_handlers, default: []
+            class_attribute :_success_handlers, default: []
+
+            extend ClassMethods
+          end
+        end
+
+        module ClassMethods
+          # ONLY raised exceptions (i.e. NOT fail!). Skipped if exception is rescued via .rescues.
+          def on_exception(matcher = -> { true }, &handler)
+            raise ArgumentError, "on_exception must be called with a block" unless block_given?
+
+            self._exception_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
+          end
+
+          # ONLY raised on fail! (i.e. NOT unhandled exceptions).
+          def on_failure(matcher = -> { true }, &handler)
+            raise ArgumentError, "on_failure must be called with a block" unless block_given?
+
+            self._failure_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
+          end
+
+          # Handles both fail! and unhandled exceptions... but is NOT affected by .rescues
+          def on_error(matcher = -> { true }, &handler)
+            raise ArgumentError, "on_error must be called with a block" unless block_given?
+
+            self._error_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
+          end
+
+          # 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(&handler)
+            raise ArgumentError, "on_success must be called with a block" unless block_given?
+
+            # Prepend like after hooks - child handlers run before parent handlers
+            self._success_handlers = [handler] + _success_handlers
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module ExceptionExecution
+        def self.included(base)
+          base.class_eval do
+            include InstanceMethods
+
+            def _trigger_on_exception(exception)
+              interceptor = self.class._error_interceptor_for(exception:, action: self)
+              return if interceptor&.should_report_error == false
+
+              # Call any handlers registered on *this specific action* class
+              self.class._exception_handlers.each do |handler|
+                handler.execute_if_matches(exception:, action: self)
+              end
+
+              # Call any global handlers
+              Action.config.on_exception(exception, action: self, context: context_for_logging)
+            rescue StandardError => e
+              # No action needed -- downstream #on_exception implementation should ideally log any internal failures, but
+              # we don't want exception *handling* failures to cascade and overwrite the original exception.
+              Axn::Util.piping_error("executing on_exception hooks", action: self, exception: e)
+            end
+
+            def _trigger_on_success
+              # Call success handlers in child-first order (like after hooks)
+              self.class._success_handlers.each do |handler|
+                instance_exec(&handler)
+              rescue StandardError => e
+                # Log the error but continue with other handlers
+                Axn::Util.piping_error("executing on_success hook", action: self, exception: e)
+              end
+            end
+          end
+        end
+
+        module InstanceMethods
+          private
+
+          def _with_exception_handling
+            yield
+          rescue StandardError => e
+            # on_error handlers run for both unhandled exceptions and fail!
+            self.class._error_handlers.each do |handler|
+              handler.execute_if_matches(exception: e, action: self)
+            end
+
+            # on_failure handlers run ONLY for fail!
+            if e.is_a?(Action::Failure)
+              self.class._failure_handlers.each do |handler|
+                handler.execute_if_matches(exception: e, action: self)
+              end
+            else
+              # on_exception handlers run for ONLY for unhandled exceptions. AND NOTE: may be skipped if the exception is rescued via `rescues`.
+              _trigger_on_exception(e)
+
+              @__context.exception = e
+            end
+
+            # Set failure state using accessor method
+            @__context.send(:failure=, true)
+          end
+
+          def try
+            yield
+          rescue Action::Failure => e
+            # NOTE: re-raising so we can still fail! from inside the block
+            raise e
+          rescue StandardError => e
+            _trigger_on_exception(e)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Flow
+      module Messages
+        def self.included(base)
+          base.class_eval do
+            class_attribute :_success_msg, :_error_msg
+            class_attribute :_custom_error_interceptors, default: []
+
+            extend ClassMethods
+            include InstanceMethods
+          end
+        end
+
+        module ClassMethods
+          def messages(success: nil, error: nil)
+            self._success_msg = success if success.present?
+            self._error_msg = error if error.present?
+
+            true
+          end
+
+          def error_from(matcher = nil, message = nil, **match_and_messages)
+            _register_error_interceptor(matcher, message, should_report_error: true, **match_and_messages)
+          end
+
+          def rescues(matcher = nil, message = nil, **match_and_messages)
+            _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
+          end
+
+          def default_error = new.internal_context.default_error
+
+          # Private helpers
+
+          def _error_interceptor_for(exception:, action:)
+            Array(_custom_error_interceptors).detect do |int|
+              int.matches?(exception:, action:)
+            end
+          end
+
+          def _register_error_interceptor(matcher, message, should_report_error:, **match_and_messages)
+            method_name = should_report_error ? "error_from" : "rescues"
+            raise ArgumentError, "#{method_name} must be called with a key/value pair, or else keyword args" if [matcher, message].compact.size == 1
+
+            interceptors = { matcher => message }.compact.merge(match_and_messages).map do |(matcher, message)| # rubocop:disable Lint/ShadowingOuterLocalVariable
+              Action::EventHandlers::CustomErrorInterceptor.new(matcher:, message:, should_report_error:)
+            end
+
+            self._custom_error_interceptors += interceptors
+          end
+        end
+
+        module InstanceMethods
+          delegate :default_error, to: :internal_context
+        end
+      end
+    end
+  end
+end

data/lib/action/core/flow.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "action/core/flow/messages"
+require "action/core/flow/callbacks"
+require "action/core/flow/exception_execution"
+
+module Action
+  module Core
+    module Flow
+      def self.included(base)
+        base.class_eval do
+          include Messages
+          include Callbacks
+          include ExceptionExecution
+        end
+      end
+    end
+  end
+end

data/lib/action/core/hoist_errors.rb

@@ -1,55 +1,57 @@
 # frozen_string_literal: true
 
 module Action
-  module HoistErrors
-    def self.included(base)
-      base.class_eval do
-        include InstanceMethods
+  module Core
+    module HoistErrors
+      def self.included(base)
+        base.class_eval do
+          include InstanceMethods
+        end
       end
-    end
 
-    module InstanceMethods
-      private
+      module InstanceMethods
+        private
 
-      MinimalFailedResult = Data.define(:error, :exception) do
-        def ok? = false
-      end
-
-      # This method is used to ensure that the result of a block is successful before proceeding.
-      #
-      # Assumes success unless the block raises an exception or returns a failed result.
-      # (i.e. if you wrap logic that is NOT an action call, it'll be successful unless it raises an exception)
-      def hoist_errors(prefix: nil)
-        raise ArgumentError, "#hoist_errors must be given a block to execute" unless block_given?
-
-        result = begin
-          yield
-        rescue StandardError => e
-          log "hoist_errors block transforming a #{e.class.name} exception: #{e.message}"
-          MinimalFailedResult.new(error: nil, exception: e)
+        MinimalFailedResult = Data.define(:error, :exception) do
+          def ok? = false
         end
 
-        # This ensures the last line of hoist_errors was an Action call
-        #
-        # CAUTION: if there are multiple calls per block, only the last one will be checked!
+        # This method is used to ensure that the result of a block is successful before proceeding.
         #
-        unless result.respond_to?(:ok?)
-          raise ArgumentError,
-                "#hoist_errors is expected to wrap an Action call, but it returned a #{result.class.name} instead"
+        # Assumes success unless the block raises an exception or returns a failed result.
+        # (i.e. if you wrap logic that is NOT an action call, it'll be successful unless it raises an exception)
+        def hoist_errors(prefix: nil)
+          raise ArgumentError, "#hoist_errors must be given a block to execute" unless block_given?
+
+          result = begin
+            yield
+          rescue StandardError => e
+            log "hoist_errors block transforming a #{e.class.name} exception: #{e.message}"
+            MinimalFailedResult.new(error: nil, exception: e)
+          end
+
+          # This ensures the last line of hoist_errors was an Action call
+          #
+          # CAUTION: if there are multiple calls per block, only the last one will be checked!
+          #
+          unless result.respond_to?(:ok?)
+            raise ArgumentError,
+                  "#hoist_errors is expected to wrap an Action call, but it returned a #{result.class.name} instead"
+          end
+
+          return result if result.ok?
+
+          _handle_hoisted_errors(result, prefix:)
         end
 
-        return result if result.ok?
+        # Separate method to allow overriding in subclasses
+        def _handle_hoisted_errors(result, prefix: nil)
+          @__context.exception = result.exception if result.exception.present?
+          @__context.error_prefix = prefix if prefix.present?
 
-        _handle_hoisted_errors(result, prefix:)
-      end
-
-      # Separate method to allow overriding in subclasses
-      def _handle_hoisted_errors(result, prefix: nil)
-        @context.exception = result.exception if result.exception.present?
-        @context.error_prefix = prefix if prefix.present?
-
-        error = result.exception.is_a?(Action::Failure) ? result.exception.message : result.error
-        fail! error
+          error = result.exception.is_a?(Action::Failure) ? result.exception.message : result.error
+          fail! error
+        end
       end
     end
   end

data/lib/action/core/hooks.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Hooks
+      def self.included(base)
+        base.class_eval do
+          class_attribute :around_hooks, default: []
+          class_attribute :before_hooks, default: []
+          class_attribute :after_hooks, default: []
+
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        # Public: Declare hooks to run around action execution. The around
+        # method may be called multiple times; subsequent calls append declared
+        # hooks to existing around hooks.
+        #
+        # Around hooks wrap the entire action execution, including before and
+        # after hooks. Parent hooks wrap child hooks (parent outside, child inside).
+        #
+        # hooks - Zero or more Symbol method names representing instance methods
+        #         to be called around action execution. Each instance method
+        #         invocation receives an argument representing the next link in
+        #         the around hook chain.
+        # block - An optional block to be executed as a hook. If given, the block
+        #         is executed after methods corresponding to any given Symbols.
+        def around(*hooks, &block)
+          hooks << block if block
+          hooks.each { |hook| self.around_hooks += [hook] }
+        end
+
+        # Public: Declare hooks to run before action execution. The before
+        # method may be called multiple times; subsequent calls append declared
+        # hooks to existing before hooks.
+        #
+        # Before hooks run in parent-first order (general setup first, then specific).
+        # Parent hooks run before child hooks.
+        #
+        # hooks - Zero or more Symbol method names representing instance methods
+        #         to be called before action execution.
+        # block - An optional block to be executed as a hook. If given, the block
+        #         is executed after methods corresponding to any given Symbols.
+        def before(*hooks, &block)
+          hooks << block if block
+          hooks.each { |hook| self.before_hooks += [hook] }
+        end
+
+        # Public: Declare hooks to run after action execution. The after
+        # method may be called multiple times; subsequent calls prepend declared
+        # hooks to existing after hooks.
+        #
+        # After hooks run in child-first order (specific cleanup first, then general).
+        # Child hooks run before parent hooks.
+        #
+        # hooks - Zero or more Symbol method names representing instance methods
+        #         to be called after action execution.
+        # block - An optional block to be executed as a hook. If given, the block
+        #         is executed before methods corresponding to any given Symbols.
+        def after(*hooks, &block)
+          hooks << block if block
+          hooks.each { |hook| self.after_hooks = [hook] + after_hooks }
+        end
+      end
+
+      private
+
+      def _with_hooks
+        _run_around_hooks do
+          _run_before_hooks
+          yield
+          _run_after_hooks
+        end
+      end
+
+      # Around hooks are reversed before injection to ensure parent hooks wrap
+      # child hooks (parent outside, child inside).
+      def _run_around_hooks(&block)
+        self.class.around_hooks.reverse.inject(block) do |chain, hook|
+          proc { _run_hook(hook, chain) }
+        end.call
+      end
+
+      # Before hooks run in the order they were added (parent first, then child).
+      def _run_before_hooks
+        _run_hooks(self.class.before_hooks)
+      end
+
+      # After hooks are reversed to ensure child hooks run before parent hooks
+      # (specific cleanup first, then general).
+      def _run_after_hooks
+        _run_hooks(self.class.after_hooks.reverse)
+      end
+
+      # Internal: Run a collection of hooks. The "_run_hooks" method is the common
+      # interface by which collections of either before or after hooks are run.
+      #
+      # hooks - An Array of Symbol and Procs.
+      #
+      # Returns nothing.
+      def _run_hooks(hooks)
+        hooks.each { |hook| _run_hook(hook) }
+      end
+
+      # Internal: Run an individual hook. The "_run_hook" method is the common
+      # interface by which an individual hook is run. If the given hook is a
+      # symbol, the method is invoked whether public or private. If the hook is a
+      # proc, the proc is evaluated in the context of the current instance.
+      #
+      # hook - A Symbol or Proc hook.
+      # args - Zero or more arguments to be passed as block arguments into the
+      #        given block or as arguments into the method described by the given
+      #        Symbol method name.
+      #
+      # Returns nothing.
+      def _run_hook(hook, *)
+        hook.is_a?(Symbol) ? send(hook, *) : instance_exec(*, &hook)
+      end
+    end
+  end
+end

data/lib/action/core/logging.rb

@@ -3,33 +3,35 @@
 require "active_support/core_ext/module/delegation"
 
 module Action
-  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
+  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
-    end
 
-    module ClassMethods
-      def default_log_level = Action.config.default_log_level
+      module ClassMethods
+        def log_level = Action.config.log_level
 
-      def log(message, level: default_log_level, before: nil, after: nil)
-        msg = [_log_prefix, message].compact_blank.join(" ")
-        msg = [before, msg, after].compact_blank.join if before || after
+        def log(message, level: log_level, before: nil, after: nil)
+          msg = [_log_prefix, message].compact_blank.join(" ")
+          msg = [before, msg, after].compact_blank.join if before || after
 
-        Action.config.logger.send(level, msg)
-      end
+          Action.config.logger.send(level, msg)
+        end
 
-      LEVELS.each do |level|
-        define_method(level) do |message, before: nil, after: nil|
-          log(message, level:, before:, after:)
+        LEVELS.each do |level|
+          define_method(level) do |message, before: nil, after: nil|
+            log(message, level:, before:, after:)
+          end
         end
-      end
 
-      def _log_prefix = "[#{name.presence || "Anonymous Class"}]"
+        def _log_prefix = "[#{name.presence || "Anonymous Class"}]"
+      end
     end
   end
 end

data/lib/action/core/timing.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Timing
+      def self.included(base)
+        base.class_eval do
+          include InstanceMethods
+        end
+      end
+
+      # Get the current monotonic time
+      def self.now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Calculate elapsed time in milliseconds
+      def self.elapsed_ms(start_time)
+        ((now - start_time) * 1000).round(3)
+      end
+
+      # Calculate elapsed time in seconds
+      def self.elapsed_seconds(start_time)
+        (now - start_time).round(6)
+      end
+
+      module InstanceMethods
+        private
+
+        def _with_timing
+          timing_start = Core::Timing.now
+          yield
+        ensure
+          elapsed_mils = Core::Timing.elapsed_ms(timing_start)
+          @__context.elapsed_time = elapsed_mils
+        end
+      end
+    end
+  end
+end

data/lib/action/core/tracing.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Tracing
+      private
+
+      def _with_tracing(&)
+        return yield unless Action.config.wrap_with_trace
+
+        Action.config.wrap_with_trace.call(self.class.name || "AnonymousClass", &)
+      rescue StandardError => e
+        Axn::Util.piping_error("running trace hook", action: self, exception: e)
+      end
+    end
+  end
+end

data/lib/action/core/use_strategy.rb

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

data/lib/action/core/validation/fields.rb

@@ -15,6 +15,8 @@ module Action
       end
 
       def read_attribute_for_validation(attr)
+        # The context here is actually a facade (InternalContext or Result)
+        # which already handles reading from the correct data source
         @context.public_send(attr)
       end