serega 0.15.0 → 0.17.0

data/lib/serega/plugins/batch/lib/validations/check_batch_opt_key.rb

@@ -22,45 +22,15 @@ class Serega
 
             raise SeregaError, must_be_callable unless key.respond_to?(:call)
 
-            if key.is_a?(Proc)
-              check_block(key)
-            else
-              check_callable(key)
-            end
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(key, "batch option :key")
+            params_count = SeregaUtils::ParamsCount.call(key, max_count: 2)
+            raise SeregaError, params_count_error if params_count > 2
           end
 
           private
 
-          def check_block(block)
-            return if valid_parameters?(block, accepted_count: 0..2)
-
-            raise SeregaError, block_parameters_error
-          end
-
-          def check_callable(callable)
-            return if valid_parameters?(callable.method(:call), accepted_count: 2..2)
-
-            raise SeregaError, callable_parameters_error
-          end
-
-          def valid_parameters?(data, accepted_count:)
-            params = data.parameters
-            accepted_count.include?(params.count) && valid_parameters_types?(params)
-          end
-
-          def valid_parameters_types?(params)
-            params.all? do |param|
-              type = param[0]
-              (type == :req) || (type == :opt)
-            end
-          end
-
-          def block_parameters_error
-            "Invalid :batch option :key. When it is a Proc it can have maximum two regular parameters (object, context)"
-          end
-
-          def callable_parameters_error
-            "Invalid :batch option :key. When it is a callable object it must have two regular parameters (object, context)"
+          def params_count_error
+            "Invalid :batch option :key. It can accept maximum 2 parameters (object, context)"
           end
 
           def must_be_callable

data/lib/serega/plugins/batch/lib/validations/check_batch_opt_loader.rb

@@ -22,45 +22,15 @@ class Serega
 
             raise SeregaError, must_be_callable unless loader.respond_to?(:call)
 
-            if loader.is_a?(Proc)
-              check_block(loader)
-            else
-              check_callable(loader)
-            end
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(loader, ":batch option :loader")
+            params_count = SeregaUtils::ParamsCount.call(loader, max_count: 3)
+            raise SeregaError, params_count_error if params_count > 3
           end
 
           private
 
-          def check_block(block)
-            return if valid_parameters?(block, accepted_count: 0..3)
-
-            raise SeregaError, block_parameters_error
-          end
-
-          def check_callable(callable)
-            return if valid_parameters?(callable.method(:call), accepted_count: 3..3)
-
-            raise SeregaError, callable_parameters_error
-          end
-
-          def valid_parameters?(data, accepted_count:)
-            params = data.parameters
-            accepted_count.include?(params.count) && valid_parameters_types?(params)
-          end
-
-          def valid_parameters_types?(params)
-            params.all? do |param|
-              type = param[0]
-              (type == :req) || (type == :opt)
-            end
-          end
-
-          def block_parameters_error
-            "Invalid :batch option :loader. When it is a Proc it can have maximum three regular parameters (keys, context, point)"
-          end
-
-          def callable_parameters_error
-            "Invalid :batch option :loader. When it is a callable object it must have three regular parameters (keys, context, point)"
+          def params_count_error
+            "Invalid :batch option :loader. It can accept maximum 3 parameters (keys, context, plan)"
           end
 
           def must_be_callable

data/lib/serega/plugins/batch/lib/validations/check_opt_batch.rb

@@ -23,7 +23,7 @@ class Serega
             SeregaValidations::Utils::CheckOptIsHash.call(opts, :batch)
 
             batch = opts[:batch]
-            SeregaValidations::Utils::CheckAllowedKeys.call(batch, %i[key loader default])
+            SeregaValidations::Utils::CheckAllowedKeys.call(batch, %i[key loader default], :batch)
 
             check_batch_opt_key(batch, serializer_class)
             check_batch_opt_loader(batch)
@@ -50,7 +50,7 @@ class Serega
           end
 
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :batch can not be used together with option :key" if opts.key?(:key)
+            raise SeregaError, "Option :batch can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :batch can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :batch can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :batch can not be used together with option :delegate" if opts.key?(:delegate)

