axn 0.1.0.pre.alpha.2.4 → 0.1.0.pre.alpha.2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3313bd117a57aae98551088df5895b6db302830101dda0e2fb95f057f97000f
-  data.tar.gz: 9517e1d297998af62a2fc2107d3a002a71d5b767dda250b6ebec4d29958902a6
+  metadata.gz: 19221983bd11ff17620830a4807b4080f8ea35dfb07050e2af2e6c1dac1e1b7d
+  data.tar.gz: 7ac5fc8f9ae99bd9a5a189ad53f6113c4c544181ff760bbe923ca1867f011877
 SHA512:
-  metadata.gz: e3b80de43c96e2362562dc35d88fd28d7c7b97a0dba2e73168031063fa8bed3d64ae3c46dd4f751af6ea051c17fc4592e6c246f505f9e319e5dd6e87caabfc67
-  data.tar.gz: c451f8b99639f94bb38d982ab4913b5e126ee099ed97f31cf2ad70903efbc5acb69bc715e634d39e56aad0720d8bd4007a24794255ea9519307f268b4f312061
+  metadata.gz: 4115cc144bfac9420ff85de1ff9198efd092f63594811aed1afbf3ac5a07a5b73a9017b9d9665aac78e128c312d79e996d8dc2f8710fb30a8b9825a51caa30e5
+  data.tar.gz: 7528abe56dd99066409a59a57f07d04f9b9ea98fd399b62aab7318a762920027eb0870b7895b5f8bff525023a7d754c67f0d8c484661929c8a4dab1a360caf6f

data/.rubocop.yml

@@ -36,10 +36,10 @@ Metrics/PerceivedComplexity:
   Max: 15
 
 Metrics/AbcSize:
-  Max: 51
+  Max: 60
 
 Metrics/CyclomaticComplexity:
-  Max: 12
+  Max: 14
 
 Lint/EmptyBlock:
   Enabled: false

data/CHANGELOG.md

@@ -3,6 +3,9 @@
 ## UNRELEASED
 * N/A
 
+## 0.1.0-alpha.2.4.1
+* [FEAT] Adds full suite of per-Axn callbacks: `on_exception`, `on_failure`, `on_error`, `on_success`
+
 ## 0.1.0-alpha.2.4
 * [FEAT] Adds per-Axn `on_exception` handlers
 

data/docs/reference/class.md

@@ -72,11 +72,38 @@ messages error: "bad"
 rescues ActiveRecord::InvalidRecord => "Invalid params provided"
 
 # These WILL trigger error handler (second demonstrates callable matcher AND message)
