axn 0.1.0.pre.alpha.2.6 → 0.1.0.pre.alpha.2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49a6ab763d534efa878ff7f0d833beefeaae604bddb1c2e89090788a1e7df1a0
-  data.tar.gz: 828cfbd5ad2b9f753bf938bdb84201edbb406b367c159d4b1f437054a3bc213f
+  metadata.gz: 30c00229f0062bdba5979d0e69de4ffddb6bece3f31413f83b7f7778d3075ef7
+  data.tar.gz: 92d944caf300ddfc9a134d34ae2cb73e6d235e0af9f7a10a3ee93065ae834690
 SHA512:
-  metadata.gz: 8be59eb695a3df836513fb477b2338bb539da209821d17ab6502314ea57e62204e9a0e5ae49ec579db5d5c8e99ca6de57596acf577ee2027d8410e23a5013f15
-  data.tar.gz: 1a559aff5de117890928f67a5e0adefe1f2615c24f15ac6357dff0c74bd3f9a9470110618228a30aaba35ae489844cca4efd1f701aba0f1805c18b5c71edd7a9
+  metadata.gz: 600b1572f324b8cbbaf2b5dd48108546db86e63e3c7d49a04e1eb9f0f2e83720eafdaabb94ccf0550ff1c0e63b3ec555950443eb5c064698dbc65cf97c2b1733
+  data.tar.gz: e9229f25cd10dcc54f1f7c5b83ff81b997d96263296818caaf2cfc245fde93ab24d7f0605700ea042c085ab7456f5fc1b20c2cc643324609bc0f4662ecbdcd21

data/.rubocop.yml

@@ -42,8 +42,11 @@ Metrics/BlockLength:
 Metrics/ModuleLength:
   Enabled: false
 
+Metrics/ClassLength:
+  Max: 110
+
 Metrics/MethodLength:
-  Max: 60
+  Max: 70
 
 Metrics/PerceivedComplexity:
   Max: 16

data/CHANGELOG.md

@@ -3,6 +3,19 @@
 ## Unreleased
 * N/A
 
+## 0.1.0-alpha.2.6.1
+* [FEAT] Added `elapsed_time` and `outcome` methods to `Action::Result`
+  * `elapsed_time` returns execution time in milliseconds (Float)
+  * `outcome` returns execution outcome as symbol (`:success`, `:failure`, or `:exception`)
+* [BREAKING] `emit_metrics` hook now receives the full `Action::Result` object instead of just the outcome
+  * Provides access to both outcome and elapsed time for richer metrics
+  * Example: `proc { |resource, result| TS::Metrics.histogram("action.duration", result.elapsed_time) }`
+* [BREAKING] Replaced `Action.config.default_log_level` and `default_autolog_level` with simpler `log_level`
+* [BREAKING] `autolog_level` method overrides with e.g. `auto_log :warn` or `auto_log false`
+* [BREAKING] Direct access to exposed fields in callables no longer works -- `foo` becomes `result.foo`
+* [BREAKING] Removed `success?` check on Action::Result (use `ok?` instead)
+* [FEAT] Added callback and strategy support to Axn::Factory.build
+
 ## 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

data/docs/reference/action-result.md

@@ -9,6 +9,8 @@ Every `call` invocation on an Action will return an `Action::Result` instance, w
 | `success` | User-facing success message (string), if `ok?` (else nil)
 | `message` | User-facing message (string), always defined (`ok? ? success : error`)
 | `exception` | If not `ok?` because an exception was swallowed, will be set to the swallowed exception (note: rarely used outside development; prefer to let the library automatically handle exception handling for you)
