axn 0.1.0.pre.alpha.3 → 0.1.0.pre.alpha.4

data/lib/axn/core/memoization.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module Memoization
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        def memo(method_name)
+          if _memo_wise_available?
+            _ensure_memo_wise_prepended
+            memo_wise(method_name)
+          else
+            _memo_minimal(method_name)
+          end
+        end
+
+        private
+
+        def _memo_wise_available?
+          defined?(MemoWise)
+        end
+
+        def _ensure_memo_wise_prepended
+          return if ancestors.include?(MemoWise)
+
+          prepend MemoWise
+        end
+
+        def _memo_minimal(method_name)
+          method = instance_method(method_name)
+          params = method.parameters
+          has_args = params.any? { |type, _name| %i[req opt rest keyreq key keyrest].include?(type) }
+
+          if has_args
+            raise ArgumentError,
+                  "Memoization of methods with arguments requires the 'memo_wise' gem. " \
+                  "Please add 'memo_wise' to your Gemfile or use a method without arguments."
+          end
+
+          # Wrap the method with memoization
+          Axn::Util::Memoization.define_memoized_reader_method(self, method_name) do
+            method.bind(self).call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/axn/core/tracing.rb

@@ -1,16 +1,89 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Axn
   module Core
     module Tracing
+      class << self
+        # Cache the tracer instance to avoid repeated lookups
+        # The tracer provider may cache internally, but we avoid the method call overhead
+        # We check defined?(OpenTelemetry) each time to handle cases where it's loaded lazily
+        def tracer
+          return nil unless defined?(OpenTelemetry)
+
+          # Re-fetch if the tracer provider has changed (e.g., in tests with mocks)
+          current_provider = OpenTelemetry.tracer_provider
+          return @tracer if defined?(@tracer) && defined?(@tracer_provider) && @tracer_provider == current_provider
+
+          @tracer_provider = current_provider
+          @tracer = current_provider.tracer("axn", Axn::VERSION)
+        end
+      end
+
       private
 
       def _with_tracing(&)
-        return yield unless Axn.config.wrap_with_trace
+        resource = self.class.name || "AnonymousClass"
+        payload = { resource:, action: self }
+
+        update_payload = proc do
+          result = self.result
+          outcome = result.outcome.to_s
+          payload[:outcome] = outcome
+          payload[:result] = result
+          payload[:elapsed_time] = result.elapsed_time
+          payload[:exception] = result.exception if result.exception
+        rescue StandardError => e
+          # Don't raise in ensure block to avoid interfering with existing exceptions
+          Axn::Internal::Logging.piping_error("updating notification payload while tracing axn.call", action: self, exception: e)
+        end
+
+        instrument_block = proc do
+          ActiveSupport::Notifications.instrument("axn.call", payload, &)
+        ensure
+          # Update payload BEFORE instrument completes so subscribers see the changes
+          update_payload.call
+        end
+
+        # NOTE: despite using block form, ActiveSupport explicitly only emits to subscribers when it's finished,
+        # which means it's not suitable for wrapping execution with a span and tracking child spans.
+        # We use OpenTelemetry for that, if available.
+        if defined?(OpenTelemetry)
+          Tracing.tracer.in_span("axn.call", attributes: { "axn.resource" => resource }) do |span|
+            instrument_block.call
+          ensure
+            # Update span with outcome and error status after execution
+            # This ensure runs before the span finishes, so we can still update it
+            begin
+              result = self.result
+              outcome = result.outcome.to_s
+              span.set_attribute("axn.outcome", outcome)
 
-        Axn.config.wrap_with_trace.call(self.class.name || "AnonymousClass", &)
-      rescue StandardError => e
-        Axn::Internal::Logging.piping_error("running trace hook", action: self, exception: e)
+              if %w[failure exception].include?(outcome) && result.exception
+                span.record_exception(result.exception)
+                error_message = result.exception.message || result.exception.class.name
+                span.status = OpenTelemetry::Trace::Status.error(error_message)
+              end
+            rescue StandardError => e
+              # Don't raise in ensure block to avoid interfering with existing exceptions
+              Axn::Internal::Logging.piping_error("updating OTel span while tracing axn.call", action: self, exception: e)
+            end
+          end
+        else
+          instrument_block.call
+        end
+      ensure
+        begin
+          emit_metrics_proc = Axn.config.emit_metrics
+          if emit_metrics_proc
+            result = self.result
+            Axn::Util::Callable.call_with_desired_shape(emit_metrics_proc, kwargs: { resource:, result: })
+          end
+        rescue StandardError => e
+          # Don't raise in ensure block to avoid interfering with existing exceptions
+          Axn::Internal::Logging.piping_error("calling emit_metrics while tracing axn.call", action: self, exception: e)
+        end
       end
     end
   end

