axn 0.1.0.pre.alpha.2.8 → 0.1.0.pre.alpha.3

data/lib/axn/async/adapters/sidekiq.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Axn
+  module Async
+    class Adapters
+      module Sidekiq
+        extend ActiveSupport::Concern
+
+        included do
+          raise LoadError, "Sidekiq is not available. Please add 'sidekiq' to your Gemfile." unless defined?(::Sidekiq)
+
+          # Use Sidekiq::Job if available (Sidekiq 7+), otherwise error
+          raise LoadError, "Sidekiq::Job is not available. Please check your Sidekiq version." unless defined?(::Sidekiq::Job)
+
+          include ::Sidekiq::Job
+
+          # Apply configuration block if present
+          class_eval(&_async_config_block) if _async_config_block
+
+          # Apply kwargs configuration if present
+          sidekiq_options(**_async_config) if _async_config&.any?
+        end
+
+        class_methods do
+          def call_async(**kwargs)
+            job_kwargs = _params_to_global_id(kwargs)
+
+            if kwargs[:_async].is_a?(Hash)
+              options = kwargs.delete(:_async)
+              if options[:wait_until]
+                return perform_at(options[:wait_until], job_kwargs)
+              elsif options[:wait]
+                return perform_in(options[:wait], job_kwargs)
+              end
+            end
+
+            perform_async(job_kwargs)
+          end
+
+          def _params_to_global_id(context = {})
+            return {} if context.nil?
+
+            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 _params_from_global_id(params)
+            return {} if params.nil?
+
+            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
+
+        def perform(*args)
+          context = self.class._params_from_global_id(args.first)
+
+          # Always use bang version so sidekiq can retry if we failed
+          self.class.call!(**context)
+        end
+      end
+    end
+  end
+end

data/lib/axn/async/adapters.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "axn/internal/registry"
+require "active_support/core_ext/string/inflections"
+
+module Axn
+  module Async
+    class AdapterNotFound < Axn::Internal::Registry::NotFound; end
+    class DuplicateAdapterError < Axn::Internal::Registry::DuplicateError; end
+
+    class Adapters < Axn::Internal::Registry
+      class << self
+        def registry_directory = __dir__
+
+        private
+
+        def item_type = "Adapter"
+        def not_found_error_class = AdapterNotFound
+        def duplicate_error_class = DuplicateAdapterError
+      end
+    end
+
+    # Trigger registry loading to ensure adapters are available
+    Adapters.all
+  end
+end

data/lib/axn/async.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "axn/async/adapters"
+
+module Axn
+  module Async
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_async_adapter, :_async_config, :_async_config_block, default: nil
+    end
+
+    class_methods do
+      def async(adapter = nil, **config, &block)
+        self._async_adapter = adapter
+        self._async_config = config
+        self._async_config_block = block
+
+        case adapter
+        when false
+          include Adapters.find(:disabled)
+        when nil
+          # Use default configuration
+          async Axn.config._default_async_adapter, **Axn.config._default_async_config, &Axn.config._default_async_config_block
+        else
+          # Look up adapter in registry
+          adapter_module = Adapters.find(adapter)
+          include adapter_module
+        end
+      end
+
+      def call_async(**)
+        # Set up default async configuration if none is set
+        if _async_adapter.nil?
+          async Axn.config._default_async_adapter, **Axn.config._default_async_config, &Axn.config._default_async_config_block
+          # Call ourselves again now that the adapter is included
+          return call_async(**)
+        end
+
+        # This will be overridden by the included adapter module
+        raise NotImplementedError, "No async adapter configured. Use e.g. `async :sidekiq` or `async :active_job` to enable background processing."
+      end
+
+      # Ensure default async is applied when the class is first instantiated
+      # This is important for Sidekiq workers which load the class in a separate process
+      def new(*args, **kwargs)
+        _ensure_default_async_configured
+        super
+      end
+
+      private
+
+      def _ensure_default_async_configured
+        return if _async_adapter.present?
+        return unless Axn.config._default_async_adapter.present?
+
+        async Axn.config._default_async_adapter, **Axn.config._default_async_config, &Axn.config._default_async_config_block
+      end
+    end
+  end
+end

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

@@ -1,17 +1,35 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
+  class RailsConfiguration
+    attr_accessor :app_actions_autoload_namespace
+  end
+
   class Configuration
     attr_accessor :wrap_with_trace, :emit_metrics
-    attr_writer :logger, :env, :on_exception, :additional_includes, :log_level
+    attr_writer :logger, :env, :on_exception, :additional_includes, :log_level, :rails
 
     def log_level = @log_level ||= :info
 
     def additional_includes = @additional_includes ||= []
 