-error_for ArgumentError, ->(e) { "Argument error: #{e.message}"
+error_for ArgumentError, ->(e) { "Argument error: #{e.message}" }
 error_for -> { name == "bad" }, -> { "was given bad name: #{name}" }
 ```
 
-## `on_exception`
+## Callbacks
+
+In addition to the [global exception handler](/reference/configuration#on-exception), a number of custom callback are available for you as well, if you want to take specific actions when a given Axn succeeds or fails.
+
+::: danger ALPHA
+* The callbacks themselves are functional. Note the ordering _between_ callbacks is not well defined (currently a side effect of the order they're defined).
+  * Ordering may change at any time so while in alpha DO NOT MAKE ASSUMPTIONS ABOUT THE ORDER OF CALLBACK EXECUTION!
+:::
+
+
+::: tip Callbacks vs Hooks
+  * *Hooks* (`before`/`after`) are executed _as part of the `call`_ -- exceptions or `fail!`s here _will_ change a successful action call to a failure (i.e. `result.ok?` will be false)
+  * *Callbacks* (defined below) are executed _after_ the `call` -- exceptions or `fail!`s here will _not_ change `result.ok?`
+:::
+
+### `on_success`
+
+This is triggered after the Axn completes, if it was successful.  Difference from `after`: if the given block raises an error, this WILL be reported to the global exception handler, but will NOT change `ok?` to false.
+
+### `on_error`
+
+Triggered on ANY error (explicit `fail!` or uncaught exception). Optional filter argument works the same as `on_exception` (documented below).
+
+### `on_failure`
+
+Triggered ONLY on explicit `fail!` (i.e. _not_ by an uncaught exception). Optional filter argument works the same as `on_exception` (documented below).
+
+### `on_exception`
 
 Much like the [globally-configured on_exception hook](/reference/configuration#on-exception), you can also specify exception handlers for a _specific_ Axn class:
 

data/docs/usage/writing.md

@@ -104,23 +104,22 @@ Foo.call(name: "Adams").meaning_of_life # => "Hello Adams, the meaning of life i
 
 In addition to `#call`, there are a few additional pieces to be aware of:
 
-### `#rollback`
+<!-- ### `#rollback`
+*** TODO: rollback actually only applies to rolling back *completed* steps of a multi-step Axn chain.  Do not document for now -- need to decide if adding a trigger-when-axn-itself-fails rollback path. ***
 
 ::: danger ALPHA
 * ⚠️ `#rollback` is _expected_ to be added shortly, but is not yet functional!
 :::
 
-If you define a `#rollback` method, it'll be called (_before_ returning an `Action::Result` to the caller) whenever your action fails.
+If you define a `#rollback` method, it'll be called (_before_ returning an `Action::Result` to the caller) whenever your action fails. -->
 
 ### Hooks
 
-`before` and `after` hooks are also supported. They can receive a block directly, or the symbol name of a local method.
+`before` and `after` hooks are supported. They can receive a block directly, or the symbol name of a local method.
 
-Note execution is halted whenever `fail!` is called or an exception is raised (so a `before` block failure won't execute `call` or `after`, while an `after` block failure will make `resuilt.ok?` be false even though `call` completed successfully).
+Note execution is halted whenever `fail!` is called or an exception is raised (so a `before` block failure won't execute `call` or `after`, while an `after` block failure will make `result.ok?` be false even though `call` completed successfully).
 
-### Concrete example
-
-Given this series of methods and hooks:
+For instance, given this configuration:
 
 ```ruby
 class Foo
@@ -133,10 +132,6 @@ class Foo
     log("in call")
   end
 
-  def rollback
-    log("rolling back")
-  end
-
   private
 
   def log_after
@@ -153,8 +148,11 @@ end
 before hook
 in call
 after hook
-rolling back
 ```
 
+### Callbacks
+
+A number of custom callback are available for you as well, if you want to take specific actions when a given Axn succeeds or fails. See the [Class Interface docs](/reference/class#callbacks) for details.
+
 ## Debugging
 Remember you can [enable debug logging](/reference/configuration.html#global-debug-logging) to print log lines before and after each action is executed.

data/lib/action/core/event_handlers.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Action
+  module EventHandlers
+    class CustomErrorInterceptor
+      def initialize(matcher:, message:, should_report_error:)
+        @matcher = Matcher.new(matcher)
+        @message = message
+        @should_report_error = should_report_error
+      end
+
+      delegate :matches?, to: :@matcher
+      attr_reader :message, :should_report_error
+    end
+
+    class ConditionalHandler
+      def initialize(matcher:, handler:)
+        @matcher = Matcher.new(matcher)
+        @handler = handler
+      end
+
+      delegate :matches?, to: :@matcher
+
+      def execute_if_matches(action:, exception:)
+        return false unless matches?(exception:, action:)
+
+        action.instance_exec(exception, &@handler)
+        true
+      rescue StandardError => e
+        action.warn("Ignoring #{e.class.name} in when evaluating #{self.class.name} handler: #{e.message}")
+        nil
+      end
+    end
+
+    class Matcher
+      def initialize(matcher)
+        @matcher = matcher
+      end
+
+      def matches?(exception:, action:)
+        if matcher.respond_to?(:call)
+          if matcher.arity == 1
+            !!action.instance_exec(exception, &matcher)
+          else
+            !!action.instance_exec(&matcher)
+          end
+        elsif matcher.is_a?(String) || matcher.is_a?(Symbol)
+          klass = Object.const_get(matcher.to_s)
+          klass && exception.is_a?(klass)
+        elsif matcher < Exception
+          exception.is_a?(matcher)
+        else
+          action.warn("Ignoring apparently-invalid matcher #{matcher.inspect} -- could not find way to apply it")
+          false
+        end
+      rescue StandardError => e
+        action.warn("Ignoring #{e.class.name} raised while determining matcher: #{e.message}")
+        false
+      end
+
+      private attr_reader :matcher
+    end
+  end
+end

data/lib/action/core/exceptions.rb

@@ -11,7 +11,7 @@ module Action
       @context = context
     end
 
-    def message = @message.presence || "Execution was halted"
+    def message = @message.presence || @context.error_from_user.presence || "Execution was halted"
 
     def inspect = "#<#{self.class.name} '#{message}'>"
   end

data/lib/action/core/swallow_exceptions.rb

@@ -1,42 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "event_handlers"
+
 module Action
   module SwallowExceptions
-    CustomErrorInterceptor = Data.define(:matcher, :message, :should_report_error)
-    CustomErrorHandler = Data.define(:matcher, :block)
-
-    class CustomErrorInterceptor
-      def self.matches?(matcher:, exception:, action:)
-        if matcher.respond_to?(:call)
-          if matcher.arity == 1
-            !!action.instance_exec(exception, &matcher)
-          else
-            !!action.instance_exec(&matcher)
-          end
-        elsif matcher.is_a?(String) || matcher.is_a?(Symbol)
-          klass = Object.const_get(matcher.to_s)
-          klass && exception.is_a?(klass)
-        elsif matcher < Exception
-          exception.is_a?(matcher)
-        else
-          action.warn("Ignoring apparently-invalid matcher #{matcher.inspect} -- could not find way to apply it")
-          false
-        end
-      rescue StandardError => e
-        action.warn("Ignoring #{e.class.name} raised while determining matcher: #{e.message}")
-        false
-      end
-
-      def matches?(exception:, action:)
-        self.class.matches?(matcher:, exception:, action:)
-      end
-    end
-
     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
@@ -44,9 +18,22 @@ module Action
         def run_with_exception_swallowing!
           original_run!
         rescue StandardError => e
-          raise if e.is_a?(Action::Failure) # TODO: avoid raising if this was passed along from a child action (esp. if wrapped in hoist_errors)
+          # 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
+
+            # TODO: avoid raising if this was passed along from a child action (esp. if wrapped in hoist_errors)
+            raise e
+          end
 
-          # Add custom hook for intercepting exceptions (e.g. Teamshares automatically logs to Honeybadger)
+          # 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
@@ -65,15 +52,17 @@ module Action
           raise if @context.object_id != e.context.object_id
         end
 
-        def trigger_on_exception(e)
-          interceptor = self.class._error_interceptor_for(exception: e, action: self)
+        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
-          _on_exception(e)
+          self.class._exception_handlers.each do |handler|
+            handler.execute_if_matches(exception:, action: self)
+          end
 
           # Call any global handlers
-          Action.config.on_exception(e,
+          Action.config.on_exception(exception,
                                      action: self,
                                      context: respond_to?(:context_for_logging) ? context_for_logging : @context.to_h)
         rescue StandardError => e
@@ -114,10 +103,34 @@ module Action
         _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
       end
 
-      def on_exception(matcher = StandardError, &block)
+      # 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 += [CustomErrorHandler.new(matcher:, block:)]
+        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
+
+      # 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?
+
+        after do
+          try { instance_exec(&block) }
+        end
       end
 
       def default_error = new.internal_context.default_error
@@ -134,9 +147,11 @@ module Action
         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
 
-        { matcher => message }.compact.merge(match_and_messages).each do |(matcher, message)| # rubocop:disable Lint/ShadowingOuterLocalVariable
-          self._custom_error_interceptors += [CustomErrorInterceptor.new(matcher:, message:, should_report_error:)]
+        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
 
@@ -148,7 +163,7 @@ module Action
         @context.error_from_user = message if message.present?
 
         # TODO: should we use context_for_logging here? But doublecheck the one place where we're checking object_id on it...
-        raise Action::Failure.new(@context) # rubocop:disable Style/RaiseArgs
+        raise Action::Failure.new(@context, message:)
       end
 
       def try
@@ -161,18 +176,6 @@ module Action
       end
 
       delegate :default_error, to: :internal_context
-
-      def _on_exception(exception)
-        handlers = self.class._exception_handlers.select do |this|
-          CustomErrorInterceptor.matches?(matcher: this.matcher, exception:, action: self)
-        end
-
-        handlers.each do |handler|
-          instance_exec(exception, &handler.block)
-        rescue StandardError => e
-          warn("Ignoring #{e.class.name} in on_exception hook: #{e.message}")
-        end
-      end
     end
   end
 end

data/lib/axn/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.4
+  version: 0.1.0.pre.alpha.2.4.1
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-27 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -93,6 +93,7 @@ files:
 - lib/action/core/contract.rb
 - lib/action/core/contract_validator.rb
 - lib/action/core/enqueueable.rb
+- lib/action/core/event_handlers.rb
 - lib/action/core/exceptions.rb
 - lib/action/core/hoist_errors.rb
 - lib/action/core/logging.rb