convenient_service 0.15.0 → 0.17.0

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/error/exceptions.rb

@@ -10,7 +10,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   Both `args` and `kwargs` are passed to the `error` method.
 
@@ -23,7 +23,7 @@ module ConvenientService
                   error(message: "Helpful text", code: :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
@@ -31,7 +31,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   `kwargs` passed to `error` method contain JSend keys and extra keys. That's NOT allowed.
 
@@ -61,12 +61,12 @@ module ConvenientService
                   error(data: {foo: :bar}, message: "foo", code: :foo)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
             class MoreThanTwoArgsArePassed < ::ConvenientService::Exception
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   More than two `args` are passed to the `error` method.
 
@@ -76,7 +76,7 @@ module ConvenientService
                   error("Helpful text", :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/error/middleware.rb

@@ -15,7 +15,7 @@ module ConvenientService
             # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
             #
             def next(*args, **kwargs, &block)
-              raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
+              ::ConvenientService.raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
 
               args.any? ? error_from_args : error_from_kwargs
             end
@@ -31,7 +31,7 @@ module ConvenientService
               when 1 then chain.next(message: next_arguments.args[0])
               when 2 then chain.next(message: next_arguments.args[0], code: next_arguments.args[1])
               else
-                raise Exceptions::MoreThanTwoArgsArePassed.new
+                ::ConvenientService.raise Exceptions::MoreThanTwoArgsArePassed.new
               end
             end
 
@@ -44,7 +44,7 @@ module ConvenientService
             def error_from_kwargs
               return chain.next(data: next_arguments.kwargs) if [:data, :message, :code].none? { |key| next_arguments.kwargs.has_key?(key) }
 
-              raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
+              ::ConvenientService.raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
 
               chain.next(**next_arguments.kwargs)
             end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/failure/exceptions.rb

@@ -10,7 +10,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   `kwargs` passed to `failure` method contain JSend keys and extra keys. That's NOT allowed.
 
@@ -40,7 +40,7 @@ module ConvenientService
                   failure(data: {foo: :bar}, message: "foo", code: :foo)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
@@ -48,7 +48,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   Both `args` and `kwargs` are passed to the `failure` method.
 
@@ -61,7 +61,7 @@ module ConvenientService
                   failure(message: "Helpful text", code: :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
@@ -69,7 +69,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   More than two `args` are passed to the `failure` method.
 
@@ -79,7 +79,7 @@ module ConvenientService
                   failure("Helpful text", :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/failure/middleware.rb

@@ -15,7 +15,7 @@ module ConvenientService
             # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
             #
             def next(*args, **kwargs, &block)
-              raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
+              ::ConvenientService.raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
 
               args.any? ? failure_from_args : failure_from_kwargs
             end
@@ -31,7 +31,7 @@ module ConvenientService
               when 1 then chain.next(message: next_arguments.args[0])
               when 2 then chain.next(message: next_arguments.args[0], code: next_arguments.args[1])
               else
-                raise Exceptions::MoreThanTwoArgsArePassed.new
+                ::ConvenientService.raise Exceptions::MoreThanTwoArgsArePassed.new
               end
             end
 
@@ -44,7 +44,7 @@ module ConvenientService
             def failure_from_kwargs
               return chain.next(data: next_arguments.kwargs) if [:data, :message, :code].none? { |key| next_arguments.kwargs.has_key?(key) }
 
-              raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
+              ::ConvenientService.raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
 
               chain.next(**next_arguments.kwargs)
             end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/commands/refute_kwargs_contain_j_send_and_extra_keys.rb

@@ -56,7 +56,7 @@ module ConvenientService
 
                 return if kwargs.keys.difference([:data, :message, :code]).none?
 
-                raise Exceptions::KwargsContainJSendAndExtraKeys.new
+                ::ConvenientService.raise Exceptions::KwargsContainJSendAndExtraKeys.new
               end
             end
           end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/exceptions.rb

@@ -10,7 +10,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   `kwargs` passed to `success` method contain JSend keys and extra keys. That's NOT allowed.
 
@@ -30,7 +30,7 @@ module ConvenientService
                   success(code: :foo)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end

data/lib/convenient_service/service/plugins/has_j_send_result_status_check_short_syntax/concern.rb

@@ -10,7 +10,6 @@ module ConvenientService
           class_methods do
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def success?(...)
               result(...).success?
@@ -18,7 +17,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def error?(...)
               result(...).error?
@@ -26,7 +24,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def failure?(...)
               result(...).failure?
@@ -34,7 +31,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def not_success?(...)
               result(...).not_success?
@@ -42,7 +38,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def not_error?(...)
               result(...).not_error?
@@ -50,7 +45,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def not_failure?(...)
               result(...).not_failure?
@@ -58,7 +52,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.12.0
             #
             def ok?(...)
               result(...).success?
@@ -66,7 +59,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.12.0
             #
             def not_ok?(...)
               result(...).not_success?

data/lib/convenient_service/service/plugins/has_result/concern.rb

@@ -23,7 +23,7 @@ module ConvenientService
             # @raise [ConvenientService::Service::Plugins::HasResult::Exceptions::ResultIsNotOverridden]
             #
             def result
-              raise Exceptions::ResultIsNotOverridden.new(service: self)
+              ::ConvenientService.raise Exceptions::ResultIsNotOverridden.new(service: self)
             end
           end
         end

data/lib/convenient_service/service/plugins/has_result/exceptions.rb

@@ -6,12 +6,12 @@ module ConvenientService
       module HasResult
         module Exceptions
           class ResultIsNotOverridden < ::ConvenientService::Exception
-            def initialize(service:)
+            def initialize_with_kwargs(service:)
               message = <<~TEXT
                 Result method (#result) of `#{service.class}` is NOT overridden.
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

data/lib/convenient_service/service/plugins/raises_on_double_result/exceptions.rb

@@ -6,7 +6,7 @@ module ConvenientService
       module RaisesOnDoubleResult
         module Exceptions
           class DoubleResult < ::ConvenientService::Exception
-            def initialize(service:)
+            def initialize_with_kwargs(service:)
               message = <<~TEXT
                 `#{service.class}` service has a double result.
 
@@ -24,7 +24,7 @@ module ConvenientService
                 end
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

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

@@ -48,7 +48,7 @@ module ConvenientService
           def refute_has_j_send_result!
             return unless entity.internals.cache.exist?(:has_j_send_result)
 
-            raise Exceptions::DoubleResult.new(service: entity)
+            ::ConvenientService.raise Exceptions::DoubleResult.new(service: entity)
           end
 
           ##

data/lib/convenient_service/service/plugins/raises_on_not_result_return_value/exceptions.rb

@@ -6,7 +6,7 @@ module ConvenientService
       module RaisesOnNotResultReturnValue
         module Exceptions
           class ReturnValueNotKindOfResult < ::ConvenientService::Exception
-            def initialize(service:, result:, method:)
+            def initialize_with_kwargs(service:, result:, method:)
               message = <<~TEXT
                 Return value of service `#{service.class}` is NOT a `Result`.
                 It is `#{result.class}`.
@@ -14,7 +14,7 @@ module ConvenientService
                 Did you forget to call `success`, `failure`, or `error` from the `:#{method}` method?
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

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

@@ -16,7 +16,7 @@ module ConvenientService
 
             return original_result if commands.is_result?(original_result)
 
-            raise Exceptions::ReturnValueNotKindOfResult.new(service: entity, result: original_result, method: method)
+            ::ConvenientService.raise Exceptions::ReturnValueNotKindOfResult.new(service: entity, result: original_result, method: method)
           end
         end
       end

data/lib/convenient_service/support/abstract_method/exceptions.rb

@@ -5,7 +5,7 @@ module ConvenientService
     module AbstractMethod
       module Exceptions
         class AbstractMethodNotOverridden < ::ConvenientService::Exception
-          def initialize(instance:, method:)
+          def initialize_with_kwargs(instance:, method:)
             klass = instance.is_a?(::Class) ? instance : instance.class
             method_type = Utils::Object.resolve_type(instance)
 
@@ -13,7 +13,7 @@ module ConvenientService
               `#{klass}` should implement abstract #{method_type} method `#{method}`.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end

data/lib/convenient_service/support/abstract_method.rb

@@ -11,7 +11,7 @@ module ConvenientService
         def abstract_method(*names)
           names.each do |name|
             define_method(name) do |*args, **kwargs, &block|
-              raise Exceptions::AbstractMethodNotOverridden.new(instance: self, method: name)
+              ::ConvenientService.raise Exceptions::AbstractMethodNotOverridden.new(instance: self, method: name)
             end
           end
         end

data/lib/convenient_service/support/backtrace_cleaner.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+##
+# @note Other gems are also trying to integrate with Rails Backtrace Cleaner.
+# @see https://github.com/sidekiq/sidekiq/pull/5796
+# @see https://github.com/sidekiq/sidekiq/issues/5589
+# @see https://github.com/appsignal/appsignal-ruby/issues/380
+#
+module ConvenientService
+  module Support
+    ##
+    # Rails v7.1.2 Backtrace Cleaner descendant.
+    # Has Convenient Service specific silencer - `add_convenient_service_silencer`.
+    # By default, it uses only `add_stdlib_silencer` and `add_convenient_service_silencer`.
+    #
+    # @see https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html
+    # @see https://medium.com/one-medical-technology/filtering-ruby-backtraces-for-debugging-4df75133ab71
+    # @see https://twitter.com/websebdev/status/1375831554518360065?ref_src=twsrc%5Etfw%7Ctwcamp%5Etweetembed%7Ctwterm%5E1375831554518360065%7Ctwgr%5E459595174e71c0f1aa3826c89f2ffca0c3da6ea3%7Ctwcon%5Es1_&ref_url=https%3A%2F%2Fwww.redditmedia.com%2Fmediaembed%2Fmegii9%2F%3Fresponsive%3Dtrueis_nightmode%3Dtrue
+    # @see https://stackoverflow.com/questions/22727219/using-backtracecleaner-in-rails-console
+    #
+    class BacktraceCleaner < Dependencies::Extractions::ActiveSupportBacktraceCleaner::BacktraceCleaner
+      ##
+      # @return [void]
+      #
+      # @note `ConvenientService::Support::BacktraceCleaner` intentionally does NOT exclude external gems lines from backtrace.
+      #
+      # @see https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L34
+      #
+      # @internal
+      #   IMPORTANT: Convenient Service integrates with external gems.
+      #   This means that external gems exceptions should NOT be considered as Convenient Service internal exceptions.
+      #
+      def initialize(...)
+        super
+
+        remove_filters!
+        remove_silencers!
+
+        ##
+        # NOTE: Uses `::RbConfig` to resolve stdlib directory.
+        # - https://idiosyncratic-ruby.com/42-ruby-config.html
+        # - https://github.com/ruby/ruby/blob/master/tool/mkconfig.rb
+        #
+        add_stdlib_silencer
+
+        ##
+        # NOTE:
+        #
+        add_convenient_service_silencer
+      end
+
+      ##
+      # @note `add_gem_filter` is made public to have a way to bring back Rails Backtrace Cleaner default behavior if necessary.
+      #
+      # @return [void]
+      #
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L110
+      #
+      public :add_gem_filter
+
+      ##
+      # @note `add_gem_silencer` is made public to have a way to bring back Rails Backtrace Cleaner default behavior if necessary.
+      #
+      # @return [void]
+      #
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L119
+      #
+      public :add_gem_silencer
+
+      ##
+      # @note `add_stdlib_silencer` is made public to allow the end-user to adjust clean in any way.
+      #
+      # @return [void]
+      #
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L123
+      #
+      public :add_stdlib_silencer
+
+      ##
+      # Since Convenient Service is using middleware chains under the hood, exception backtraces may be huge.
+      # As a consequence, it takes too much time during the debugging process to find the application line of code that causes the exception.
+      # This silencer removes all Convenient Service lines from backtraces.
+      #
+      # @note To bring back Convenient Service lines to backtraces, use the `remove_silencers` or check the `CleansExceptionBacktrace` plugin.
+      #
+      # @return [void]
+      #
+      def add_convenient_service_silencer
+        add_silencer { |line| line.start_with?(::ConvenientService.root.to_s) && !line.start_with?(::ConvenientService.examples_root.to_s) }
+      end
+
+      ##
+      # Works exactly in the same way as the original `clean`, except it falls back to the original backtrace in case of any exceptions inside filters or silencers.
+      # Also returns an empty array, when `backtrace` is `nil`.
+      #
+      # @return [Array<String>]
+      #
+      # @see https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html#method-i-clean
+      #
+      # @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 clean(backtrace, *args)
+        if backtrace.nil?
+          ::ConvenientService.logger.warn { "[BacktraceCleaner] `nil` backtrace | Empty array is used as fallback" }
+
+          return []
+        end
+
+        begin
+          super
+        rescue
+          ::ConvenientService.logger.warn { "[BacktraceCleaner] Some filter or silencer is broken | Original backtrace is used as fallback" }
+
+          backtrace
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/cache/exceptions.rb

@@ -9,14 +9,14 @@ module ConvenientService
           # @param backend [Symbol]
           # @return [void]
           #
-          def initialize(backend:)
+          def initialize_with_kwargs(backend:)
             message = <<~TEXT
               Backend `#{backend}` is NOT supported.
 
               Supported backends are #{printable_backends}.
             TEXT
 
-            super(message)
+            initialize(message)
           end
 
           private

data/lib/convenient_service/support/cache.rb

@@ -21,7 +21,7 @@ module ConvenientService
           when Constants::Backends::THREAD_SAFE_ARRAY
             Entities::Caches::ThreadSafeArray.new
           else
-            raise Exceptions::NotSupportedBackend.new(backend: backend)
+            ::ConvenientService.raise Exceptions::NotSupportedBackend.new(backend: backend)
           end
         end
       end

data/lib/convenient_service/support/castable/exceptions.rb

@@ -5,22 +5,22 @@ module ConvenientService
     module Castable
       module Exceptions
         class CastIsNotOverridden < ::ConvenientService::Exception
-          def initialize(klass:)
+          def initialize_with_kwargs(klass:)
             message = <<~TEXT
               Cast method (.cast) of `#{klass}` is NOT overridden.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
 
         class FailedToCast < ::ConvenientService::Exception
-          def initialize(other:, klass:)
+          def initialize_with_kwargs(other:, klass:)
             message = <<~TEXT
               Failed to cast `#{other.inspect}` into `#{klass}`.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end

data/lib/convenient_service/support/castable.rb

@@ -34,7 +34,7 @@ module ConvenientService
         def cast!(other, **options)
           casted = cast(other, **options)
 
-          raise Exceptions::FailedToCast.new(other: other, klass: self) unless casted
+          ::ConvenientService.raise Exceptions::FailedToCast.new(other: other, klass: self) unless casted
 
           casted
         end

data/lib/convenient_service/support/command.rb

@@ -8,12 +8,12 @@ module ConvenientService
     class Command
       module Exceptions
         class CallIsNotOverridden < ::ConvenientService::Exception
-          def initialize(command:)
+          def initialize_with_kwargs(command:)
             message = <<~TEXT
               Call method (#call) of `#{command.class}` is NOT overridden.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end
@@ -57,7 +57,7 @@ module ConvenientService
       # @raise [ConvenientService::Support::Command::Exceptions::CallIsNotOverridden]
       #
       def call
-        raise Exceptions::CallIsNotOverridden.new(command: self)
+        ::ConvenientService.raise Exceptions::CallIsNotOverridden.new(command: self)
       end
     end
   end

data/lib/convenient_service/support/counter.rb

@@ -19,7 +19,7 @@ module ConvenientService
           # @param max_value [Integer]
           # @return [void]
           #
-          def initialize(n:, current_value:, max_value:)
+          def initialize_with_kwargs(n:, current_value:, max_value:)
             message = <<~TEXT
               Value after increment by `#{n}` is greater than the max value.
 
@@ -28,7 +28,7 @@ module ConvenientService
               Max value is `#{max_value}`.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
 
@@ -39,7 +39,7 @@ module ConvenientService
           # @param min_value [Integer]
           # @return [void]
           #
-          def initialize(n:, current_value:, min_value:)
+          def initialize_with_kwargs(n:, current_value:, min_value:)
             message = <<~TEXT
               Value after decrement by `#{n}` is lower than the min value.
 
@@ -48,7 +48,7 @@ module ConvenientService
               Min value is `#{min_value}`.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end
@@ -123,7 +123,7 @@ module ConvenientService
       #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save-21
       #
       def increment!(n = 1)
-        raise Exceptions::ValueAfterIncrementIsGreaterThanMaxValue.new(n: n, current_value: @current_value, max_value: @max_value) if @current_value + n > @max_value
+        ::ConvenientService.raise Exceptions::ValueAfterIncrementIsGreaterThanMaxValue.new(n: n, current_value: @current_value, max_value: @max_value) if @current_value + n > @max_value
 
         @current_value += n
       end
@@ -176,7 +176,7 @@ module ConvenientService
       #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save-21
       #
       def decrement!(n = 1)
-        raise Exceptions::ValueAfterDecrementIsLowerThanMinValue.new(n: n, current_value: @current_value, min_value: @min_value) if @current_value - n < @min_value
+        ::ConvenientService.raise Exceptions::ValueAfterDecrementIsLowerThanMinValue.new(n: n, current_value: @current_value, min_value: @min_value) if @current_value - n < @min_value
 
         @current_value -= n
       end

data/lib/convenient_service/support/dependency_container/commands/assert_valid_container.rb

@@ -24,7 +24,7 @@ module ConvenientService
           # @raise [ConvenientService::Support::DependencyContainer::Exceptions::NotExportableModule]
           #
           def call
-            raise Exceptions::NotExportableModule.new(mod: container) unless Utils::Module.include_module?(container, DependencyContainer::Export)
+            ::ConvenientService.raise Exceptions::NotExportableModule.new(mod: container) unless Utils::Module.include_module?(container, DependencyContainer::Export)
           end
         end
       end

data/lib/convenient_service/support/dependency_container/commands/assert_valid_method.rb

@@ -40,7 +40,7 @@ module ConvenientService
           # @raise [ConvenientService::Support::DependencyContainer::Exceptions::NotExportedMethod]
           #
           def call
-            raise Exceptions::NotExportedMethod.new(method_name: slug, method_scope: scope, mod: container) unless method
+            ::ConvenientService.raise Exceptions::NotExportedMethod.new(method_name: slug, method_scope: scope, mod: container) unless method
           end
 
           private

data/lib/convenient_service/support/dependency_container/commands/assert_valid_scope.rb

@@ -24,7 +24,7 @@ module ConvenientService
           # @raise [ConvenientService::Support::DependencyContainer::Exceptions::InvalidScope]
           #
           def call
-            raise Exceptions::InvalidScope.new(scope: scope) unless Constants::SCOPES.include?(scope)
+            ::ConvenientService.raise Exceptions::InvalidScope.new(scope: scope) unless Constants::SCOPES.include?(scope)
           end
         end
       end