axn 0.1.0.pre.alpha.1

data/lib/action/contract.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/module/delegation"
+
+require "action/contract_validator"
+require "action/context_facade"
+
+module Action
+  module Contract
+    def self.included(base)
+      base.class_eval do
+        class_attribute :internal_field_configs, :external_field_configs, default: []
+
+        extend ClassMethods
+        include InstanceMethods
+        include ValidationInstanceMethods
+
+        # Remove public context accessor
+        remove_method :context
+
+        around do |hooked|
+          _apply_inbound_preprocessing!
+          _apply_defaults!(:inbound)
+          _validate_contract!(:inbound)
+          hooked.call
+          _apply_defaults!(:outbound)
+          _validate_contract!(:outbound)
+        end
+      end
+    end
+
+    FieldConfig = Data.define(:field, :validations, :default, :preprocess, :sensitive)
+
+    module ClassMethods
+      def gets(*fields, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
+               **validations)
+        _parse_field_configs(*fields, allow_blank:, 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?
+
+          # NOTE: avoid <<, which would update value for parents and children
+          self.internal_field_configs += configs
+        end
+      end
+
+      def sets(*fields, allow_blank: false, default: nil, sensitive: false, **validations)
+        _parse_field_configs(*fields, allow_blank:, 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?
+
+          # NOTE: avoid <<, which would update value for parents and children
+          self.external_field_configs += configs
+        end
+      end
+
+      private
+
+      def _parse_field_configs(*fields, allow_blank: false, default: nil, preprocess: nil, sensitive: false,
+                               **validations)
+        # 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)
+        fields.each do |field|
+          define_method(field) { internal_context.public_send(field) }
+        end
+
+        if allow_blank
+          validations.transform_values! do |v|
+            v = { value: v } unless v.is_a?(Hash)
+            { allow_blank: true }.merge(v)
+          end
+        elsif validations.key?(:boolean)
+          validations[:presence] = false
+        else
+          validations[:presence] = true unless validations.key?(:presence)
+        end
+
+        fields.map { |field| FieldConfig.new(field:, validations:, default:, preprocess:, sensitive:) }
+      end
+    end
+
+    module InstanceMethods
+      def internal_context = @internal_context ||= _build_context_facade(:inbound)
+      def external_context = @external_context ||= _build_context_facade(:outbound)
+
+      # NOTE: ideally no direct access from client code, but we need to set this for internal Interactor methods
+      # (and passing through control methods to underlying context) in order to avoid rewriting internal methods.
+      def context = external_context
+
+      # Accepts either two positional arguments (key, value) or a hash of key/value pairs
+      def set(*args, **kwargs)
+        if args.any?
+          if args.size != 2
+            raise ArgumentError,
+                  "set must be called with exactly two positional arguments (or a hash of key/value pairs)"
+          end
+
+          kwargs.merge!(args.first => args.last)
+        end
+
+        kwargs.each do |key, value|
+          raise Action::ContractViolation::UnknownExposure, key unless external_context.respond_to?(key)
+
+          @context.public_send("#{key}=", value)
+        end
+      end
+
+      private
+
+      def _build_context_facade(direction)
+        raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
+
+        klass = direction == :inbound ? Action::InternalContext : Action::Result
+        implicitly_allowed_fields = direction == :inbound ? declared_fields(:outbound) : []
+
+        klass.new(action: self, context: @context, declared_fields: declared_fields(direction), implicitly_allowed_fields:)
+      end
+    end
+
+    module ValidationInstanceMethods
+      def _apply_inbound_preprocessing!
+        internal_field_configs.each do |config|
+          next unless config.preprocess
+
+          initial_value = @context.public_send(config.field)
+          new_value = config.preprocess.call(initial_value)
+          @context.public_send("#{config.field}=", new_value)
+        rescue StandardError => e
+          raise Action::ContractViolation::PreprocessingError, "Error preprocessing field '#{config.field}': #{e.message}"
+        end
+      end
+
+      def _validate_contract!(direction)
+        raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
+
+        configs = direction == :inbound ? internal_field_configs : external_field_configs
+        validations = configs.each_with_object({}) do |config, hash|
+          hash[config.field] = config.validations
+        end
+        context = direction == :inbound ? internal_context : external_context
+        exception_klass = direction == :inbound ? Action::InboundValidationError : Action::OutboundValidationError
+
+        ContractValidator.validate!(validations:, context:, exception_klass:)
+      end
+
+      def _apply_defaults!(direction)
+        raise ArgumentError, "Invalid direction: #{direction}" unless %i[inbound outbound].include?(direction)
+
+        configs = direction == :inbound ? internal_field_configs : external_field_configs
+        defaults_mapping = configs.each_with_object({}) do |config, hash|
+          hash[config.field] = config.default
+        end.compact
+
+        defaults_mapping.each do |field, default_value|
+          unless @context.public_send(field)
+            @context.public_send("#{field}=",
+                                 default_value.respond_to?(:call) ? default_value.call : default_value)
+          end
+        end
+      end
+
+      def context_for_logging(direction = nil)
+        inspection_filter.filter(@context.to_h.slice(*declared_fields(direction)))
+      end
+
+      protected
+
+      def inspection_filter
+        @inspection_filter ||= ActiveSupport::ParameterFilter.new(sensitive_fields)
+      end
+
+      def sensitive_fields
+        (internal_field_configs + external_field_configs).select(&:sensitive).map(&:field)
+      end
+
+      def declared_fields(direction)
+        raise ArgumentError, "Invalid direction: #{direction}" unless direction.nil? || %i[inbound outbound].include?(direction)
+
+        configs = case direction
+                  when :inbound then internal_field_configs
+                  when :outbound then external_field_configs
+                  else (internal_field_configs + external_field_configs)
+                  end
+
+        configs.map(&:field)
+      end
+    end
+  end
+end

data/lib/action/contract_validator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Action
+  class ContractValidator
+    include ActiveModel::Validations
+
+    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::ContractValidator::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
+
+    # Allow for custom validators to be defined in the context of the action
+    class ValidateValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value)
+        msg = begin
+          options[:with].call(value)
+        rescue StandardError => e
+          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
+
+    class BooleanValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value)
+        return if [true, false].include?(value)
+
+        record.errors.add(attribute, "must be true or false")
+      end
+    end
+
+    class TypeValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value)
+        return if value.blank? # Handled with a separate default presence validator
+
+        # TODO: 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
+
+        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? { |type| value.is_a?(type) }
+      end
+    end
+  end
+end