+| `outcome` | The execution outcome as a symbol (`:success`, `:failure`, or `:exception`)
+| `elapsed_time` | Execution time in milliseconds (Float)
 | any `expose`d values | guaranteed to be set if `ok?` (since they have outgoing presence validations by default; any missing would have failed the action)
 
 NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `messages` declaration](/reference/class#messages).

data/docs/reference/class.md

@@ -89,10 +89,16 @@ will succeed if given _either_ an actual Date object _or_ a string that Date.par
 
 The `messages` declaration allows you to customize the `error` and `success` messages on the returned result.
 
-Accepts `error` and/or `success` keys.  Values can be a string (returned directly) or a callable (evaluated in the action's context, so can access instance methods).  If `error` is provided with a callable that expects a positional argument, the exception that was raised will be passed in as that value.
+Accepts `error` and/or `success` keys.  Values can be a string (returned directly) or a callable (evaluated in the action's context, so can access instance methods and variables).  If `error` is provided with a callable that expects a positional argument, the exception that was raised will be passed in as that value.
+
+In callables, you can access:
+- **Input data**: Use field names directly (e.g., `name`)
+- **Output data**: Use `result.field` pattern (e.g., `result.greeting`)
+- **Instance methods and variables**: Direct access
 
 ```ruby
-messages success: "All good!", error: ->(e) { "Bad news: #{e.message}" }
+messages success: -> { "Hello #{name}, your greeting: #{result.greeting}" },
+         error: ->(e) { "Bad news: #{e.message}" }
 ```
 
 ## `error_from` and `rescues`
@@ -101,15 +107,17 @@ While `.messages` sets the _default_ error/success messages and is more commonly
 
 `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).
 
+Callable matchers and messages follow the same data access patterns as other callables: input fields directly, output fields via `result.field`, instance variables, and methods.
+
 ```ruby
 messages error: "bad"
 
 # Note this will NOT trigger Action.config.on_exception
 rescues ActiveRecord::InvalidRecord => "Invalid params provided"
 
-# These WILL trigger error handler (second demonstrates callable matcher AND message)
+# These WILL trigger error handler (callable matcher + message with data access)
 error_from ArgumentError, ->(e) { "Argument error: #{e.message}" }
-error_from -> { name == "bad" }, -> { "was given bad name: #{name}" }
+error_from -> { name == "bad" }, -> { "Bad input #{name}, result: #{result.status}" }
 ```
 
 ## Callbacks

data/docs/reference/configuration.md

@@ -4,18 +4,16 @@ Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call
 
 
 ```ruby
-  Action.configure do |c|
-    c.on_exception = ...
-
-    c.top_level_around_hook = ...
-
-    c.additional_includes = []
-
-    c.default_log_level = :info
-    c.default_autolog_level = :debug
-
-    c.logger = ...
+Action.configure do |c|
+  c.log_level = :info
+  c.logger = ...
+  c.on_exception = proc do |e, action:, context:|
+    message = "[#{action.class.name}] Failing due to #{e.class.name}: #{e.message}"
+
+    Rails.logger.warn(message)
+    Honeybadger.notify(message, context: { axn_context: context })
   end
+end
 ```
 
 ## `on_exception`
@@ -68,7 +66,7 @@ If you're using an APM provider, observability can be greatly enhanced by adding
 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.
+- **`emit_metrics`**: A post-execution hook that receives the action result. Do NOT call any blocks.
 
 For example, to wire up Datadog:
 
@@ -80,8 +78,9 @@ For example, to wire up Datadog:
       end
     end
 
-    c.emit_metrics = proc do |resource, outcome|
-      TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome:, resource: })
+    c.emit_metrics = proc do |resource, result|
+      TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome, resource: })
+      TS::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
     end
   end
 ```
@@ -89,9 +88,9 @@ For example, to wire up Datadog:
 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.
+  * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that the result object provides access to the outcome (`success`, `failure`, `exception`) and elapsed time of the 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
+  * The `emit_metrics` hook is called after execution with the result - do not call any blocks
 
 
 ## `logger`
@@ -112,11 +111,11 @@ For example:
 
 For a practical example of this in practice, see [our 'memoization' recipe](/recipes/memoization).
 
-## `default_log_level`
+## `log_level`
 
-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.
+Sets the log level used when you call `log "Some message"` in your Action.  Note this is read via a `log_level` class method, so you can easily use inheritance to support different log levels for different sets of actions.
 
-## `default_autolog_level`
+## Automatic Logging
 
 By default, every `action.call` will emit log lines when it is called and after it completes:
 
@@ -125,4 +124,27 @@ By default, every `action.call` will emit log lines when it is called and after
     [YourCustomAction] Execution completed (with outcome: success) in 0.957 milliseconds
   ```
 
-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).
+Automatic logging will log at `Action.config.log_level` by default, but can be overridden or disabled using the declarative `auto_log` method:
+
+```ruby
+# Set default for all actions (affects both explicit logging and automatic logging)
+Action.configure do |c|
+  c.log_level = :debug
+end
+
+# Override for specific actions
+class MyAction
+  auto_log :warn  # Use warn level for this action
+end
+
+class SilentAction
+  auto_log false  # Disable automatic logging for this action
+end
+
+# Use default level (no auto_log call needed)
+class DefaultAction
+  # Uses Action.config.log_level
+end
+```
+
+The `auto_log` method supports inheritance, so subclasses will inherit the setting from their parent class unless explicitly overridden.

data/docs/usage/writing.md

@@ -79,7 +79,7 @@ class Foo
   expects :name, type: String
   exposes :meaning_of_life
 
-  messages success: -> { "Revealed the secret of life to #{name}" }, # [!code focus:2]
+  messages success: -> { "Revealed to #{name}: #{result.meaning_of_life}" }, # [!code focus:2]
            error: ->(e) { "No secret of life for you: #{e.message}" }
 
   def call

data/lib/action/attachable/steps.rb

@@ -38,10 +38,25 @@ module Action
           step = Entry.new(label: "Step #{idx + 1}", axn: step) if step.is_a?(Class)
 
           hoist_errors(prefix: "#{step.label} step") do
-            step.axn.call(@context)
+            step.axn.call(**merged_context_data).tap do |step_result|
+              merge_step_exposures!(step_result)
+            end
           end
         end
       end
+
+      private
+
+      def merged_context_data
+        @__context.__combined_data
+      end
+
+      # Each step can expect the data exposed from the previous steps
+      def merge_step_exposures!(step_result)
+        step_result.declared_fields.each do |field|
+          @__context.exposed_data[field] = step_result.public_send(field)
+        end
+      end
     end
   end
 end

data/lib/action/configuration.rb

@@ -3,10 +3,9 @@
 module Action
   class Configuration
     attr_accessor :wrap_with_trace, :emit_metrics
-    attr_writer :logger, :env, :on_exception, :additional_includes, :default_log_level, :default_autolog_level
+    attr_writer :logger, :env, :on_exception, :additional_includes, :log_level
 
-    def default_log_level = @default_log_level ||= :info
-    def default_autolog_level = @default_autolog_level ||= :info
+    def log_level = @log_level ||= :info
 
     def additional_includes = @additional_includes ||= []
 

data/lib/action/context.rb

@@ -1,28 +1,38 @@
 # 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
+  class Context
+    attr_accessor :provided_data, :exposed_data
 
-    def success?
-      !failure?
-    end
+    def initialize(**provided_data)
+      @provided_data = provided_data
+      @exposed_data = {}
 
-    def failure?
-      @failure || false
+      # Framework-managed fields
+      @failure = false
+      @exception = nil
+      @error_from_user = nil
+      @error_prefix = nil
+      @elapsed_time = nil
     end
 
-    def fail!(context = {})
-      context.each { |key, value| self[key.to_sym] = value }
-      @failure = true
-      raise Action::Failure, self
+    def fail!(message = nil)
+      @error_from_user = message if message.present?
+      raise Action::Failure, message
     end
+
+    # INTERNAL: base for further filtering (for logging) or providing user with usage hints
+    def __combined_data = @provided_data.merge(@exposed_data)
+
+    # Framework state methods
+    def ok? = !@failure
+    def failed? = @failure || false
+
+    # Framework field accessors
+    attr_accessor :exception, :error_from_user, :error_prefix, :elapsed_time
+
+    # Internal failure state setter (for framework use)
+    attr_writer :failure
+    private :failure=
   end
 end
-# rubocop:enable Style/OpenStructUse, Style/CaseEquality

data/lib/action/core/automatic_logging.rb

@@ -7,19 +7,34 @@ module Action
         base.class_eval do
           extend ClassMethods
           include InstanceMethods
+
+          # Single class_attribute - nil means disabled, any level means enabled
+          class_attribute :auto_log_level, default: Action.config.log_level
         end
       end
 
       module ClassMethods
-        def autolog_level = Action.config.default_autolog_level
+        def auto_log(level)
+          self.auto_log_level = level.presence
+        end
       end
 
       module InstanceMethods
         private
 
+        def _with_logging
+          _log_before if self.class.auto_log_level
+          yield
+        ensure
+          _log_after if self.class.auto_log_level
+        end
+
         def _log_before
-          public_send(
-            self.class.autolog_level,
+          level = self.class.auto_log_level
+          return unless level
+
+          self.class.public_send(
+            level,
             [
               "About to execute",
               _log_context(:inbound),
@@ -30,13 +45,14 @@ module Action
           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)
+        def _log_after
+          level = self.class.auto_log_level
+          return unless level
 
-          public_send(
-            self.class.autolog_level,
+          self.class.public_send(
+            level,
             [
-              "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
+              "Execution completed (with outcome: #{result.outcome}) in #{result.elapsed_time} milliseconds",
               _log_context(:outbound),
             ].compact.join(". Set: "),
             after: Action.config.env.production? ? nil : "\n------\n",

data/lib/action/core/context/facade.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_support/parameter_filter"
+
+module Action
+  class ContextFacade
+    def initialize(action:, context:, declared_fields:, implicitly_allowed_fields: nil)
+      if self.class.name == "Action::ContextFacade" # rubocop:disable Style/ClassEqualityComparison
+        raise "Action::ContextFacade is an abstract class and should not be instantiated directly"
+      end
+
+      @context = context
+      @action = action
+      @declared_fields = declared_fields
+
+      (@declared_fields + Array(implicitly_allowed_fields)).each do |field|
+        singleton_class.define_method(field) do
+          context_data_source[field]
+        end
+      end
+    end
+
+    attr_reader :declared_fields
+
+    def inspect = ContextFacadeInspector.new(facade: self, action:, context:).call
+
+    def fail!(...)
+      raise Action::ContractViolation::MethodNotAllowed, "Call fail! directly rather than on the context"
+    end
+
+    private
+
+    attr_reader :action, :context
+
+    def action_name = @action.class.name.presence || "The action"
+
+    def context_data_source = raise NotImplementedError
+
+    def determine_error_message(only_default: false)
+      return @context.error_from_user if @context.error_from_user.present?
+
+      # 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
+        interceptor = action.class._error_interceptor_for(exception:, action:)
+        msg = interceptor.message if interceptor
+      end
+
+      stringified(msg, exception:).presence || "Something went wrong"
+    end
+
+    # Allow for callable OR string messages
+    def stringified(msg, exception: nil)
+      return msg.presence unless msg.respond_to?(:call)
+
+      # The error message callable can take the exception as an argument
+      if exception && msg.arity == 1
+        action.instance_exec(exception, &msg)
+      else
+        action.instance_exec(&msg)
+      end
+    rescue StandardError => e
+      Axn::Util.piping_error("determining message callable", action:, exception: e)
+    end
+  end
+end

data/lib/action/core/context/facade_inspector.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Action
+  class ContextFacadeInspector
+    def initialize(action:, facade:, context:)
+      @action = action
+      @facade = facade
+      @context = context
+    end
+
+    def call
+      str = [status, visible_fields].compact_blank.join(" ")
+
+      "#<#{class_name} #{str}>"
+    end
+
+    private
+
+    attr_reader :action, :facade, :context
+
+    def status
+      return unless facade.is_a?(Action::Result)
+
+      return "[OK]" if context.ok?
+      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
+
+    def visible_fields
+      declared_fields.map do |field|
+        value = facade.public_send(field)
+
+        "#{field}: #{format_for_inspect(field, value)}"
+      end.join(", ")
+    end
+
+    def class_name = facade.class.name
+    def declared_fields = facade.send(:declared_fields)
+
+    def format_for_inspect(field, value)
+      return value.inspect if value.nil?
+
+      # Initially based on https://github.com/rails/rails/blob/800976975253be2912d09a80757ee70a2bb1e984/activerecord/lib/active_record/attribute_methods.rb#L527
+      inspected_value = if value.is_a?(String) && value.length > 50
+                          "#{value[0, 50]}...".inspect
+                        elsif value.is_a?(Date) || value.is_a?(Time)
+                          %("#{value.to_fs(:inspect)}")
+                        elsif defined?(::ActiveRecord::Relation) && value.instance_of?(::ActiveRecord::Relation)
+                          # Avoid hydrating full AR relation (i.e. avoid loading records just to report an error)
+                          "#{value.name}::ActiveRecord_Relation"
+                        else
+                          value.inspect
+                        end
+
+      inspection_filter.filter_param(field, inspected_value)
+    end
+
+    def inspection_filter = action.send(:inspection_filter)
+  end
+end

data/lib/action/core/context/internal.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "action/core/context/facade"
+
+module Action
+  # Inbound / Internal ContextFacade
+  class InternalContext < ContextFacade
+    # So can be referenced from within e.g. rescues callables
+    def default_error
+      [@context.error_prefix, determine_error_message(only_default: true)].compact.join(" ").squeeze(" ")
+    end
+
+    private
+
+    def context_data_source = @context.provided_data
+
+    def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)
+      if @context.__combined_data.key?(method_name.to_sym)
+        msg = <<~MSG
+          Method ##{method_name} is not available on Action::InternalContext!
+
+          #{action_name} may be missing a line like:
+            expects :#{method_name}
+        MSG
+
+        raise Action::ContractViolation::MethodNotAllowed, msg
+      end
+
+      super
+    end
+  end
+end

data/lib/action/core/contract.rb

@@ -4,7 +4,8 @@ require "active_support/core_ext/enumerable"
 require "active_support/core_ext/module/delegation"
 
 require "action/core/validation/fields"
-require "action/core/context_facade"
+require "action/result"
+require "action/core/context/internal"
 
 module Action
   module Core
@@ -70,13 +71,13 @@ module Action
         private
 
         RESERVED_FIELD_NAMES_FOR_EXPECTATIONS = %w[
-          fail! success? ok?
+          fail! ok?
           inspect default_error
           each_pair
         ].freeze
 
         RESERVED_FIELD_NAMES_FOR_EXPOSURES = %w[
-          fail! success? ok?
+          fail! ok?
           inspect each_pair default_error
           ok error success message
         ].freeze
@@ -114,13 +115,15 @@ module Action
           define_method(field) { internal_context.public_send(field) }
         end
 
-        def _define_model_reader(field, klass)
+        def _define_model_reader(field, klass, &id_extractor)
           name = field.to_s.delete_suffix("_id")
           raise ArgumentError, "Model validation expects to be given a field ending in _id (given: #{field})" unless field.to_s.end_with?("_id")
           raise ArgumentError, "Failed to define model reader - #{name} is already defined" if method_defined?(name)
 
+          id_extractor ||= -> { public_send(field) }
+
           define_memoized_reader_method(name) do
-            Validators::ModelValidator.instance_for(field:, klass:, id: public_send(field))
+            Validators::ModelValidator.instance_for(field:, klass:, id: instance_exec(&id_extractor))
           end
         end
 
@@ -166,23 +169,37 @@ module Action
           kwargs.each do |key, value|
             raise Action::ContractViolation::UnknownExposure, key unless result.respond_to?(key)
 
-            @context.public_send("#{key}=", value)
+            @__context.exposed_data[key] = value
           end
         end
 
         def context_for_logging(direction = nil)
-          inspection_filter.filter(@context.to_h.slice(*_declared_fields(direction)))
+          inspection_filter.filter(@__context.__combined_data.slice(*_declared_fields(direction)))
         end
 
         private
 
+        def _with_contract
+          _apply_inbound_preprocessing!
+          _apply_defaults!(:inbound)
+          _validate_contract!(:inbound)
+
+          yield
+
+          _apply_defaults!(:outbound)
+          _validate_contract!(:outbound)
+
+          # TODO: improve location of this triggering
+          _trigger_on_success if respond_to?(:_trigger_on_success)
+        end
+
         def _build_context_facade(direction)
           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) : []
 
-          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
 
         def inspection_filter

data/lib/action/core/contract_for_subfields.rb

@@ -86,7 +86,7 @@ module Action
             Action::Validation::Subfields.extract(field, public_send(on))
           end
 
-          _define_model_reader(field, validations[:model]) if validations.key?(:model)
+          _define_model_reader(field, validations[:model]) { Action::Validation::Subfields.extract(field, public_send(on)) } if validations.key?(:model)
         end
       end