thunderoperation 0.2.0

data/lib/thunderoperation/parameters/hash_parameter.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Parameters
+    class HashParameter < Base
+      attr_reader :configuration
+
+      def initialize(_type = nil, options = {}, &block)
+        super(Hash, options)
+
+        @configuration = {}
+
+        instance_exec(&block) if block
+        check_map_declaration!
+      end
+
+      def param(field_name, *, &)
+        @configuration[field_name.to_sym] = self.class.from_args(*, &)
+      end
+
+      # WARN: AI MADE
+      # The word of returns and event payloads (`returns Hash do field :title, String end`); params keep `param`.
+      alias field param
+
+      # A nested Hash read from an object's association when an external operation renders its result; elsewhere,
+      # the same as `field name, Hash do ... end`.
+      def association(field_name, options = {}, &)
+        field(field_name, Hash, options, &)
+      end
+
+      # WARN: AI MADE
+      # A map: `keys Date` and `values Integer` (or `values Hash do ... end`), for a Hash whose keys are data (dates,
+      # ids); a Hash with fixed keys declares them with `field`. A protobuf `map`.
+      def keys(*args)
+        return @keys if args.empty?
+
+        @keys = Base.from_args(*args)
+      end
+
+      def values(*args, &)
+        return @values if args.empty? && !block_given?
+
+        @values = Base.from_args(*args, &)
+      end
+
+      def map? = !@keys.nil? || !@values.nil?
+
+      def output_keys
+        @configuration.map { |field_name, parameter| parameter.options[:as] || field_name }
+      end
+
+      def filter(value)
+        return FILTERED if sensitive?
+        return value if value.nil?
+        return value.transform_values { |item| @values.filter(item) } if map?
+        return value if @configuration.empty?
+
+        filter_fields(value)
+      end
+
+      def sanitize(value, path: nil)
+        validate!(value, path:)
+
+        return if value.nil?
+        return sanitize_map(value, path) if map?
+        return value if @configuration.empty?
+
+        @configuration.filter_map { |field_name, parameter| sanitize_field(value, field_name, parameter, path) }.to_h
+      end
+
+      # WARN: AI MADE
+      def resolve_types!(&)
+        @configuration.each_value { |parameter| parameter.resolve_types!(&) }
+        @keys&.resolve_types!(&)
+        @values&.resolve_types!(&)
+      end
+
+      def check!(value, path: nil)
+        validate!(value, path:)
+        return if value.nil?
+        return check_map!(value, path) if map?
+        return if @configuration.empty?
+
+        unknown = value.keys.map(&:to_sym) - @configuration.keys
+        if unknown.any?
+          field_path = [path, unknown.first].compact.join('.')
+          raise Exceptions::ParameterError.new("Unknown field '#{field_path}'", field: field_path)
+        end
+
+        @configuration.each { |field_name, parameter| check_field!(value, field_name, parameter, path) }
+      end
+
+      private
+
+      # WARN: AI MADE
+      def check_map_declaration!
+        return unless map?
+        raise Exceptions::DeclarationError, 'a map declares both keys and values' if @keys.nil? || @values.nil?
+        return if @configuration.empty?
+
+        raise Exceptions::DeclarationError, 'a Hash declares fields or keys/values, not both'
+      end
+
+      def filter_fields(value)
+        @configuration.filter_map do |field_name, parameter|
+          key = parameter.options[:as] || field_name
+          [key, parameter.filter(value[key])] if value.key?(key)
+        end.to_h
+      end
+
+      def check_map!(value, path)
+        value.each do |key, item|
+          @keys.check!(key, path: "#{path}[#{key}]")
+          @values.check!(item, path: "#{path}[#{key}]")
+        end
+      end
+
+      def sanitize_map(value, path)
+        value.to_h do |key, item|
+          [@keys.sanitize(key, path: "#{path}[#{key}]"), @values.sanitize(item, path: "#{path}[#{key}]")]
+        end
+      end
+
+      def check_field!(value, field_name, parameter, path)
+        key = input_key(value, field_name)
+        field_path = path ? "#{path}.#{field_name}" : field_name.to_s
+
+        if key
+          parameter.check!(value[key], path: field_path)
+        elsif parameter.required?
+          raise Exceptions::ParameterError.new("Required field '#{field_path}' is missing", field: field_path)
+        end
+      end
+
+      def sanitize_field(value, field_name, parameter, path)
+        key = input_key(value, field_name)
+        field_path = path ? "#{path}.#{field_name}" : field_name.to_s
+
+        if key
+          [parameter.options[:as] || field_name, parameter.sanitize(value[key], path: field_path)]
+        elsif parameter.required?
+          raise Exceptions::ParameterError.new("Required field '#{field_path}' is missing", field: field_path)
+        end
+      end
+
+      def input_key(value, field_name)
+        return field_name if value.key?(field_name)
+
+        string_key = field_name.name
+        string_key if value.key?(string_key)
+      end
+    end
+  end
+end

