convenient_service 0.19.0 → 0.20.0

data/lib/convenient_service/support/middleware/stack_builder/entities/builders/custom.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "custom/constants"
+require_relative "custom/entities"
+require_relative "custom/exceptions"
+
+module ConvenientService
+  module Support
+    module Middleware
+      class StackBuilder
+        module Entities
+          module Builders
+            class Custom
+              include Support::AbstractMethod
+
+              ##
+              # @!attribute [r] stack
+              #   @return [Array<#call<Hash>>]
+              #
+              attr_reader :stack
+
+              ##
+              # @!attribute [r] name
+              #   @return [String]
+              #
+              attr_reader :name
+
+              ##
+              # @return [Object] Can be any type.
+              #
+              abstract_method :call_with_original
+
+              ##
+              # @return [Object] Can be any type.
+              #
+              abstract_method :call
+
+              ##
+              # @param kwargs [Hash{Symbol => Object}]
+              # @return [void]
+              #
+              def initialize(**kwargs)
+                @name = kwargs.fetch(:name) { "Stack" }
+                @stack = kwargs.fetch(:stack) { [] }
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def empty?
+                stack.empty?
+              end
+
+              ##
+              # @param some_middleware [#call<Hash>]
+              # @return [Boolean]
+              #
+              def has?(some_middleware)
+                stack.any? { |middleware| middleware == some_middleware }
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def clear
+                stack.clear
+
+                self
+              end
+
+              ##
+              # @param middleware [#call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              def unshift(middleware)
+                stack.unshift(middleware)
+
+                self
+              end
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              alias_method :prepend, :unshift
+
+              ##
+              # @param middleware [#call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              def use(middleware)
+                stack << middleware
+
+                self
+              end
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              alias_method :append, :use
+
+              ##
+              # @param index_or_middleware [Integer, #call<Hash>]
+              # @param other_middleware [#call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              # @raise [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom::Exceptions::MissingMiddleware]
+              #
+              def insert(index_or_middleware, other_middleware)
+                index = cast_index(index_or_middleware)
+
+                stack.insert(index, other_middleware)
+
+                self
+              end
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              alias_method :insert_before, :insert
+
+              ##
+              # @param index_or_middleware [Integer, #call<Hash>]
+              # @param other_middleware [#call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              # @raise [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom::Exceptions::MissingMiddleware]
+              #
+              def insert_after(index_or_middleware, other_middleware)
+                index = cast_index(index_or_middleware)
+
+                stack.insert(index + 1, other_middleware)
+
+                self
+              end
+
+              ##
+              # @param other_middleware [#call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              def insert_before_each(other_middleware)
+                @stack = stack.reduce([]) { |stack, middleware| stack.push(other_middleware, middleware) }
+
+                self
+              end
+
+              ##
+              # @param other_middleware [#call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              def insert_after_each(other_middleware)
+                @stack = stack.reduce([]) { |stack, middleware| stack.push(middleware, other_middleware) }
+
+                self
+              end
+
+              ##
+              # @param index_or_middleware [Integer, #call<Hash>]
+              # @param other_middleware [#call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              # @raise [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom::Exceptions::MissingMiddleware]
+              #
+              def replace(index_or_middleware, other_middleware)
+                index = cast_index(index_or_middleware)
+
+                stack[index] = other_middleware
+
+                self
+              end
+
+              ##
+              # @param index_or_middleware [Integer, #call<Hash>]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              # @raise [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom::Exceptions::MissingMiddleware]
+              #
+              def delete(index_or_middleware)
+                index = cast_index(index_or_middleware)
+
+                stack.delete_at(index)
+
+                self
+              end
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              alias_method :remove, :delete
+
+              ##
+              # @param other [Object] Can be any type.
+              # @return [Boolean, nil]
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if name != other.name
+                return false if stack != other.stack
+
+                true
+              end
+
+              ##
+              # @return [Array]
+              #
+              def to_a
+                stack
+              end
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom]
+              #
+              def dup
+                self.class.new(name: name.dup, stack: stack.dup)
+              end
+
+              private
+
+              ##
+              # @param index_or_middleware [Integer, #call<Hash>]
+              # @return [Integer]
+              # @raise [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Custom::Exceptions::MissingMiddleware]
+              #
+              def cast_index(index_or_middleware)
+                return index_or_middleware if index_or_middleware.instance_of?(Integer)
+
+                index = stack.find_index { |middleware| middleware == index_or_middleware }
+
+                ::ConvenientService.raise Exceptions::MissingMiddleware.new(middleware: index_or_middleware) unless index
+
+                index
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/middleware/stack_builder/entities/builders/naive.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Support
+    module Middleware
+      class StackBuilder
+        module Entities
+          module Builders
+            class Naive < Custom
+              ##
+              # @param env [Hash{Symbol => Object}]
+              # @param original [Proc]
+              # @return [Object] Can be any type.
+              #
+              # @internal
+              #   TODO: Direct specs.
+              #
+              def call_with_original(env, original)
+                dup.use(Custom::Entities::ProcWithNew.new(original)).call(env)
+              end
+
+              ##
+              # @param env [Hash{Symbol => Object}]
+              # @return [Object] Can be any type.
+              #
+              # @see https://github.com/rack/rack/blob/v3.1.7/lib/rack/builder.rb#L268
+              # @see https://github.com/Ibsciss/ruby-middleware/blob/v0.4.2/lib/middleware/runner.rb#L7
+              #
+              # @internal
+              #   NOTE: When stack is empty - `env` is returned. Just like `ruby-middleware` does.
+              #   NOTE: `reduce` for empty array returns initial value.
+              #
+              #   TODO: Direct specs.
+              #
+              def call(env)
+                return env if stack.empty?
+
+                app = Custom::Constants::INITIAL_MIDDLEWARE
+
+                stack.reverse_each { |middleware| app = middleware.new(app) }
+
+                app.call(env)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/middleware/stack_builder/entities/builders/rack.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Support
+    module Middleware
+      class StackBuilder
+        module Entities
+          module Builders
+            class Rack < Builders::Custom
+              ##
+              # @param env [Hash{Symbol => Object}]
+              # @param original [Proc]
+              # @return [Object] Can be any type.
+              #
+              # @internal
+              #   TODO: Direct specs.
+              #
+              def call_with_original(env, original)
+                dup.use(Custom::Entities::ProcWithNew.new(original)).call(env)
+              end
+
+              ##
+              # @param env [Hash{Symbol => Object}]
+              # @return [Object] Can be any type.
+              #
+              # @see https://github.com/rack/rack/blob/v3.1.7/lib/rack/builder.rb#L268
+              # @see https://github.com/Ibsciss/ruby-middleware/blob/v0.4.2/lib/middleware/runner.rb#L7
+              #
+              # @internal
+              #   NOTE: When stack is empty - `env` is returned. Just like `ruby-middleware` does.
+              #   NOTE: `reduce` for empty array returns initial value.
+              #
+              #   TODO: Direct specs.
+              #
+              def call(env)
+                return env if stack.empty?
+
+                app =
+                  stack
+                    .map { |middleware| proc { |app| middleware.new(app) } }
+                    .reverse
+                    .reduce(Custom::Constants::INITIAL_MIDDLEWARE) { |a, e| e[a] }
+
+                app.call(env)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/middleware/stack_builder/entities/builders/ruby_middleware.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Support
+    module Middleware
+      class StackBuilder
+        module Entities
+          module Builders
+            ##
+            # @internal
+            #   TODO: Contribute.
+            #
+            #   NOTE: Minimal `ibsciss-middleware` version - `0.4.2`.
+            #   - https://github.com/marian13/ruby-middleware/tree/v0.4.2
+            #
+            class RubyMiddleware < Dependencies::Extractions::RubyMiddleware::Middleware::Builder
+              ##
+              # @param opts [Hash]
+              # @param block [Proc, nil]
+              # @return [void]
+              #
+              # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L43
+              # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L59
+              #
+              def initialize(opts = {}, &block)
+                super
+
+                @middleware_name = opts.fetch(:name) { "Stack" }
+
+                ##
+                # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L174
+                #
+                self.stack = opts[:stack] if opts.has_key?(:stack)
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def empty?
+                stack.empty?
+              end
+
+              ##
+              # @param some_middleware [#call<Hash>]
+              # @return [Boolean]
+              #
+              def has?(some_middleware)
+                stack.any? { |middleware| middleware == [some_middleware, [], nil] }
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def clear
+                stack.clear
+
+                self
+              end
+
+              ##
+              # @param env [Hash{Symbol => Object}]
+              # @param original [Proc]
+              # @return [Object] Can be any type.
+              #
+              # @internal
+              #   TODO: Direct specs.
+              #
+              def call_with_original(env, original)
+                dup.use(original).call(env)
+              end
+
+              ##
+              # @param middleware [#call<Hash>]
+              # @param args [Array<Object>]
+              # @param block [Proc, nil]
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::RubyMiddleware]
+              #
+              # @internal
+              #   TODO: Rewrite middleware backend. Consider to use `Array` descendant?
+              #
+              def unshift(middleware, *args, &block)
+                stack.unshift([middleware, args, block])
+
+                self
+              end
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::RubyMiddleware]
+              #
+              alias_method :prepend, :unshift
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::RubyMiddleware]
+              #
+              # @internal
+              #   TODO: Direct specs when a `Builder` is passed as argument.
+              #
+              alias_method :remove, :delete
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::RubyMiddleware]
+              #
+              # @internal
+              #   TODO: Direct specs when a `Builder` is passed as argument.
+              #
+              alias_method :append, :use
+
+              ##
+              # @param other [ConvenientService::Support::Middleware::StackBuilder, Object]
+              # @return [Boolean, nil]
+              #
+              # @internal
+              #   TODO: Direct specs.
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if name != other.name
+                return false if stack != other.stack
+
+                true
+              end
+
+              ##
+              # @return [Array]
+              #
+              # @internal
+              #   NOTE: `use` can accept additional arguments and block, that is why `stack` contains tuples like [middleware, args, block].
+              #   - https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L76
+              #
+              #   TODO: better name than just `to_a`.
+              #
+              def to_a
+                stack.map(&:first)
+              end
+
+              ##
+              # @return [ConvenientService::Support::Middleware::StackBuilder]
+              #
+              # @internal
+              #   TODO: Direct specs.
+              #
+              def dup
+                self.class.new(
+                  ##
+                  # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L45
+                  #
+                  runner_class: @runner_class,
+                  ##
+                  # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L46
+                  #
+                  name: @middleware_name.dup,
+                  ##
+                  # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L167
+                  #
+                  stack: stack.dup
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/middleware/stack_builder/entities/builders/stateful.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Support
+    module Middleware
+      class StackBuilder
+        module Entities
+          module Builders
+            class Stateful < Builders::Custom
+              ##
+              # @param kwargs [Hash{Symbol => Object}]
+              # @return [void]
+              #
+              def initialize(**kwargs)
+                super
+
+                @index = -1
+              end
+
+              ##
+              # @param env [Hash{Symbol => Object}]
+              # @param original [Proc]
+              # @return [Object] Can be any type.
+              #
+              # @internal
+              #   TODO: Direct specs.
+              #
+              def call_with_original(env, original)
+                dup.use(Custom::Entities::ProcWithNew.new(original)).call(env)
+              end
+
+              ##
+              # @param env [Hash{Symbol => Object}]
+              # @return [Object] Can be any type.
+              #
+              # @internal
+              #   NOTE: When stack is empty - `env` is returned. Just like `ruby-middleware` does.
+              #   NOTE: Once middleware backends are unified, consider to create new object to ensure thread-safety.
+              #   NOTE: Once middleware backends are unified, move `stack.empty?` and `index == stack.size - 1` to entrypoint method.
+              #
+              #   TODO: Direct specs.
+              #
+              def call(env)
+                self.index += 1
+
+                return env if index == stack.size
+
+                stack[index].new(self).call(env)
+              ensure
+                self.index = -1
+              end
+
+              private
+
+              ##
+              # @!attribute [r] index
+              #   @return [Integer]
+              #
+              attr_accessor :index
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/middleware/stack_builder/entities/builders.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "builders/ruby_middleware"
+
+require_relative "builders/custom"
+require_relative "builders/rack"
+require_relative "builders/stateful"
+require_relative "builders/naive"

data/lib/convenient_service/support/middleware/stack_builder/entities.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "entities/builders"

data/lib/convenient_service/support/middleware/stack_builder/exceptions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Support
+    module Middleware
+      class StackBuilder
+        module Exceptions
+          class NotSupportedBackend < ::ConvenientService::Exception
+            ##
+            # @param backend [Symbol]
+            # @return [void]
+            #
+            def initialize_with_kwargs(backend:)
+              message = <<~TEXT
+                Middleware backend `#{backend.inspect}` is NOT supported.
+
+                Supported backends are #{printable_backends}.
+              TEXT
+
+              initialize(message)
+            end
+
+            private
+
+            ##
+            # @return [String]
+            #
+            def printable_backends
+              Constants::Backends::ALL.map { |backend| "`#{backend.inspect}`" }.join(", ")
+            end
+          end
+        end
+      end
+    end
+  end
+end