data/lib/axn/core/validation/validators/type_validator.rb

@@ -39,7 +39,7 @@ module Axn
       private
 
       def types = Array(options[:klass])
-      def msg = types.size == 1 ? "is not a #{types.first}" : "is not one of #{types.join(", ")}"
+      def msg = types.size == 1 ? "is not a #{types.first}" : "is not one of #{types.join(', ')}"
 
       def valid_type?(type:, value:, allow_blank:)
         # NOTE: allow mocks to pass type validation by default (much easier testing ergonomics)

data/lib/axn/core.rb

@@ -5,6 +5,7 @@ require "axn/internal/logging"
 require "axn/context"
 
 require "axn/strategies"
+require "axn/extras"
 require "axn/core/hooks"
 require "axn/core/logging"
 require "axn/core/flow"
@@ -12,8 +13,8 @@ require "axn/core/automatic_logging"
 require "axn/core/use_strategy"
 require "axn/core/timing"
 require "axn/core/tracing"
-require "axn/core/profiling"
 require "axn/core/nesting_tracking"
+require "axn/core/memoization"
 
 # CONSIDER: make class names match file paths?
 require "axn/core/validation/validators/model_validator"
@@ -25,9 +26,27 @@ require "axn/core/contract_validation"
 require "axn/core/contract_validation_for_subfields"
 require "axn/core/contract"
 require "axn/core/contract_for_subfields"
+require "axn/core/default_call"
 
 module Axn
   module Core
+    module ClassMethods
+      def call(**)
+        new(**).tap(&:_run).result
+      end
+
+      def call!(**)
+        result = call(**)
+        return result if result.ok?
+
+        # When we're nested, we want to raise a failure that includes the source action to support
+        # the error message generation's `from` filter
+        raise Axn::Failure.new(result.error, source: result.__action__), cause: result.exception if _nested_in_another_axn?
+
+        raise result.exception
+      end
+    end
+
     def self.included(base)
       base.class_eval do
         extend ClassMethods
@@ -36,7 +55,6 @@ module Axn
         include Core::AutomaticLogging
         include Core::Tracing
         include Core::Timing
-        include Core::Profiling
 
         include Core::Flow
 
@@ -47,42 +65,21 @@ module Axn
         include Core::NestingTracking
 
         include Core::UseStrategy
+        include Core::Memoization
+        include Core::DefaultCall
       end
     end
 
-    module ClassMethods
-      def call(**)
-        new(**).tap(&:_run).result
-      end
-
-      def call!(**)
-        result = call(**)
-        return result if result.ok?
-
-        # When we're nested, we want to raise a failure that includes the source action to support
-        # the error message generation's `from` filter
-        raise Axn::Failure.new(result.error, source: result.__action__), cause: result.exception if _nested_in_another_axn?
-
-        raise result.exception
-      end
-    end
-
-    def initialize(**)
-      @__context = Axn::Context.new(**)
-    end
-
     # Main entry point for action execution
     def _run
       _tracking_nesting(self) do
-        _with_profiling do
-          _with_tracing do
-            _with_logging do
-              _with_timing do
-                _with_exception_handling do # Exceptions stop here; outer wrappers access result status (and must not introduce another exception layer)
-                  _with_contract do # Library internals -- any failures (e.g. contract violations) *should* fail the Action::Result
-                    _with_hooks do # User hooks -- any failures here *should* fail the Action::Result
-                      call
-                    end
+        _with_tracing do
+          _with_logging do
+            _with_timing do
+              _with_exception_handling do # Exceptions stop here; outer wrappers access result status (and must not introduce another exception layer)
+                _with_contract do # Library internals -- any failures (e.g. contract violations) *should* fail the Action::Result
+                  _with_hooks do # User hooks -- any failures here *should* fail the Action::Result
+                    call
                   end
                 end
               end
