axn 0.1.0.pre.alpha.2.4.1 → 0.1.0.pre.alpha.2.5.1

data/lib/action/core/exceptions.rb

@@ -3,15 +3,16 @@
 module Action
   # Raised internally when fail! is called -- triggers failure + rollback handling
   class Failure < StandardError
-    attr_reader :context
+    DEFAULT_MESSAGE = "Execution was halted"
 
-    def initialize(context = nil, message: nil)
-      super()
-      @message = message if message.present?
-      @context = context
+    def initialize(message = nil, **)
+      @message = message
+      super(**)
     end
 
-    def message = @message.presence || @context.error_from_user.presence || "Execution was halted"
+    def message
+      @message.presence || DEFAULT_MESSAGE
+    end
 
     def inspect = "#<#{self.class.name} '#{message}'>"
   end

data/lib/action/core/hoist_errors.rb

@@ -29,8 +29,10 @@ module Action
           MinimalFailedResult.new(error: nil, exception: e)
         end
 
-        # This ensures the last line of hoist_errors was an Action call (CAUTION: if there are multiple
-        # calls per block, only the last one will be checked!)
+        # This ensures the last line of hoist_errors was an Action call
+        #
+        # CAUTION: if there are multiple calls per block, only the last one will be checked!
+        #
         unless result.respond_to?(:ok?)
           raise ArgumentError,
                 "#hoist_errors is expected to wrap an Action call, but it returned a #{result.class.name} instead"

data/lib/action/core/logging.rb

@@ -14,8 +14,9 @@ module Action
     end
 
     module ClassMethods
-      def log(message, level: :info)
-        level = :info if level == :debug && _targeted_for_debug_logging?
+      def default_log_level = Action.config.default_log_level
+
+      def log(message, level: default_log_level)
         msg = [_log_prefix, message].compact_blank.join(" ")
 
         Action.config.logger.send(level, msg)
@@ -29,13 +30,6 @@ module Action
 
       # TODO: this is ugly, we should be able to override in the config class...
       def _log_prefix = name == "Action::Configuration" ? nil : "[#{name || "Anonymous Class"}]"
-
-      def _targeted_for_debug_logging?
-        return true if Action.config.global_debug_logging?
-
-        target_class_names = (ENV["SA_DEBUG_TARGETS"] || "").split(",").map(&:strip)
-        target_class_names.include?(name)
-      end
     end
   end
 end

data/lib/action/core/swallow_exceptions.rb

@@ -15,8 +15,8 @@ module Action
         include InstanceMethods
         extend ClassMethods
 
-        def run_with_exception_swallowing!
-          original_run!
+        def run
+          run!
         rescue StandardError => e
           # on_error handlers run for both unhandled exceptions and fail!
           self.class._error_handlers.each do |handler|
@@ -25,31 +25,19 @@ module Action
 
           # on_failure handlers run ONLY for fail!
           if e.is_a?(Action::Failure)
+            @context.instance_variable_set("@error_from_user", e.message) if e.message.present?
+
             self.class._failure_handlers.each do |handler|
               handler.execute_if_matches(exception: e, action: self)
             end
+          else
+            # on_exception handlers run for ONLY for unhandled exceptions. AND NOTE: may be skipped if the exception is rescued via `rescues`.
+            trigger_on_exception(e)
 
-            # TODO: avoid raising if this was passed along from a child action (esp. if wrapped in hoist_errors)
-            raise e
+            @context.exception = e
           end
 
-          # on_exception handlers run for ONLY for unhandled exceptions. AND NOTE: may be skipped if the exception is rescued via `rescues`.
-          trigger_on_exception(e)
-
-          @context.exception = e
-
-          fail!
-        end
-
-        alias_method :original_run!, :run!
-        alias_method :run!, :run_with_exception_swallowing!
-
-        # Tweaked to check @context.object_id rather than context (since forwarding object_id causes Ruby to complain)
-        # TODO: do we actually need the object_id check? Do we need this override at all?
-        def run
-          run!
-        rescue Action::Failure => e
-          raise if @context.object_id != e.context.object_id
+          @context.instance_variable_set("@failure", true)
         end
 
         def trigger_on_exception(exception)
@@ -72,17 +60,12 @@ module Action
         end
 
         class << base
-          def call_bang_with_unswallowed_exceptions(context = {})
+          def call!(context = {})
             result = call(context)
             return result if result.ok?
 
-            raise result.exception if result.exception
-
-            raise Action::Failure.new(result.instance_variable_get("@context"), message: result.error)
+            raise result.exception || Action::Failure.new(result.error)
           end
-
-          alias_method :original_call!, :call!
-          alias_method :call!, :call_bang_with_unswallowed_exceptions
         end
       end
     end
