servactory 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ba22a3302a9dde10fcadfc2cc5777e83589e86862b8e96484ddd3ad62e78782
+  data.tar.gz: 4fa891477fb78494b3df34bb50f3b5bea018d331471662e235d91c49d82b9e6c
+SHA512:
+  metadata.gz: c4c5e7cbf5c7708cc468f25152086d974c1ecfee76222bade55215c4f14ee9b0b20194755338152ac21e72845e8c1358f4e185b08b6db08319c48990b5cf43ef
+  data.tar.gz: 70c1325c6b7de415565d41f4471798d1349c0627eeca7a329b876d703500b338acb725a5bd5adc41578656488541a13690358d377799c493f8e8ba719bb1c710

data/README.md

@@ -0,0 +1,116 @@
+# Servactory
+
+A set of tools for building reliable services of any complexity.
+
+## Requirements
+
+- Ruby >= 2.7
+
+## Getting started
+
+### Conventions
+
+- Services are subclasses of `Servactory::Base` and are located in the `app/services` directory. It is common practice to create and inherit from `ApplicationService::Base`, which is a subclass of `Servactory::Base`.
+- Name services by what they do, not by what they accept. Try to use verbs in names. For example, `UsersService::Create` instead of `UsersService::Creation`.
+
+### Installation
+
+Add this to `Gemfile`:
+
+```ruby
+gem "servactory"
+```
+
+And execute:
+
+```shell
+bundle install
+```
+
+### Preparation
+
+We recommend that you first prepare the following files in your project.
+
+#### ApplicationService::Errors
+
+```ruby
+# app/services/application_service/errors.rb
+
+module ApplicationService
+  module Errors
+    class InputArgumentError < Servactory::Errors::InputArgumentError; end
+    class OutputArgumentError < Servactory::Errors::OutputArgumentError; end
+    class InternalArgumentError < Servactory::Errors::InternalArgumentError; end
+
+    class Failure < Servactory::Errors::Failure; end
+  end
+end
+```
+
+#### ApplicationService::Base
+
+```ruby
+# app/services/application_service/base.rb
+
+module ApplicationService
+  class Base < Servactory::Base
+    configuration do
+      input_argument_error_class ApplicationService::Errors::InputArgumentError
+      output_argument_error_class ApplicationService::Errors::OutputArgumentError
+      internal_argument_error_class ApplicationService::Errors::InternalArgumentError
+
+      failure_class ApplicationService::Errors::Failure
+    end
+  end
+end
+```
+
+## Usage
+
+### Minimal example
+
+```ruby
+class SendService < ApplicationService::Base
+  stage { make :something }
+  
+  private
+  
+  def something
+    # ...
+  end
+end
+```
+
+### Inputs
+
+```ruby
+class SendService < ApplicationService::Base
+  input :user, type: User
+  
+  stage { make :something }
+  
+  private
+  
+  def something
+    # ...
+  end
+end
+```
+
+### Outputs
+
+```ruby
+class SendService < ApplicationService::Base
+  input :user, type: User
+  
+  output :notification, type: Notification
+  
+  stage { make :something }
+  
+  private
+  
+  def something
+    self.notification = Notification.create!
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/servactory/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Servactory
+  class Base
+    include Context::DSL
+    include InputArguments::DSL
+    include InternalArguments::DSL
+    include OutputArguments::DSL
+    include Stage::DSL
+  end
+end

data/lib/servactory/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Servactory
+  class Configuration
+    attr_accessor :input_argument_error_class,
+                  :internal_argument_error_class,
+                  :output_argument_error_class,
+                  :failure_class
+
+    def initialize
+      @input_argument_error_class = Servactory::Errors::InputArgumentError
+      @internal_argument_error_class = Servactory::Errors::InternalArgumentError
+      @output_argument_error_class = Servactory::Errors::OutputArgumentError
+
+      @failure_class = Servactory::Errors::Failure
+    end
+  end
+end

data/lib/servactory/context/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Context
+    class Configuration
+      def input_argument_error_class(input_argument_error_class)
+        Servactory.configuration.input_argument_error_class = input_argument_error_class
+      end
+
+      def output_argument_error_class(output_argument_error_class)
+        Servactory.configuration.output_argument_error_class = output_argument_error_class
+      end
+
+      def internal_argument_error_class(internal_argument_error_class)
+        Servactory.configuration.internal_argument_error_class = internal_argument_error_class
+      end
+
+      def failure_class(failure_class)
+        Servactory.configuration.failure_class = failure_class
+      end
+    end
+  end
+end

data/lib/servactory/context/dsl.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Context
+    module DSL
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def call!(arguments) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          @context_store ||= Store.new(self)
+
+          assign_data_with(arguments)
+
+          input_arguments_workbench.find_unnecessary!
+          input_arguments_workbench.check_rules!
+          output_arguments_workbench.find_conflicts_in!(collection_of_internal_arguments:)
+
+          prepare_data
+
+          input_arguments_workbench.check!
+
+          stage_handyman.run_methods!
+
+          Servactory::Result.prepare_for(
+            context: context_store.context,
+            collection_of_output_arguments:
+          )
+        end
+
+        private
+
+        attr_reader :context_store
+
+        def assign_data_with(arguments)
+          input_arguments_workbench.assign(context: context_store.context, arguments:)  # 1
+          internal_arguments_workbench.assign(context: context_store.context)           # 2
+          output_arguments_workbench.assign(context: context_store.context)             # 3
+          stage_handyman&.assign(context: context_store.context)                        # 4
+        end
+
+        def prepare_data
+          input_arguments_workbench.prepare     # 1
+
+          output_arguments_workbench.prepare    # 2
+          internal_arguments_workbench.prepare  # 3
+        end
+
+        def configuration(&)
+          context_configuration = Servactory::Context::Configuration.new
+
+          context_configuration.instance_eval(&)
+        end
+      end
+    end
+  end
+end

data/lib/servactory/context/store.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Context
+    class Store
+      attr_reader :context
+
+      def initialize(service_class)
+        @context = service_class.new
+
+        service_class.class_eval(service_class_template_with(context))
+      end
+
+      private
+
+      # EXAMPLE:
+      #
+      #   attr_reader(:inputs)
+      #
+      #   def assign_inputs(inputs)
+      #     @inputs = inputs
+      #   end
+      #
+      #   def fail_input!(input_attribute_name, message, prefix: true)
+      #     message_text = prefix ? "[#{context.class.name}] Custom `\#{input_attribute_name}` input error: " : ""
+      #
+      #     message_text += message
+      #
+      #     raise Servactory.configuration.input_argument_error_class, message_text
+      #   end
+      #
+      def service_class_template_with(context)
+        <<-RUBY
+          attr_reader(:inputs)
+
+          def assign_inputs(inputs)
+            @inputs = inputs
+          end
+
+          def fail_input!(input_attribute_name, message, prefix: true)
+            message_text = prefix ? "[#{context.class.name}] Custom `\#{input_attribute_name}` input error: " : ""
+
+            message_text += message
+
+            raise Servactory.configuration.input_argument_error_class, message_text
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/servactory/errors/base.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class Base < StandardError; end
+  end
+end