@@ -90,13 +87,8 @@ module Axn
           end
         end
       end
-    ensure
-      _emit_metrics
     end
 
-    # User-defined action logic - override this method in your action classes
-    def call; end
-
     def fail!(message = nil, **exposures)
       expose(**exposures) if exposures.any?
       raise Axn::Failure, message
@@ -109,15 +101,8 @@ module Axn
 
     private
 
-    def _emit_metrics
-      return unless Axn.config.emit_metrics
-
-      Axn.config.emit_metrics.call(
-        self.class.name || "AnonymousClass",
-        result,
-      )
-    rescue StandardError => e
-      Axn::Internal::Logging.piping_error("running metrics hook", action: self, exception: e)
+    def initialize(**)
+      @__context = Axn::Context.new(**)
     end
   end
 end

data/lib/axn/extras/strategies/client.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockNesting
+module Axn
+  module Extras
+    module Strategies
+      module Client
+        def self.configure(name: :client, prepend_config: nil, debug: false, user_agent: nil, error_handler: nil, **options, &block)
+          # Aliasing to avoid shadowing/any confusion
+          client_name = name
+          error_handler_config = error_handler
+
+          Module.new do
+            extend ActiveSupport::Concern
+
+            included do
+              raise ArgumentError, "client strategy: desired client name '#{client_name}' is already taken" if method_defined?(client_name)
+
+              define_method client_name do
+                # Hydrate options that are callable (e.g. procs), so we can set e.g. per-request expiration
+                # headers and/or other non-static values.
+                hydrated_options = options.transform_values do |value|
+                  value.respond_to?(:call) ? value.call : value
+                end
+
+                ::Faraday.new(**hydrated_options) do |conn|
+                  conn.headers["Content-Type"] = "application/json"
+                  conn.headers["User-Agent"] = user_agent || "#{client_name} / Axn Client Strategy / v#{Axn::VERSION}"
+
+                  # Because middleware is executed in reverse order, downstream user may need flexibility in where to inject configs
+                  prepend_config&.call(conn)
+
+                  conn.response :raise_error
+                  conn.request :url_encoded
+                  conn.request :json
+                  conn.response :json, content_type: /\bjson$/
+
+                  # Enable for debugging
+                  conn.response :logger if debug
+
+                  # Inject error handler middleware if configured
+                  if error_handler_config && defined?(Faraday)
+                    unless Client.const_defined?(:ErrorHandlerMiddleware, false)
+                      Client.const_set(:ErrorHandlerMiddleware, Class.new(::Faraday::Middleware) do
+                        def initialize(app, config)
+                          super(app)
+                          @config = config
+                        end
+
+                        def call(env)
+                          @app.call(env).on_complete do |response_env|
+                            body = parse_body(response_env.body)
+                            condition = @config[:if] || -> { status != 200 }
+
+                            @response_env = response_env
+                            @body = body
+                            should_handle = instance_exec(&condition)
+
+                            handle_error(response_env, body) if should_handle
+                          end
+                        end
+
+                        def status
+                          @response_env&.status
+                        end
+
+                        attr_reader :body, :response_env
+
+                        private
+
+                        def parse_body(body)
+                          return {} if body.blank?
+
+                          body.is_a?(String) ? JSON.parse(body) : body
+                        rescue JSON::ParserError
+                          {}
+                        end
+
+                        def handle_error(response_env, body)
+                          error = extract_value(body, @config[:error_key])
+                          details = extract_value(body, @config[:detail_key]) if @config[:detail_key]
+                          backtrace = extract_value(body, @config[:backtrace_key]) if @config[:backtrace_key]
+
+                          formatted_message = if @config[:formatter]
+                                                @config[:formatter].call(error, details, response_env)
+                                              else
+                                                format_default_message(error, details)
+                                              end
+
+                          prefix = "Error while #{response_env.method.to_s.upcase}ing #{response_env.url}"
+                          message = formatted_message.present? ? "#{prefix}: #{formatted_message}" : prefix
+
+                          exception_class = @config[:exception_class] || ::Faraday::BadRequestError
+                          exception = exception_class.new(message)
+                          exception.set_backtrace(backtrace) if backtrace.present?
+                          raise exception
+                        end
+
+                        def extract_value(data, key)
+                          return nil if key.blank?
+
+                          keys = key.split(".")
+                          keys.reduce(data) do |current, k|
+                            return nil unless current.is_a?(Hash)
+
+                            current[k.to_s] || current[k.to_sym]
+                          end
+                        end
+
+                        def format_default_message(error, details)
+                          parts = []
+                          parts << error if error
+
+                          if details
+                            if @config[:extract_detail]
+                              extracted = if details.is_a?(Hash)
+                                            details.map { |key, value| @config[:extract_detail].call(key, value) }.compact.to_sentence
+                                          else
+                                            Array(details).map { |node| @config[:extract_detail].call(node) }.compact.to_sentence
+                                          end
+                              parts << extracted if extracted.present?
+                            elsif details.present?
+                              raise ArgumentError, "must provide extract_detail when detail_key is set and details is not a string" unless details.is_a?(String)
+
+                              parts << details
+                            end
+                          end
+
+                          parts.compact.join(" - ")
+                        end
+                      end)
+                    end
+                    conn.use Client::ErrorHandlerMiddleware, error_handler_config
+                  end
+
+                  block&.call(conn)
+                end
+              end
+              memo client_name
+            end
+          end
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockNesting
+
+# Register the strategy only if faraday is available
+Axn::Strategies.register(:client, Axn::Extras::Strategies::Client) if defined?(Faraday)

