axn 0.1.0.pre.alpha.2.6 → 0.1.0.pre.alpha.2.6.1

data/lib/action/core/contract_validation.rb

@@ -9,9 +9,9 @@ module Action
         internal_field_configs.each do |config|
           next unless config.preprocess
 
-          initial_value = @context.public_send(config.field)
+          initial_value = @__context.provided_data[config.field]
           new_value = config.preprocess.call(initial_value)
-          @context.public_send("#{config.field}=", new_value)
+          @__context.provided_data[config.field] = new_value
         rescue StandardError => e
           raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}"
         end
@@ -33,17 +33,28 @@ module Action
       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|
-          next if @context.public_send(field).present?
+          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
 
-          @context.public_send("#{field}=", default_value)
+          data_hash[field] = default_value
         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

@@ -46,8 +46,8 @@ module Action
 
         # 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?
+          @__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

data/lib/action/core/hooks.rb

@@ -67,44 +67,44 @@ module Action
 
       private
 
-      def with_hooks
-        run_around_hooks do
-          run_before_hooks
+      def _with_hooks
+        _run_around_hooks do
+          _run_before_hooks
           yield
-          run_after_hooks
+          _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)
+      def _run_around_hooks(&block)
         self.class.around_hooks.reverse.inject(block) do |chain, hook|
-          proc { run_hook(hook, chain) }
+          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)
+      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)
+      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
+      # 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) }
+      def _run_hooks(hooks)
+        hooks.each { |hook| _run_hook(hook) }
       end
 
-      # Internal: Run an individual hook. The "run_hook" method is the common
+      # 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.
@@ -115,7 +115,7 @@ module Action
       #        Symbol method name.
       #
       # Returns nothing.
-      def run_hook(hook, *)
+      def _run_hook(hook, *)
         hook.is_a?(Symbol) ? send(hook, *) : instance_exec(*, &hook)
       end
     end

data/lib/action/core/logging.rb

@@ -15,9 +15,9 @@ module Action
       end
 
       module ClassMethods
-        def default_log_level = Action.config.default_log_level
+        def log_level = Action.config.log_level
 
-        def log(message, level: default_log_level, before: nil, after: nil)
+        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
 

data/lib/action/core/timing.rb

@@ -3,6 +3,12 @@
 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)
@@ -17,6 +23,18 @@ module Action
       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/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
 

data/lib/action/core.rb

@@ -6,9 +6,10 @@ require "action/strategies"
 require "action/core/hooks"
 require "action/core/logging"
 require "action/core/hoist_errors"
-require "action/core/handle_exceptions"
+require "action/core/flow"
 require "action/core/automatic_logging"
 require "action/core/use_strategy"
+require "action/core/tracing"
 
 # CONSIDER: make class names match file paths?
 require "action/core/validation/validators/model_validator"
@@ -28,8 +29,10 @@ module Action
         include Core::Hooks
         include Core::Logging
         include Core::AutomaticLogging
+        include Core::Tracing
+        include Core::Timing
 
-        include Core::HandleExceptions
+        include Core::Flow
 
         include Core::ContractValidation
         include Core::Contract
@@ -41,84 +44,32 @@ module Action
     end
 
     module ClassMethods
-      def call(context = {})
-        new(context).tap(&:run).result
+      def call(**)
+        new(**).tap(&:_run).result
       end
 
-      def call!(context = {})
-        result = call(context)
+      def call!(**)
+        result = call(**)
         return result if result.ok?
 
         raise result.exception || Action::Failure.new(result.error)
       end
     end
 
-    def initialize(context = {})
-      @context = Action::Context.build(context)
+    def initialize(**)
+      @__context = Action::Context.new(**)
     end
 