@@ -162,8 +145,7 @@ module Action
         @context.instance_variable_set("@failure", true)
         @context.error_from_user = message if message.present?
 
-        # TODO: should we use context_for_logging here? But doublecheck the one place where we're checking object_id on it...
-        raise Action::Failure.new(@context, message:)
+        raise Action::Failure, message
       end
 
       def try

data/lib/action/core/top_level_around_hook.rb

@@ -6,46 +6,39 @@ module Action
       base.class_eval do
         around :__top_level_around_hook
 
+        extend AutologgingClassMethods
+        include AutologgingInstanceMethods
         include InstanceMethods
       end
     end
 
-    module InstanceMethods
-      def __top_level_around_hook(hooked)
-        timing_start = Time.now
-        _log_before
-
-        _configurable_around_wrapper do
-          (@outcome, @exception) = _call_and_return_outcome(hooked)
-        end
-
-        _log_after(timing_start:, outcome: @outcome)
-
-        raise @exception if @exception
-      end
+    module AutologgingClassMethods
+      def default_autolog_level = Action.config.default_autolog_level
+    end
 
+    module AutologgingInstanceMethods
       private
 
-      def _configurable_around_wrapper(&)
-        return yield unless Action.config.top_level_around_hook
-
-        Action.config.top_level_around_hook.call(self.class.name || "AnonymousClass", &)
-      end
-
       def _log_before
-        debug [
-          "About to execute",
-          context_for_logging(:inbound).presence&.inspect,
-        ].compact.join(" with: ")
+        public_send(
+          self.class.default_autolog_level,
+          [
+            "About to execute",
+            context_for_logging(:inbound).presence&.inspect,
+          ].compact.join(" with: "),
+        )
       end
 
       def _log_after(outcome:, timing_start:)
         elapsed_mils = ((Time.now - timing_start) * 1000).round(3)
 
-        debug [
-          "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
-          _log_after_data_peak,
-        ].compact.join(". Set: ")
+        public_send(
+          self.class.default_autolog_level,
+          [
+            "Execution completed (with outcome: #{outcome}) in #{elapsed_mils} milliseconds",
+            _log_after_data_peak,
+          ].compact.join(". Set: "),
+        )
       end
 
       def _log_after_data_peak
@@ -58,6 +51,29 @@ module Action
           return str[0, max_length - suffix.length] + suffix if str.length > max_length
         end
       end
+    end
+
+    module InstanceMethods
+      def __top_level_around_hook(hooked)
+        timing_start = Time.now
+        _log_before
+
+        _configurable_around_wrapper do
+          (@outcome, @exception) = _call_and_return_outcome(hooked)
+        end
+
+        _log_after(timing_start:, outcome: @outcome)
+
+        raise @exception if @exception
+      end
+
+      private
+
+      def _configurable_around_wrapper(&)
+        return yield unless Action.config.top_level_around_hook
+
+        Action.config.top_level_around_hook.call(self.class.name || "AnonymousClass", &)
+      end
 
       def _call_and_return_outcome(hooked)
         hooked.call

data/lib/action/core/validation/fields.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Action
+  module Validation
+    class Fields
+      include ActiveModel::Validations
+
+      # NOTE: defining classes where needed b/c we explicitly register it'll affect ALL the consuming apps' validators as well
+      ModelValidator = Validators::ModelValidator
+      TypeValidator = Validators::TypeValidator
+      ValidateValidator = Validators::ValidateValidator
+
+      def initialize(context)
+        @context = context
+      end
+
+      def read_attribute_for_validation(attr)
+        @context.public_send(attr)
+      end
+
+      def self.validate!(validations:, context:, exception_klass:)
+        validator = Class.new(self) do
+          def self.name = "Action::Validation::Fields::OneOff"
+
+          validations.each do |field, field_validations|
+            field_validations.each do |key, value|
+              validates field, key => value
+            end
+          end
+        end.new(context)
+
+        return if validator.valid?
+
+        raise exception_klass, validator.errors
+      end
+    end
+  end
+end

