axn 0.1.0.pre.alpha.2.3 → 0.1.0.pre.alpha.2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac3f240b093cdf14fef16b5eb6993dbb8f6d49ba58c837245128a0efb3558f11
-  data.tar.gz: 40b631f49349b51811ebb0bbc60cbc7962a3f7d633bab1134b7b234b4f681123
+  metadata.gz: 19221983bd11ff17620830a4807b4080f8ea35dfb07050e2af2e6c1dac1e1b7d
+  data.tar.gz: 7ac5fc8f9ae99bd9a5a189ad53f6113c4c544181ff760bbe923ca1867f011877
 SHA512:
-  metadata.gz: c8ac8be69e70d72d04b0c5be89e4ec198223c4a1771a15d254b82b0a204543c627a80321b3de95d69fa97a244fc56c9c39ca59262600c6b991c363603e0a7beb
-  data.tar.gz: 4eba5152626d0417ff3be725da9512034276d4b034898f8ad331890499196c1851a1d3dcd1cde880955c42f425090ab6c5fe30cac1496835013c7bd6cda52cdb
+  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,12 @@
 ## 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
+
 ## 0.1.0-alpha.2.3
 * `expects` / `exposes`: Add `type: :uuid` special case validation
 * [BUGFIX] Allow `hoist_errors` to pass the result through on success (allow access to subactions' exposures)

data/docs/reference/class.md

@@ -63,7 +63,7 @@ messages success: "All good!", error: ->(e) { "Bad news: #{e.message}" }
 
 While `.messages` sets the _default_ error/success messages and is more commonly used, there are times when you want specific error messages for specific failure cases.
 
-`error_for` and `rescues` both register a matcher (exception class, exception class name (string), or callable) and a message to use if the matcher succeeds.  They act exactly the same, except if a matcher registered with `rescues` succeeds, the exception _will not_ trigger the configured global error handler.
+`error_for` and `rescues` both register a matcher (exception class, exception class name (string), or callable) and a message to use if the matcher succeeds.  They act exactly the same, except if a matcher registered with `rescues` succeeds, the exception _will not_ trigger the configured exception handlers (global or specific to this class).
 
 ```ruby
 messages error: "bad"
@@ -72,6 +72,67 @@ 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}" }
 ```
+
+## 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:
+
+```ruby
+class Foo
+  include Action
+
+  on_exception do |exception| # [!code focus:3]
+    # e.g. trigger a slack error
+  end
+end
+```
+
+Note that by default the `on_exception` block will be applied to _any_ `StandardError` that is raised, but you can specify a matcher using the same logic as for [`error_for` and `rescues`](#error-for-and-rescues):
+
+```ruby
+class Foo
+  include Action
+
+  on_exception NoMethodError do |exception| # [!code focus]
+    # e.g. trigger a slack error
+  end
+
+  on_exception ->(e) { e.is_a?(ZeroDivisionError) } do # [!code focus]
+    # e.g. trigger a slack error
+  end
+end
+```
+
+If multiple `on_exception` handlers are provided, ALL that match the raised exception will be triggered in the order provided.
+
+The _global_ handler will be triggered _after_ all class-specific handlers.

data/docs/reference/configuration.md

@@ -39,6 +39,7 @@ A couple notes:
 
   * `context` will contain the arguments passed to the `action`, _but_ any marked as sensitive (e.g. `expects :foo, sensitive: true`) will be filtered out in the logs.
   * If your handler raises, the failure will _also_ be swallowed and logged
+  * This handler is global across _all_ Axns.  You can also specify per-Action handlers via [the class-level declaration](/reference/class#on-exception).
 
 
 ## `top_level_around_hook`

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,35 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "event_handlers"
+
 module Action
   module SwallowExceptions
-    CustomErrorInterceptor = Data.define(:matcher, :message, :should_report_error)
-    class CustomErrorInterceptor
-      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
-    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
@@ -37,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
@@ -58,11 +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
 
-          Action.config.on_exception(e,
+          # 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: respond_to?(:context_for_logging) ? context_for_logging : @context.to_h)
         rescue StandardError => e
@@ -103,6 +103,36 @@ module Action
         _register_error_interceptor(matcher, message, should_report_error: false, **match_and_messages)
       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?
+
+        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
 
       # Private helpers
@@ -117,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
 
@@ -131,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

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.2.3"
+  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.3
+  version: 0.1.0.pre.alpha.2.4.1
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-22 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