convenient_service 0.12.0 → 0.13.0

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/chain/concern.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "concern/class_methods"
+require_relative "concern/instance_methods"
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Chain < Middlewares::Base
+                  module Concern
+                    include Support::Concern
+
+                    included do |middleware_class|
+                      middleware_class.include InstanceMethods
+
+                      middleware_class.extend ClassMethods
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/chain/entities/method_chain.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                ##
+                # @abstract Subclass and override `#next`.
+                #
+                # @internal
+                #   NOTE: Do NOT pollute the interface of this class until really needed.
+                #   Avoid even pollution of private methods.
+                #   This way there is a lower risk that a plugin developer accidentally overwrites an internal middleware behavior.
+                #   https://github.com/Ibsciss/ruby-middleware#a-basic-example
+                #
+                class Chain < Middlewares::Base
+                  module Entities
+                    ##
+                    # @internal
+                    #   NOTE: Do NOT pollute the interface of this class until really needed.
+                    #
+                    class MethodChain
+                      ##
+                      # @param stack [#call<Hash>]
+                      # @param env [Hash]
+                      # @return [void]
+                      #
+                      def initialize(stack:, env: {})
+                        @stack = stack
+                        @env = env
+                      end
+
+                      ##
+                      # @param args [Array<Object>]
+                      # @param kwargs [Hash{Symbol => Object}]
+                      # @param block [Proc, nil]
+                      # @return [Object] Can be any type.
+                      #
+                      # @internal
+                      #   TODO: Enforce to always pass args, kwargs, block.
+                      #
+                      def next(*args, **kwargs, &block)
+                        stack.call(env.merge(args: args, kwargs: kwargs, block: block))
+                      end
+
+                      ##
+                      # @param other [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Chain, Object]
+                      # @return [Boolean]
+                      #
+                      def ==(other)
+                        return unless other.instance_of?(self.class)
+
+                        return false if stack != other.stack
+                        return false if env != other.env
+
+                        true
+                      end
+
+                      protected
+
+                      ##
+                      # @!attribute [r] stack
+                      #   @return [#call<Hash>]
+                      #
+                      attr_reader :stack
+
+                      ##
+                      # @!attribute [r] env
+                      #   @return [Hash]
+                      #
+                      attr_reader :env
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/chain/entities.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "entities/method_chain"

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/chain.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "chain/commands"
+require_relative "chain/concern"
+require_relative "chain/entities"
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                ##
+                # @abstract Subclass and override `#next`.
+                #
+                # @internal
+                #   NOTE: Do NOT pollute the interface of this class until really needed.
+                #   Avoid even pollution of private methods.
+                #   This way there is a lower risk that a plugin developer accidentally overwrites an internal middleware behavior.
+                #   https://github.com/Ibsciss/ruby-middleware#a-basic-example
+                #
+                class Chain < Middlewares::Base
+                  include Concern
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/classic.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                ##
+                # @abstract Subclass and override `#call`.
+                #
+                # @internal
+                #   NOTE: Do NOT pollute the interface of this class until really needed.
+                #   Avoid even pollution of private methods.
+                #   This way there is a lower risk that a plugin developer accidentally overwrites an internal middleware behavior.
+                #   https://github.com/Ibsciss/ruby-middleware#a-basic-example
+                #
+                class Classic < Middlewares::Base
+                  ##
+                  # @return [Object] Can be any type.
+                  #
+                  def call(env)
+                    stack.call(env)
+                  end
+
+                  ##
+                  # @return [#call<Hash>]
+                  #
+                  def stack
+                    @__stack__
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "middlewares/base"
+
+require_relative "middlewares/classic"
+require_relative "middlewares/chain"

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/stack.rb

@@ -7,6 +7,10 @@ module ConvenientService
         module Entities
           class MethodMiddlewares
             module Entities
+              ##
+              # @internal
+              #   TODO: Better error explanations.
+              #
               class Stack
                 ##
                 # @overload initialize(name:)
@@ -46,8 +50,8 @@ module ConvenientService
                 end
 
                 ##
-                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param args [Array<Object>]
                 # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
@@ -67,8 +71,8 @@ module ConvenientService
                 alias_method :insert_before, :insert
 
                 ##
-                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param args [Array<Object>]
                 # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
@@ -82,7 +86,7 @@ module ConvenientService
                 end
 
                 ##
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param args [Array<Object>]
                 # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
@@ -96,7 +100,7 @@ module ConvenientService
                 end
 
                 ##
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param args [Array<Object>]
                 # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
