convenient_service 0.12.0 → 0.14.0

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "base/concern"
+require_relative "base/constants"
+require_relative "base/commands"
+require_relative "base/structs"
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Base
+                  include Concern
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Chain < Middlewares::Base
+                  module Commands
+                    class CreateObservableMiddleware < Support::Command
+                      ##
+                      # @!attribute [r] middleware
+                      #   @return [Class]
+                      #
+                      attr_reader :middleware
+
+                      ##
+                      # @param middleware [Class]
+                      # @return [void]
+                      #
+                      def initialize(middleware:)
+                        @middleware = middleware
+                      end
+
+                      ##
+                      # @return [Class]
+                      #
+                      def call
+                        ::Class.new(middleware) do
+                          class << self
+                            def chain_class
+                              ::Class.new(super) do
+                                def initialize(**kwargs)
+                                  arguments = Support::Arguments.new(**Utils::Hash.except(kwargs, [:middleware_events]))
+
+                                  @__middleware_events__ = kwargs[:middleware_events]
+
+                                  @__middleware_events__[:before_chain_initialize].notify_observers(arguments)
+
+                                  super(**arguments.kwargs)
+
+                                  @__middleware_events__[:after_chain_initialize].notify_observers(arguments)
+                                end
+
+                                def next(...)
+                                  arguments = Support::Arguments.new(...)
+
+                                  @__middleware_events__[:before_chain_next].notify_observers(arguments)
+
+                                  value = super
+
+                                  @__middleware_events__[:after_chain_next].notify_observers(value, arguments)
+
+                                  value
+                                end
+                              end
+                            end
+                          end
+
+                          def next(...)
+                            arguments = Support::Arguments.new(...)
+
+                            @__middleware_events__[:before_next].notify_observers(arguments)
+
+                            value = super
+
+                            @__middleware_events__[:after_next].notify_observers(value, arguments)
+
+                            value
+                          end
+
+                          def chain
+                            @__chain__ ||= self.class.chain_class.new(stack: @__stack__, middleware_events: @__middleware_events__)
+                          end
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "commands/create_observable_middleware"

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Chain < Middlewares::Base
+                  module Concern
+                    module ClassMethods
+                      ##
+                      # @return [Class]
+                      #
+                      def chain_class
+                        Entities::MethodChain
+                      end
+
+                      ##
+                      # @return [Class]
+                      #
+                      def to_observable_middleware
+                        Commands::CreateObservableMiddleware.call(middleware: super)
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Chain < Middlewares::Base
+                  module Concern
+                    module InstanceMethods
+                      include Support::AbstractMethod
+
+                      ##
+                      # @return [Object] Can be any type.
+                      # @raise [ConvenientService::Support::AbstractMethod::Exceptions::AbstractMethodNotOverridden] if NOT overridden in descendant.
+                      #
+                      # @example Subclass should call `value = chain.next(*args, **kwargs, &block)` to trigger next middleware in a stack.
+                      #   def next(*args, **kwargs, &block)
+                      #     # pre processing...
+                      #
+                      #     value = chain.next(*args, **kwargs, &block)
+                      #
+                      #     # post processing...
+                      #
+                      #     post_processed_value
+                      #   end
+                      #
+                      # @see https://refactoring.guru/design-patterns/decorator
+                      #
+                      # @note But it completely OK, to omit `chain.next(*args, **kwargs, &block)` completely.
+                      #   This way middleware stack is stopped in the "middle" and its "middle" value is returned.
+                      # @see https://refactoring.guru/design-patterns/proxy
+                      # @see https://refactoring.guru/design-patterns/chain-of-responsibility
+                      #
+                      abstract_method :next
+
+                      ##
+                      # @param env [Hash]
+                      # @return [Object] Can be any type.
+                      #
+                      def call(env)
+                        @__env__ = env
+
+                        ##
+                        # IMPORTANT: This is a library code. Do NOT do things like this in your application code.
+                        #
+                        chain.instance_variable_set(:@env, env)
+
+                        ##
+                        # NOTE: `__send__` is used since `next` is ruby keyword.
+                        # https://ruby-doc.org/core-2.7.0/doc/keywords_rdoc.html
+                        #
+                        # TODO: Enforce to always pass args, kwargs, block.
+                        #
+                        __send__(:next, *env[:args], **env[:kwargs], &env[:block])
+                      end
+
+                      ##
+                      # @return [Class, Object]
+                      #
+                      # @internal
+                      #   NOTE: `@__env__` is set inside `call`.
+                      #
+                      def entity
+                        @__env__[:entity]
+                      end
+
+                      ##
+                      # @return [Symbol]
+                      #
+                      # @note Fallback to avoid `if` conditions based on `method` value when possible, prefer to create separate middlewares instead.
+                      #
+                      # @internal
+                      #   NOTE: `@__env__` is set inside `call`.
+                      #
+                      def method
+                        @__env__[:method]
+                      end
+
+                      ##
+                      # @return [ConvenientService::Support::Arguments]
+                      #
+                      # @internal
+                      #   NOTE: `@__env__` is set inside `call`.
+                      #   NOTE: `@__env__[:args]` is set in `ConvenientService::Common::Plugins::NormalizesEnv::Middleware`.
+                      #
+                      def next_arguments
+                        return unless @__env__.has_key?(:args)
+
+                        @__next_arguments__ ||= Support::Arguments.new(*@__env__[:args], **@__env__[:kwargs], &@__env__[:block])
+                      end
+
+                      ##
+                      # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Chain]
+                      #
+                      # @internal
+                      #   NOTE: `@__env__` is set inside `call`.
+                      #
+                      def chain
+                        @__chain__ ||= self.class.chain_class.new(stack: @__stack__)
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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]