axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/lib/{action → axn}/core/validation/subfields.rb

@@ -2,7 +2,7 @@
 
 require "active_support/core_ext/hash/indifferent_access"
 
-module Action
+module Axn
   module Validation
     class Subfields
       include ActiveModel::Validations
@@ -17,24 +17,26 @@ module Action
       end
 
       def read_attribute_for_validation(attr)
-        self.class.extract(attr, @source)
+        # Only use action's reader methods for model fields that need special resolution
+        # For all other fields, use the unified FieldResolvers system
+        if @action && @validations&.key?(:model) && @action.respond_to?(attr)
+          @action.public_send(attr)
+        else
+          Axn::Core::FieldResolvers.resolve(type: :extract, field: attr, provided_data: @source)
+        end
       end
 
-      def self.extract(attr, source)
-        return source.public_send(attr) if source.respond_to?(attr)
-        raise "Unclear how to extract #{attr} from #{source.inspect}" unless source.respond_to?(:dig)
-
-        base = source.respond_to?(:with_indifferent_access) ? source.with_indifferent_access : source
-        base.dig(*attr.to_s.split("."))
-      end
-
-      def self.validate!(field:, validations:, source:, exception_klass:)
+      def self.validate!(field:, validations:, source:, exception_klass:, action: nil)
         validator = Class.new(self) do
-          def self.name = "Action::Validation::Subfields::OneOff"
+          def self.name = "Axn::Validation::Subfields::OneOff"
 
           validates field, **validations
         end.new(source)
 
+        # Set the action context for model field resolution
+        validator.instance_variable_set(:@action, action)
+        validator.instance_variable_set(:@validations, validations)
+
         return if validator.valid?
 
         raise exception_klass, validator.errors

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Axn
+  module Validators
+    class ModelValidator < ActiveModel::EachValidator
+      # Syntactic sugar: model: User -> model: { klass: User }
+      def self.apply_syntactic_sugar(value, fields)
+        (value.is_a?(Hash) ? value.dup : { klass: value }).tap do |options|
+          # Set default klass based on field name if not provided
+          options[:klass] = nil if options[:klass] == true
+          options[:klass] ||= fields.first.to_s.classify
+
+          # Constantize string klass names
+          options[:klass] = options[:klass].constantize if options[:klass].is_a?(String)
+
+          # Set default finder if not provided
+          options[:finder] ||= :find
+        end
+      end
+
+      def check_validity!
+        return unless options[:klass].nil?
+
+        raise ArgumentError, "must supply :klass"
+      end
+
+      def validate_each(record, attribute, value)
+        # The value is already resolved by the facade, just validate the type
+        type_validator = TypeValidator.new(attributes: [attribute], **options)
+        type_validator.validate_each(record, attribute, value)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Axn
+  module Validators
+    class TypeValidator < ActiveModel::EachValidator
+      def self.apply_syntactic_sugar(value, _fields)
+        return value if value.is_a?(Hash)
+
+        { klass: value }
+      end
+
+      def check_validity!
+        raise ArgumentError, "must supply :klass" if options[:klass].nil?
+      end
+
+      # NOTE: we override the default validate method to allow for custom allow_blank logic
+      # (e.g. type: Hash should fail if given false or "", but by default EachValidator would skip)
+      def validate(record)
+        attributes.each do |attribute|
+          value = record.read_attribute_for_validation(attribute)
+          validate_each(record, attribute, value)
+        end
+      end
+
+      def validate_each(record, attribute, value)
+        # Custom allow_blank logic: only skip validation for nil, not other blank values
+        return if value.nil? && (options[:allow_nil] || options[:allow_blank])
+
+        # Check if any of the types are valid
+        valid = types.any? do |type|
+          valid_type?(type:, value:, allow_blank: options[:allow_blank])
+        end
+
+        record.errors.add attribute, (options[:message] || msg) unless valid
+      end
+
+      private
+
+      def types = Array(options[:klass])
+      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)
+        return true if Axn.config.env.test? && value.class.name&.start_with?("RSpec::Mocks::")
+
+        case type
+        when :boolean
+          boolean_type?(value)
+        when :uuid
+          uuid_type?(value, allow_blank:)
+        when :params
+          params_type?(value)
+        else
+          class_type?(type, value)
+        end
+      end
+
+      def boolean_type?(value)
+        [true, false].include?(value)
+      end
+
+      def uuid_type?(value, allow_blank: false)
+        return false unless value.is_a?(String)
+        return true if value.blank? && allow_blank
+
+        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)
+      end
+
+      def params_type?(value)
+        value.is_a?(Hash) || (defined?(ActionController::Parameters) && value.is_a?(ActionController::Parameters))
+      end
+
+      def class_type?(type, value)
+        value.is_a?(type)
+      end
+    end
+  end
+end

