convenient_service 0.12.0 → 0.13.0

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Base
+                  module Commands
+                    class CreateObservableMiddleware < Support::Command
+                      ##
+                      # @!attribute [r] middleware
+                      #   @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                      #
+                      attr_reader :middleware
+
+                      ##
+                      # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                      # @return [void]
+                      #
+                      def initialize(middleware:)
+                        @middleware = middleware
+                      end
+
+                      ##
+                      # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                      #
+                      def call
+                        observable_middleware.class_exec(middleware) do |middleware|
+                          ##
+                          # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                          #
+                          define_singleton_method(:middleware) { middleware }
+
+                          ##
+                          # @param other [Object] Can be any type.
+                          # @return [Boolean, nil]
+                          #
+                          define_singleton_method(:==) { |other| self.middleware == other.middleware if other.respond_to?(:middleware) }
+
+                          ##
+                          # @return [String]
+                          #
+                          define_singleton_method(:inspect) { "Observable(#{middleware})" }
+                        end
+
+                        observable_middleware
+                      end
+
+                      private
+
+                      ##
+                      # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                      #
+                      def observable_middleware
+                        @observable_middleware ||=
+                          ::Class.new(middleware) do
+                            ##
+                            # @param stack [#call<Hash>]
+                            # @param kwargs [Hash{Symbol => Object}]
+                            # @return [void]
+                            #
+                            def initialize(stack, **kwargs)
+                              arguments = Support::Arguments.new(stack, **Utils::Hash.except(kwargs, [:middleware_events]))
+
+                              @__middleware_events__ = kwargs[:middleware_events]
+
+                              @__middleware_events__[:before_initialize].notify_observers(arguments)
+
+                              super(stack, **arguments.kwargs)
+
+                              @__middleware_events__[:after_initialize].notify_observers(arguments)
+                            end
+
+                            ##
+                            # @return [Object] Can be any type.
+                            #
+                            def call(...)
+                              arguments = Support::Arguments.new(...)
+
+                              @__middleware_events__[:before_call].notify_observers(arguments)
+
+                              value = super
+
+                              @__middleware_events__[:after_call].notify_observers(value, arguments)
+
+                              value
+                            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/base/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/base/concern/class_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
+                ##
+                # @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 Base
+                  module Concern
+                    module ClassMethods
+                      ##
+                      # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::MiddlewareCreators::With]
+                      #
+                      def with(...)
+                        Entities::MiddlewareCreators::With.new(middleware: self, middleware_arguments: Support::Arguments.new(...))
+                      end
+
+                      ##
+                      # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::MiddlewareCreators::Observable]
+                      #
+                      def observable
+                        Entities::MiddlewareCreators::Observable.new(middleware: self)
+                      end
+
+                      ##
+                      # @return [Hash{Symbol => Object}]
+                      #
+                      def extra_kwargs
+                        {}
+                      end
+
+                      ##
+                      # @return [Array<ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Structs::IntendedMethod>]
+                      #
+                      # @internal
+                      #   TODO: Consider to wrap with `WeakRef` to reduce memory consumption.
+                      #
+                      def intended_methods
+                        @intended_methods ||= []
+                      end
+
+                      ##
+                      # @return [Class]
+                      #
+                      def to_observable_middleware
+                        Commands::CreateObservableMiddleware.call(middleware: self)
+                      end
+
+                      private
+
+                      ##
+                      # @param method [Symbol]
+                      # @param scope [Symbol, ConvenientService::Support::UniqueValue]
+                      # @param entity [Symbol, ConvenientService::Support::UniqueValue]
+                      # @return [Array<ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Structs::IntendedMethod>]
+                      #
+                      # @internal
+                      #   TODO: Direct specs.
+                      #
+                      def intended_for(method, entity:, scope: :instance)
+                        intended_methods << Structs::IntendedMethod.new(method, scope, entity)
+                      end
+
+                      ##
+                      # @return [ConvenientService::Support::UniqueValue]
+                      #
+                      # @internal
+                      #   TODO: Direct specs.
+                      #
+                      def any_method
+                        Constants::ANY_METHOD
+                      end
+
+                      ##
+                      # @return [ConvenientService::Support::UniqueValue]
+                      #
+                      # @internal
+                      #   TODO: Direct specs.
+                      #
+                      def any_scope
+                        Constants::ANY_SCOPE
+                      end
+
+                      ##
+                      # @return [ConvenientService::Support::UniqueValue]
+                      #
+                      # @internal
+                      #   TODO: Direct specs.
+                      #
+                      def any_entity
+                        Constants::ANY_ENTITY
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# 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 Base
+                  module Concern
+                    module InstanceMethods
+                      include Support::AbstractMethod
+
+                      ##
+                      # @return [Object] Can be any type.
+                      #
+                      abstract_method :call
+
+                      ##
+                      # @param stack [#call<Hash>]
+                      # @return [void]
+                      #
+                      def initialize(stack, **kwargs)
+                        @__stack__ = stack
+                        @__env__ = kwargs.fetch(:env) { {} }
+                        @__middleware_arguments__ = kwargs.fetch(:middleware_arguments) { Support::Arguments.null_arguments }
+                      end
+
+                      ##
+                      # @return [ConvenientService::Support::Arguments]
+                      #
+                      def middleware_arguments
+                        @__middleware_arguments__
+                      end
+
+                      ##
+                      # @param other [Object] Can be any type.
+                      # @return [Boolean, nil]
+                      #
+                      def ==(other)
+                        return unless other.instance_of?(self.class)
+
+                        return false if @__stack__ != other.instance_variable_get(:@__stack__)
+                        return false if @__env__ != other.instance_variable_get(:@__env__)
+                        return false if @__middleware_arguments__ != other.instance_variable_get(:@__middleware_arguments__)
+
+                        true
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "concern/instance_methods"
+require_relative "concern/class_methods"
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class 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/base/constants.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Base
+                  module Constants
+                    ##
+                    # @return [ConvenientService::Support::UniqueValue]
+                    #
+                    ANY_METHOD = Support::UniqueValue.new("any_method")
+
+                    ##
+                    # @return [ConvenientService::Support::UniqueValue]
+                    #
+                    ANY_SCOPE = Support::UniqueValue.new("any_scope")
+
+                    ##
+                    # @return [ConvenientService::Support::UniqueValue]
+                    #
+                    ANY_ENTITY = Support::UniqueValue.new("any_entity")
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Base
+                  module Structs
+                    IntendedMethod = ::Struct.new(:method, :scope, :entity)
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "structs/intended_method"

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