axn 0.1.0.pre.alpha.2.5.3.1 → 0.1.0.pre.alpha.2.6

data/lib/action/core/handle_exceptions.rb

@@ -1,163 +1,143 @@
 # frozen_string_literal: true
 
-require_relative "event_handlers"
+# TODO: maybe namespace those under core?
+require "action/core/event_handlers"
 
 module Action
-  module HandleExceptions
-    def self.included(base)
-      base.class_eval do
-        class_attribute :_success_msg, :_error_msg
-        class_attribute :_custom_error_interceptors, default: []
-        class_attribute :_error_handlers, default: []
-        class_attribute :_exception_handlers, default: []
-        class_attribute :_failure_handlers, default: []
-
-        include InstanceMethods
-        extend ClassMethods
-
-        def run
-          run!
-        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)
-            @context.instance_variable_set("@error_from_user", e.message) if e.message.present?
-
-            self.class._failure_handlers.each do |handler|
-              handler.execute_if_matches(exception: e, action: self)
+  module Core
+    module HandleExceptions
+      def self.included(base)
+        base.class_eval do
+          class_attribute :_success_msg, :_error_msg
+          class_attribute :_custom_error_interceptors, default: []
+          class_attribute :_error_handlers, default: []
+          class_attribute :_exception_handlers, default: []
+          class_attribute :_failure_handlers, default: []
+          class_attribute :_success_handlers, default: []
+
+          include InstanceMethods
+          extend ClassMethods
+
+          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
-          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
+            # Call any global handlers
+            Action.config.on_exception(exception,
+                                       action: self,
+                                       context: respond_to?(:context_for_logging) ? context_for_logging : @context.to_h)
+          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
 
-          @context.instance_variable_set("@failure", true)
+          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
 
-        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
+      module ClassMethods
+        def messages(success: nil, error: nil)
+          self._success_msg = success if success.present?
+          self._error_msg = error if error.present?
 
-          # Call any global handlers
-          Action.config.on_exception(exception,
-                                     action: self,
-                                     context: respond_to?(:context_for_logging) ? context_for_logging : @context.to_h)
-        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)
+          true
         end
 
-        class << base
-          def call!(context = {})
-            result = call(context)
-            return result if result.ok?
-
-            raise result.exception || Action::Failure.new(result.error)
-          end
+        def error_from(matcher = nil, message = nil, **match_and_messages)
+          _register_error_interceptor(matcher, message, should_report_error: true, **match_and_messages)
         end
-      end
-    end
 
-    module ClassMethods
-      def messages(success: nil, error: nil)
-        self._success_msg = success if success.present?
-        self._error_msg = error if error.present?
+        def rescues(matcher = nil, message = nil, **match_and_messages)
+          _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
+        end
 
-        true
-      end
+        # 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?
 
-      def error_from(matcher = nil, message = nil, **match_and_messages)
-        _register_error_interceptor(matcher, message, should_report_error: true, **match_and_messages)
-      end
+          self._exception_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
+        end
 
-      def rescues(matcher = nil, message = nil, **match_and_messages)
-        _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
-      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?
 
-      # 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._failure_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
+        end
 
-        self._exception_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?
 
-      # 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._error_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
+        end
 
-        self._failure_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?
 
-      # 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?
+          # Prepend like after hooks - child handlers run before parent handlers
+          self._success_handlers = [handler] + _success_handlers
+        end
 
-        self._error_handlers += [Action::EventHandlers::ConditionalHandler.new(matcher:, handler:)]
-      end
+        def default_error = new.internal_context.default_error
 
-      # Syntactic sugar for "after { try" (after, but if it fails do NOT fail the action)
-      def on_success(&block)
-        raise ArgumentError, "on_success must be called with a block" unless block_given?
+        # Private helpers
 
-        after do
-          try { instance_exec(&block) }
+        def _error_interceptor_for(exception:, action:)
+          Array(_custom_error_interceptors).detect do |int|
+            int.matches?(exception:, action:)
+          end
         end
-      end
 
-      def default_error = new.internal_context.default_error
+        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
 
-      # Private helpers
+          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
 
-      def _error_interceptor_for(exception:, action:)
-        Array(_custom_error_interceptors).detect do |int|
-          int.matches?(exception:, action:)
+          self._custom_error_interceptors += interceptors
         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
+      module InstanceMethods
+        private
 
-        self._custom_error_interceptors += interceptors
-      end
-    end
-
-    module InstanceMethods
-      private
+        def fail!(message = nil)
+          @context.instance_variable_set("@failure", true)
+          @context.error_from_user = message if message.present?
 
-      def fail!(message = nil)
-        @context.instance_variable_set("@failure", true)
-        @context.error_from_user = message if message.present?
+          raise Action::Failure, message
+        end
 
-        raise Action::Failure, message
-      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
 
-      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)
+        delegate :default_error, to: :internal_context
       end
-
-      delegate :default_error, to: :internal_context
     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 default_log_level = Action.config.default_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: default_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,22 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module Timing
+      # 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
+    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