data/lib/action/enqueueable.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Action
+  module Enqueueable
+    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 objects in the context 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

data/lib/action/exceptions.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Action
+  # Raised internally when fail! is called -- triggers failure + rollback handling
+  class Failure < StandardError
+    attr_reader :context
+
+    def initialize(context = nil, message: nil)
+      super()
+      @message = message if message.present?
+      @context = context
+    end
+
+    def message = @message.presence || "Execution was halted"
+  end
+
+  class StepsRequiredForInheritanceSupportError < StandardError
+    def message
+      <<~MSG
+        ** Inheritance support requires the following steps: **
+
+        Add this to your Gemfile:
+          gem "interactor", github: "kaspermeyer/interactor", branch: "fix-hook-inheritance"
+
+        Explanation:
+          Unfortunately the upstream interactor gem does not support inheritance of hooks, which is required for this feature.
+          This branch is a temporary fork that adds support for inheritance of hooks, but published gems cannot specify a branch dependency.
+          In the future we may inline the upstream Interactor gem entirely and remove this necessity, but while we're in alpha we're continuing
+          to use the upstream gem for stability (and there has been recent activity on the project, so they *may* be adding additional functionality
+          soon).
+      MSG
+    end
+  end
+
+  class ContractViolation < StandardError
+    class MethodNotAllowed < ContractViolation; end
+    class PreprocessingError < ContractViolation; end
+
+    class UnknownExposure < ContractViolation
+      def initialize(key)
+        @key = key
+        super()
+      end
+
+      def message = "Attempted to set unknown key '#{@key}': be sure to declare it with `sets :#{@key}`"
+    end
+  end
+
+  class DuplicateFieldError < ContractViolation; end
+
+  class ValidationError < ContractViolation
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super
+    end
+
+    def message = errors.full_messages.to_sentence
+    def to_s = message
+  end
+
+  class InboundValidationError < ValidationError; end
+  class OutboundValidationError < ValidationError; end
+end

data/lib/action/hoist_errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Action
+  module HoistErrors
+    def self.included(base)
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      MinimalFailedResult = Data.define(:error, :exception) do
+        def ok? = false
+      end
+
+      # This method is used to ensure that the result of a block is successful before proceeding.
+      #
+      # Assumes success unless the block raises an exception or returns a failed result.
+      # (i.e. if you wrap logic that is NOT an action call, it'll be successful unless it raises an exception)
+      def hoist_errors(prefix: nil)
+        raise ArgumentError, "#hoist_errors must be given a block to execute" unless block_given?
+
+        result = begin
+          yield
+        rescue StandardError => e
+          warn "hoist_errors block swallowed an exception: #{e.message}"
+          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!)
+        unless result.respond_to?(:ok?)
+          raise ArgumentError,
+                "#hoist_errors is expected to wrap an Action call, but it returned a #{result.class.name} instead"
+        end
+
+        _handle_hoisted_errors(result, prefix:) unless result.ok?
+      end
+
+      # Separate method to allow overriding in subclasses
+      def _handle_hoisted_errors(result, prefix: nil)
+        @context.exception = result.exception if result.exception.present?
+        @context.error_prefix = prefix if prefix.present?
+
+        fail! result.error
+      end
+    end
+  end
+end

