thunderoperation 0.2.0

data/lib/thunderoperation/adapters/rich_parameters.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Adapters
+    class RichParameters < Adapter
+      def execute(_params, operation_instance, _options, &block)
+        operation_instance._load_params
+
+        block.call
+      end
+
+      adapted do
+        def self.param(*, &)
+          @param_ivars = nil
+          base_parameter.param(*, &)
+        end
+
+        def self.base_parameter
+          @base_parameter ||= Parameters::HashParameter.new
+        end
+
+        def self.param_ivars
+          @param_ivars ||= base_parameter.output_keys.to_h { |key| [key, :"@#{key}"] }.freeze
+        end
+
+        def _reportable_params
+          return unless defined?(@sanitized_params) && @sanitized_params
+
+          self.class.base_parameter.filter(@sanitized_params)
+        end
+
+        def _load_params
+          @sanitized_params = self.class.base_parameter.sanitize(@params || {})
+
+          self.class.param_ivars.each do |key, ivar|
+            instance_variable_set(ivar, @sanitized_params[key]) if @sanitized_params.key?(key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/thunderoperation/adapters/validations.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Adapters
+    class Validations < Adapter
+      def execute(_params, _operation_instance, _options, &block)
+        validate_steps!
+
+        response = block.call
+        validate_return!(response) if check_return?(response)
+
+        response
+      end
+
+      private
+
+      def validate_steps!
+        steps = operation_class.steps
+        return if steps.equal?(StepsDefinition::NONE)
+
+        unknown = operation_class.flow.method_names - steps.names
+        return if unknown.empty?
+
+        raise Exceptions::UnknownStep,
+              "#{operation_class.name}: flow calls #{unknown.join(', ')}, not defined in `steps do ... end`"
+      end
+
+      # WARN: AI MADE
+      # Only with ThunderOperation.config.validate_returns, and not when an adapter renders the payload instead.
+      def check_return?(response)
+        response.success? && ThunderOperation.config.validate_returns &&
+          operation_class.returns.is_a?(Parameters::Base) && !operation_class.renders_returns?
+      end
+
+      # A missing payload fails unless the returns is optional: `success` without a payload is a mistake too.
+      def validate_return!(response)
+        returns = operation_class.returns
+        if response.payload.nil? && !returns.optional?
+          raise Exceptions::ParameterError.new("Invalid value for 'returns': expected #{returns.type}, got NilClass",
+                                               field: 'returns')
+        end
+
+        returns.check!(response.payload, path: 'returns')
+      rescue Exceptions::ParameterError => e
+        raise Exceptions::ReturnTypeError, "#{operation_class.name}: #{e.message} (#{response.payload.inspect})"
+      end
+    end
+  end
+end

data/lib/thunderoperation/base.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  class Base
+    include Concerns::HasAdapter
+
+    class OptionsProxy
+      def initialize(operation_class, options)
+        @operation_class = operation_class
+        @options = options
+      end
+
+      def call(params = nil, **kwargs, &block)
+        @operation_class.execute(params || kwargs, @options, &block)
+      end
+
+      def call!(params = nil, **kwargs, &block)
+        @operation_class.execute(params || kwargs, @options.merge(insecure_mode: true), &block)
+      end
+    end
+
+    NO_OPTIONS = {}.freeze
+    INSECURE_OPTIONS = { insecure_mode: true }.freeze
+
+    attr_accessor :_current_step
+
+    def initialize(params, options = {})
+      @params = params
+      @options = options
+    end
+
+    class << self
+      def flow(&block)
+        return @flow = Flow.build(&block) if block
+
+        @flow || (superclass.respond_to?(:flow) ? superclass.flow : Flow::EMPTY)
+      end
+
+      def steps(&block)
+        return @steps = StepsDefinition.build(self, &block) if block
+
+        @steps || StepsDefinition::NONE
+      end
+
+      # WARN: AI MADE
+      # What the operation returns, declared as a param: `returns Book::Relation`, `returns Hash do field ... end`,
+      # `returns Array do items Hash do ... end end`. A Symbol names a builder an adapter adds.
+      def returns(type = nil, options = {}, &block)
+        return @returns = returns_builder(type).call(self, &block) if type.is_a?(Symbol)
+        return @returns = Parameters::Base.from_args(*[type, options].compact, &block) if type || block
+
+        @returns || (superclass.respond_to?(:returns) ? superclass.returns : nil)
+      end
+
+      # True when an adapter renders the payload through `returns` (Framer) instead of only checking it.
+      def renders_returns? = false
+
+      def returns_builders
+        @returns_builders ||= superclass.respond_to?(:returns_builders) ? superclass.returns_builders.dup : {}
+      end
+
+      def call(params = nil, **kwargs, &block)
+        execute(params || kwargs, NO_OPTIONS, &block)
+      end
+
+      def call!(params = nil, **kwargs, &block)
+        execute(params || kwargs, INSECURE_OPTIONS, &block)
+      end
+
+      def failure_key_prefix
+        name.to_s.underscore.tr('/', '.')
+      end
+
+      def with(**options)
+        OptionsProxy.new(self, options)
+      end
+
+      def execute(params, options, &block)
+        raise ArgumentError, 'call! does not take a handlers block' if block && options[:insecure_mode]
+
+        response = run_instance(params, options)
+
+        block ? Handlers.run(response, &block) : response
+      end
+
+      private
+
+      def returns_builder(kind)
+        returns_builders.fetch(kind) do
+          raise ArgumentError, "unknown returns kind #{kind.inspect}; append the adapter that defines it"
+        end
+      end
+
+      def run_instance(params, options)
+        operation_instance = new(params, options)
+
+        handle_adapters(params, operation_instance, options) { operation_instance._run }
+      rescue StandardError => e
+        raise Exceptions::Trail.record(e, operation_instance) if options[:insecure_mode]
+
+        operation_instance._report_error(e)
+        operation_instance._failure(e)
+      end
+    end
+
+    def _run
+      self.class.flow.run(self) || _success
+    end
+
+    def _report_error(error)
+      handler = ThunderOperation.config.error_handler
+
+      return unless handler
+
+      level = error.is_a?(Exceptions::OperationError) ? :warning : :error
+      handler.call(error, level:, operation: self.class, step: _current_step&.name, params: _reportable_params)
+    end
+
+    def _reportable_params
+      nil
+    end
+
+    def raise_failure(message_key, extras: nil, status: nil)
+      raise Exceptions::OperationError.new(message_key, self.class, extras:, status:)
+    end
+
+    def _success(payload = nil, status: nil)
+      Response.new(was_success: true, payload:, status:, operation_name: self.class.name)
+    end
+
+    def _failure(exception, status = :unprocessable_entity, payload: nil)
+      Exceptions::Trail.record(exception, self)
+
+      Response.new(
+        was_success: false,
+        payload:,
+        operation_name: self.class.name,
+        error: exception,
+        status:,
+        failed_step: _current_step&.name
+      )
+    end
+  end
+end

data/lib/thunderoperation/clauses/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Clauses
+    class Base
+      def call(_instance, *_args, **_kwargs, &_run)
+        raise NotImplementedError, "#{self.class.name}#call"
+      end
+    end
+  end
+end

data/lib/thunderoperation/clauses/transaction.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Clauses
+    class Transaction < Base
+      def call(_instance, &run)
+        ThunderOperation.config.transaction.call(&run)
+      end
+    end
+  end
+end

data/lib/thunderoperation/clauses.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Clauses
+    extend Lookup
+
+    def self.lookup(name)
+      resolve(name, base: Base, except: %w[Base])&.new&.freeze
+    end
+  end
+end

data/lib/thunderoperation/concerns/has_adapter.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Concerns
+    module HasAdapter
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def append_adapter(adapter_class)
+          adapters << adapter_class
+          @adapter_rings = nil
+
+          return unless adapter_class.adapted_block
+
+          class_exec(&adapter_class.adapted_block)
+        end
+
+        def adapters
+          @adapters ||= superclass.respond_to?(:adapters) ? superclass.adapters.dup : []
+        end
+
+        def handle_adapters(params, operation_instance, options, &block)
+          deep_ring, outer_ring = adapter_rings
+
+          deep_block = deep_ring.reduce(block) do |previous_block, adapter|
+            proc { adapter.deep_execute(params, operation_instance, options, &previous_block) }
+          end
+
+          outer_ring.reduce(deep_block) do |previous_block, adapter|
+            proc { adapter.execute(params, operation_instance, options, &previous_block) }
+          end.call
+        end
+
+        private
+
+        def adapter_rings
+          @adapter_rings ||= begin
+            instances = adapters.map { |adapter_class| adapter_class.new(self).freeze }
+            [instances.select { |adapter| adapter.respond_to?(:deep_execute) }.freeze, instances.freeze].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/thunderoperation/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  class Config
+    attr_accessor :transaction
+
+    attr_accessor :error_handler
+
+    # WARN: AI MADE
+    # Whether a payload is checked against `returns` (Validations); off by default, so a mistake in a declaration
+    # does not fail an operation in production.
+    attr_accessor :validate_returns
+
+    def initialize
+      @transaction = ->(&block) { block.call }
+      @error_handler = nil
+      @validate_returns = false
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def reset_config!
+      @config = Config.new
+    end
+  end
+end

data/lib/thunderoperation/exceptions/trail.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Exceptions
+    module Trail
+      Entry = Data.define(:operation_class, :step) do
+        def to_s
+          step ? "#{operation_class.name}##{step}" : operation_class.name.to_s
+        end
+      end
+
+      def self.record(error, operation)
+        return error if error.nil? || error.frozen?
+
+        error.extend(self) unless error.is_a?(self)
+        entry = Entry.new(operation.class, operation._current_step&.name)
+        error.operation_trail << entry unless error.operation_trail.last == entry
+
+        error
+      end
+
+      def operation_trail
+        @operation_trail ||= []
+      end
+    end
+  end
+end

data/lib/thunderoperation/exceptions.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Exceptions
+    class Interruption < StandardError; end
+
+    class ParameterError < StandardError
+      attr_reader :field
+
+      def initialize(message, field: nil)
+        @field = field
+        super(message)
+      end
+    end
+
+    class OperationError < StandardError
+      attr_reader :message_key, :extras, :status
+
+      def initialize(message_key, operation_class, extras: nil, status: nil)
+        @message_key = message_key
+        @extras = extras
+        @status = status
+
+        super("operation_exception.#{operation_class.failure_key_prefix}.#{message_key}")
+      end
+    end
+
+    class DeclarationError < ScriptError; end
+    class UnknownStep < DeclarationError; end
+    class ReturnTypeError < DeclarationError; end
+  end
+end

data/lib/thunderoperation/flow/builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  class Flow
+    class Builder < BasicObject
+      def self.record(&block)
+        builder = new
+        builder.instance_eval(&block)
+        builder.__steps__
+      end
+
+      def initialize
+        @steps = []
+      end
+
+      def __steps__
+        @steps
+      end
+
+      def method_missing(name, *args, **kwargs, &block)
+        @steps << ::ThunderOperation::Steps.build(name, *args, **kwargs, &block)
+
+        nil
+      end
+
+      def respond_to_missing?(*)
+        true
+      end
+    end
+  end
+end

data/lib/thunderoperation/flow.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  class Flow
+    include Enumerable
+
+    attr_reader :steps
+
+    def self.build(&block)
+      new(Builder.record(&block))
+    end
+
+    def initialize(steps = [])
+      @steps = steps.dup.freeze
+      freeze
+    end
+
+    EMPTY = new
+
+    def each(&)
+      steps.each(&)
+    end
+
+    def names
+      steps.map(&:name)
+    end
+
+    def method_names
+      steps.flat_map do |step|
+        case step
+        when Steps::Method then [step.name]
+        when Steps::Clause then step.flow.method_names
+        else []
+        end
+      end.uniq
+    end
+
+    def empty?
+      steps.empty?
+    end
+
+    def run(instance)
+      steps.each do |step|
+        instance._current_step = step
+        result = step.run(instance)
+
+        return result if result.is_a?(Response)
+      end
+
+      nil
+    end
+
+    def to_s
+      steps.map(&:to_s).join(', ')
+    end
+  end
+end

data/lib/thunderoperation/handlers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  class Handlers < BasicObject
+    def self.run(response, &block)
+      handlers = new
+      handlers.instance_exec(&block)
+      handlers.__dispatch__(response, block.binding.receiver)
+      response
+    end
+
+    def initialize
+      @success = nil
+      @failure = nil
+    end
+
+    def success(&block)
+      @success = block
+    end
+
+    def failure(&block)
+      @failure = block
+    end
+
+    def __dispatch__(response, receiver)
+      if response.success?
+        receiver.instance_exec(response, &@success) if @success
+      elsif @failure
+        receiver.instance_exec(response, &@failure)
+      else
+        ::Kernel.raise response.error
+      end
+    end
+
+    def method_missing(name, *)
+      ::Kernel.raise ::ArgumentError, "only `success` and `failure` are allowed in a call block, got `#{name}`"
+    end
+
+    def respond_to_missing?(*)
+      false
+    end
+  end
+end

data/lib/thunderoperation/lookup.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Lookup
+    def resolve(name, base:, except: [])
+      const_name = name.to_s.camelize
+      return if except.include?(const_name) || !const_defined?(const_name, false)
+
+      klass = const_get(const_name, false)
+      klass if klass.is_a?(Class) && klass < base
+    end
+  end
+end

data/lib/thunderoperation/parameters/array_parameter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Parameters
+    class ArrayParameter < Base
+      def initialize(_type = nil, options = {}, &block)
+        super(Array, options)
+
+        @items = nil
+
+        instance_exec(&block) if block
+      end
+
+      def items(*args, &block)
+        return @items if args.empty? && block.nil?
+
+        @items = self.class.from_args(*args, &block)
+      end
+
+      def filter(values)
+        return FILTERED if sensitive?
+        return values if @items.nil? || values.nil?
+
+        values.map { |value| @items.filter(value) }
+      end
+
+      # WARN: AI MADE
+      def resolve_types!(&)
+        @items&.resolve_types!(&)
+      end
+
+      def check!(values, path: nil)
+        validate!(values, path:)
+        return if @items.nil? || values.nil?
+
+        values.each_with_index { |value, index| @items.check!(value, path: "#{path}[#{index}]") }
+      end
+
+      def sanitize(values, path: nil)
+        validate!(values, path:)
+
+        return values if @items.nil? || values.nil?
+
+        values.each_with_index.map { |value, index| @items.sanitize(value, path: "#{path}[#{index}]") }
+      end
+    end
+  end
+end

data/lib/thunderoperation/parameters/base.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Parameters
+    class Base
+      FILTERED = '[FILTERED]'
+
+      attr_reader :type, :options
+
+      def self.from_args(*args, &block)
+        type, options = parse_args(args)
+
+        raise Exceptions::DeclarationError, "parameter type is required, got nil" if type.nil? && !block
+
+        klass = (Parameters.for_type(type) if type.is_a?(Class)) || (block ? HashParameter : Base)
+
+        klass.new(type, options, &block)
+      end
+
+      def self.parse_args(args)
+        # A String names a class the engine does not know yet ('Models::Supplier'); whoever loads the operation
+        # replaces it through resolve_types!.
+        case args
+        in [Class | String => type, Hash => options] then [type, options]
+        in [Hash => options] then [nil, options]
+        in [Class | String => type] then [type, {}]
+        else [nil, {}]
+        end
+      end
+      private_class_method :parse_args
+
+      def initialize(type = nil, options = {})
+        @type = type
+        @options = options
+      end
+
+      def optional?
+        @options[:optional] == true
+      end
+
+      def required?
+        !optional?
+      end
+
+      def sensitive?
+        @options[:sensitive] == true
+      end
+
+      def filter(value)
+        sensitive? ? FILTERED : value
+      end
+
+      def sanitize(value, path: nil)
+        validate!(value, path:)
+
+        value
+      end
+
+      def valid?(value)
+        if unresolved_type?
+          raise Exceptions::DeclarationError, "type '#{@type}' was never resolved to a class"
+        end
+
+        (@type.nil? || value.is_a?(@type)) ||
+          (options[:null] != false && value.nil?)
+      end
+
+      # WARN: AI MADE
+      # Replaces a type given by name with the class the block returns for it; nested parameters do the same.
+      def resolve_types!
+        @type = yield(@type) if @type.is_a?(String)
+      end
+
+      def unresolved_type? = @type.is_a?(String)
+
+      # The value has exactly the declared shape (returns and event payloads): the type, and for a Hash every
+      # declared key and no other. Raises ParameterError with the path of the first difference.
+      def check!(value, path: nil)
+        validate!(value, path:)
+      end
+
+      def validate!(value, path: nil)
+        return if valid?(value)
+
+        raise Exceptions::ParameterError.new(
+          "Invalid value for '#{path}': expected #{@type}, got #{value.class}",
+          field: path
+        )
+      end
+    end
+  end
+end