+    def _default_async_adapter = @default_async_adapter ||= false
+    def _default_async_config = @default_async_config ||= {}
+    def _default_async_config_block = @default_async_config_block
+
+    def set_default_async(adapter = false, **config, &block) # rubocop:disable Style/OptionalBooleanParameter
+      raise ArgumentError, "Cannot set default async adapter to nil as it would cause infinite recursion" if adapter.nil?
+
+      @default_async_adapter = adapter unless adapter.nil?
+      @default_async_config = config.any? ? config : {}
+      @default_async_config_block = block_given? ? block : nil
+    end
+
+    def rails = @rails ||= RailsConfiguration.new
+
     def on_exception(e, action:, context: {})
       msg = "Handled exception (#{e.class.name}): #{e.message}"
-      msg = ("#" * 10) + " #{msg} " + ("#" * 10) unless Action.config.env.production?
+      msg = ("#" * 10) + " #{msg} " + ("#" * 10) unless Axn.config.env.production?
       action.log(msg)
 
       return unless @on_exception

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

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   class Context
-    attr_accessor :provided_data, :exposed_data
-
     def initialize(**provided_data)
       @provided_data = provided_data
       @exposed_data = {}
@@ -17,18 +15,37 @@ module Action
     # Framework state methods
     def ok? = !@failure
     def failed? = @failure || false
+    def finalized? = @finalized || false
 
     # Framework field accessors
-    attr_accessor :elapsed_time
+    attr_accessor :provided_data, :exposed_data, :elapsed_time
     attr_reader :exception
     private :elapsed_time=
 
+    #
+    # Here down intended for internal use only
+    #
+
     # INTERNAL: base for further filtering (for logging) or providing user with usage hints
     def __combined_data = @provided_data.merge(@exposed_data)
 
+    def __early_completion? = @early_completion || false
+
     def __record_exception(e)
       @exception = e
       @failure = true
+      @finalized = true
+    end
+
+    def __record_early_completion(message)
+      @early_completion_message = message unless message == Axn::Internal::EarlyCompletion.new.message
+      @early_completion = true
+    end
+
+    def __early_completion_message = @early_completion_message.presence
+
+    def __finalize!
+      @finalized = true
     end
   end
 end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   module Core
     module AutomaticLogging
       def self.included(base)
@@ -9,7 +9,7 @@ module Action
           include InstanceMethods
 
           # Single class_attribute - nil means disabled, any level means enabled
-          class_attribute :auto_log_level, default: Action.config.log_level
+          class_attribute :auto_log_level, default: Axn.config.log_level
         end
       end
 
@@ -39,10 +39,10 @@ module Action
               "About to execute",
               _log_context(:inbound),
             ].compact.join(" with: "),
-            before: Action.config.env.production? ? nil : "\n------\n",
+            before: Axn.config.env.production? ? nil : "\n------\n",
           )
         rescue StandardError => e
-          Axn::Util.piping_error("logging before hook", action: self, exception: e)
+          Axn::Internal::Logging.piping_error("logging before hook", action: self, exception: e)
         end
 
         def _log_after
@@ -55,10 +55,10 @@ module Action
               "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",
+            after: Axn.config.env.production? ? nil : "\n------\n",
           )
         rescue StandardError => e
-          Axn::Util.piping_error("logging after hook", action: self, exception: e)
+          Axn::Internal::Logging.piping_error("logging after hook", action: self, exception: e)
         end
 
         def _log_context(direction)

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_support/parameter_filter"
+
+module Axn
+  class ContextFacade
+    def initialize(action:, context:, declared_fields:, implicitly_allowed_fields: nil)
+      if self.class.name == "Axn::ContextFacade" # rubocop:disable Style/ClassEqualityComparison
+        raise "Axn::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|
+        if _model_fields.key?(field)
+          _define_model_field_method(field, _model_fields[field])
+        else
+          singleton_class.define_method(field) do
+            _context_data_source[field]
+          end
+        end
+      end
+    end
+
+    attr_reader :declared_fields
+
+    def inspect = ContextFacadeInspector.new(facade: self, action:, context:).call
+
+    def fail!(...)
+      raise Axn::ContractViolation::MethodNotAllowed, "Call fail! directly rather than on the context"
+    end
+
+    private
+
+    attr_reader :action, :context
+
+    def _model_fields
+      action.internal_field_configs.each_with_object({}) do |config, hash|
+        hash[config.field] = config.validations[:model] if config.validations.key?(:model)
+      end
+    end
+
+    def action_name = @action.class.name.presence || "The action"
+
+    def _define_model_field_method(field, options)
+      Axn::Util::Memoization.define_memoized_reader_method(singleton_class, field) do
+        Axn::Core::FieldResolvers.resolve(
+          type: :model,
+          field:,
+          options:,
+          provided_data: _context_data_source,
+        )
+      end
+    end
+
+    def _context_data_source = raise NotImplementedError
+
+    def _msg_resolver(event_type, exception:)
+      Axn::Core::Flow::Handlers::Resolvers::MessageResolver.new(
+        action._messages_registry,
+        event_type,
+        action:,
+        exception:,
+      )
+    end
+  end
+end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Action
+module Axn
   class ContextFacadeInspector
     def initialize(action:, facade:, context:)
       @action = action
