axn 0.1.0.pre.alpha.2.5.3 → 0.1.0.pre.alpha.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d62aa4b98c8f159761234817e6b2ded26e0fcafa46d07685049d827281e92235
-  data.tar.gz: d3ffb46353e17db427393049767a6a03fbf3d5b30e94e4011a47397644364c32
+  metadata.gz: 49a6ab763d534efa878ff7f0d833beefeaae604bddb1c2e89090788a1e7df1a0
+  data.tar.gz: 828cfbd5ad2b9f753bf938bdb84201edbb406b367c159d4b1f437054a3bc213f
 SHA512:
-  metadata.gz: 54a4ea06f021850cc1d4e1e9bf18a6ec20f495871f23efab20380cd2a8135c52df46099f03281944c4dbe4419c836a72309cfd719e769ae3fd7e48a2ad7683db
-  data.tar.gz: 474eea3af1b53ad4ae85096a2e39d4b141b01c8c4f239f710cd13de933046d92b7efc67333902c78ed29c882bda5ada0a44e9e2efeab05721681f5ded1633b41
+  metadata.gz: 8be59eb695a3df836513fb477b2338bb539da209821d17ab6502314ea57e62204e9a0e5ae49ec579db5d5c8e99ca6de57596acf577ee2027d8410e23a5013f15
+  data.tar.gz: 1a559aff5de117890928f67a5e0adefe1f2615c24f15ac6357dff0c74bd3f9a9470110618228a30aaba35ae489844cca4efd1f701aba0f1805c18b5c71edd7a9

data/CHANGELOG.md

@@ -3,6 +3,20 @@
 ## Unreleased
 * N/A
 
+## 0.1.0-alpha.2.6
+* Inline interactor code (no more dependency on unpublished forked branch to support inheritance)
+  * Refactor internals to clean implementation now that we have direct control
+  * [BREAKING] Replaced `Action.config.top_level_around_hook` with `.wrap_with_trace` and `.emit_metrics`
+  * [BREAKING] the order of hooks with inheritance has changed to more intuitively follow the natural pattern of setup (general → specific) and teardown (specific → general):
+    * **Before hooks**: Parent → Child (general setup first, then specific)
+    * **After hooks**: Child → Parent (specific cleanup first, then general)
+    * **Around hooks**: Parent wraps child (parent outside, child inside)
+* Removed non-functional #rollback traces (use on_exception hook instead)
+* Clean requires structure
+
+## 0.1.0-alpha.2.5.3.1
+* Remove explicit 'require rspec' from `axn/testing/spec_helpers` (must already be loaded)
+
 ## 0.1.0-alpha.2.5.3
 * More aggressive logging of swallowed exceptions when not in production mode
 * Make automatic pre/post logging more digestible
@@ -10,7 +24,7 @@
 ## 0.1.0-alpha.2.5.2
 * [BREAKING] Removing `EnqueueAllInBackground` + `EnqueueAllWorker` - better + simply solved at application level
 * [TEST] Expose spec helpers to consumers (add `require "axn/testing/spec_helpers"` to your `spec_helper.rb`)
-# [FEAT] Added ability to use custom Strategies (via e.g. `use :transaction`)
+* [FEAT] Added ability to use custom Strategies (via e.g. `use :transaction`)
 
 ## 0.1.0-alpha.2.5.1.2
 * [BUGFIX] Subfield expectations: now support hashes with string keys (using with_indifferent_access)

data/README.md

@@ -1,20 +1,11 @@
 # Axn -- [AHK-sin] (a.k.a. "Action")
 
