convenient_service 0.11.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,10 +50,10 @@ 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 args [Array]
-                # @param block [Proc]
+                # @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]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L88
@@ -67,10 +71,10 @@ 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 args [Array]
-                # @param block [Proc]
+                # @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]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L97
@@ -82,9 +86,9 @@ module ConvenientService
                 end
 
                 ##
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
-                # @param args [Array]
-                # @param block [Proc]
+                # @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]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L104
@@ -96,9 +100,9 @@ module ConvenientService
                 end
 
                 ##
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
-                # @param args [Array]
-                # @param block [Proc]
+                # @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]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L111
@@ -110,10 +114,10 @@ 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 args [Array]
-                # @param block [Proc]
+                # @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]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L118
@@ -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,9 +141,9 @@ module ConvenientService
                 end
 
                 ##
-                # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
-                # @param args [Array]
-                # @param block [Proc]
+                # @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]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L76
@@ -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,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "entities/caller"
-require_relative "entities/chain"
 require_relative "entities/container"
-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]
             #
@@ -93,7 +93,7 @@ module ConvenientService
             #   NOTE: Consider to remove when support for Ruby 2.7 is dropped.
             #
             def resolve_super_method(entity)
-              klass.commit_config!
+              klass.commit_config!(trigger: Constants::Triggers::RESOLVE_METHOD_MIDDLEWARES_SUPER_METHOD)
 
               container.resolve_super_method(method, entity)
             end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Exceptions
+          class ConfigIsCommitted < ::ConvenientService::Exception
+            ##
+            # @param config [ConvenientService::Core::Entities::Config]
+            # @return [void]
+            #
+            def initialize(config:)
+              message = <<~TEXT
+                Config for `#{config.klass}` is already committed. Only uncommitted configs can be modified.
+
+                Did you accidentally call `concerns(&configuration_block)` or `middlewares(method, scope: scope, &configuration_block)` after using any plugin, after calling `commit_config!`?
+              TEXT
+
+              super(message)
+            end
+          end
+
+          class TooManyCommitsFromMethodMissing < ::ConvenientService::Exception
+            ##
+            # @param config [ConvenientService::Core::Entities::Config]
+            # @return [void]
+            #
+            # @internal
+            #   TODO: Create a troubleshooting page with possible reasons (preliminary RSpec mocks etc).
+            #   Append a link to it to the error message.
+            #
+            def initialize(config:)
+              message = <<~TEXT
+                `#{config.klass}` config is committed too many times from `method_missing`.
+
+                In order to resolve this issue try to commit it manually before usage of any config-dependent method.
+
+                Example 1 (outside class):
+
+                  # Commitment:
+                  #{config.klass}.commit_config!
+
+                  # Few lines later - usage:
+                  #{config.klass}.result # or whatever method.
+
+                Example 2 (inside class):
+
+                  class #{config.klass}
+                    # ...
+                    commit_config!
+
+                    step :result # or any other method that becomes available after config commitment.
+                  end
+              TEXT
+
+              super(message)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "config/commands"
 require_relative "config/entities"
-require_relative "config/errors"
+require_relative "config/exceptions"
 
 module ConvenientService
   module Core
@@ -57,13 +58,13 @@ module ConvenientService
         # @overload middlewares(method)
         #   Returns all instance middlewares for particular method.
         #   @param method [Symbol] Method name.
-        #   @return [Hash<Symbol, Hash<Symbol, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares>>]
+        #   @return [Hash{Symbol => Hash{Symbol => ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares}}]
         #
         # @overload middlewares(method, scope:)
         #   Returns all scoped middlewares for particular method.
         #   @param method [Symbol] Method name.
         #   @param scope [:instance, :class]
-        #   @return [Hash<Symbol, Hash<Symbol, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares>>]
+        #   @return [Hash{Symbol => Hash{Symbol => ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares}}]
         #
         # @overload middlewares(method, &configuration_block)
         #   Configures instance middlewares for particular method.
@@ -105,32 +106,54 @@ module ConvenientService
           @middlewares[scope][method] || Entities::MethodMiddlewares.new(scope: scope, method: method, klass: klass)
         end
 
+        ##
+        # @return [ConvenientService::Support::ThreadSafeCounter]
+        #
+        def method_missing_commits_counter
+          @method_missing_commits_counter ||= Support::ThreadSafeCounter.new(max_value: Constants::Commits::METHOD_MISSING_MAX_TRIES)
+        end
+
         ##
         # @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
 
         ##
         # Commits config when called for the first time.
         # Does nothing for the subsequent calls.
         #
+        # @param trigger [ConvenientService::Support::UniqueValue]
         # @return [Boolean] true if called for the first time, false otherwise (similarly as Kernel#require).
         #
         # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
         #
-        def commit!
-          concerns.include!
+        # @internal
+        #   IMPORTANT: `commit!` MUST be thread safe.
+        #
+        def commit!(trigger: Constants::Triggers::USER)
+          (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::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.
@@ -139,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,8 +1,8 @@
 # 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"
 
 require_relative "core/aliases"
@@ -11,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
@@ -42,3 +49,10 @@ require "rubygems"
 #   - https://github.com/ruby/singleton
 #
 require "singleton"
+
+##
+# @internal
+#   - https://ruby-doc.org/core-2.7.0/Mutex.html
+#   - https://docs.ruby-lang.org/en/2.1.0/Mutex.html
+#
+require "thread"