convenient_service 0.6.0 → 0.8.0

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/commands/format_backtrace.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module RescuesResultUnhandledExceptions
+        module Commands
+          class FormatBacktrace < Support::Command
+            ##
+            # @!attribute [r] backtrace
+            #   @return [Array, nil]
+            #
+            attr_reader :backtrace
+
+            ##
+            # @!attribute [r] max_size
+            #   @return [Integer]
+            #
+            attr_reader :max_size
+
+            ##
+            # @param backtrace [Array, nil]
+            # @param max_size [Integer]
+            # @return [void]
+            #
+            # @internal
+            #   IMPORTANT: Sometimes `exception.backtrace` can be `nil`.
+            #   - https://blog.kalina.tech/2019/04/exception-without-backtrace-in-ruby.html
+            #   - https://github.com/jruby/jruby/issues/4467
+            #
+            def initialize(backtrace:, max_size:)
+              @backtrace = backtrace.to_a
+              @max_size = max_size
+            end
+
+            ##
+            # @return [String]
+            #
+            # @note Exceptions formatting is inspired by RSpec. It has almost the same output (at least for RSpec 3).
+            #
+            # @example Backtrace with upto 10 lines.
+            #
+            #   # /gem/lib/convenient_service/factories/services.rb:120:in `result'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `block in result'
+            #   # /gem/lib/convenient_service/dependencies/extractions/ruby_middleware/middleware/runner.rb:67:in `block (2 levels) in build_call_chain'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `block in next'
+            #   # /gem/lib/convenient_service/support/cache.rb:110:in `fetch'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `next'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware.rb:73:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #
+            # @example Backtrace with more than 10 lines.
+            #
+            #   # /gem/lib/convenient_service/factories/services.rb:120:in `result'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `block in result'
+            #   # /gem/lib/convenient_service/dependencies/extractions/ruby_middleware/middleware/runner.rb:67:in `block (2 levels) in build_call_chain'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `block in next'
+            #   # /gem/lib/convenient_service/support/cache.rb:110:in `fetch'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `next'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware.rb:73:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #   # ...
+            #
+            def call
+              message = backtrace.take(max_size).map { |line| Commands::FormatLine.call(line: line) }.join("\n")
+
+              message << "\n# ..." if backtrace.size > max_size
+
+              message
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/commands/format_cause.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module RescuesResultUnhandledExceptions
+        module Commands
+          class FormatCause < Support::Command
+            ##
+            # @!attribute [r] exception
+            #   @return [StandardError, nil]
+            #
+            attr_reader :cause
+
+            ##
+            # @param cause [StandardError]
+            # @return [void]
+            #
+            def initialize(cause:)
+              @cause = cause
+            end
+
+            ##
+            # @return [String]
+            #
+            # @note Cause formatting is inspired by RSpec. It has almost the same output (at least for RSpec 3).
+            #
+            # @example Cause.
+            #
+            #   ------------------
+            #   --- Caused by: ---
+            #   StandardError:
+            #     cause message
+            #   # /gem/lib/convenient_service/factories/service/class.rb:41:in `result'
+            #
+            def call
+              return "" unless cause
+
+              <<~MESSAGE.chomp
+                ------------------
+                --- Caused by: ---
+                #{cause.class}:
+                  #{cause.message}
+                #{formatted_cause_first_line}
+              MESSAGE
+            end
+
+            private
+
+            ##
+            # @return [String, nil]
+            #
+            # @internal
+            #   IMPORTANT: Sometimes `exception.backtrace` can be `nil`.
+            #   - https://blog.kalina.tech/2019/04/exception-without-backtrace-in-ruby.html
+            #   - https://github.com/jruby/jruby/issues/4467
+            #
+            def cause_first_line
+              return "" unless cause
+              return "" unless cause.backtrace
+
+              cause.backtrace.first
+            end
+
+            ##
+            # @return [String, nil]
+            #
+            def formatted_cause_first_line
+              return "" unless cause_first_line
+
+              Commands::FormatLine.call(line: cause_first_line)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/commands/format_exception.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module RescuesResultUnhandledExceptions
+        module Commands
+          class FormatException < Support::Command
+            ##
+            # @!attribute [r] exception
+            #   @return [StandardError]
+            #
+            attr_reader :exception
+
+            ##
+            # @!attribute [r] args
+            #   @return [StandardError]
+            #
+            attr_reader :args
+
+            ##
+            # @!attribute [r] kwargs
+            #   @return [StandardError]
+            #
+            attr_reader :kwargs
+
+            ##
+            # @!attribute [r] block
+            #   @return [StandardError]
+            #
+            attr_reader :block
+
+            ##
+            # @param exception [StandardError]
+            # @param args [Array]
+            # @param kwargs [Hash]
+            # @param block [Proc, nil]
+            # @return [void]
+            #
+            def initialize(exception:, args:, kwargs:, block:)
+              @exception = exception
+              @args = args
+              @kwargs = kwargs
+              @block = block
+            end
+
+            ##
+            # @return [String]
+            #
+            # @note Exceptions formatting is inspired by RSpec. It has almost the same output (at least for RSpec 3).
+            #
+            # @example Simple exception.
+            #
+            #   StandardError:
+            #     exception message
+            #   # /gem/lib/convenient_service/factories/services.rb:120:in `result'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `block in result'
+            #   # /gem/lib/convenient_service/dependencies/extractions/ruby_middleware/middleware/runner.rb:67:in `block (2 levels) in build_call_chain'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `block in next'
+            #   # /gem/lib/convenient_service/support/cache.rb:110:in `fetch'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `next'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware.rb:73:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #
+            # @example Exception with backtrace with more than 10 lines.
+            #
+            #   StandardError:
+            #     exception message
+            #   # /gem/lib/convenient_service/factories/services.rb:120:in `result'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `block in result'
+            #   # /gem/lib/convenient_service/dependencies/extractions/ruby_middleware/middleware/runner.rb:67:in `block (2 levels) in build_call_chain'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `block in next'
+            #   # /gem/lib/convenient_service/support/cache.rb:110:in `fetch'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `next'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware.rb:73:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #   # ...
+            #
+            # @example Exception with cause.
+            #
+            #   StandardError:
+            #     exception message
+            #   # /gem/lib/convenient_service/factories/service/class.rb:43:in `rescue in result'
+            #   # /gem/lib/convenient_service/factories/service/class.rb:40:in `result'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `call'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb:116:in `block in result'
+            #   # /gem/lib/convenient_service/dependencies/extractions/ruby_middleware/middleware/runner.rb:67:in `block (2 levels) in build_call_chain'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/chain.rb:35:in `next'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `block in next'
+            #   # /gem/lib/convenient_service/support/cache.rb:110:in `fetch'
+            #   # /gem/lib/convenient_service/common/plugins/caches_return_value/middleware.rb:17:in `next'
+            #   # /gem/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware.rb:73:in `call'
+            #   ------------------
+            #   --- Caused by: ---
+            #   StandardError:
+            #     cause message
+            #   # /gem/lib/convenient_service/factories/service/class.rb:41:in `result'
+            #
+            # @internal
+            #   TODO: Think about the following questions:
+            #   - How to format args, kwargs and block?
+            #   - Who should format them? The end-user or this plugin?
+            #
+            def call
+              <<~MESSAGE.rstrip
+                #{formatted_exception}
+                #{formatted_exception_backtrace}
+                #{formatted_exception_cause}
+              MESSAGE
+            end
+
+            private
+
+            ##
+            # @return [String]
+            #
+            def formatted_exception
+              <<~MESSAGE.chomp
+                #{exception.class}:
+                  #{exception.message}
+              MESSAGE
+            end
+
+            ##
+            # Formats exception backtrace. When backtrace has more then `max_backtrace_size` lines, the extra lines are trimmed.
+            # That is especially important for the monitoring system with the limited amount of memory, since it may too expensive to store the full backtrace all the time.
+            #
+            # @return [String]
+            #
+            # @internal
+            #   TODO: Add an ability to set `max_backtrace_size` while configuring the middleware. For example:
+            #
+            #     class Service
+            #       include ConvenientService::Standard::Config
+            #
+            #       middlewares :result, scope: :class do
+            #         use ConvenientService::Service::Plugins::RescuesResultUnhandledExceptions::Middleware, max_backtrace_size: 1_000
+            #       end
+            #
+            #       # ...
+            #     end
+            #
+            def formatted_exception_backtrace
+              Commands::FormatBacktrace.call(backtrace: exception.backtrace, max_size: max_backtrace_size)
+            end
+
+            ##
+            # @return [String]
+            #
+            def formatted_exception_cause
+              Commands::FormatCause.call(cause: exception.cause)
+            end
+
+            ##
+            # @return [Integer]
+            #
+            def max_backtrace_size
+              Constants::DEFAULT_MAX_BACKTRACE_SIZE
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/commands/format_line.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module RescuesResultUnhandledExceptions
+        module Commands
+          class FormatLine < Support::Command
+            ##
+            # @!attribute [r] line
+            #   @return [String]
+            #
+            attr_reader :line
+
+            ##
+            # @param line [String]
+            # @return [void]
+            #
+            def initialize(line:)
+              @line = line
+            end
+
+            ##
+            # @return [String]
+            #
+            # @note Exceptions formatting is inspired by RSpec. It has almost the same output (at least for RSpec 3).
+            #
+            # @example Line.
+            #
+            #   # /gem/lib/convenient_service/factories/services.rb:120:in `result'
+            #
+            def call
+              "# #{line}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/commands.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "commands/format_backtrace"
+require_relative "commands/format_cause"
+require_relative "commands/format_line"
+
+require_relative "commands/format_exception"

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/constants.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module RescuesResultUnhandledExceptions
+        module Constants
+          DEFAULT_MAX_BACKTRACE_SIZE = 10
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/middleware.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module RescuesResultUnhandledExceptions
+        class Middleware < Core::MethodChainMiddleware
+          ##
+          # @param args [Array]
+          # @param kwargs [Hash]
+          # @param block [Proc, nil]
+          # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+          #
+          # @internal
+          #   NOTE: `rescue => exception` is the same as `rescue ::StandardError => exception`.
+          #
+          #   IMPORTANT: Never rescue `Exception` since its direct descendants are used internally by Ruby, rescue `StandardError` instead.
+          #   - https://thoughtbot.com/blog/rescue-standarderror-not-exception
+          #   - https://stackoverflow.com/questions/10048173/why-is-it-bad-style-to-rescue-exception-e-in-ruby
+          #   - https://ruby-doc.org/core-2.7.0/Exception.html
+          #
+          def next(*args, **kwargs, &block)
+            chain.next(*args, **kwargs, &block)
+          rescue => exception
+            failure_result_from(exception, *args, **kwargs, &block)
+          end
+
+          private
+
+          ##
+          # @param exception [StandardError]
+          # @param args [Array]
+          # @param kwargs [Hash]
+          # @param block [Proc, nil]
+          # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+          #
+          def failure_result_from(exception, *args, **kwargs, &block)
+            entity.failure(
+              data: {exception: exception},
+              message: format_exception(exception, *args, **kwargs, &block)
+            )
+          end
+
+          ##
+          # @param exception [StandardError]
+          # @param args [Array]
+          # @param kwargs [Hash]
+          # @param block [Proc, nil]
+          # @return [String]
+          #
+          def format_exception(exception, *args, **kwargs, &block)
+            Commands::FormatException.call(exception: exception, args: args, kwargs: kwargs, block: block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "rescues_result_unhandled_exceptions/commands"
+require_relative "rescues_result_unhandled_exceptions/constants"
+require_relative "rescues_result_unhandled_exceptions/middleware"

data/lib/convenient_service/services/run_method_in_organizer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Services
+    class RunMethodInOrganizer
+      ##
+      # @internal
+      #   TODO: Reuse parent config?
+      #
+      include Configs::Standard
+
+      attr_reader :method_name, :organizer, :kwargs
+
+      def initialize(method_name:, organizer:, **kwargs)
+        @method_name = method_name
+        @organizer = organizer
+        @kwargs = kwargs
+      end
+
+      def result
+        ##
+        # NOTE: `kwargs` are intentionally NOT passed, since all the corresponding methods are available inside `organizer.__send__(method_name)` body.
+        #
+        organizer.__send__(method_name)
+      end
+    end
+  end
+end

data/lib/convenient_service/services/run_own_method_in_organizer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Services
+    class RunOwnMethodInOrganizer
+      module Errors
+        class MethodForStepIsNotDefined < ConvenientService::Error
+          def initialize(service_class:, method_name:)
+            message = <<~TEXT
+              Service #{service_class} tries to use `#{method_name}` method in a step, but it NOT defined.
+
+              Did you forget to define it?
+            TEXT
+
+            super(message)
+          end
+        end
+      end
+
+      ##
+      # @internal
+      #   TODO: Reuse parent config?
+      #
+      include Configs::Standard
+
+      attr_reader :method_name, :organizer, :kwargs
+
+      def initialize(method_name:, organizer:, **kwargs)
+        @method_name = method_name
+        @organizer = organizer
+        @kwargs = kwargs
+      end
+
+      def result
+        raise Errors::MethodForStepIsNotDefined.new(service_class: organizer.class, method_name: method_name) unless own_method
+
+        ##
+        # NOTE: `kwargs` are intentionally NOT passed, since all the corresponding methods are available inside `own_method` body.
+        #
+        own_method.call
+      end
+
+      private
+
+      ##
+      # @return [Method, nil]
+      #
+      # @internal
+      #   TODO: A possible bottleneck. Should be removed if receives negative feedback.
+      #
+      #   NOTE: `own_method.bind(organizer).call` is logically the same as `own_method.bind_call(organizer)`.
+      #   - https://ruby-doc.org/core-2.7.1/UnboundMethod.html#method-i-bind_call
+      #   - https://blog.saeloun.com/2019/10/17/ruby-2-7-adds-unboundmethod-bind_call-method.html
+      #
+      def own_method
+        method = Utils::Module.get_own_instance_method(organizer.class, method_name, private: true)
+
+        return unless method
+
+        method.bind(organizer)
+      end
+    end
+  end
+end

data/lib/convenient_service/{service/plugins/has_result_method_steps/services.rb → services.rb}

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
-require_relative "services/method_step_config"
 require_relative "services/run_own_method_in_organizer"
 require_relative "services/run_method_in_organizer"

data/lib/convenient_service/support/copyable.rb

@@ -20,8 +20,12 @@ module ConvenientService
       #   NOTE: This method is NOT likely to be ever changed, that is why inline logic is preferred over command classes in this particular case.
       #
       def copy(overrides: {})
-        overrides[:args] ||= {}
-        overrides[:kwargs] ||= {}
+        defaults = {args: {}, kwargs: {}}
+
+        ##
+        # IMPORTANT: Do not mutate `overrides`.
+        #
+        overrides = defaults.merge(overrides)
 
         ##
         # TODO: Refactor runtime `respond_to?`. Investigate before refactoring.

data/lib/convenient_service/support/dependency_container/errors.rb

@@ -56,7 +56,7 @@ module ConvenientService
             message = <<~TEXT
               Module `#{mod}` does NOT export method `#{method_name}` with `#{method_scope}` scope.
 
-              Did you forget to export if from `#{mod}`? For example:
+              Did you forget to export it from `#{mod}`? For example:
 
               module #{mod}
                 export #{method_name}, scope: :#{method_scope} do |*args, **kwargs, &block|

data/lib/convenient_service/support/not_passed.rb

@@ -2,6 +2,8 @@
 
 module ConvenientService
   module Support
-    NOT_PASSED = ::Object.new
+    NOT_PASSED = ::Object.new.tap do |object|
+      object.define_singleton_method(:inspect) { "not_passed" }
+    end
   end
 end

data/lib/convenient_service/support/undefined.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    UNDEFINED = ::Object.new.tap do |object|
+      object.define_singleton_method(:inspect) { "undefined" }
+    end
+  end
+end

data/lib/convenient_service/support.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "support/not_passed"
+require_relative "support/undefined"
+
 require_relative "support/concern"
 
 require_relative "support/abstract_method"

data/lib/convenient_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConvenientService
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/convenient_service.rb

@@ -30,6 +30,12 @@ require_relative "convenient_service/common"
 require_relative "convenient_service/service"
 require_relative "convenient_service/configs"
 
+##
+# @internal
+#   Convenient Service Predefined Services.
+#
+require_relative "convenient_service/services"
+
 ##
 # @internal
 #   Convenient Service Aliases.