data/lib/servactory/errors/failure.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class Failure < Servactory::Errors::Base; end
+  end
+end

data/lib/servactory/errors/input_argument_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class InputArgumentError < Servactory::Errors::Base; end
+  end
+end

data/lib/servactory/errors/internal_argument_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class InternalArgumentError < Servactory::Errors::Base; end
+  end
+end

data/lib/servactory/errors/output_argument_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class OutputArgumentError < Servactory::Errors::Base; end
+  end
+end

data/lib/servactory/input_arguments/checks/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    module Checks
+      class Base
+        def initialize
+          @errors = []
+        end
+
+        attr_reader :errors
+
+        protected
+
+        def add_error(message, **arguments)
+          message = message.call(**arguments) if message.is_a?(Proc)
+
+          errors.push(message)
+        end
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/checks/inclusion.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    module Checks
+      class Inclusion < Base
+        DEFAULT_MESSAGE = lambda do |service_class_name:, input:|
+          "[#{service_class_name}] Wrong value in `#{input.name}`, must be one of `#{input.inclusion}`"
+        end
+
+        private_constant :DEFAULT_MESSAGE
+
+        def self.check(context:, input:, value:, check_key:, **)
+          return unless should_be_checked_for?(input, check_key)
+
+          new(context:, input:, value:).check
+        end
+
+        def self.should_be_checked_for?(input, check_key)
+          check_key == :inclusion && input.inclusion_present?
+        end
+
+        ##########################################################################
+
+        def initialize(context:, input:, value:)
+          super()
+
+          @context = context
+          @input = input
+          @value = value
+        end
+
+        def check
+          return if @input.inclusion.include?(@value)
+
+          add_error(
+            DEFAULT_MESSAGE,
+            service_class_name: @context.class.name,
+            input: @input
+          )
+        end
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/checks/must.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    module Checks
+      class Must < Base
+        DEFAULT_MESSAGE = lambda do |service_class_name:, input:, code:|
+          "[#{service_class_name}] Input `#{input.name}` " \
+            "must \"#{code.to_s.humanize(capitalize: false, keep_id_suffix: true)}\""
+        end
+
+        private_constant :DEFAULT_MESSAGE
+
+        def self.check(context:, input:, value:, check_key:, check_options:)
+          return unless should_be_checked_for?(input, check_key)
+
+          new(context:, input:, value:, check_options:).check
+        end
+
+        def self.should_be_checked_for?(input, check_key)
+          check_key == :must && input.must_present?
+        end
+
+        ##########################################################################
+
+        def initialize(context:, input:, value:, check_options:)
+          super()
+
+          @context = context
+          @input = input
+          @value = value
+          @check_options = check_options
+        end
+
+        def check
+          @check_options.each do |code, options|
+            message = call_or_fetch_message_from(code, options)
+
+            next if message.blank?
+
+            add_error(
+              DEFAULT_MESSAGE,
+              service_class_name: @context.class.name,
+              input: @input,
+              code:
+            )
+          end
+
+          errors
+        end
+
+        private
+
+        def call_or_fetch_message_from(code, options) # rubocop:disable Metrics/MethodLength
+          check, message = options.values_at(:is, :message)
+
+          return if check.call(value: @value)
+
+          message.presence || DEFAULT_MESSAGE
+        rescue StandardError => e
+          message_text =
+            "[#{@context.class.name}] Syntax error inside `#{code}` of " \
+            "`#{@input.name}` input: [#{e.class}] #{e.message}"
+
+          add_error(
+            message_text,
+            service_class_name: @context.class.name,
+            input: @input,
+            code:
+          )
+        end
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/checks/required.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    module Checks
+      class Required < Base
+        DEFAULT_MESSAGE = lambda do |service_class_name:, input:, value:|
+          if input.array? && value.present?
+            "[#{service_class_name}] Required element in input array `#{input.name}` is missing"
+          else
+            "[#{service_class_name}] Required input `#{input.name}` is missing"
+          end
+        end
+
+        private_constant :DEFAULT_MESSAGE
+
+        def self.check(context:, input:, value:, **)
+          return unless should_be_checked_for?(input)
+
+          new(context:, input:, value:).check
+        end
+
+        def self.should_be_checked_for?(input)
+          input.required?
+        end
+
+        ##########################################################################
+
+        def initialize(context:, input:, value:)
+          super()
+
+          @context = context
+          @input = input
+          @value = value
+        end
+
+        def check # rubocop:disable Metrics/MethodLength
+          if @input.array? && @value.present?
+            return if @value.respond_to?(:all?) && @value.all?(&:present?)
+          elsif @value.present?
+            return
+          end
+
+          add_error(
+            DEFAULT_MESSAGE,
+            service_class_name: @context.class.name,
+            input: @input,
+            value: @value
+          )
+        end
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/checks/type.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    module Checks
+      class Type < Base
+        DEFAULT_MESSAGE = lambda do |service_class_name:, input:, expected_type:, given_type:|
+          if input.array?
+            "[#{service_class_name}] Wrong type in input array `#{input.name}`, expected `#{expected_type}`"
+          else
+            "[#{service_class_name}] Wrong type of input `#{input.name}`, " \
+              "expected `#{expected_type}`, " \
+              "got `#{given_type}`"
+          end
+        end
+
+        private_constant :DEFAULT_MESSAGE
+
+        def self.check(context:, input:, value:, check_key:, check_options:)
+          return unless should_be_checked_for?(input, value, check_key)
+
+          new(context:, input:, value:, types: check_options).check
+        end
+
+        def self.should_be_checked_for?(input, value, check_key)
+          check_key == :types && (
+            input.required? || (
+              input.optional? && !input.default.nil?
+            ) || (
+              input.optional? && !value.nil?
+            )
+          )
+        end
+
+        ##########################################################################
+
+        def initialize(context:, input:, value:, types:)
+          super()
+
+          @context = context
+          @input = input
+          @value = value
+          @types = types
+        end
+
+        def check # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          return if prepared_types.any? do |type|
+            if @input.array?
+              prepared_value.is_a?(::Array) &&
+              prepared_value.respond_to?(:all?) && prepared_value.all?(type)
+            else
+              prepared_value.is_a?(type)
+            end
+          end
+
+          add_error(
+            DEFAULT_MESSAGE,
+            service_class_name: @context.class.name,
+            input: @input,
+            expected_type: prepared_types.join(", "),
+            given_type: prepared_value.class.name
+          )
+        end
+
+        ########################################################################
+
+        def prepared_types
+          @prepared_types ||=
+            @types.map do |type|
+              if type.is_a?(String)
+                Object.const_get(type)
+              else
+                type
+              end
+            end
+        end
+
+        def prepared_value
+          @prepared_value ||= @input.optional? && !@input.default.nil? ? @input.default : @value
+        end
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/collection.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    class Collection
+      # NOTE: http://words.steveklabnik.com/beware-subclassing-ruby-core-classes
+      extend Forwardable
+      def_delegators :@collection, :<<, :each, :map
+
+      def initialize(*)
+        @collection = []
+      end
+
+      def names
+        map(&:name)
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/dsl.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    module DSL
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        private
+
+        def input(name, **options)
+          collection_of_input_arguments << InputArgument.new(name, **options)
+        end
+
+        def collection_of_input_arguments
+          @collection_of_input_arguments ||= Collection.new
+        end
+
+        def input_arguments_workbench
+          @input_arguments_workbench ||= Workbench.work_with(collection_of_input_arguments)
+        end
+      end
+    end
+  end
+end