convenient_service 0.11.0 → 0.12.0

data/docker/truffleruby-22.3/Dockerfile

@@ -0,0 +1,91 @@
+##
+# TruffleRuby 22.3 (CRuby 3.1 compatible) with Node.js 16.x.
+# - https://github.com/graalvm/container/blob/master/truffleruby/README.md
+# - https://github.com/oracle/truffleruby/blob/master/doc/user/compatibility.md
+#
+# NOTE: Linted by hadolint.
+#
+#   docker run --rm -i ghcr.io/hadolint/hadolint < docker/truffleruby-22.3/Dockerfile
+#
+# NOTE: A command to build image.
+#
+#   cd convenient_service
+#   cp Gemfile Gemfile.truffleruby-22.3
+#   docker build . -f docker/truffleruby-22.3/Dockerfile -t convenient_service:truffleruby-22.3
+#   # or `task docker:build:jruby_9.4`
+#
+# NOTE: A command to run bash in container.
+#
+#   cd convenient_service
+#   docker run --rm -it -v $(pwd):/gem convenient_service:truffleruby-22.3 bash
+#   # or `task docker:bash:jruby_9.4`
+#
+# NOTE: If there are no memory, performance, or cost constraints, prefer to use as standard Linux distribution as it is possible.
+# In a general case, you simply won't have enough time to resolve all the "quirks" of more specific distributions if you are an application developer.
+# `ghcr.io/graalvm/truffleruby:debian-22.3` uses Debian (that is similar to Ubuntu) under the hood.
+# - https://github.com/graalvm/container/pkgs/container/truffleruby/65464856?tag=debian-22.3
+# - https://github.com/graalvm/container/blob/master/truffleruby/Dockerfile.debian#L6
+# - https://www.graalvm.org/latest/docs/getting-started/container-images/
+#
+# NOTE: Gallium means Node.js 16.x.
+# https://github.com/nodejs/Release
+#
+FROM ghcr.io/graalvm/truffleruby:debian-22.3
+
+##
+# NOTE: `git`, `make`, `gcc` are `bundle install` dependencies.
+#
+# NOTE: `curl` and `gnupg2` are Node.js 16.x dependencies.
+# https://github.com/timbru31/docker-ruby-node/blob/master/3.2/16/slim/Dockerfile
+#
+RUN apt-get update -qq \
+  && apt-get install --no-install-recommends -y git \
+  && apt-get install --no-install-recommends -y make \
+  && apt-get install --no-install-recommends -y gcc \
+  && apt-get install --no-install-recommends -y curl \
+  && apt-get install --no-install-recommends -y gnupg2 \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN mkdir -p /gem
+
+WORKDIR /gem
+
+COPY . /gem
+
+##
+# NOTE: Every container has its own copy of `Gemfile`. This way a developer doesn't need to delete `Gemfile.lock` all the time when changing containers.
+# - https://docs.docker.com/engine/reference/builder/#env
+# - https://stackoverflow.com/questions/48863711/is-it-possible-to-koverride-gemfile-for-local-development
+#
+ENV BUNDLE_GEMFILE=Gemfile.truffleruby-22.3
+
+RUN bundle install
+
+RUN bundle exec appraisal install
+
+##
+# NOTE: Installs `task`.
+# https://taskfile.dev/installation/#install-script
+#
+# NOTE: `task` is installed into `~/bin`. That is why `-b /bin` is used. See `echo ${PATH}` to debug.
+#
+RUN sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /bin
+
+##
+# NOTE: Intalls Node.js 16.x and `yarn`.
+# https://github.com/timbru31/docker-ruby-node/blob/master/3.2/16/slim/Dockerfile
+#
+RUN curl -sL https://deb.nodesource.com/setup_16.x | bash -\
+  && apt-get update -qq \
+  && apt-get install -qq --no-install-recommends nodejs \
+  && apt-get upgrade -qq \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/*\
+  && npm install -g yarn@1
+
+##
+# NOTE: Is used to check whether a command is executed inside a Docker container. See Rakefile for examples.
+# https://stackoverflow.com/a/65942222/12201472
+#
+ENV IN_DOCKER_CONTAINER=true

data/lib/convenient_service/common/plugins/aliases.rb

@@ -3,6 +3,5 @@
 module ConvenientService
   module Plugins
     Common = ::ConvenientService::Common::Plugins
-    Internals = ::ConvenientService::Common::Plugins::HasInternals::Entities::Internals::Plugins
   end
 end

data/lib/convenient_service/common/plugins/assigns_attributes_in_constructor/using_active_model_attribute_assignment/middleware.rb

@@ -7,18 +7,22 @@ module ConvenientService
         module UsingActiveModelAttributeAssignment
           class Middleware < Core::MethodChainMiddleware
             ##
-            # TODO: Consider creation of a plugin that assigns `*args` with `assign_attributes` as well, not only `**kwargs`.
-            # Check `Method#parameters` for a possible solution.
-            # https://ruby-doc.org/core-3.1.0/Method.html#method-i-parameters
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [void]
+            #
+            # @internal
+            #   TODO: Consider creation of a plugin that assigns `*args` with `assign_attributes` as well, not only `**kwargs`.
+            #   Check `Method#parameters` for a possible solution.
+            #   - https://ruby-doc.org/core-3.1.0/Method.html#method-i-parameters
+            #
+            #   NOTE: `assign_attributes` expects `attr_writer` for all `kwargs` keys.
+            #   - https://api.rubyonrails.org/classes/ActiveModel/AttributeAssignment.html#method-i-assign_attributes
             #
             def next(*args, **kwargs, &block)
               chain.next(*args, **kwargs, &block)
 
-              ##
-              # NOTE: `assign_attributes` expects `attr_writer` for all `kwargs` keys.
-              #
-              # https://api.rubyonrails.org/classes/ActiveModel/AttributeAssignment.html#method-i-assign_attributes
-              #
               entity.assign_attributes(kwargs)
             end
           end

data/lib/convenient_service/common/plugins/caches_return_value/middleware.rb

@@ -6,9 +6,9 @@ module ConvenientService
       module CachesReturnValue
         class Middleware < Core::MethodChainMiddleware
           ##
-          # @param args [Array]
-          # @param kwargs [Hash]
-          # @param block [Proc]
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
           # @return [Object] Can be any type.
           #
           def next(*args, **kwargs, &block)

data/lib/convenient_service/common/plugins/can_have_user_provided_entity/errors.rb

@@ -5,7 +5,7 @@ module ConvenientService
     module Plugins
       module CanHaveUserProvidedEntity
         module Errors
-          class ProtoEntityHasNoName < ConvenientService::Error
+          class ProtoEntityHasNoName < ::ConvenientService::Error
             def initialize(proto_entity:)
               message = <<~TEXT
                 Proto entity `#{proto_entity}` has no name.
@@ -22,7 +22,7 @@ module ConvenientService
             end
           end
 
-          class ProtoEntityHasNoConcern < ConvenientService::Error
+          class ProtoEntityHasNoConcern < ::ConvenientService::Error
             def initialize(proto_entity:)
               message = <<~TEXT
                 Proto entity `#{proto_entity}` has no concern.

data/lib/convenient_service/common/plugins/has_around_callbacks/errors.rb

@@ -5,7 +5,7 @@ module ConvenientService
     module Plugins
       module HasAroundCallbacks
         module Errors
-          class AroundCallbackChainIsNotContinued < ConvenientService::Error
+          class AroundCallbackChainIsNotContinued < ::ConvenientService::Error
             def initialize(callback:)
               message = <<~TEXT
                 Around callback chain is NOT continued from `#{callback.block.source_location}`.

data/lib/convenient_service/common/plugins/has_callbacks/entities/callback.rb

@@ -20,7 +20,7 @@ module ConvenientService
 
             ##
             # @param types [ConvenientService::Common::Plugins::HasCallbacks::Entities::TypeCollection]
-            # @param block [Proc]
+            # @param block [Proc, nil]
             # @return [void]
             #
             def initialize(types:, block:)
@@ -74,9 +74,9 @@ module ConvenientService
 
             ##
             # @param context [Object] Can be any type.
-            # @param args [Array]
-            # @param kwargs [Hash]
-            # @param block [Proc]
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
             # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback]
             #
             def call_in_context_with_arguments(context, *args, **kwargs, &block)
@@ -86,9 +86,9 @@ module ConvenientService
             ##
             # @param context [Object] Can be any type.
             # @param value [Object] Can be any type.
-            # @param args [Array]
-            # @param kwargs [Hash]
-            # @param block [Proc]
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
             # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback]
             #
             def call_in_context_with_value_and_arguments(context, value, *args, **kwargs, &block)

data/lib/convenient_service/common/plugins/has_internals/entities/internals/plugins/aliases.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Plugins
+    Internals = ::ConvenientService::Common::Plugins::HasInternals::Entities::Internals::Plugins
+  end
+end

data/lib/convenient_service/common/plugins/has_internals/entities/internals/plugins.rb

@@ -1,3 +1,5 @@
 # frozen_string_literal: true
 
 require_relative "plugins/has_cache"
+
+require_relative "plugins/aliases"

data/lib/convenient_service/configs/minimal.rb

@@ -71,14 +71,7 @@ module ConvenientService
         middlewares :step, scope: :class do
           use Plugins::Common::NormalizesEnv::Middleware
 
-          ##
-          # IMPORTANT:
-          #   - `CanHaveMethodSteps` is disabled in the Standard config since it causes race conditions in combination with `CanHaveStubbedResult`.
-          #   - It will be reenabled after the introduction of thread-safety specs.
-          #   - Do not use it in production yet.
-          #
-          # use Plugins::Service::CanHaveMethodSteps::Middleware
-
+          use Plugins::Service::CanHaveMethodSteps::Middleware
           use Plugins::Service::CanHaveResultStep::Middleware
         end
 
@@ -100,13 +93,13 @@ module ConvenientService
 
             use Plugins::Common::HasConstructor::Concern
 
-            use Plugins::Result::HasJsendStatusAndAttributes::Concern
+            use Plugins::Result::HasJSendStatusAndAttributes::Concern
           end
 
           middlewares :initialize do
             use Plugins::Common::NormalizesEnv::Middleware
 
-            use Plugins::Result::HasJsendStatusAndAttributes::Middleware
+            use Plugins::Result::HasJSendStatusAndAttributes::Middleware
           end
 
           middlewares :success? do
@@ -149,6 +142,22 @@ module ConvenientService
             use Plugins::Common::NormalizesEnv::Middleware
           end
 
+          class self::Data
+            include Core
+          end
+
+          class self::Message
+            include Core
+          end
+
+          class self::Code
+            include Core
+          end
+
+          class self::Status
+            include Core
+          end
+
           class self::Internals
             include Core
 

data/lib/convenient_service/core/class_methods.rb

@@ -6,28 +6,41 @@ module ConvenientService
       ##
       # @see ConvenientService::Core::Entities::Config#concerns
       #
+      # @internal
+      #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+      #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+      #
       def concerns(...)
-        (@__config__ ||= Entities::Config.new(klass: self)).concerns(...)
+        (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).concerns(...)
       end
 
       ##
       # @see ConvenientService::Core::Entities::Config#middlewares
       #
+      # @internal
+      #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+      #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+      #
       def middlewares(...)
-        (@__config__ ||= Entities::Config.new(klass: self)).middlewares(...)
+        (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).middlewares(...)
       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_config!
-        (@__config__ ||= Entities::Config.new(klass: self)).commit!
-          .tap { ConvenientService.logger.debug { "[Core] Committed config for `#{self}` | Triggered by `.commit_config!`" } }
+      # @internal
+      #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+      #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+      #
+      def commit_config!(trigger: ConvenientService::Core::Constants::Triggers::USER)
+        (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).commit!(trigger: trigger)
+          .tap { ConvenientService.logger.debug { "[Core] Committed config for `#{self}` | Triggered by `.commit_config!(trigger: #{trigger.inspect})` " } }
       end
 
       ##
@@ -58,15 +71,17 @@ module ConvenientService
       #
       # @param method [Symbol]
       # @param args [Array<Object>]
-      # @param kwargs [Hash<Symbol, Object>]
-      # @param block [Proc]
+      # @param kwargs [Hash{Symbol => Object}]
+      # @param block [Proc, nil]
       # @return [void]
       #
       # @internal
-      #   IMPORTANT: `method_missing` should be thread-safe.
+      #   IMPORTANT: `method_missing` MUST be thread-safe.
+      #
+      #   NOTE: `__send__` is used instead of `Support::SafeMethod` intentionally, since checking whether a method is defined is performed earlier by `Utils::Module.class_method_defined?`.
       #
       def method_missing(method, *args, **kwargs, &block)
-        commit_config!
+        commit_config!(trigger: Constants::Triggers::CLASS_METHOD_MISSING)
 
         return super unless Utils::Module.class_method_defined?(self, method, private: true)
 

data/lib/convenient_service/core/constants.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Constants
+      module Commits
+        ##
+        # @return [Integer]
+        #
+        METHOD_MISSING_MAX_TRIES = 10
+      end
+
+      module Triggers
+        ##
+        # @return [ConvenientService::Support::UniqueValue]
+        #
+        CLASS_METHOD_MISSING = Support::UniqueValue.new("CLASS_METHOD_MISSING")
+
+        ##
+        # @return [ConvenientService::Support::UniqueValue]
+        #
+        INSTANCE_METHOD_MISSING = Support::UniqueValue.new("INSTANCE_METHOD_MISSING")
+
+        ##
+        # @return [ConvenientService::Support::UniqueValue]
+        #
+        RESOLVE_METHOD_MIDDLEWARES_SUPER_METHOD = Support::UniqueValue.new("RESOLVE_METHOD_MIDDLEWARES_SUPER_METHOD")
+
+        ##
+        # @return [ConvenientService::Support::UniqueValue]
+        #
+        USER = Support::UniqueValue.new("USER")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Commands
+          class TrackMethodMissingCommitTrigger < Support::Command
+            ##
+            # @!attribute [r] config
+            #   @return [ConvenientService::Core::Entities::Config]
+            #
+            attr_reader :config
+
+            ##
+            # @!attribute [r] trigger
+            #   @return [ConvenientService::Support::UniqueValue]
+            #
+            attr_reader :trigger
+
+            ##
+            # @param config [ConvenientService::Core::Entities::Config]
+            # @param trigger [ConvenientService::Support::UniqueValue]
+            # @return [void]
+            #
+            def initialize(config:, trigger:)
+              @config = config
+              @trigger = trigger
+            end
+
+            ##
+            # @return [void]
+            #
+            def call
+              return unless method_missing_trigger_valid?
+              return if method_missing_commits_counter_incremented?
+
+              raise Errors::TooManyCommitsFromMethodMissing.new(config: config)
+            end
+
+            ##
+            # @return [Boolean]
+            #
+            def method_missing_trigger_valid?
+              method_missing_triggers.any?(trigger)
+            end
+
+            ##
+            # @return [Boolean]
+            #
+            def method_missing_commits_counter_incremented?
+              Utils::Object.memoize_including_falsy_values(self, :@method_missing_commits_counter_incremented) { config.method_missing_commits_counter.bincrement }
+            end
+
+            ##
+            # @return [Array<ConvenientService::Support::UniqueValue>]
+            #
+            def method_missing_triggers
+              @method_missing_triggers ||= [
+                Constants::Triggers::INSTANCE_METHOD_MISSING,
+                Constants::Triggers::CLASS_METHOD_MISSING
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -51,8 +51,8 @@ module ConvenientService
                 ##
                 # @param index_or_concern [Integer, ConvenientService::Support::Concern, Module]
                 # @param concern [ConvenientService::Support::Concern, Module]
-                # @param args [Array]
-                # @param block [Proc]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L88
@@ -72,8 +72,8 @@ module ConvenientService
                 ##
                 # @param index_or_concern [Integer, ConvenientService::Support::Concern, Module]
                 # @param concern [ConvenientService::Support::Concern, Module]
-                # @param args [Array]
-                # @param block [Proc]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L97
@@ -86,8 +86,8 @@ module ConvenientService
 
                 ##
                 # @param concern [ConvenientService::Support::Concern, Module]
-                # @param args [Array]
-                # @param block [Proc]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L104
@@ -113,8 +113,8 @@ module ConvenientService
                 ##
                 # @param index_or_concern [Integer, ConvenientService::Support::Concern, Module]
                 # @param concern [ConvenientService::Support::Concern, Module]
-                # @param args [Array]
-                # @param block [Proc]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L118
@@ -139,8 +139,8 @@ module ConvenientService
 
                 ##
                 # @param concern [ConvenientService::Support::Concern, Module]
-                # @param args [Array]
-                # @param block [Proc]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
                 # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
                 #
                 # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L76

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

@@ -23,9 +23,9 @@ module ConvenientService
                 end
 
                 ##
-                # @param args [Array]
-                # @param kwargs [Hash]
-                # @param block [Proc]
+                # @param args [Array<Object>]
+                # @param kwargs [Hash{Symbol => Object}]
+                # @param block [Proc, nil]
                 # @return [Object] Can be any type.
                 #
                 # @internal

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

@@ -43,13 +43,23 @@ module ConvenientService
                 #
                 abstract_method :next
 
+                class << self
+                  ##
+                  # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::MiddlewareCreator]
+                  #
+                  def with(...)
+                    Entities::MiddlewareCreator.new(middleware: self, arguments: Support::Arguments.new(...))
+                  end
+                end
+
                 ##
                 # @param stack [#call<Hash>]
                 # @return [void]
                 #
-                def initialize(stack, env: {})
+                def initialize(stack, env: {}, arguments: Support::Arguments.null_arguments)
                   @__stack__ = stack
                   @__env__ = env
+                  @__arguments__ = arguments
                 end
 
                 ##
@@ -104,6 +114,13 @@ module ConvenientService
                 def chain
                   @__chain__ ||= Entities::Chain.new(stack: @__stack__)
                 end
+
+                ##
+                # @return [ConvenientService::Support::Arguments]
+                #
+                def arguments
+                  @__arguments__
+                end
               end
             end
           end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              class MiddlewareCreator
+                ##
+                # @!attribute [r] middleware
+                #   @return [Class]
+                #
+                attr_reader :middleware
+
+                ##
+                # @!attribute [r] arguments
+                #   @return [ConvenientService::Support::Arguments]
+                #
+                attr_reader :arguments
+
+                ##
+                # @param middleware [Class]
+                # @param arguments [ConvenientService::Support::Arguments]
+                # @return [void]
+                #
+                def initialize(middleware:, arguments:)
+                  @middleware = middleware
+                  @arguments = arguments
+                end
+
+                ##
+                # @param other [Object]
+                # @return [Boolean, nil]
+                #
+                def ==(other)
+                  return unless other.instance_of?(self.class)
+
+                  return false if middleware != other.middleware
+                  return false if arguments != other.arguments
+
+                  true
+                end
+
+                ##
+                # @param stack [#call<Hash>]
+                # @param env [Hash]
+                # @param arguments [ConvenientService::Support::Arguments]
+                # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware]
+                #
+                def new(stack, env: {}, arguments: self.arguments)
+                  middleware.new(stack, env: env, arguments: arguments)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end