data/lib/thunderoperation/parameters.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Parameters
+    extend Lookup
+
+    def self.for_type(type)
+      resolve("#{type.name}Parameter", base: Base) if type
+    end
+  end
+end

data/lib/thunderoperation/response.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  Response = Data.define(
+    :payload,
+    :was_success,
+    :error,
+    :status,
+    :headers,
+    :failed_step,
+    :operation_name
+  ) do
+    def initialize(error: nil, status: nil, headers: nil, failed_step: nil, **args)
+      super(**args, error:, status:, headers:, failed_step:)
+    end
+
+    def success?
+      was_success
+    end
+
+    def failure?
+      !was_success
+    end
+
+    alias_method :failed?, :failure?
+
+    def failure_message
+      error&.message
+    end
+
+    def failure_extras
+      error.extras if error.respond_to?(:extras)
+    end
+
+    def trail
+      return [] unless error.respond_to?(:operation_trail)
+
+      error.operation_trail.map(&:to_s)
+    end
+
+    def interrupted?
+      error.is_a?(Exceptions::Interruption)
+    end
+
+    def failure_data
+      return unless error
+
+      {
+        failed_step:,
+        trail:,
+        failure_message: error.message,
+        error_class: error.class.name,
+        operation_name:,
+        failure_extras:
+      }
+    end
+
+    def to_h
+      super.merge(failure_data:)
+    end
+  end
+end

data/lib/thunderoperation/rubocop.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Entry point for `require: thunderoperation/rubocop` in .rubocop.yml: cops for the operation DSL.
+require 'rubocop'
+
+# WARN: AI MADE
+# The defaults in config/default.yml, merged into RuboCop's own, so a project only has to load the cops.
+module ThunderOperation
+  module RuboCop
+    CONFIG_DEFAULT = File.expand_path('../../config/default.yml', __dir__)
+
+    def self.inject_defaults!
+      hash = ::RuboCop::ConfigLoader.send(:load_yaml_configuration, CONFIG_DEFAULT)
+      config = ::RuboCop::ConfigLoader.merge_with_default(::RuboCop::Config.new(hash, CONFIG_DEFAULT), CONFIG_DEFAULT)
+      ::RuboCop::ConfigLoader.instance_variable_set(:@default_configuration, config)
+    end
+  end
+end
+
+ThunderOperation::RuboCop.inject_defaults!
+
+require_relative '../rubocop/cop/thunderoperation/operation_helpers'
+require_relative '../rubocop/cop/thunderoperation/operation_section_order'
+require_relative '../rubocop/cop/thunderoperation/flow_required'
+require_relative '../rubocop/cop/thunderoperation/unknown_step'
+require_relative '../rubocop/cop/thunderoperation/missing_steps'
+require_relative '../rubocop/cop/thunderoperation/unused_step'
+require_relative '../rubocop/cop/thunderoperation/steps_order'
+require_relative '../rubocop/cop/thunderoperation/steps_cannot_call_steps'
+require_relative '../rubocop/cop/thunderoperation/def_outside_steps'
+require_relative '../rubocop/cop/thunderoperation/call_handlers'

data/lib/thunderoperation/steps/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Steps
+    class Base
+      def self.build(_name, *args, **kwargs)
+        new(*args, **kwargs)
+      end
+
+      def self.step_name
+        @step_name ||= name.demodulize.underscore.to_sym
+      end
+
+      def initialize
+        freeze
+      end
+
+      def name
+        self.class.step_name
+      end
+
+      def run(_instance)
+        raise NotImplementedError, "#{self.class.name}#run"
+      end
+
+      def to_s
+        name.to_s
+      end
+
+      def inspect
+        "#<#{self.class.name} #{self}>"
+      end
+
+      protected
+
+      def signature(name, args, kwargs)
+        rendered = args.map(&:inspect) + kwargs.map { |key, value| "#{key}: #{value.inspect}" }
+        return name.to_s if rendered.empty?
+
+        "#{name}(#{rendered.join(', ')})"
+      end
+    end
+  end
+end