data/lib/axn/extras/strategies/vernier.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "axn/core/flow/handlers/invoker"
+
+module Axn
+  module Extras
+    module Strategies
+      module Vernier
+        # @param if [Proc, Symbol, #call, nil] Optional condition to determine when to profile
+        # @param sample_rate [Float] Sampling rate (0.0 to 1.0, default: 0.1)
+        # @param output_dir [String, Pathname] Output directory for profile files (default: Rails.root/tmp/profiles or tmp/profiles)
+        # @return [Module] A configured module that adds profiling to the action
+        def self.configure(if: nil, sample_rate: 0.1, output_dir: nil)
+          condition = binding.local_variable_get(:if)
+          sample_rate_value = sample_rate
+          output_dir_value = output_dir || _default_output_dir
+
+          Module.new do
+            extend ActiveSupport::Concern
+
+            included do
+              class_attribute :_vernier_condition, default: condition
+              class_attribute :_vernier_sample_rate, default: sample_rate_value
+              class_attribute :_vernier_output_dir, default: output_dir_value
+
+              around do |hooked|
+                _with_vernier_profiling { hooked.call }
+              end
+            end
+
+            private
+
+            def _with_vernier_profiling(&)
+              return yield unless _should_profile?
+
+              _profile_with_vernier(&)
+            end
+
+            def _profile_with_vernier(&)
+              _ensure_vernier_available!
+
+              class_name = self.class.name.presence || "AnonymousAction"
+              profile_name = "axn_#{class_name}_#{Time.now.to_i}"
+
+              # Ensure output directory exists (only once per instance)
+              _ensure_output_directory_exists
+
+              # Build output file path
+              output_dir = self.class._vernier_output_dir || _default_output_dir
+              output_file = File.join(output_dir, "#{profile_name}.json")
+
+              # Configure Vernier with our settings
+              collector_options = {
+                out: output_file,
+                allocation_sample_rate: (self.class._vernier_sample_rate * 1000).to_i,
+              }
+
+              ::Vernier.profile(**collector_options, &)
+            end
+
+            def _ensure_output_directory_exists
+              return if @_vernier_directory_created
+
+              output_dir = self.class._vernier_output_dir || _default_output_dir
+              FileUtils.mkdir_p(output_dir)
+              @_vernier_directory_created = true
+            end
+
+            def _should_profile?
+              # Fast path: no condition means always profile
+              return true unless self.class._vernier_condition
+
+              # Slow path: evaluate condition (only when needed)
+              Axn::Core::Flow::Handlers::Invoker.call(
+                action: self,
+                handler: self.class._vernier_condition,
+                operation: "determining if profiling should run",
+              )
+            end
+
+            def _ensure_vernier_available!
+              return if defined?(::Vernier) && ::Vernier.is_a?(Module)
+
+              begin
+                require "vernier"
+              rescue LoadError
+                raise LoadError, <<~ERROR
+                  Vernier profiler is not available. To use profiling, add 'vernier' to your Gemfile:
+
+                    gem 'vernier', '~> 1.0'
+
+                  Then run: bundle install
+                ERROR
+              end
+            end
+
+            def _default_output_dir
+              if defined?(Rails) && Rails.respond_to?(:root)
+                Rails.root.join("tmp", "profiles")
+              else
+                Pathname.new("tmp/profiles")
+              end
+            end
+          end
+        end
+
+        private_class_method def self._default_output_dir
+          if defined?(Rails) && Rails.respond_to?(:root)
+            Rails.root.join("tmp", "profiles")
+          else
+            Pathname.new("tmp/profiles")
+          end
+        end
+      end
+    end
+  end
+end
+
+# Register the strategy (it handles missing vernier dependency gracefully)
+Axn::Strategies.register(:vernier, Axn::Extras::Strategies::Vernier)