@@ -110,8 +114,8 @@ module ConvenientService
                 end
 
                 ##
-                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param args [Array<Object>]
                 # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
@@ -125,7 +129,7 @@ module ConvenientService
                 end
 
                 ##
-                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L126
@@ -137,7 +141,7 @@ module ConvenientService
                 end
 
                 ##
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param args [Array<Object>]
                 # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
@@ -150,6 +154,37 @@ module ConvenientService
                   self
                 end
 
+                ##
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
+                # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+                #
+                # @note `observe` exists only for testing purposes. Do NOT use it in production code.
+                #
+                # @internal
+                #   TODO: Raise if middleware is NOT used yet.
+                #
+                def observe(middleware, *args, &block)
+                  plain_stack.replace(middleware, middleware.observable, *args, &block)
+
+                  self
+                end
+
+                ##
+                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
+                # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+                #
+                # @note `use_and_observe` exists only for testing purposes. Do NOT use it in production code.
+                #
+                def use_and_observe(middleware, *args, &block)
+                  plain_stack.use(middleware.observable, *args, &block)
+
+                  self
+                end
+
                 ##
                 # @return [Boolean]
                 #
@@ -170,7 +205,7 @@ module ConvenientService
                 end
 
                 ##
-                # @return [Array<ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware>]
+                # @return [Array<ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base>]
                 #
                 def to_a
                   plain_stack.to_a

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "entities/caller"
-require_relative "entities/chain"
 require_relative "entities/container"
-require_relative "entities/middleware_creator"
-require_relative "entities/middleware"
+require_relative "entities/middleware_creators"
+require_relative "entities/middlewares"
 require_relative "entities/stack"

data/lib/convenient_service/core/entities/config/entities/method_middlewares.rb

@@ -63,7 +63,7 @@ module ConvenientService
             end
 
             ##
-            # @note: Works in a similar way as `Kernel.require`.
+            # @note Works in a similar way as `Kernel.require`.
             #
             # @return [Boolean]
             #

data/lib/convenient_service/core/entities/config/{errors.rb → exceptions.rb}

@@ -4,8 +4,8 @@ module ConvenientService
   module Core
     module Entities
       class Config
-        module Errors
-          class ConfigIsCommitted < ::ConvenientService::Error
+        module Exceptions
+          class ConfigIsCommitted < ::ConvenientService::Exception
             ##
             # @param config [ConvenientService::Core::Entities::Config]
             # @return [void]
@@ -21,7 +21,7 @@ module ConvenientService
             end
           end
 
-          class TooManyCommitsFromMethodMissing < ::ConvenientService::Error
+          class TooManyCommitsFromMethodMissing < ::ConvenientService::Exception
             ##
             # @param config [ConvenientService::Core::Entities::Config]
             # @return [void]

data/lib/convenient_service/core/entities/config.rb

@@ -2,7 +2,7 @@
 
 require_relative "config/commands"
 require_relative "config/entities"
-require_relative "config/errors"
+require_relative "config/exceptions"
 
 module ConvenientService
   module Core
@@ -116,8 +116,18 @@ module ConvenientService
         ##
         # @return [Boolean]
         #
+        # @internal
+        #   IMPORTANT:
+        #     - Memoization of only `true` is intentional.
+        #     - It is done for performance purposes.
+        #     - It is OK to memoize only `true` since "uncommitment" of config is even theoretically NOT possible.
+        #     - It is NOT possible to uninclude Ruby modules.
+        #     - See `benchmark/has_committed_config/ips.rb`.
+        #
+        #   IMPORTANT: `committed?` MUST be thread safe.
+        #
         def committed?
-          concerns.included?
+          @committed ||= concerns.included?
         end
 
         ##
@@ -129,18 +139,21 @@ module ConvenientService
         #
         # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
         #
+        # @internal
+        #   IMPORTANT: `commit!` MUST be thread safe.
+        #
         def commit!(trigger: Constants::Triggers::USER)
-          concerns.include!
+          (committed? ? false : concerns.include!)
             .tap { Commands::TrackMethodMissingCommitTrigger.call(config: self, trigger: trigger) }
         end
 
         private
 
         ##
-        # @note: Config is committed either by `commit_config` or `method_missing` from `ConvenientService::Core::InstanceMethods` and `ConvenientService::Core::ClassMethods`.
+        # @note Config is committed either by `commit_config` or `method_missing` from `ConvenientService::Core::InstanceMethods` and `ConvenientService::Core::ClassMethods`.
         #
         # @return [void]