data/lib/action/core/validation/subfields.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/indifferent_access"
+
+module Action
+  module Validation
+    class Subfields
+      include ActiveModel::Validations
+
+      # NOTE: defining classes where needed b/c we explicitly register it'll affect ALL the consuming apps' validators as well
+      ModelValidator = Validators::ModelValidator
+      TypeValidator = Validators::TypeValidator
+      ValidateValidator = Validators::ValidateValidator
+
+      def initialize(source)
+        @source = source
+      end
+
+      def read_attribute_for_validation(attr)
+        self.class.extract(attr, @source)
+      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:)
+        validator = Class.new(self) do
+          def self.name = "Action::Validation::Subfields::OneOff"
+
+          validates field, **validations
+        end.new(source)
+
+        return if validator.valid?
+
+        raise exception_klass, validator.errors
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Action
+  module Validators
+    class ModelValidator < ActiveModel::EachValidator
+      def self.model_for(field:, klass: nil)
+        return klass if defined?(ActiveRecord::Base) && klass.is_a?(ActiveRecord::Base)
+
+        field.to_s.delete_suffix("_id").classify.constantize
+      end
+
+      def self.instance_for(field:, klass:, id:)
+        klass = model_for(field:, klass:)
+        return unless klass.respond_to?(:find_by)
+
+        klass.find_by(id:)
+      end
+
+      def validate_each(record, attribute, id)
+        klass = self.class.model_for(field: attribute, klass: options[:with])
+        instance = self.class.instance_for(field: attribute, klass:, id:)
+        return if instance.present?
+
+        msg = id.blank? ? "not found (given a blank ID)" : "not found for class #{klass.name} and ID #{id}"
+        record.errors.add(attribute, msg)
+      rescue StandardError => e
+        warn("Model validation on field '#{attribute}' raised #{e.class.name}: #{e.message}")
+
+        record.errors.add(attribute, "error raised while trying to find a valid #{klass.name}")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Action
+  module Validators
+    class TypeValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value)
+        # NOTE: the last one (:value) might be my fault from the make-it-a-hash fallback in #parse_field_configs
+        types = options[:in].presence || Array(options[:with]).presence || Array(options[:value]).presence
+
+        return if value.blank? && !types.include?(:boolean) # Handled with a separate default presence validator
+
+        msg = types.size == 1 ? "is not a #{types.first}" : "is not one of #{types.join(", ")}"
+        record.errors.add attribute, (options[:message] || msg) unless types.any? do |type|
+          if type == :boolean
+            [true, false].include?(value)
+          elsif type == :uuid
+            value.is_a?(String) && 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)
+          else
+            # NOTE: allow mocks to pass type validation by default (much easier testing ergonomics)
+            next true if Action.config.env.test? && value.class.name.start_with?("RSpec::Mocks::")
+
+            value.is_a?(type)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action/core/validation/validators/validate_validator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Action
+  module Validators
+    class ValidateValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value)
+        msg = begin
+          options[:with].call(value)
+        rescue StandardError => e
+          Action.config.logger.warn("Custom validation on field '#{attribute}' raised #{e.class.name}: #{e.message}")
+
+          "failed validation: #{e.message}"
+        end
+
+        record.errors.add(attribute, msg) if msg.present?
+      end
+    end
+  end
+end

data/lib/action/enqueueable/enqueue_all_in_background.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Action
+  module Enqueueable
+    module EnqueueAllInBackground
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def enqueue_all_in_background
+          raise NotImplementedError, "#{name} must implement a .enqueue_all method in order to use .enqueue_all_in_background" unless respond_to?(:enqueue_all)
+
+          ::Action::Enqueueable::EnqueueAllWorker.enqueue(klass_name: name)
+        end
+      end
+    end
+  end
+end

data/lib/action/enqueueable/enqueue_all_worker.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# NOTE: this is a standalone worker for enqueueing all instances of a class.
+# Unlike the other files in the folder, it is NOT included in the Action stack.
+
+# Note it uses Axn-native enqueueing, so will automatically support additional
+# backends as they are added (initially, just Sidekiq)
+
+module Action
+  module Enqueueable
+    class EnqueueAllWorker
+      include Action
+
+      expects :klass_name, type: String
+
+      def call
+        klass_name.constantize.enqueue_all
+      end
+    end
+  end
+end

data/lib/action/enqueueable/via_sidekiq.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Action
+  module Enqueueable
+    module ViaSidekiq
+      def self.included(base)
+        base.class_eval do
+          begin
+            require "sidekiq"
+            include Sidekiq::Job
+          rescue LoadError
+            puts "Sidekiq not available -- skipping Enqueueable"
+            return
+          end
+
+          define_method(:perform) do |*args|
+            context = self.class._params_from_global_id(args.first)
+            bang = args.size > 1 ? args.last : false
+
+            if bang
+              self.class.call!(context)
+            else
+              self.class.call(context)
+            end
+          end
+
+          def self.enqueue(context = {})
+            perform_async(_process_context_to_sidekiq_args(context))
+          end
+
+          def self.enqueue!(context = {})
+            perform_async(_process_context_to_sidekiq_args(context), true)
+          end
+
+          def self.queue_options(opts)
+            opts = opts.transform_keys(&:to_s)
+            self.sidekiq_options_hash = get_sidekiq_options.merge(opts)
+          end
+
+          private
+
+          def self._process_context_to_sidekiq_args(context)
+            client = Sidekiq::Client.new
+
+            _params_to_global_id(context).tap do |args|
+              if client.send(:json_unsafe?, args).present?
+                raise ArgumentError,
+                      "Cannot pass non-JSON-serializable objects to Sidekiq. Make sure all expected arguments are serializable (or respond to to_global_id)."
+              end
+            end
+          end
+
+          def self._params_to_global_id(context)
+            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 self._params_from_global_id(params)
+            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
+      end
+    end
+  end
+end