-Just spinning this up -- not yet released (i.e. doc updates in flight).
+Just spinning this up -- not yet publicly released, changes coming frequently.
 
 ## Installation & Usage
 
 See our [User Guide](https://teamshares.github.io/axn/) for details.
 
-## [!!] Inheritance Support
-
-Out of the box Axn only supports a direct style (every action must `include Action`).
-
-If you want to support inheritance, you'll need to add this line to your `Gemfile` (we're layered over Interactor, and their released version doesn't yet support inheritance):
-
-    gem "interactor", github: "kaspermeyer/interactor", branch: "fix-hook-inheritance"
-
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -27,4 +18,4 @@ See our [contribution guidelines](CONTRIBUTING.md) for more information.
 
 ## Thank You
 
-A very special thank you to [Collective Idea](https://collectiveidea.com/)'s fantastic [Interactor](https://github.com/collectiveidea/interactor?tab=readme-ov-file#interactor) library, which [we](https://www.teamshares.com/) used successfully for a number of years and which still forms the basis of this library today.
+A very special thank you to [Collective Idea](https://collectiveidea.com/)'s fantastic [Interactor](https://github.com/collectiveidea/interactor?tab=readme-ov-file#interactor) library, which [we](https://www.teamshares.com/) used successfully for a number of years and which we used to scaffold early versions of this library.

data/docs/reference/class.md

@@ -95,11 +95,11 @@ Accepts `error` and/or `success` keys.  Values can be a string (returned directl
 messages success: "All good!", error: ->(e) { "Bad news: #{e.message}" }
 ```
 
-## `error_for` and `rescues`
+## `error_from` and `rescues`
 
 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 exception handlers (global or specific to this class).
+`error_from` 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"
@@ -108,8 +108,8 @@ 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 -> { name == "bad" }, -> { "was given bad name: #{name}" }
+error_from ArgumentError, ->(e) { "Argument error: #{e.message}" }
+error_from -> { name == "bad" }, -> { "was given bad name: #{name}" }
 ```
 
 ## Callbacks
@@ -153,7 +153,7 @@ class Foo
 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):
+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_from` and `rescues`](#error-for-and-rescues):
 
 ```ruby
 class Foo

data/docs/reference/configuration.md

@@ -63,17 +63,26 @@ A couple notes:
 
 If you're using an APM provider, observability can be greatly enhanced by adding automatic _tracing_ of Action calls and/or emitting count metrics after each call completes.
 
+### Tracing and Metrics
+
+The framework provides two distinct hooks for observability:
+
+- **`wrap_with_trace`**: An around hook that wraps the entire action execution. You MUST call the provided block to execute the action.
+- **`emit_metrics`**: A post-execution hook that receives the action outcome. Do NOT call any blocks.
+
 For example, to wire up Datadog:
 
 ```ruby
   Action.configure do |c|
-    c.top_level_around_hook = proc do |resource, &action|
+    c.wrap_with_trace = proc do |resource, &action|
       Datadog::Tracing.trace("Action", resource:) do
-        (outcome, _exception) = action.call
-
-        TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome:, resource: })
+        action.call
       end
     end
+
+    c.emit_metrics = proc do |resource, outcome|
+      TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome:, resource: })
+    end
   end
 ```
 
@@ -81,6 +90,8 @@ A couple notes:
 
   * `Datadog::Tracing` is provided by [the datadog gem](https://rubygems.org/gems/datadog)
   * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that outcome (`success`, `failure`, `exception`) of the action is reported so you can easily track e.g. success rates per action.
+  * The `wrap_with_trace` hook is an around hook - you must call the provided block to execute the action
+  * The `emit_metrics` hook is called after execution with the outcome - do not call any blocks
 
 
 ## `logger`

data/docs/reference/instance.md

@@ -12,7 +12,7 @@ Primarily used for its side effects, but it does return a Hash with the key/valu
 
 ## `#fail!`
 
-Called with a string, it immediately halts execution (including triggering any [rollback handler](/reference/class#rollback) you have defined) and sets `result.error` to the provided string.
+Called with a string, it immediately halts execution and sets `result.error` to the provided string.
 
 ## `#log`
 
@@ -31,7 +31,7 @@ A few details:
 * An explicit `fail!` call _will_ still fail the action
 * Any exceptions swallowed _will_ still be reported via the `on_exception` handler
 
-This is primarily useful in an after block, e.g. trigger notifications after an action has been taken.  If the notification fails to send you DO want to log the failure somewhere to investigate, but since the core action has already been taken often you do _not_ want to fail and roll back.
+This is primarily useful in an after block, e.g. trigger notifications after an action has been taken.  If the notification fails to send you DO want to log the failure somewhere to investigate, but since the core action has already been taken often you do _not_ want to fail.
 
 Example:
 

data/docs/strategies/index.md

@@ -155,7 +155,7 @@ Action::Strategies.register(:retry, RetryStrategy)
 
 ### Example: Complete Custom Strategy
 
-Here's a complete example of a custom strategy that adds performance monitoring:
+Here's a complete example of a custom strategy that adds performance monitoring (note Axn already logs elapsed time, this is just a toy example):
 
 ```ruby
 module PerformanceMonitoringStrategy

data/docs/usage/setup.md

@@ -19,6 +19,6 @@ By default any swallowed errors are noted in the logs, but it's _highly recommen
 
 ### Metrics / Tracing
 
-If you're using an APM provider, observability can be greatly enhanced by [configuring a `top_level_around_hook`](/reference/configuration#top-level-around-hook).
+If you're using an APM provider, observability can be greatly enhanced by [configuring tracing and metrics hooks](/reference/configuration#tracing-and-metrics).
 
 

data/docs/usage/writing.md

@@ -104,18 +104,11 @@ 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`
-*** 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. -->
 
 ### Hooks
 
-`before` and `after` hooks are supported. They can receive a block directly, or the symbol name of a local method.
+`before`, `after`, and `around` 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 `result.ok?` be false even though `call` completed successfully).
 
@@ -150,6 +143,13 @@ in call
 after hook
 ```
 
+**Hook Ordering with Inheritance:**
+- **Around hooks**: Parent wraps child (parent outside, child inside)
+- **Before hooks**: Parent → Child (general setup first, then specific)
+- **After hooks**: Child → Parent (specific cleanup first, then general)
+
+This follows the natural pattern of setup (general → specific) and teardown (specific → general).
+
 ### 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.

data/lib/action/attachable.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "attachable/base"
-require_relative "attachable/steps"
-require_relative "attachable/subactions"
+require "action/attachable/base"
+require "action/attachable/steps"
+require "action/attachable/subactions"
 
 module Action
   module Attachable

data/lib/action/{core/configuration.rb → configuration.rb}

@@ -2,7 +2,7 @@
 
 module Action
   class Configuration
-    attr_accessor :top_level_around_hook
+    attr_accessor :wrap_with_trace, :emit_metrics
     attr_writer :logger, :env, :on_exception, :additional_includes, :default_log_level, :default_autolog_level
 
     def default_log_level = @default_log_level ||= :info

data/lib/action/context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# NOTE: This is a temporary file to be removed when we have a better way to handle context.
+# rubocop:disable Style/OpenStructUse, Style/CaseEquality
+require "ostruct"
+
+module Action
+  class Context < OpenStruct
+    def self.build(context = {})
+      self === context ? context : new(context)
+    end
+
+    def success?
+      !failure?
+    end
+
+    def failure?
+      @failure || false
+    end
+
+    def fail!(context = {})
+      context.each { |key, value| self[key.to_sym] = value }
+      @failure = true
+      raise Action::Failure, self
+    end
+  end
+end
+# rubocop:enable Style/OpenStructUse, Style/CaseEquality

data/lib/action/core/automatic_logging.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Action
+  module Core
+    module AutomaticLogging
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+        end
+      end
+
+      module ClassMethods
+        def autolog_level = Action.config.default_autolog_level
+      end
+
+      module InstanceMethods
+        private
+
+        def _log_before
+          public_send(
+            self.class.autolog_level,
+            [
+              "About to execute",
+              _log_context(:inbound),
+            ].compact.join(" with: "),
+            before: Action.config.env.production? ? nil : "\n------\n",
+          )
+        rescue StandardError => e
+          Axn::Util.piping_error("logging before hook", action: self, exception: e)
+        end
+
+        def _log_after(outcome:, timing_start:)
+          elapsed_mils = Core::Timing.elapsed_ms(timing_start)
+
+          public_send(
+            self.class.autolog_level,
+            [
+              "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
+              _log_context(:outbound),
+            ].compact.join(". Set: "),
+            after: Action.config.env.production? ? nil : "\n------\n",
+          )
+        rescue StandardError => e
+          Axn::Util.piping_error("logging after hook", action: self, exception: e)
+        end
+
+        def _log_context(direction)
+          data = context_for_logging(direction)
+          return unless data.present?
+
+          max_length = 150
+          suffix = "…<truncated>…"
+
+          _log_object(data).tap do |str|
+            return str[0, max_length - suffix.length] + suffix if str.length > max_length
+          end
+        end
+
+        def _log_object(data)
+          case data
+          when Hash
+            # NOTE: slightly more manual in order to avoid quotes around ActiveRecord objects' <Class#id> formatting
+            "{#{data.map { |k, v| "#{k}: #{_log_object(v)}" }.join(", ")}}"
+          when Array
+            data.map { |v| _log_object(v) }
+          else
+            return data.to_unsafe_h if defined?(ActionController::Parameters) && data.is_a?(ActionController::Parameters)
+            return "<#{data.class.name}##{data.to_param.presence || "unpersisted"}>" if defined?(ActiveRecord::Base) && data.is_a?(ActiveRecord::Base)
+
+            data.inspect
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/context_facade.rb

@@ -120,7 +120,7 @@ module Action
     end
 
     # Poke some holes for necessary internal control methods
-    delegate :called!, :rollback!, :each_pair, to: :context
+    delegate :each_pair, to: :context
 
     # External interface
     delegate :success?, :exception, to: :context