axn 0.1.0.pre.alpha.2.4 → 0.1.0.pre.alpha.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3313bd117a57aae98551088df5895b6db302830101dda0e2fb95f057f97000f
-  data.tar.gz: 9517e1d297998af62a2fc2107d3a002a71d5b767dda250b6ebec4d29958902a6
+  metadata.gz: ad00a162e22de940a1c6e4a4de1f75533fb1aa5440c6cf8808f81a964e2457d4
+  data.tar.gz: dfb840d11657f80f92d3e1aa19bef3cb64b1d28a84f70f0dd1b92c5726f4fd7f
 SHA512:
-  metadata.gz: e3b80de43c96e2362562dc35d88fd28d7c7b97a0dba2e73168031063fa8bed3d64ae3c46dd4f751af6ea051c17fc4592e6c246f505f9e319e5dd6e87caabfc67
-  data.tar.gz: c451f8b99639f94bb38d982ab4913b5e126ee099ed97f31cf2ad70903efbc5acb69bc715e634d39e56aad0720d8bd4007a24794255ea9519307f268b4f312061
+  metadata.gz: 6704196ea530709faf393c51886f0ab4ed34fd5f9654cf4d086d08ba30a455140297bf695d29d0e7a15376b8b3064c9093e882f74f84139e21dc2bdc1e122298
+  data.tar.gz: e319dcdf830b8b49fafa2db5f8461b951bf96db8a57b1b1172075a69db2f1eacd4674807526480d7f56a5fbe03265bf549f755359986a02805a5e982f0c769d1

data/.rubocop.yml

@@ -3,6 +3,10 @@ AllCops:
   SuggestExtensions: false
   NewCops: enable
 
+
+Style/MultilineBlockChain:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
@@ -36,10 +40,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,24 @@
 ## UNRELEASED
 * N/A
 
+## 0.1.0-alpha.2.5
+* Support blank exposures for `Action::Result.ok`
+* Modify Action::Failure's initialize signature (to better match StandardError)
+* Reduce reserved fields to allow some `expects` (e.g. `message`) that would shadow internals if used as `exposes`
+* Default logging changes:
+  * Add `default_log_level` and `default_autolog_level` class methods (so inheritable) via `Action.config`
+  * Remove `global_debug_logging?` from Configuration + unused `SA_DEBUG_TARGETS` approach to configuring logging
+* Improved testing ergonomics: the `type` expectation will now return `true` for _any_ `RSpec::Mocks::` subclass
+* Enqueueable improvements:
+  * Extracted out of Core
+  * Renamed to `Enqueueable::ViaSidekiq` (make it easier to support different background runners in the future)
+  * Added ability to call `.enqueue_all_in_background` to run an Action's class-level `.enqueue_all` method (if defined) on a background worker
+    (important if triggered via a clock process that is NOT intended to execute actual jobs)
+* Restructure internals (call/call! + run/run! + Action::Failure) to simplify upstream implementation since we always wrap any raised exceptions
+
+## 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/recipes/testing.md