data/lib/serega/plugins/camel_case/camel_case.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    #
+    # Plugin :camel_case
+    #
+    # By default when we add attribute like `attribute :first_name` this means:
+    # - adding a `:first_name` key to resulted hash
+    # - adding a `#first_name` method call result as value
+    #
+    # But its often desired to response with *camelCased* keys.
+    # Earlier this can be achieved by specifying attribute name and method directly
+    # for each attribute: `attribute :firstName, method: first_name`
+    #
+    # Now this plugin transforms all attribute names automatically.
+    # We use simple regular expression to replace `_x` to `X` for the whole string.
+    # You can provide your own callable transformation when defining plugin,
+    # for example `plugin :camel_case, transform: ->(name) { name.camelize }`
+    #
+    # For any attribute camelCase-behavior can be skipped when
+    # `camel_case: false` attribute option provided.
+    #
+    # @example Define plugin
+    #  class AppSerializer < Serega
+    #    plugin :camel_case
+    #  end
+    #
+    #  class UserSerializer < AppSerializer
+    #    attribute :first_name
+    #    attribute :last_name
+    #    attribute :full_name, camel_case: false, value: proc { |user| [user.first_name, user.last_name].compact.join(" ") }
+    #  end
+    #
+    #  require "ostruct"
+    #  user = OpenStruct.new(first_name: "Bruce", last_name: "Wayne")
+    #  UserSerializer.to_h(user) # {firstName: "Bruce", lastName: "Wayne", full_name: "Bruce Wayne"}
+    #
+    module CamelCase
+      # Default camel-case transformation
+      TRANSFORM_DEFAULT = proc { |attribute_name|
+        attribute_name.gsub!(/_[a-z]/) { |m| m[-1].upcase! }
+        attribute_name
+      }
+
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :camel_case
+      end
+
+      #
+      # Applies plugin code to specific serializer
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **_opts)
+        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+        serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
+        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
+      end
+
+      #
+      # Adds config options and runs other callbacks after plugin was loaded
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      def self.after_load_plugin(serializer_class, **opts)
+        config = serializer_class.config
+        config.opts[:camel_case] = {}
+        config.camel_case.transform = opts[:transform] || TRANSFORM_DEFAULT
+
+        config.attribute_keys << :camel_case
+      end
+
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::CamelCase::CamelCaseConfig] `camel_case` plugin config
+        def camel_case
+          @camel_case ||= CamelCaseConfig.new(opts.fetch(:camel_case))
+        end
+      end
+
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+          CheckOptCamelCase.call(opts)
+        end
+      end
+
+      #
+      # Validator for attribute :camel_case option
+      #
+      class CheckOptCamelCase
+        class << self
+          #
+          # Checks attribute :camel_case option must be boolean
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            camel_case_option_exists = opts.key?(:camel_case)
+            return unless camel_case_option_exists
+
+            value = opts[:camel_case]
+            return if value.equal?(true) || value.equal?(false)
+
+            raise SeregaError, "Attribute option :camel_case must have a boolean value, but #{value.class} was provided"
+          end
+        end
+      end
+
+      # CamelCase config object
+      class CamelCaseConfig
+        attr_reader :opts
+
+        #
+        # Initializes CamelCaseConfig object
+        #
+        # @param opts [Hash] camel_case plugin options
+        # @option opts [#call] :transform Callable object that transforms original attribute name
+        #
+        # @return [Serega::SeregaPlugins::CamelCase::CamelCaseConfig] CamelCaseConfig object
+        #
+        def initialize(opts)
+          @opts = opts
+        end
+
+        # @return [#call] defined object that transforms name
+        def transform
+          opts.fetch(:transform)
+        end
+
+        # Sets transformation callable object
+        #
+        # @param value [#call] transformation
+        #
+        # @return [#call] camel_case plugin transformation callable object
+        def transform=(value)
+          raise SeregaError, "Transform value must respond to #call" unless value.respond_to?(:call)
+
+          params = value.is_a?(Proc) ? value.parameters : value.method(:call).parameters
+          if params.count != 1 || !params.all? { |param| (param[0] == :req) || (param[0] == :opt) }
+            raise SeregaError, "Transform value must respond to #call and accept 1 regular parameter"
+          end
+
+          opts[:transform] = value
+        end
+      end
+
+      #
+      # SeregaAttributeNormalizer additional/patched instance methods
+      #
+      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
+      #
+      module AttributeNormalizerInstanceMethods
+        private
+
+        #
+        # Patch for original `prepare_name` method
+        #
+        # Makes camelCased name
+        #
+        def prepare_name
+          res = super
+          return res if init_opts[:camel_case] == false
+
+          self.class.serializer_class.config.camel_case.transform.call(res.to_s).to_sym
+        end
+      end
+    end
+
+    register_plugin(CamelCase.plugin_name, CamelCase)
+  end
+end