data/lib/thunderoperation/steps/clause.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Steps
+    class Clause < Base
+      attr_reader :name, :handler, :args, :kwargs, :flow
+
+      def initialize(name, handler, *args, **kwargs, &block)
+        raise ArgumentError, "clause `#{name}` requires a block" unless block
+
+        @name = name.to_sym
+        @handler = handler
+        @args = args.freeze
+        @kwargs = kwargs.freeze
+        @flow = Flow.build(&block)
+        super()
+      end
+
+      def steps
+        flow.steps
+      end
+
+      def run(instance)
+        handler.call(instance, *args, **kwargs) { flow.run(instance) }
+      end
+
+      def to_s
+        "#{signature(name, args, kwargs)} { #{flow} }"
+      end
+    end
+  end
+end

data/lib/thunderoperation/steps/method.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Steps
+    class Method < Base
+      attr_reader :name, :args, :kwargs
+
+      def self.build(name, *args, **kwargs)
+        new(name, *args, **kwargs)
+      end
+
+      def initialize(name, *args, **kwargs)
+        @name = name.to_sym
+        @args = args.freeze
+        @kwargs = kwargs.freeze
+        super()
+      end
+
+      def run(instance)
+        if args.empty? && kwargs.empty?
+          instance.send(name)
+        else
+          instance.send(name, *args, **kwargs)
+        end
+
+        nil
+      end
+
+      def to_s
+        signature(name, args, kwargs)
+      end
+    end
+  end
+end

data/lib/thunderoperation/steps/render.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Steps
+    class Render < Success
+      attr_reader :status
+
+      def initialize(payload = nil, status: nil)
+        @status = status
+        super(payload)
+      end
+
+      def run(instance)
+        instance._success(resolve(instance), status:)
+      end
+
+      def to_s
+        signature(:render, payload.nil? ? [] : [payload], status ? { status: } : {})
+      end
+    end
+  end
+end

data/lib/thunderoperation/steps/success.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Steps
+    class Success < Base
+      attr_reader :payload
+
+      def initialize(payload = nil)
+        @payload = payload
+        @ivar = :"@#{payload}" if payload.is_a?(Symbol)
+        super()
+      end
+
+      def run(instance)
+        instance._success(resolve(instance))
+      end
+
+      def to_s
+        payload.nil? ? 'success' : "success(#{payload.inspect})"
+      end
+
+      protected
+
+      def resolve(instance)
+        @ivar ? instance.instance_variable_get(@ivar) : payload
+      end
+    end
+  end
+end

data/lib/thunderoperation/steps.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Steps
+    extend Lookup
+
+    INTERNAL = %w[Base Method Clause].freeze
+
+    class << self
+      def build(name, *args, **kwargs, &block)
+        return build_clause(name, *args, **kwargs, &block) if block
+
+        (lookup(name) || Method).build(name, *args, **kwargs)
+      end
+
+      def lookup(name)
+        resolve(name, base: Base, except: INTERNAL)
+      end
+
+      private
+
+      def build_clause(name, *args, **kwargs, &block)
+        handler = Clauses.lookup(name)
+        unless handler
+          raise ArgumentError,
+                "unknown clause `#{name}`; define ThunderOperation::Clauses::#{name.to_s.camelize}"
+        end
+
+        Clause.new(name, handler, *args, **kwargs, &block)
+      end
+    end
+  end
+end

data/lib/thunderoperation/steps_definition.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  class StepsDefinition
+    include Enumerable
+
+    MODULE_NAME = :StepMethods
+
+    class Methods < Module
+      attr_reader :names
+
+      def initialize
+        super
+        @names = []
+      end
+
+      def method_added(name)
+        super
+        @names << name unless @names.include?(name)
+        private(name)
+      end
+    end
+
+    attr_reader :owner, :methods_module
+
+    def self.build(owner, &block)
+      methods_module = methods_module_for(owner)
+      methods_module.class_exec(&block)
+
+      new(owner, methods_module)
+    end
+
+    def self.methods_module_for(owner)
+      return owner.const_get(MODULE_NAME, false) if owner.const_defined?(MODULE_NAME, false)
+
+      Methods.new.tap do |methods_module|
+        owner.const_set(MODULE_NAME, methods_module)
+        owner.include(methods_module)
+      end
+    end
+    private_class_method :methods_module_for
+
+    def initialize(owner, methods_module)
+      @owner = owner
+      @methods_module = methods_module
+      freeze
+    end
+
+    def names
+      methods_module.respond_to?(:names) ? methods_module.names : []
+    end
+
+    def each(&)
+      names.each(&)
+    end
+
+    def include?(name)
+      names.include?(name.to_sym)
+    end
+
+    def instance_method(name)
+      methods_module.instance_method(name)
+    end
+
+    def empty?
+      names.empty?
+    end
+
+    def to_s
+      names.join(', ')
+    end
+
+    NONE = new(nil, Module.new.freeze)
+  end
+end