data/lib/axn/extras.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "axn/extras/strategies/client"
+require "axn/extras/strategies/vernier"

data/lib/axn/factory.rb

@@ -2,6 +2,8 @@
 
 module Axn
   class Factory
+    NOT_PROVIDED = :__not_provided__
+
     class << self
       # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
       def build(
@@ -38,6 +40,14 @@ module Axn
         # Async configuration
         async: nil,
 
+        # Logging configuration
+        log_calls: NOT_PROVIDED,
+        log_errors: NOT_PROVIDED,
+
+        # Internal flag to prevent recursion during action class creation
+        # Tracks which target class is having an action class created for it
+        _creating_action_class_for: nil,
+
         &block
       )
         raise ArgumentError, "[Axn::Factory] Cannot receive both a callable and a block" if callable.present? && block_given?
@@ -66,7 +76,7 @@ module Axn
         end
 
         # NOTE: inheriting from wrapping class, so we can set default values (e.g. for HTTP headers)
-        _build_axn_class(superclass:, args:, executable:, expose_return_as:, include:, extend:, prepend:).tap do |axn|
+        _build_axn_class(superclass:, args:, executable:, expose_return_as:, include:, extend:, prepend:, _creating_action_class_for:).tap do |axn|
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end
@@ -75,6 +85,10 @@ module Axn
             axn.exposes(field, **opts)
           end
 
+          # Apply logging configuration (always apply if provided to override defaults)
+          axn.log_calls(log_calls) unless log_calls == NOT_PROVIDED
+          axn.log_errors(log_errors) unless log_errors == NOT_PROVIDED
+
           # Apply success and error handlers
           _apply_handlers(axn, :success, success, Axn::Core::Flow::Handlers::Descriptors::MessageDescriptor)
           _apply_handlers(axn, :error, error, Axn::Core::Flow::Handlers::Descriptors::MessageDescriptor)
@@ -155,7 +169,11 @@ module Axn
         end
       end
 
-      def _build_axn_class(superclass:, args:, executable:, expose_return_as:, include: nil, extend: nil, prepend: nil)
+      def _build_axn_class(superclass:, args:, executable:, expose_return_as:, include: nil, extend: nil, prepend: nil, _creating_action_class_for: nil) # rubocop:disable Lint/UnderscorePrefixedVariableName
+        # Mark superclass if we're creating an action class (for recursion prevention)
+        # Track which target class is having an action created for it
+        superclass.instance_variable_set(:@_axn_creating_action_class_for, _creating_action_class_for) if _creating_action_class_for && superclass
+
         Class.new(superclass || Object) do
           include Axn unless self < Axn
 
@@ -177,6 +195,8 @@ module Axn
             expose(expose_return_as => retval) if expose_return_as.present?
           end
         end
+      ensure
+        superclass.instance_variable_set(:@_axn_creating_action_class_for, nil) if _creating_action_class_for && superclass
       end
 
       def _apply_async_config(axn, async)