-    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
-
-    def with_logging
-      timing_start = Core::Timing.now
-      _log_before
-      yield
-    ensure
-      _log_after(timing_start:, outcome: _determine_outcome)
-    end
-
-    def with_contract
-      _apply_inbound_preprocessing!
-      _apply_defaults!(:inbound)
-      _validate_contract!(:inbound)
-
-      yield
-
-      _apply_defaults!(:outbound)
-      _validate_contract!(:outbound)
-
-      # TODO: improve location of this triggering
-      trigger_on_success if respond_to?(:trigger_on_success)
-    end
-
-    def with_exception_swallowing
-      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)
-        @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)
-        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
-
-      @context.instance_variable_set("@failure", true)
-    end
-
-    def run
-      with_tracing do
-        with_logging do
-          with_exception_swallowing 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
+    # Main entry point for action execution
+    def _run
+      _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
@@ -128,8 +79,11 @@ module Action
       _emit_metrics
     end
 
+    # User-defined action logic - override this method in your action classes
     def call; end
 
+    delegate :fail!, to: :@__context
+
     private
 
     def _emit_metrics
@@ -137,17 +91,10 @@ module Action
 
       Action.config.emit_metrics.call(
         self.class.name || "AnonymousClass",
-        _determine_outcome,
+        result,
       )
     rescue StandardError => e
       Axn::Util.piping_error("running metrics hook", action: self, exception: e)
     end
-
-    def _determine_outcome
-      return "exception" if @context.exception
-      return "failure" if @context.failure?
-
-      "success"
-    end
   end
 end

data/lib/action/enqueueable/via_sidekiq.rb

@@ -18,9 +18,9 @@ module Action
             bang = args.size > 1 ? args.last : false
 
             if bang
-              self.class.call!(context)
+              self.class.call!(**context)
             else
-              self.class.call(context)
+              self.class.call(**context)
             end
           end
 

data/lib/action/result.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "action/core/context/facade"
+require "action/core/context/facade_inspector"
+
+module Action
+  # Outbound / External ContextFacade
+  class Result < ContextFacade
+    # For ease of mocking return results in tests
+    class << self
+      def ok(msg = nil, **exposures)
+        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+
+        Axn::Factory.build(exposes:, messages: { success: msg }) do
+          exposures.each do |key, value|
+            expose(key, value)
+          end
+        end.call
+      end
+
+      def error(msg = nil, **exposures, &block)
+        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+        rescues = [-> { true }, msg]
+
+        Axn::Factory.build(exposes:, rescues:) do
+          exposures.each do |key, value|
+            expose(key, value)
+          end
+          block.call if block_given?
+          fail!
+        end.call
+      end
+    end
+
+    # Poke some holes for necessary internal control methods
+    delegate :each_pair, to: :context
+
+    # External interface
+    delegate :ok?, :exception, to: :context
+
+    def error
+      return if ok?
+
+      [@context.error_prefix, determine_error_message].compact.join(" ").squeeze(" ")
+    end
+
+    def success
+      return unless ok?
+
+      stringified(action._success_msg).presence || "Action completed successfully"
+    end
+
+    def ok = success
+
+    def message = error || success
+
+    # Outcome constants for action execution results
+    OUTCOMES = [
+      OUTCOME_SUCCESS = :success,
+      OUTCOME_FAILURE = :failure,
+      OUTCOME_EXCEPTION = :exception,
+    ].freeze
+
+    def outcome
+      return OUTCOME_EXCEPTION if exception
+      return OUTCOME_FAILURE if @context.failed?
+
+      OUTCOME_SUCCESS
+    end
+
+    # Elapsed time in milliseconds
+    def elapsed_time
+      @context.elapsed_time
+    end
+
+    private
+
+    def context_data_source = @context.exposed_data
+
+    def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)
+      if @context.__combined_data.key?(method_name.to_sym)
+        msg = <<~MSG
+          Method ##{method_name} is not available on Action::Result!
+
+          #{action_name} may be missing a line like:
+            exposes :#{method_name}
+        MSG
+
+        raise Action::ContractViolation::MethodNotAllowed, msg
+      end
+
+      super
+    end
+  end
+end