@@ -19,12 +19,12 @@ module Action
     attr_reader :action, :facade, :context
 
     def status
-      return unless facade.is_a?(Action::Result)
+      return unless facade.is_a?(Axn::Result)
 
       return "[OK]" if context.ok?
 
-      if context.exception.is_a?(Action::Failure)
-        return context.exception.message.present? ? "[failed with '#{context.exception.message}']" : "[failed]"
+      if facade.outcome.failure?
+        return context.exception.default_message? ? "[failed]" : "[failed with '#{context.exception.message}']"
       end
 
       %([failed with #{context.exception.class.name}: '#{context.exception.message}'])
@@ -56,9 +56,36 @@ module Action
                           value.inspect
                         end
 
+      # Handle subfield filtering for hash values
+      if value.is_a?(Hash) && sensitive_subfields?(field)
+        filtered_value = filter_subfields(field, value)
+        return filtered_value.inspect
+      end
+
       inspection_filter.filter_param(field, inspected_value)
     end
 
     def inspection_filter = action.send(:inspection_filter)
+
+    def sensitive_subfields?(field)
+      action.subfield_configs.any? { |config| config.on == field && config.sensitive }
+    end
+
+    def filter_subfields(field, value)
+      # Build a nested structure with subfield paths for filtering
+      nested_data = { field => value }
+
+      # Create a filter with the subfield paths
+      sensitive_subfield_paths = action.subfield_configs
+                                       .select { |config| config.on == field && config.sensitive }
+                                       .map { |config| "#{field}.#{config.field}" }
+
+      return value if sensitive_subfield_paths.empty?
+
+      subfield_filter = ActiveSupport::ParameterFilter.new(sensitive_subfield_paths)
+      filtered_data = subfield_filter.filter(nested_data)
+
+      filtered_data[field]
+    end
   end
 end

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

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "action/core/context/facade"
+require "axn/core/context/facade"
 
-module Action
+module Axn
   # Inbound / Internal ContextFacade
   class InternalContext < ContextFacade
-    def default_error = _msg_resolver(:error, exception: Action::Failure.new).resolve_default_message
+    def default_error = _msg_resolver(:error, exception: Axn::Failure.new).resolve_default_message
     def default_success = _msg_resolver(:success, exception: nil).resolve_default_message
 
     private
@@ -15,13 +15,13 @@ module Action
     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!
+          Method ##{method_name} is not available on Axn::InternalContext!
 
           #{action_name} may be missing a line like:
             expects :#{method_name}
         MSG
 
-        raise Action::ContractViolation::MethodNotAllowed, msg
+        raise Axn::ContractViolation::MethodNotAllowed, msg
       end
 
       super

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

@@ -3,11 +3,11 @@
 require "active_support/core_ext/enumerable"
 require "active_support/core_ext/module/delegation"
 
-require "action/core/validation/fields"
-require "action/result"
-require "action/core/context/internal"
+require "axn/core/validation/fields"
+require "axn/result"
+require "axn/core/context/internal"
 
-module Action
+module Axn
   module Core
     module Contract
       def self.included(base)
@@ -27,20 +27,21 @@ module Action
           on: nil,
           allow_blank: false,
           allow_nil: false,
+          optional: false,
           default: nil,
           preprocess: nil,
           sensitive: false,
           **validations
         )
-          return _expects_subfields(*fields, on:, allow_blank:, allow_nil:, default:, preprocess:, sensitive:, **validations) if on.present?
-
           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|
+          return _expects_subfields(*fields, on:, allow_blank:, allow_nil:, optional:, default:, preprocess:, sensitive:, **validations) if on.present?
+
+          _parse_field_configs(*fields, allow_blank:, allow_nil:, optional:, 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?
+            raise Axn::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
 
             # NOTE: avoid <<, which would update value for parents and children
             self.internal_field_configs += configs
@@ -51,6 +52,7 @@ module Action
           *fields,
           allow_blank: false,
           allow_nil: false,
+          optional: false,
           default: nil,
           sensitive: false,
           **validations
@@ -59,9 +61,9 @@ module Action
             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|
+          _parse_field_configs(*fields, allow_blank:, allow_nil:, optional:, 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?
+            raise Axn::DuplicateFieldError, "Duplicate field(s) declared: #{duplicated.join(", ")}" if duplicated.any?
 
             # NOTE: avoid <<, which would update value for parents and children
             self.external_field_configs += configs
@@ -74,77 +76,69 @@ module Action
           fail! ok?
           inspect default_error
           each_pair
+          default_success
+          action_name
         ].freeze
 
         RESERVED_FIELD_NAMES_FOR_EXPOSURES = %w[
           fail! ok?
           inspect each_pair default_error
           ok error success message
+          result
+          outcome
+          exception
+          elapsed_time
+          finalized?
+          __action__
         ].freeze
 
         def _parse_field_configs(
           *fields,
           allow_blank: false,
           allow_nil: false,
+          optional: false,
           default: nil,
           preprocess: nil,
           sensitive: false,
           **validations
         )
+          # Handle optional: true by setting allow_blank: true
+          allow_blank ||= optional
+
           _parse_field_validations(*fields, allow_nil:, allow_blank:, **validations).map do |field, parsed_validations|
             _define_field_reader(field)
-            _define_model_reader(field, parsed_validations[:model]) if parsed_validations.key?(:model)
             FieldConfig.new(field:, validations: parsed_validations, default:, preprocess:, sensitive:)
           end
         end
 
-        def define_memoized_reader_method(field, &block)
-          define_method(field) do
-            ivar = :"@_memoized_reader_#{field}"
-            cached_val = instance_variable_get(ivar)
-            return cached_val if cached_val.present?
-
-            value = instance_exec(&block)
-            instance_variable_set(ivar, value)
-          end
-        end
-
         def _define_field_reader(field)
           # 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)
           define_method(field) { internal_context.public_send(field) }
         end
 
-        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: instance_exec(&id_extractor))
-          end
-        end
-
+        # This method applies any top-level options to each of the individual validations given.
+        # It also allows our custom validators to accept a direct value rather than a hash of options.
         def _parse_field_validations(
           *fields,
           allow_nil: false,
           allow_blank: false,
           **validations
         )
-          if allow_blank
-            validations.transform_values! do |v|
-              v = { value: v } unless v.is_a?(Hash)
-              { allow_blank: true }.merge(v)
-            end
-          elsif allow_nil
+          # Apply syntactic sugar for our custom validators (convert shorthand to full hash of options)
+          validations[:type] = Axn::Validators::TypeValidator.apply_syntactic_sugar(validations[:type], fields) if validations.key?(:type)
+          validations[:model] = Axn::Validators::ModelValidator.apply_syntactic_sugar(validations[:model], fields) if validations.key?(:model)
+          validations[:validate] = Axn::Validators::ValidateValidator.apply_syntactic_sugar(validations[:validate], fields) if validations.key?(:validate)
+
+          # Push allow_blank and allow_nil to the individual validations
+          if allow_blank || allow_nil
             validations.transform_values! do |v|
-              v = { value: v } unless v.is_a?(Hash)
-              { allow_nil: true }.merge(v)
+              { allow_blank:, allow_nil: }.merge(v)
             end
           else
-            validations[:presence] = true unless validations.key?(:presence) || Array(validations[:type]).include?(:boolean)
+            # Apply default presence validation (unless the type is boolean or params)
+            type_values = Array(validations.dig(:type, :klass))
+            validations[:presence] = true unless validations.key?(:presence) || type_values.include?(:boolean) || type_values.include?(:params)
           end
 
           fields.map { |field| [field, validations] }
@@ -155,6 +149,8 @@ module Action
         def internal_context = @internal_context ||= _build_context_facade(:inbound)
         def result = @result ||= _build_context_facade(:outbound)
 
+        delegate :default_error, :default_success, to: :internal_context
+
         # Accepts either two positional arguments (key, value) or a hash of key/value pairs
         def expose(*args, **kwargs)
           if args.any?
@@ -167,7 +163,7 @@ module Action
           end
 
           kwargs.each do |key, value|
-            raise Action::ContractViolation::UnknownExposure, key unless result.respond_to?(key)
+            raise Axn::ContractViolation::UnknownExposure, key unless result.respond_to?(key)
 
             @__context.exposed_data[key] = value
           end
@@ -190,13 +186,14 @@ module Action
           _validate_contract!(:outbound)
 
           # TODO: improve location of this triggering
+          @__context.__finalize! # Mark result as finalized
           _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
+          klass = direction == :inbound ? Axn::InternalContext : Axn::Result
           implicitly_allowed_fields = direction == :inbound ? _declared_fields(:outbound) : []
 
           klass.new(action: self, context: @__context, declared_fields: _declared_fields(direction), implicitly_allowed_fields:)
@@ -207,7 +204,7 @@ module Action
         end
 
         def sensitive_fields
-          (internal_field_configs + external_field_configs).select(&:sensitive).map(&:field)
+          (internal_field_configs + external_field_configs + subfield_configs).select(&:sensitive).map(&:field)
         end
 
         def _declared_fields(direction)