@@ -31,6 +31,56 @@ before do
 end
 ```
 
+### `call!`
+
+The semantics of call-bang are a little different -- if Subaction is called via `call!`, you'll need slightly different code to handle success vs failure:
+
+### Success
+
+```ruby
+let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+
+before do
+  expect(Subaction).to receive(:call!).and_return(subaction_response)
+end
+```
+
+### Failure
+
+Because `call!` will _raise_, we need to use `and_raise` rather than `and_return`:
+
+```ruby
+let(:subaction_exception) { SomeValidErrorClass.new("whatever you expect subclass to raise") }
+
+before do
+  expect(Subaction).to receive(:call!).and_raise(subaction_exception)
+end
+```
+
+NOTE: to mock subaction failing via explicit `fail!` call, you'd use an `Action::Failure` exception class.
+
+## Mocking Axn arguments
+
+Be aware that in order to improve testing ergonomics, the `type` validation will return `true` for _any_ `RSpec::Mocks::` subclass _as long as `Action.config.env.test?` is `true`_.
+
+This makes it much easier to test Axns, as you can pass in mocks without immediately failing the inbound validation.
+
+```ruby
+subject(:result) { action.call!(sym:) }
+
+let(:action) { build_action { expects :sym, type: Symbol } }
+
+context "with a symbol" do
+  let(:sym) { :hello }
+  it { is_expected.to be_ok }
+end
+
+context "with an RSpec double" do
+  let(:sym) { double(to_s: "hello") }  # [!code focus:2]
+  it { is_expected.to be_ok }
+end
+```
+
 ## RSpec configuration
 
 Configuring rspec to treat files in spec/actions as service specs (very optional):

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/reference/configuration.md

@@ -11,7 +11,8 @@ Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call
 
     c.additional_includes = []
 
-    c.global_debug_logging = false
+    c.default_log_level = :info
+    c.default_autolog_level = :debug
 
     c.logger = ...
   end
@@ -84,21 +85,17 @@ For example:
 
 For a practical example of this in practice, see [our 'memoization' recipe](/recipes/memoization).
 
-## `global_debug_logging`
+## `default_log_level`
 
-By default, every `action.call` will emit _debug_ log lines when it is called and after it completes:
+Sets the log level used when you call `log "Some message"` in your Action.  Note this is read via a `default_log_level` class method, so you can easily use inheritance to support different log levels for different sets of actions.
+
+## `default_autolog_level`
+
+By default, every `action.call` will emit log lines when it is called and after it completes:
 
   ```
     [YourCustomAction] About to execute with: {:foo=>"bar"}
     [YourCustomAction] Execution completed (with outcome: success) in 0.957 milliseconds
   ```
 
-You can bump the log level from `debug` to `info` for specific actions by including their class name (comma separated, if multiple) in a `SA_DEBUG_TARGETS` ENV variable.
-
-You can also turn this on _globally_ by setting `global_debug_logging = true`.
-
-```ruby
-  Action.configure do |c|
-    c.global_debug_logging = true
-  end
-```
+You can change the default _auto_-log level separately from the log level used for your explicit `log` calls (just like above, via Action.config or a `default_autolog_level` class method).

data/docs/reference/instance.md

@@ -61,6 +61,12 @@ Accepts a `prefix` keyword argument -- when set, prefixes the `error` message fr
 
 NOTE: expects a single action call in the block -- if there are multiple calls, only the last one will be checked for `ok?` (although anything _raised_ in the block will still be handled).
 
+::: tip Versus `call!`
+* If you just want to make sure your action fails if the subaction fails: call subaction via `call!` (any failures will raise, which will fail the parent).
+  * Note this passes _child_ exception into _parent_ `messages :error` parsing.
+* If you want _the child's_ `result.error` to become the _parent's_ `result.error` on failure, use `hoist_errors` + `call`
+:::
+
 ### Example
 
 ```ruby

data/docs/usage/using.md

@@ -55,3 +55,33 @@ Sidekiq integration is NOT YET TESTED/NOT YET USED IN OUR APP, and naming will V
     * enqueue will not retry even if fails
     * enqueue! will go through normal sidekiq retries on any failure (including user-facing `fail!`)
     * Note implicit GlobalID support (if not serializable, will get ArgumentError at callsite)