data/lib/{action → axn}/core/validation/validators/validate_validator.rb

@@ -2,14 +2,24 @@
 
 require "active_model"
 
-module Action
+module Axn
   module Validators
     class ValidateValidator < ActiveModel::EachValidator
+      def self.apply_syntactic_sugar(value, _fields)
+        return value if value.is_a?(Hash)
+
+        { with: value }
+      end
+
+      def check_validity!
+        raise ArgumentError, "must supply :with" if options[:with].nil?
+      end
+
       def validate_each(record, attribute, value)
         msg = begin
           options[:with].call(value)
         rescue StandardError => e
-          Axn::Util.piping_error("applying custom validation on field '#{attribute}'", exception: e)
+          Axn::Internal::Logging.piping_error("applying custom validation on field '#{attribute}'", exception: e)
 
           "failed validation: #{e.message}"
         end

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

@@ -1,28 +1,52 @@
 # frozen_string_literal: true
 
-require "action/context"
-
-require "action/strategies"
-require "action/core/hooks"
-require "action/core/logging"
-require "action/core/flow"
-require "action/core/automatic_logging"
-require "action/core/use_strategy"
-require "action/core/timing"
-require "action/core/tracing"
-require "action/core/nesting_tracking"
+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"
+require "axn/core/automatic_logging"
+require "axn/core/use_strategy"
+require "axn/core/timing"
+require "axn/core/tracing"
+require "axn/core/nesting_tracking"
+require "axn/core/memoization"
 
 # CONSIDER: make class names match file paths?
-require "action/core/validation/validators/model_validator"
-require "action/core/validation/validators/type_validator"
-require "action/core/validation/validators/validate_validator"
+require "axn/core/validation/validators/model_validator"
+require "axn/core/validation/validators/type_validator"
+require "axn/core/validation/validators/validate_validator"
+
+require "axn/core/field_resolvers"
+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
 
-require "action/core/contract_validation"
-require "action/core/contract"
-require "action/core/contract_for_subfields"
+      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
 
-module Action
-  module Core
     def self.included(base)
       base.class_eval do
         extend ClassMethods
@@ -35,35 +59,17 @@ module Action
         include Core::Flow
 
         include Core::ContractValidation
+        include Core::ContractValidationForSubfields
         include Core::Contract
         include Core::ContractForSubfields
         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 Action::Failure.new(result.error, source: result.__action__), cause: result.exception if _nested_in_another_axn?
-
-        raise result.exception
-      end
-    end
-
-    def initialize(**)
-      @__context = Action::Context.new(**)
-    end
-
     # Main entry point for action execution
     def _run
       _tracking_nesting(self) do
@@ -81,28 +87,22 @@ module Action
           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
+    end
 
-    def fail!(message = nil)
-      raise Action::Failure, message
+    def done!(message = nil, **exposures)
+      expose(**exposures) if exposures.any?
+      raise Axn::Internal::EarlyCompletion, message
     end
 
     private
 
-    def _emit_metrics
-      return unless Action.config.emit_metrics
-
-      Action.config.emit_metrics.call(
-        self.class.name || "AnonymousClass",
-        result,
-      )
-    rescue StandardError => e
-      Axn::Util.piping_error("running metrics hook", action: self, exception: e)
+    def initialize(**)
+      @__context = Axn::Context.new(**)
     end
   end
 end

data/lib/{action → axn}/exceptions.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
-module Action
-  # Raised internally when fail! is called
+module Axn
+  module Internal
+    # Internal only -- rescued before Axn::Result is returned
+    class EarlyCompletion < StandardError; end
+  end
+
+  # Raised when fail! is called
   class Failure < StandardError
     DEFAULT_MESSAGE = "Execution was halted"
 
@@ -22,6 +27,10 @@ module Action
     def inspect = "#<#{self.class.name} '#{message}'>"
   end
 
+  module Mountable
+    class MountingError < ArgumentError; end
+  end
+
   class ContractViolation < StandardError
     class ReservedAttributeError < ContractViolation
       def initialize(name)
@@ -34,6 +43,7 @@ module Action
 
     class MethodNotAllowed < ContractViolation; end
     class PreprocessingError < ContractViolation; end
+    class DefaultAssignmentError < ContractViolation; end
 
     class UnknownExposure < ContractViolation
       def initialize(key)

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"