data/lib/action/logging.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+module Action
+  module Logging
+    LEVELS = %i[debug info warn error fatal].freeze
+
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        delegate :log, *LEVELS, to: :class
+      end
+    end
+
+    module ClassMethods
+      def log(message, level: :info)
+        level = :info if level == :debug && _targeted_for_debug_logging?
+        msg = [_log_prefix, message].compact_blank.join(" ")
+
+        Action.config.logger.send(level, msg)
+      end
+
+      LEVELS.each do |level|
+        define_method(level) do |message|
+          log(message, level:)
+        end
+      end
+
+      # 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/organizer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+#
+# CAUTION - ALPHA - TODO -- this code is extremely rough -- we have not yet gotten around to using it in production, so
+# consider this a work in progress / an indicator of things to come.
+#
+
+module Action
+  # NOTE: replaces, rather than layers on, the upstream Interactor::Organizer module (only three methods, and
+  # we want ability to implement a more complex interface where we pass options into the organized interactors)
+  module Organizer
+    def self.included(base)
+      base.class_eval do
+        include ::Action
+
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+
+    # NOTE: pulled unchanged from https://github.com/collectiveidea/interactor/blob/master/lib/interactor/organizer.rb
+    module ClassMethods
+      def organize(*interactors)
+        @organized = interactors.flatten
+      end
+
+      def organized
+        @organized ||= []
+      end
+    end
+
+    module InstanceMethods
+      # NOTE: override to use the `hoist_errors` method (internally, replaces call! with call + overrides to use @context directly)
+      def call
+        self.class.organized.each do |interactor|
+          hoist_errors { interactor.call(@context) }
+        end
+      end
+    end
+  end
+end

data/lib/action/swallow_exceptions.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Action
+  module SwallowExceptions
+    def self.included(base)
+      base.class_eval do
+        class_attribute :_success_msg, :_error_msg
+        class_attribute :_error_rescues, default: []
+
+        include InstanceMethods
+        extend ClassMethods
+
+        def run_with_exception_swallowing!
+          original_run!
+        rescue Action::Failure => e
+          # Just re-raise these (so we don't hit the unexpected-error case below)
+          raise e
+        rescue StandardError => e
+          # Add custom hook for intercepting exceptions (e.g. Teamshares automatically logs to Honeybadger)
+          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
+        end
+
+        def trigger_on_exception(e)
+          Action.config.on_exception(e,
+                                     action: self,
+                                     context: respond_to?(:context_for_logging) ? context_for_logging : @context.to_h)
+        rescue StandardError => e
+          # No action needed -- downstream #on_exception implementation should ideally log any internal failures, but
+          # we don't want exception *handling* failures to cascade and overwrite the original exception.
+          warn("Ignoring #{e.class.name} in on_exception hook: #{e.message}")
+        end
+
+        class << base
+          def call_bang_with_unswallowed_exceptions(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)
+          end
+
+          alias_method :original_call!, :call!
+          alias_method :call!, :call_bang_with_unswallowed_exceptions
+        end
+      end
+    end
+
+    module ClassMethods
+      def messages(success: nil, error: nil)
+        self._success_msg = success if success.present?
+        self._error_msg = error if error.present?
+
+        true
+      end
+
+      def rescues(matcher = nil, message = nil, **match_and_messages)
+        raise ArgumentError, "rescues must be called with a key, value pair or else keyword args" if [matcher, message].compact.size == 1
+
+        { matcher => message }.compact.merge(match_and_messages).each { |mam| self._error_rescues += [mam] }
+      end
+
+      def default_error = new.internal_context.default_error
+    end
+
+    module InstanceMethods
+      private
+
+      def fail!(message = nil)
+        @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) # rubocop:disable Style/RaiseArgs
+      end
+
+      def try
+        yield
+      rescue Action::Failure => e
+        # NOTE: re-raising so we can still fail! from inside the block
+        raise e
+      rescue StandardError => e
+        trigger_on_exception(e)
+      end
+
+      delegate :default_error, to: :internal_context
+    end
+  end
+end

data/lib/action/top_level_around_hook.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Action
+  module TopLevelAroundHook
+    def self.included(base)
+      base.class_eval do
+        around :__top_level_around_hook
+
+        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
+
+      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: ")
+      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",
+          context_for_logging(:outbound).presence&.inspect,
+        ].compact.join(". Set: ")
+      end
+
+      def _call_and_return_outcome(hooked)
+        hooked.call
+
+        "success"
+      rescue StandardError => e
+        [
+          e.is_a?(Action::Failure) ? "failure" : "exception",
+          e,
+        ]
+      end
+    end
+  end
+end