data/lib/serega/plugins/depth_limit/depth_limit.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    #
+    # Plugin :depth_limit
+    #
+    # Helps to secure from malicious queries that require to serialize too much
+    # or from accidental serializing of objects with cyclic relations.
+    #
+    # Depth limit is checked when constructing a serialization plan, that is when
+    # `#new` method is called, ex: `SomeSerializer.new(with: params[:with])`.
+    # It can be useful to instantiate serializer before any other business logic
+    # to get possible errors earlier.
+    #
+    # Any class-level serialization methods also check depth limit as they also instantiate serializer.
+    #
+    # When depth limit is exceeded `Serega::DepthLimitError` is raised.
+    # Depth limit error details can be found in additional `Serega::DepthLimitError#details` method
+    #
+    # Limit can be checked or changed with next config options:
+    #
+    #   - config.depth_limit.limit
+    #   - config.depth_limit.limit=
+    #
+    # There are no default limit, but it should be set when enabling plugin.
+    #
+    # @example
+    #
+    #   class AppSerializer < Serega
+    #     plugin :depth_limit, limit: 10 # set limit for all child classes
+    #   end
+    #
+    #   class UserSerializer < AppSerializer
+    #     config.depth_limit.limit = 5 # overrides limit for UserSerializer
+    #   end
+    #
+    module DepthLimit
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :depth_limit
+      end
+
+      #
+      # Applies plugin code to specific serializer
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **_opts)
+        serializer_class::SeregaPlan.include(PlanInstanceMethods)
+        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+      end
+
+      #
+      # Adds config options and runs other callbacks after plugin was loaded
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      def self.after_load_plugin(serializer_class, **opts)
+        config = serializer_class.config
+        limit = opts.fetch(:limit) { raise SeregaError, "Please provide :limit option. Example: `plugin :depth_limit, limit: 10`" }
+        config.opts[:depth_limit] = {}
+        config.depth_limit.limit = limit
+      end
+
+      # DepthLimit config object
+      class DepthLimitConfig
+        attr_reader :opts
+
+        #
+        # Initializes DepthLimitConfig object
+        #
+        # @param opts [Hash] depth_limit plugin options
+        #
+        # @return [SeregaPlugins::DepthLimit::DepthLimitConfig] DepthLimitConfig object
+        #
+        def initialize(opts)
+          @opts = opts
+        end
+
+        # @return [Integer] defined depth limit
+        def limit
+          opts.fetch(:limit)
+        end
+
+        #
+        # Set depth limit
+        #
+        # @param value [Integer] depth limit
+        #
+        # @return [Integer] depth limit
+        def limit=(value)
+          raise SeregaError, "Depth limit must be an Integer" unless value.is_a?(Integer)
+
+          opts[:limit] = value
+        end
+      end
+
+      #
+      # Serega::SeregaConfig additional/patched class methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::DepthLimit::DepthLimitConfig] current depth_limit config
+        def depth_limit
+          @depth_limit ||= DepthLimitConfig.new(opts.fetch(:depth_limit))
+        end
+      end
+
+      #
+      # SeregaPlan additional/patched instance methods
+      #
+      # @see SeregaPlan
+      #
+      module PlanInstanceMethods
+        #
+        # Initializes serialization plan
+        # Overrides original method (adds depth_limit validation)
+        #
+        def initialize(parent_plan_point, *)
+          check_depth_limit_exceeded(parent_plan_point)
+          super
+        end
+
+        private
+
+        def check_depth_limit_exceeded(current_point)
+          plan = self
+          depth_level = 1
+          point = current_point
+
+          while point
+            depth_level += 1
+            plan = point.plan
+            point = plan.parent_plan_point
+          end
+
+          root_serializer = plan.class.serializer_class
+          root_depth_limit = root_serializer.config.depth_limit.limit
+
+          if depth_level > root_depth_limit
+            fields_chain = [current_point.name]
+            fields_chain << current_point.name while (current_point = current_point.plan.parent_plan_point)
+            details = "#{root_serializer} (depth limit: #{root_depth_limit}) -> #{fields_chain.reverse!.join(" -> ")}"
+            raise DepthLimitError.new("Depth limit was exceeded", details)
+          end
+        end
+      end
+    end
+
+    register_plugin(DepthLimit.plugin_name, DepthLimit)
+  end
+
+  #
+  # Special error for depth_limit plugin
+  #
+  class DepthLimitError < SeregaError
+    #
+    # Details of why depth limit error happens.
+    #
+    # @return [String] error details
+    #
+    attr_reader :details
+
+    #
+    # Initializes new error
+    #
+    # @param message [String] Error message
+    # @param details [String] Error additional details
+    #
+    # @return [DepthLimitError] error instance
+    #
+    def initialize(message, details = nil)
+      super(message)
+      @details = details
+    end
+  end
+end