data/lib/thunderoperation/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  VERSION = '0.2.0'
+end

data/lib/thunderoperation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+require 'thunderframe'
+
+require_relative 'thunderoperation/version'
+require_relative 'thunderoperation/config'
+require_relative 'thunderoperation/lookup'
+require_relative 'thunderoperation/exceptions'
+require_relative 'thunderoperation/exceptions/trail'
+require_relative 'thunderoperation/response'
+require_relative 'thunderoperation/handlers'
+require_relative 'thunderoperation/adapter'
+require_relative 'thunderoperation/concerns/has_adapter'
+require_relative 'thunderoperation/parameters'
+require_relative 'thunderoperation/parameters/base'
+require_relative 'thunderoperation/parameters/hash_parameter'
+require_relative 'thunderoperation/parameters/array_parameter'
+require_relative 'thunderoperation/adapters/rich_parameters'
+require_relative 'thunderoperation/adapters/interruptable'
+require_relative 'thunderoperation/adapters/validations'
+require_relative 'thunderoperation/adapters/framer'
+require_relative 'thunderoperation/steps'
+require_relative 'thunderoperation/steps/base'
+require_relative 'thunderoperation/steps/method'
+require_relative 'thunderoperation/steps/clause'
+require_relative 'thunderoperation/steps/success'
+require_relative 'thunderoperation/steps/render'
+require_relative 'thunderoperation/clauses'
+require_relative 'thunderoperation/clauses/base'
+require_relative 'thunderoperation/clauses/transaction'
+require_relative 'thunderoperation/flow'
+require_relative 'thunderoperation/flow/builder'
+require_relative 'thunderoperation/steps_definition'
+require_relative 'thunderoperation/base'

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: thunderoperation
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Albert Alef
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: thunderframe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- config/default.yml
+- lib/rubocop/cop/thunderoperation/call_handlers.rb
+- lib/rubocop/cop/thunderoperation/def_outside_steps.rb
+- lib/rubocop/cop/thunderoperation/flow_required.rb
+- lib/rubocop/cop/thunderoperation/missing_steps.rb
+- lib/rubocop/cop/thunderoperation/operation_helpers.rb
+- lib/rubocop/cop/thunderoperation/operation_section_order.rb
+- lib/rubocop/cop/thunderoperation/steps_cannot_call_steps.rb
+- lib/rubocop/cop/thunderoperation/steps_order.rb
+- lib/rubocop/cop/thunderoperation/unknown_step.rb
+- lib/rubocop/cop/thunderoperation/unused_step.rb
+- lib/thunderoperation.rb
+- lib/thunderoperation/adapter.rb
+- lib/thunderoperation/adapters/framer.rb
+- lib/thunderoperation/adapters/interruptable.rb
+- lib/thunderoperation/adapters/rich_parameters.rb
+- lib/thunderoperation/adapters/validations.rb
+- lib/thunderoperation/base.rb
+- lib/thunderoperation/clauses.rb
+- lib/thunderoperation/clauses/base.rb
+- lib/thunderoperation/clauses/transaction.rb
+- lib/thunderoperation/concerns/has_adapter.rb
+- lib/thunderoperation/config.rb
+- lib/thunderoperation/exceptions.rb
+- lib/thunderoperation/exceptions/trail.rb
+- lib/thunderoperation/flow.rb
+- lib/thunderoperation/flow/builder.rb
+- lib/thunderoperation/handlers.rb
+- lib/thunderoperation/lookup.rb
+- lib/thunderoperation/parameters.rb
+- lib/thunderoperation/parameters/array_parameter.rb
+- lib/thunderoperation/parameters/base.rb
+- lib/thunderoperation/parameters/hash_parameter.rb
+- lib/thunderoperation/response.rb
+- lib/thunderoperation/rubocop.rb
+- lib/thunderoperation/steps.rb
+- lib/thunderoperation/steps/base.rb
+- lib/thunderoperation/steps/clause.rb
+- lib/thunderoperation/steps/method.rb
+- lib/thunderoperation/steps/render.rb
+- lib/thunderoperation/steps/success.rb
+- lib/thunderoperation/steps_definition.rb
+- lib/thunderoperation/version.rb
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Operations engine: param, flow, steps, returns, adapters'
+test_files: []