-        # @raise [ConvenientService::Core::Entities::Config::Errors::ConfigIsCommitted]
+        # @raise [ConvenientService::Core::Entities::Config::Exceptions::ConfigIsCommitted]
         #
         # @internal
         #   NOTE: Concerns must be included only once since Ruby does NOT allow to modify the order of modules in the inheritance chain.
@@ -149,7 +162,7 @@ module ConvenientService
         def assert_not_committed!
           return unless committed?
 
-          raise Errors::ConfigIsCommitted.new(config: self)
+          raise Exceptions::ConfigIsCommitted.new(config: self)
         end
       end
     end

data/lib/convenient_service/core/entities.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
-require_relative "entities/classic_middleware"
 require_relative "entities/config"

data/lib/convenient_service/core.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "core/instance_methods"
-require_relative "core/class_methods"
+require_relative "core/concern"
 
 require_relative "core/constants"
 require_relative "core/entities"
@@ -12,9 +11,12 @@ module ConvenientService
   module Core
     include Support::Concern
 
-    included do |service_class|
-      service_class.include InstanceMethods
-      service_class.extend ClassMethods
+    ##
+    # @internal
+    #   TODO: Allow to include `Core` only to classes?
+    #
+    included do |entity_class|
+      entity_class.include Concern
     end
   end
 end

data/lib/convenient_service/dependencies/built_in.rb

@@ -5,7 +5,7 @@
 #
 # @internal
 #   https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
-#
+##
 
 ##
 # @internal
@@ -14,6 +14,13 @@
 #
 require "forwardable"
 
+##
+# @internal
+#   - https://ruby-doc.org/stdlib-2.7.0/libdoc/erb/rdoc/ERB.html
+#   - https://github.com/ruby/erb
+#
+require "erb"
+
 ##
 # @internal
 #   - https://ruby-doc.org/stdlib-2.7.0/libdoc/logger/rdoc/Logger.html
@@ -23,10 +30,10 @@ require "logger"
 
 ##
 # @internal
-#   - https://ruby-doc.org/stdlib-2.7.0/libdoc/ostruct/rdoc/OpenStruct.html
-#   - https://github.com/ruby/ostruct
+#   - https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html
+#   - https://github.com/ruby/observer
 #
-require "ostruct"
+require "observer"
 
 ##
 # @internal