data/lib/serega/plugins/explicit_many_option/explicit_many_option.rb

@@ -40,7 +40,7 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./validations/check_opt_many"
+        require_relative "validations/check_opt_many"
 
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
       end

data/lib/serega/plugins/formatters/formatters.rb

@@ -11,12 +11,15 @@ class Serega
     #
     # Attribute option `:format` now can be used with name of formatter or with callable instance.
     #
+    # Formatters can accept up to 2 parameters (formatted object, context)
+    #
     # @example
     #   class AppSerializer < Serega
     #     plugin :formatters, formatters: {
     #       iso8601: ->(value) { time.iso8601.round(6) },
     #       on_off: ->(value) { value ? 'ON' : 'OFF' },
     #       money: ->(value) { value.round(2) }
+    #       date: DateTypeFormatter # callable
     #     }
     #   end
     #
@@ -35,6 +38,7 @@ class Serega
     #     attribute :updated_at, format: :iso8601
     #
     #     # Using `callable` formatter
+    #     attribute :score_percent, format: PercentFormmatter # callable class
     #     attribute :score_percent, format: proc { |percent| "#{percent.round(2)}%" }
     #   end
     #
@@ -68,6 +72,7 @@ class Serega
       def self.load_plugin(serializer_class, **_opts)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
         serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
+        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
       end
 
       #
@@ -107,6 +112,7 @@ class Serega
         # @return [void]
         def add(formatters)
           formatters.each_pair do |key, value|
+            CheckFormatter.call(key, value)
             opts[key] = value
           end
         end
@@ -124,6 +130,21 @@ class Serega
         end
       end
 
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+
+          CheckOptFormat.call(opts, self.class.serializer_class)
+        end
+      end
+
       #
       # Attribute class additional/patched instance methods
       #
@@ -143,16 +164,10 @@ class Serega
         def prepare_value_block
           return super unless formatter
 
-          if init_opts.key?(:const)
-            # Format const value in advance
-            const_value = formatter.call(init_opts[:const])
-            proc { const_value }
-          else
-            # Wrap original block into formatter block
-            proc do |object, context|
-              value = super.call(object, context)
-              formatter.call(value)
-            end
+          # Wrap original block into formatter block
+          proc do |object, context|
+            value = super.call(object, context)
+            formatter.call(value, context)
           end
         end
 
@@ -160,10 +175,69 @@ class Serega
           formatter = init_opts[:format]
           return unless formatter
 
-          if formatter.is_a?(Symbol)
-            self.class.serializer_class.config.formatters.opts.fetch(formatter)
-          else
-            formatter # already callable
+          formatter = self.class.serializer_class.config.formatters.opts.fetch(formatter) if formatter.is_a?(Symbol)
+          prepare_callable_proc(formatter)
+        end
+      end
+
+      #
+      # Validator for attribute :format option
+      #
+      class CheckOptFormat
+        class << self
+          #
+          # Checks attribute :format option must be registered or valid callable with maximum 2 args
+          #
+          # @param opts [value] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts, serializer_class)
+            return unless opts.key?(:format)
+
+            formatter = opts[:format]
+
+            if formatter.is_a?(Symbol)
+              check_formatter_defined(serializer_class, formatter)
+            else
+              CheckFormatter.call(:format, formatter)
+            end
+          end
+
+          private
+
+          def check_formatter_defined(serializer_class, formatter)
+            return if serializer_class.config.formatters.opts.key?(formatter)
+
+            raise Serega::SeregaError, "Formatter `#{formatter.inspect}` was not defined"
+          end
+        end
+      end
+
+      #
+      # Validator for formatters defined as config options or directly as attribute :format option
+      #
+      class CheckFormatter
+        class << self
+          #
+          # Check formatter type and parameters
+          #
+          # @param formatter_name [Symbol] Name of formatter
+          # @param formatter [#call] Formatter callable object
+          #
+          # @return [void]
+          #
+          def call(formatter_name, formatter)
+            raise Serega::SeregaError, "Option #{formatter_name.inspect} must have callable value" unless formatter.respond_to?(:call)
+
+            SeregaValidations::Utils::CheckExtraKeywordArg.call(formatter, "#{formatter_name.inspect} value")
+            params_count = SeregaUtils::ParamsCount.call(formatter, max_count: 2)
+
+            if params_count > 2
+              raise SeregaError, "Formatter can have maximum 2 parameters (value to format, context)"
+            end
           end
         end
       end