+
+
+### `.enqueue_all_in_background`
+
+In practice it's fairly common to need to enqueue a bunch of sidekiq jobs from a clock process.
+
+One approach is to define a class-level `.enqueue_all` method on your Action... but that ends up executing the enqueue_all logic directly from the clock process, which is undesirable.
+
+
+::: danger ALPHA
+We are actively testing this pattern -- not yet certain we'll keep it past beta.
+:::
+
+Therefore we've added an `.enqueue_all_in_background` method that will automatically call your `.enqueue_all` _from a background job_ rather than directly on the active process.
+
+```ruby
+class Foo
+  include Action
+
+  def self.enqueue_all
+    SomeModel.some_scope.find_each do |record|
+      enqueue(record:)
+    end
+  end
+
+  ...
+end
+
+Foo.enqueue_all # works, but `SomeModel.some_scope.find_each` is executed in the current context
+Foo.enqueue_all_in_background # same, but runs in the background (via Action::Enqueueable::EnqueueAllWorker)

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/configuration.rb

@@ -3,10 +3,11 @@
 module Action
   class Configuration
     include Action::Logging
-    attr_accessor :global_debug_logging, :top_level_around_hook
-    attr_writer :logger, :env, :on_exception, :additional_includes
+    attr_accessor :top_level_around_hook
+    attr_writer :logger, :env, :on_exception, :additional_includes, :default_log_level, :default_autolog_level
 
-    def global_debug_logging? = !!global_debug_logging
+    def default_log_level = @default_log_level ||= :info
+    def default_autolog_level = @default_autolog_level ||= :info
 
     def additional_includes = @additional_includes ||= []
 
@@ -15,7 +16,7 @@ module Action
         # TODO: only pass action: or context: if requested (and update documentation)
         @on_exception.call(e, action:, context:)
       else
-        log("[#{action.class.name.presence || "Anonymous Action"}] Exception swallowed: #{e.class.name} - #{e.message}")
+        log("[#{action.class.name.presence || "Anonymous Action"}] Exception raised: #{e.class.name} - #{e.message}")
       end
     end
 

data/lib/action/core/context_facade.rb

@@ -51,7 +51,9 @@ module Action
     def determine_error_message(only_default: false)
       return @context.error_from_user if @context.error_from_user.present?
 
-      exception = @context.exception || (only_default ? Action::Failure.new(@context) : nil)
+      # We need an exception for interceptors, and also in case the messages.error callable expects an argument
+      exception = @context.exception || Action::Failure.new
+
       msg = action._error_msg
 
       unless only_default
@@ -73,7 +75,7 @@ module Action
         action.instance_exec(&msg)
       end
     rescue StandardError => e
-      action.warn("Ignoring #{e.class.name} raised while determining message callable: #{e.message}")
+      action.warn("Ignoring #{e.class.name} while determining message callable: #{e.message}")
       nil
     end
   end
@@ -95,7 +97,9 @@ module Action
     # For ease of mocking return results in tests
     class << self
       def ok(msg = nil, **exposures)
-        Axn::Factory.build(exposes: exposures.keys, messages: { success: msg }) do
+        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
@@ -103,7 +107,10 @@ module Action
       end
 
       def error(msg = nil, **exposures, &block)
-        Axn::Factory.build(exposes: exposures.keys, rescues: [-> { true }, msg]) do
+        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
@@ -162,7 +169,9 @@ module Action
       return unless facade.is_a?(Action::Result)
 
       return "[OK]" if context.success?
-      return "[failed with '#{context.error_from_user}']" unless context.exception
+      unless context.exception
+        return context.error_from_user.present? ? "[failed with '#{context.error_from_user}']" : "[failed]"
+      end
 
       %([failed with #{context.exception.class.name}: '#{context.exception.message}'])
     end

data/lib/action/core/contract.rb

@@ -36,6 +36,10 @@ module Action
     module ClassMethods
       def expects(*fields, allow_blank: false, allow_nil: false, default: nil, preprocess: nil, sensitive: false,
                   **validations)
+        fields.each do |field|
+          raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES_FOR_EXPECTATIONS.include?(field.to_s)
+        end
+
         _parse_field_configs(*fields, allow_blank:, allow_nil:, default:, preprocess:, sensitive:, **validations).tap do |configs|
           duplicated = internal_field_configs.map(&:field) & configs.map(&:field)
           raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
@@ -46,6 +50,10 @@ module Action
       end
 
       def exposes(*fields, allow_blank: false, allow_nil: false, default: nil, sensitive: false, **validations)
+        fields.each do |field|
+          raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES_FOR_EXPOSURES.include?(field.to_s)
+        end
+
         _parse_field_configs(*fields, allow_blank:, allow_nil:, default:, preprocess: nil, sensitive:, **validations).tap do |configs|
           duplicated = external_field_configs.map(&:field) & configs.map(&:field)
           raise Action::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
@@ -57,10 +65,16 @@ module Action
 
       private
 
-      RESERVED_FIELD_NAMES = %w[
-        declared_fields inspect fail!
-        default_error
-        called! rollback! each_pair success? exception ok ok? error success message
+      RESERVED_FIELD_NAMES_FOR_EXPECTATIONS = %w[
+        called! fail! rollback! success? ok?
+        inspect default_error
+        each_pair
+      ].freeze
+
+      RESERVED_FIELD_NAMES_FOR_EXPOSURES = %w[
+        called! fail! rollback! success? ok?
+        inspect each_pair default_error
+        ok error success message
       ].freeze
 
       def _parse_field_configs(*fields, allow_nil: false, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
@@ -68,8 +82,6 @@ module Action
         # Allow local access to explicitly-expected fields -- even externally-expected needs to be available locally
         # (e.g. to allow success message callable to reference exposed fields)
         fields.each do |field|
-          raise ContractViolation::ReservedAttributeError, field if RESERVED_FIELD_NAMES.include?(field.to_s)
-
           define_method(field) { internal_context.public_send(field) }
         end
 
@@ -123,9 +135,9 @@ module Action
         raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
 
         klass = direction == :inbound ? Action::InternalContext : Action::Result
-        implicitly_allowed_fields = direction == :inbound ? declared_fields(:outbound) : []
+        implicitly_allowed_fields = direction == :inbound ? _declared_fields(:outbound) : []
 
-        klass.new(action: self, context: @context, declared_fields: declared_fields(direction), implicitly_allowed_fields:)
+        klass.new(action: self, context: @context, declared_fields: _declared_fields(direction), implicitly_allowed_fields:)
       end
     end
 
@@ -173,7 +185,7 @@ module Action
       end
 
       def context_for_logging(direction = nil)
-        inspection_filter.filter(@context.to_h.slice(*declared_fields(direction)))
+        inspection_filter.filter(@context.to_h.slice(*_declared_fields(direction)))
       end
 
       protected
@@ -186,7 +198,7 @@ module Action
         (internal_field_configs + external_field_configs).select(&:sensitive).map(&:field)
       end
 
-      def declared_fields(direction)
+      def _declared_fields(direction)
         raise ArgumentError, "Invalid direction: #{direction}" unless direction.nil? || %i[inbound outbound].include?(direction)
 
         configs = case direction

data/lib/action/core/contract_validator.rb

@@ -34,7 +34,7 @@ module Action
         msg = begin
           options[:with].call(value)
         rescue StandardError => e
-          warn("Custom validation on field '#{attribute}' raised #{e.class.name}: #{e.message}")
+          Action.config.logger.warn("Custom validation on field '#{attribute}' raised #{e.class.name}: #{e.message}")
 
           "failed validation: #{e.message}"
         end
@@ -45,7 +45,7 @@ module Action
 
     class TypeValidator < ActiveModel::EachValidator
       def validate_each(record, attribute, value)
-        # TODO: the last one (:value) might be my fault from the make-it-a-hash fallback in #parse_field_configs
+        # NOTE: the last one (:value) might be my fault from the make-it-a-hash fallback in #parse_field_configs
         types = options[:in].presence || Array(options[:with]).presence || Array(options[:value]).presence
 
         return if value.blank? && !types.include?(:boolean) # Handled with a separate default presence validator
@@ -57,6 +57,8 @@ module Action
           elsif type == :uuid
             value.is_a?(String) && value.match?(/\A[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\z/i)
           else
+            next true if Action.config.env.test? && value.class.name.start_with?("RSpec::Mocks::")
+
             value.is_a?(type)
           end
         end

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} when evaluating 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} while determining matcher: #{e.message}")
+        false
+      end
+
+      private attr_reader :matcher
+    end
+  end
+end

data/lib/action/core/exceptions.rb

@@ -3,15 +3,16 @@
 module Action
   # Raised internally when fail! is called -- triggers failure + rollback handling
   class Failure < StandardError
-    attr_reader :context
+    DEFAULT_MESSAGE = "Execution was halted"
 
-    def initialize(context = nil, message: nil)
-      super()
-      @message = message if message.present?
-      @context = context
+    def initialize(message = nil, **)
+      @message = message
+      super(**)
     end
 
-    def message = @message.presence || "Execution was halted"
+    def message
+      @message.presence || DEFAULT_MESSAGE
+    end
 
     def inspect = "#<#{self.class.name} '#{message}'>"
   end

data/lib/action/core/hoist_errors.rb

@@ -29,8 +29,10 @@ module Action
           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!)
+        # 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"

data/lib/action/core/logging.rb

@@ -14,8 +14,9 @@ module Action
     end
 
     module ClassMethods
-      def log(message, level: :info)
-        level = :info if level == :debug && _targeted_for_debug_logging?
+      def default_log_level = Action.config.default_log_level
+
+      def log(message, level: default_log_level)
         msg = [_log_prefix, message].compact_blank.join(" ")
 
         Action.config.logger.send(level, msg)
@@ -29,13 +30,6 @@ module Action
 
       # TODO: this is ugly, we should be able to override in the config class...
       def _log_prefix = name == "Action::Configuration" ? nil : "[#{name || "Anonymous Class"}]"
-
-      def _targeted_for_debug_logging?
-        return true if Action.config.global_debug_logging?
-
-        target_class_names = (ENV["SA_DEBUG_TARGETS"] || "").split(",").map(&:strip)
-        target_class_names.include?(name)
-      end
     end
   end
 end

data/lib/action/core/swallow_exceptions.rb

@@ -1,79 +1,56 @@
 # 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
 
-        def run_with_exception_swallowing!
-          original_run!
+        def run
+          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)
-
-          # Add custom hook for intercepting exceptions (e.g. Teamshares automatically logs to Honeybadger)
-          trigger_on_exception(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
 
-          @context.exception = e
+          # 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?
 
-          fail!
-        end
+            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)
 
-        alias_method :original_run!, :run!
-        alias_method :run!, :run_with_exception_swallowing!
+            @context.exception = e
+          end
 
-        # Tweaked to check @context.object_id rather than context (since forwarding object_id causes Ruby to complain)
-        # TODO: do we actually need the object_id check? Do we need this override at all?
-        def run
-          run!
-        rescue Action::Failure => e
-          raise if @context.object_id != e.context.object_id
+          @context.instance_variable_set("@failure", true)
         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
@@ -83,17 +60,12 @@ module Action
         end
 
         class << base
-          def call_bang_with_unswallowed_exceptions(context = {})
+          def call!(context = {})
             result = call(context)
             return result if result.ok?
 
-            raise result.exception if result.exception
-
-            raise Action::Failure.new(result.instance_variable_get("@context"), message: result.error)
+            raise result.exception || Action::Failure.new(result.error)
           end
-
-          alias_method :original_call!, :call!
-          alias_method :call!, :call_bang_with_unswallowed_exceptions
         end
       end
     end
@@ -114,10 +86,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 +130,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
 
@@ -147,8 +145,7 @@ module Action
         @context.instance_variable_set("@failure", true)
         @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, message
       end
 
       def try
@@ -161,18 +158,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/action/core/top_level_around_hook.rb

@@ -6,46 +6,39 @@ module Action
       base.class_eval do
         around :__top_level_around_hook
 
+        extend AutologgingClassMethods
+        include AutologgingInstanceMethods
         include InstanceMethods
       end
     end
 
-    module InstanceMethods
-      def __top_level_around_hook(hooked)
-        timing_start = Time.now
-        _log_before
-
-        _configurable_around_wrapper do
-          (@outcome, @exception) = _call_and_return_outcome(hooked)
-        end
-
-        _log_after(timing_start:, outcome: @outcome)
-
-        raise @exception if @exception
-      end
+    module AutologgingClassMethods
+      def default_autolog_level = Action.config.default_autolog_level
+    end
 
+    module AutologgingInstanceMethods
       private
 
-      def _configurable_around_wrapper(&)
-        return yield unless Action.config.top_level_around_hook
-
-        Action.config.top_level_around_hook.call(self.class.name || "AnonymousClass", &)
-      end
-
       def _log_before
-        debug [
-          "About to execute",
-          context_for_logging(:inbound).presence&.inspect,
-        ].compact.join(" with: ")
+        public_send(
+          self.class.default_autolog_level,
+          [
+            "About to execute",
+            context_for_logging(:inbound).presence&.inspect,
+          ].compact.join(" with: "),
+        )
       end
 
       def _log_after(outcome:, timing_start:)
         elapsed_mils = ((Time.now - timing_start) * 1000).round(3)
 
-        debug [
-          "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
-          _log_after_data_peak,
-        ].compact.join(". Set: ")
+        public_send(
+          self.class.default_autolog_level,
+          [
+            "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
+            _log_after_data_peak,
+          ].compact.join(". Set: "),
+        )
       end
 
       def _log_after_data_peak
@@ -58,6 +51,29 @@ module Action
           return str[0, max_length - suffix.length] + suffix if str.length > max_length
         end
       end
+    end
+
+    module InstanceMethods
+      def __top_level_around_hook(hooked)
+        timing_start = Time.now
+        _log_before
+
+        _configurable_around_wrapper do
+          (@outcome, @exception) = _call_and_return_outcome(hooked)
+        end
+
+        _log_after(timing_start:, outcome: @outcome)
+
+        raise @exception if @exception
+      end
+
+      private
+
+      def _configurable_around_wrapper(&)
+        return yield unless Action.config.top_level_around_hook
+
+        Action.config.top_level_around_hook.call(self.class.name || "AnonymousClass", &)
+      end
 
       def _call_and_return_outcome(hooked)
         hooked.call

data/lib/action/enqueueable/enqueue_all_in_background.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Action
+  module Enqueueable
+    module EnqueueAllInBackground
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def enqueue_all_in_background
+          raise NotImplementedError, "#{name} must implement a .enqueue_all method in order to use .enqueue_all_in_background" unless respond_to?(:enqueue_all)
+
+          ::Action::Enqueueable::EnqueueAllWorker.enqueue(klass_name: name)
+        end
+      end
+    end
+  end
+end

data/lib/action/enqueueable/enqueue_all_worker.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# NOTE: this is a standalone worker for enqueueing all instances of a class.
+# Unlike the other files in the folder, it is NOT included in the Action stack.
+
+# Note it uses Axn-native enqueueing, so will automatically support additional
+# backends as they are added (initially, just Sidekiq)
+
+module Action
+  module Enqueueable
+    class EnqueueAllWorker
+      include Action
+
+      expects :klass_name, type: String
+
+      def call
+        klass_name.constantize.enqueue_all
+      end
+    end
+  end
+end

data/lib/action/enqueueable/via_sidekiq.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Action
+  module Enqueueable
+    module ViaSidekiq
+      def self.included(base)
+        base.class_eval do
+          begin
+            require "sidekiq"
+            include Sidekiq::Job
+          rescue LoadError
+            puts "Sidekiq not available -- skipping Enqueueable"
+            return
+          end
+
+          define_method(:perform) do |*args|
+            context = self.class._params_from_global_id(args.first)
+            bang = args.size > 1 ? args.last : false
+
+            if bang
+              self.class.call!(context)
+            else
+              self.class.call(context)
+            end
+          end
+
+          def self.enqueue(context = {})
+            perform_async(_process_context_to_sidekiq_args(context))
+          end
+
+          def self.enqueue!(context = {})
+            perform_async(_process_context_to_sidekiq_args(context), true)
+          end
+
+          def self.queue_options(opts)
+            opts = opts.transform_keys(&:to_s)
+            self.sidekiq_options_hash = get_sidekiq_options.merge(opts)
+          end
+
+          private
+
+          def self._process_context_to_sidekiq_args(context)
+            client = Sidekiq::Client.new
+
+            _params_to_global_id(context).tap do |args|
+              if client.send(:json_unsafe?, args).present?
+                raise ArgumentError,
+                      "Cannot pass non-JSON-serializable objects to Sidekiq. Make sure all expected arguments are serializable (or respond to to_global_id)."
+              end
+            end
+          end
+
+          def self._params_to_global_id(context)
+            context.stringify_keys.each_with_object({}) do |(key, value), hash|
+              if value.respond_to?(:to_global_id)
+                hash["#{key}_as_global_id"] = value.to_global_id.to_s
+              else
+                hash[key] = value
+              end
+            end
+          end
+
+          def self._params_from_global_id(params)
+            params.each_with_object({}) do |(key, value), hash|
+              if key.end_with?("_as_global_id")
+                hash[key.delete_suffix("_as_global_id")] = GlobalID::Locator.locate(value)
+              else
+                hash[key] = value
+              end
+            end.symbolize_keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/enqueueable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "enqueueable/via_sidekiq"
+require_relative "enqueueable/enqueue_all_in_background"
+
+module Action
+  module Enqueueable
+    extend ActiveSupport::Concern
+
+    included do
+      include ViaSidekiq
+      include EnqueueAllInBackground
+    end
+  end
+end

data/lib/axn/factory.rb

@@ -34,7 +34,6 @@ module Axn
         end
         raise ArgumentError, "[Axn::Factory] Cannot convert block to action: block expects a splat of keyword arguments" if args[:keyrest].present?
 
-        # TODO: is there any way to support default arguments? (if so, set allow_blank: true for those)
         if args[:key].present?
           raise ArgumentError,
                 "[Axn::Factory] Cannot convert block to action: block expects keyword arguments with defaults (ruby does not allow introspecting)"
@@ -66,7 +65,7 @@ module Axn
             retval = instance_exec(**unwrapped_kwargs, &block)
             expose(expose_return_as => retval) if expose_return_as.present?
           end
-        end.tap do |axn| # rubocop: disable Style/MultilineBlockChain
+        end.tap do |axn|
           expects.each do |field, opts|
             axn.expects(field, **opts)
           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.5"
 end

data/lib/axn.rb

@@ -13,11 +13,11 @@ require_relative "action/core/top_level_around_hook"
 require_relative "action/core/contract"
 require_relative "action/core/swallow_exceptions"
 require_relative "action/core/hoist_errors"
-require_relative "action/core/enqueueable"
 
 require_relative "axn/factory"
 
 require_relative "action/attachable"
+require_relative "action/enqueueable"
 
 def Axn(callable, **) # rubocop:disable Naming/MethodName
   return callable if callable.is_a?(Class) && callable < Action
@@ -42,10 +42,9 @@ module Action
 
       include HoistErrors
 
-      include Enqueueable
-
       # --- Extensions ---
       include Attachable
+      include Enqueueable
 
       # Allow additional automatic includes to be configured
       Array(Action.config.additional_includes).each { |mod| include mod }
@@ -62,3 +61,5 @@ module Action
     end
   end
 end
+
+require "action/enqueueable/enqueue_all_worker"

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.5
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-27 00:00:00.000000000 Z
+date: 2025-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -92,12 +92,16 @@ files:
 - lib/action/core/context_facade.rb
 - 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
 - lib/action/core/swallow_exceptions.rb
 - lib/action/core/top_level_around_hook.rb
+- lib/action/enqueueable.rb
+- lib/action/enqueueable/enqueue_all_in_background.rb
+- lib/action/enqueueable/enqueue_all_worker.rb
+- lib/action/enqueueable/via_sidekiq.rb
 - lib/axn.rb
 - lib/axn/factory.rb
 - lib/axn/version.rb

data/lib/action/core/enqueueable.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Enqueueable
-    def self.included(base)
-      base.class_eval do
-        begin
-          require "sidekiq"
-          include Sidekiq::Job
-        rescue LoadError
-          puts "Sidekiq not available -- skipping Enqueueable"
-          return
-        end
-
-        define_method(:perform) do |*args|
-          context = self.class._params_from_global_id(args.first)
-          bang = args.size > 1 ? args.last : false
-
-          if bang
-            self.class.call!(context)
-          else
-            self.class.call(context)
-          end
-        end
-
-        def self.enqueue(context = {})
-          perform_async(_process_context_to_sidekiq_args(context))
-        end
-
-        def self.enqueue!(context = {})
-          perform_async(_process_context_to_sidekiq_args(context), true)
-        end
-
-        def self.queue_options(opts)
-          opts = opts.transform_keys(&:to_s)
-          self.sidekiq_options_hash = get_sidekiq_options.merge(opts)
-        end
-
-        private
-
-        def self._process_context_to_sidekiq_args(context)
-          client = Sidekiq::Client.new
-
-          _params_to_global_id(context).tap do |args|
-            if client.send(:json_unsafe?, args).present?
-              raise ArgumentError,
-                    "Cannot pass non-JSON-serializable objects to Sidekiq. Make sure all objects in the context are serializable (or respond to to_global_id)."
-            end
-          end
-        end
-
-        def self._params_to_global_id(context)
-          context.stringify_keys.each_with_object({}) do |(key, value), hash|
-            if value.respond_to?(:to_global_id)
-              hash["#{key}_as_global_id"] = value.to_global_id.to_s
-            else
-              hash[key] = value
-            end
-          end
-        end
-
-        def self._params_from_global_id(params)
-          params.each_with_object({}) do |(key, value), hash|
-            if key.end_with?("_as_global_id")
-              hash[key.delete_suffix("_as_global_id")] = GlobalID::Locator.locate(value)
-            else
-              hash[key] = value
-            end
-          end.symbolize_keys
-        end
-      end
-    end
-  end
-end