axn 0.1.0.pre.alpha.2.6 → 0.1.0.pre.alpha.2.7

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,114 @@
+# 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:, 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 }] }
+
+        Axn::Factory.build(exposes:, error: msg) do
+          exposures.each do |key, value|
+            expose(key, value)
+          end
+          if block_given?
+            begin
+              block.call
+            rescue StandardError => e
+              # Set the exception directly without triggering on_exception handlers
+              @__context.exception = e
+            end
+          end
+          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?
+
+      determine_success_message
+    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 determine_error_message
+      return @context.error_from_user if @context.error_from_user.present?
+
+      exception = @context.exception || Action::Failure.new
+      msg = action.class._message_for(:error, action:, exception:)
+      msg.presence || "Something went wrong"
+    end
+
+    def determine_success_message
+      msg = action.class._message_for(:success, action:, exception: nil)
+      msg.presence || "Action completed successfully"
+    end
+
+    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

data/lib/axn/factory.rb

@@ -13,15 +13,23 @@ module Axn
         # Expose standard class-level options
         exposes: [],
         expects: [],
-        messages: {},
-        error_from: {},
-        rescues: {},
+        success: nil,
+        error: nil,
 
         # Hooks
         before: nil,
         after: nil,
         around: nil,
 
+        # Callbacks
+        on_success: nil,
+        on_failure: nil,
+        on_error: nil,
+        on_exception: nil,
+
+        # Strategies
+        use: [],
+
         &block
       )
         args = block.parameters.each_with_object(_hash_with_default_array) { |(type, field), hash| hash[type] << field }
@@ -64,6 +72,17 @@ module Axn
             expose(expose_return_as => retval) if expose_return_as.present?
           end
         end.tap do |axn|
+          apply_message = lambda do |kind, value|
+            return unless value.present?
+
+            if value.is_a?(Array) && value.size == 2
+              matcher, msg = value
+              axn.public_send(kind, msg, if: matcher)
+            else
+              axn.public_send(kind, value)
+            end
+          end
+
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end
@@ -72,16 +91,35 @@ module Axn
             axn.exposes(field, **opts)
           end
 
-          axn.messages(**messages) if messages.present? && messages.values.any?(&:present?)
-
-          axn.error_from(**_array_to_hash(error_from)) if error_from.present?
-          axn.rescues(**_array_to_hash(rescues)) if rescues.present?
+          apply_message.call(:success, success)
+          apply_message.call(:error, error)
 
           # Hooks
           axn.before(before) if before.present?
           axn.after(after) if after.present?
           axn.around(around) if around.present?
 
+          # Callbacks
+          axn.on_success(&on_success) if on_success.present?
+          axn.on_failure(&on_failure) if on_failure.present?
+          axn.on_error(&on_error) if on_error.present?
+          axn.on_exception(&on_exception) if on_exception.present?
+
+          # Strategies
+          Array(use).each do |strategy|
+            if strategy.is_a?(Array)
+              strategy_name, *config_args = strategy
+              if config_args.last.is_a?(Hash)
+                *other_args, config = config_args
+                axn.use(strategy_name, *other_args, **config)
+              else
+                axn.use(strategy_name, *config_args)
+              end
+            else
+              axn.use(strategy)
+            end
+          end
+
           # Default exposure
           axn.exposes(expose_return_as, allow_blank: true) if expose_return_as.present?
         end

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.2.6"
+  VERSION = "0.1.0-alpha.2.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.6
+  version: 0.1.0.pre.alpha.2.7
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-07 00:00:00.000000000 Z
+date: 2025-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -80,16 +80,28 @@ files:
 - lib/action/context.rb
 - lib/action/core.rb
 - lib/action/core/automatic_logging.rb
-- lib/action/core/context_facade.rb
+- lib/action/core/context/facade.rb
+- lib/action/core/context/facade_inspector.rb
+- lib/action/core/context/internal.rb
 - lib/action/core/contract.rb
 - lib/action/core/contract_for_subfields.rb
 - lib/action/core/contract_validation.rb
-- lib/action/core/event_handlers.rb
-- lib/action/core/handle_exceptions.rb
+- lib/action/core/flow.rb
+- lib/action/core/flow/callbacks.rb
+- lib/action/core/flow/exception_execution.rb
+- lib/action/core/flow/handlers.rb
+- lib/action/core/flow/handlers/base_handler.rb
+- lib/action/core/flow/handlers/callback_handler.rb
+- lib/action/core/flow/handlers/invoker.rb
+- lib/action/core/flow/handlers/matcher.rb
+- lib/action/core/flow/handlers/message_handler.rb
+- lib/action/core/flow/handlers/registry.rb
+- lib/action/core/flow/messages.rb
 - lib/action/core/hoist_errors.rb
 - lib/action/core/hooks.rb
 - lib/action/core/logging.rb
 - lib/action/core/timing.rb
+- lib/action/core/tracing.rb
 - lib/action/core/use_strategy.rb
 - lib/action/core/validation/fields.rb
 - lib/action/core/validation/subfields.rb
@@ -99,6 +111,7 @@ files:
 - lib/action/enqueueable.rb
 - lib/action/enqueueable/via_sidekiq.rb
 - lib/action/exceptions.rb
+- lib/action/result.rb
 - lib/action/strategies.rb
 - lib/action/strategies/transaction.rb
 - lib/axn.rb