data/lib/convenient_service/dependencies/extractions/active_support_backtrace_cleaner/backtrace_cleaner.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Dependencies
+    module Extractions
+      ##
+      # @internal
+      #   NOTE:
+      #     Copied from `rails/rails` without any logic modification.
+      #     Version: v7.0.4.3.
+      #     Wrapped in a namespace `ConvenientService::Dependencies::Extractions::ActiveSupportBacktraceCleaner`.
+      #
+      #   - https://api.rubyonrails.org/v7.0.4.3/classes/ActiveSupport/BacktraceCleaner.html
+      #   - https://github.com/rails/rails/blob/v7.0.4.3/activesupport/lib/active_support/backtrace_cleaner.rb
+      #   - https://github.com/marian13/rails/blob/main/activesupport/lib/active_support/backtrace_cleaner.rb
+      #   - https://github.com/rails/rails
+      #
+      module ActiveSupportBacktraceCleaner
+        # Backtraces often include many lines that are not relevant for the context
+        # under review. This makes it hard to find the signal amongst the backtrace
+        # noise, and adds debugging time. With a BacktraceCleaner, filters and
+        # silencers are used to remove the noisy lines, so that only the most relevant
+        # lines remain.
+        #
+        # Filters are used to modify lines of data, while silencers are used to remove
+        # lines entirely. The typical filter use case is to remove lengthy path
+        # information from the start of each line, and view file paths relevant to the
+        # app directory instead of the file system root. The typical silencer use case
+        # is to exclude the output of a noisy library from the backtrace, so that you
+        # can focus on the rest.
+        #
+        #   bc = ActiveSupport::BacktraceCleaner.new
+        #   bc.add_filter   { |line| line.gsub(Rails.root.to_s, '') } # strip the Rails.root prefix
+        #   bc.add_silencer { |line| /puma|rubygems/.match?(line) } # skip any lines from puma or rubygems
+        #   bc.clean(exception.backtrace) # perform the cleanup
+        #
+        # To reconfigure an existing BacktraceCleaner (like the default one in Rails)
+        # and show as much data as possible, you can always call
+        # BacktraceCleaner#remove_silencers!, which will restore the
+        # backtrace to a pristine state. If you need to reconfigure an existing
+        # BacktraceCleaner so that it does not filter or modify the paths of any lines
+        # of the backtrace, you can call BacktraceCleaner#remove_filters!
+        # These two methods will give you a completely untouched backtrace.
+        #
+        # Inspired by the Quiet Backtrace gem by thoughtbot.
+        class BacktraceCleaner
+          def initialize
+            @filters, @silencers = [], []
+            add_gem_filter
+            add_gem_silencer
+            add_stdlib_silencer
+          end
+
+          # Returns the backtrace after all filters and silencers have been run
+          # against it. Filters run first, then silencers.
+          def clean(backtrace, kind = :silent)
+            filtered = filter_backtrace(backtrace)
+
+            case kind
+            when :silent
+              silence(filtered)
+            when :noise
+              noise(filtered)
+            else
+              filtered
+            end
+          end
+          alias :filter :clean
+
+          # Adds a filter from the block provided. Each line in the backtrace will be
+          # mapped against this filter.
+          #
+          #   # Will turn "/my/rails/root/app/models/person.rb" into "/app/models/person.rb"
+          #   backtrace_cleaner.add_filter { |line| line.gsub(Rails.root, '') }
+          def add_filter(&block)
+            @filters << block
+          end
+
+          # Adds a silencer from the block provided. If the silencer returns +true+
+          # for a given line, it will be excluded from the clean backtrace.
+          #
+          #   # Will reject all lines that include the word "puma", like "/gems/puma/server.rb" or "/app/my_puma_server/rb"
+          #   backtrace_cleaner.add_silencer { |line| /puma/.match?(line) }
+          def add_silencer(&block)
+            @silencers << block
+          end
+
+          # Removes all silencers, but leaves in the filters. Useful if your
+          # context of debugging suddenly expands as you suspect a bug in one of
+          # the libraries you use.
+          def remove_silencers!
+            @silencers = []
+          end
+
+          # Removes all filters, but leaves in the silencers. Useful if you suddenly
+          # need to see entire filepaths in the backtrace that you had already
+          # filtered out.
+          def remove_filters!
+            @filters = []
+          end
+
+          private
+            FORMATTED_GEMS_PATTERN = /\A[^\/]+ \([\w.]+\) /
+
+            def add_gem_filter
+              gems_paths = (Gem.path | [Gem.default_dir]).map { |p| Regexp.escape(p) }
+              return if gems_paths.empty?
+
+              gems_regexp = %r{\A(#{gems_paths.join('|')})/(bundler/)?gems/([^/]+)-([\w.]+)/(.*)}
+              gems_result = '\3 (\4) \5'
+              add_filter { |line| line.sub(gems_regexp, gems_result) }
+            end
+
+            def add_gem_silencer
+              add_silencer { |line| FORMATTED_GEMS_PATTERN.match?(line) }
+            end
+
+            def add_stdlib_silencer
+              add_silencer { |line| line.start_with?(RbConfig::CONFIG["rubylibdir"]) }
+            end
+
+            def filter_backtrace(backtrace)
+              @filters.each do |f|
+                backtrace = backtrace.map { |line| f.call(line) }
+              end
+
+              backtrace
+            end
+
+            def silence(backtrace)
+              @silencers.each do |s|
+                backtrace = backtrace.reject { |line| s.call(line) }
+              end
+
+              backtrace
+            end
+
+            def noise(backtrace)
+              backtrace.select do |line|
+                @silencers.any? do |s|
+                  s.call(line)
+                end
+              end
+            end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/dependencies/extractions/active_support_backtrace_cleaner.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+##
+# @internal
+#   NOTE:
+#     Copied from `rails/rails` without any logic modification.
+#     Version: v7.0.4.3.
+#     Wrapped in a namespace `ConvenientService::Dependencies::Extractions::ActiveSupportBacktraceCleaner`.
+#
+#   - https://api.rubyonrails.org/v7.0.4.3/classes/ActiveSupport/BacktraceCleaner.html
+#   - https://github.com/rails/rails/blob/v7.0.4.3/activesupport/lib/active_support/backtrace_cleaner.rb
+#   - https://github.com/marian13/rails/blob/main/activesupport/lib/active_support/backtrace_cleaner.rb
+#   - https://github.com/rails/rails
+#
+require_relative "active_support_backtrace_cleaner/backtrace_cleaner"