data/lib/action/enqueueable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "enqueueable/via_sidekiq"
+require_relative "enqueueable/enqueue_all_in_background"
+
+module Action
+  module Enqueueable
+    extend ActiveSupport::Concern
+
+    included do
+      include ViaSidekiq
+      include EnqueueAllInBackground
+    end
+  end
+end

data/lib/axn/factory.rb

@@ -34,7 +34,6 @@ module Axn
         end
         raise ArgumentError, "[Axn::Factory] Cannot convert block to action: block expects a splat of keyword arguments" if args[:keyrest].present?
 
-        # TODO: is there any way to support default arguments? (if so, set allow_blank: true for those)
         if args[:key].present?
           raise ArgumentError,
                 "[Axn::Factory] Cannot convert block to action: block expects keyword arguments with defaults (ruby does not allow introspecting)"
@@ -66,7 +65,7 @@ module Axn
             retval = instance_exec(**unwrapped_kwargs, &block)
             expose(expose_return_as => retval) if expose_return_as.present?
           end
-        end.tap do |axn| # rubocop: disable Style/MultilineBlockChain
+        end.tap do |axn|
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.2.4.1"
+  VERSION = "0.1.0-alpha.2.5.1"
 end

data/lib/axn.rb

@@ -6,18 +6,23 @@ require_relative "axn/version"
 require "interactor"
 require "active_support"
 
+require_relative "action/core/validation/validators/model_validator"
+require_relative "action/core/validation/validators/type_validator"
+require_relative "action/core/validation/validators/validate_validator"
+
 require_relative "action/core/exceptions"
 require_relative "action/core/logging"
 require_relative "action/core/configuration"
 require_relative "action/core/top_level_around_hook"
 require_relative "action/core/contract"
+require_relative "action/core/contract_for_subfields"
 require_relative "action/core/swallow_exceptions"
 require_relative "action/core/hoist_errors"
-require_relative "action/core/enqueueable"
 
 require_relative "axn/factory"
 
 require_relative "action/attachable"
+require_relative "action/enqueueable"
 
 def Axn(callable, **) # rubocop:disable Naming/MethodName
   return callable if callable.is_a?(Class) && callable < Action
@@ -37,15 +42,15 @@ module Action
       # can include those hook executions in any traces set from this hook.
       include TopLevelAroundHook
 
-      include Contract
       include SwallowExceptions
+      include Contract
+      include ContractForSubfields
 
       include HoistErrors
 
-      include Enqueueable
-
       # --- Extensions ---
       include Attachable
+      include Enqueueable
 
       # Allow additional automatic includes to be configured
       Array(Action.config.additional_includes).each { |mod| include mod }
@@ -62,3 +67,5 @@ module Action
     end
   end
 end
+
+require "action/enqueueable/enqueue_all_worker"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.4.1
+  version: 0.1.0.pre.alpha.2.5.1
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-04 00:00:00.000000000 Z
+date: 2025-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -91,14 +91,22 @@ files:
 - lib/action/core/configuration.rb
 - lib/action/core/context_facade.rb
 - lib/action/core/contract.rb
-- lib/action/core/contract_validator.rb
-- lib/action/core/enqueueable.rb
+- lib/action/core/contract_for_subfields.rb
 - lib/action/core/event_handlers.rb
 - lib/action/core/exceptions.rb
 - lib/action/core/hoist_errors.rb
 - lib/action/core/logging.rb
 - lib/action/core/swallow_exceptions.rb
 - lib/action/core/top_level_around_hook.rb
+- lib/action/core/validation/fields.rb
+- lib/action/core/validation/subfields.rb
+- lib/action/core/validation/validators/model_validator.rb
+- lib/action/core/validation/validators/type_validator.rb
+- lib/action/core/validation/validators/validate_validator.rb
+- lib/action/enqueueable.rb
+- lib/action/enqueueable/enqueue_all_in_background.rb
+- lib/action/enqueueable/enqueue_all_worker.rb
+- lib/action/enqueueable/via_sidekiq.rb
 - lib/axn.rb
 - lib/axn/factory.rb
 - lib/axn/version.rb