serega 0.14.0 → 0.16.0

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

@@ -8,10 +8,7 @@ class Serega
     # Plugin requires to add :many option when adding relationships
     # (relationships are attributes with :serializer option specified)
     #
-    # Adding this plugin makes clearer to find if relationship returns array or single object
-    #
-    # Also some plugins like :openapi load this plugin automatically as they need to know if
-    # relationship is array
+    # Adding this plugin makes it clearer to find if relationship returns array or single object
     #
     # @example
     #   class BaseSerializer < Serega
@@ -43,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/if/if.rb

@@ -56,10 +56,10 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./validations/check_opt_if"
-        require_relative "./validations/check_opt_if_value"
-        require_relative "./validations/check_opt_unless"
-        require_relative "./validations/check_opt_unless_value"
+        require_relative "validations/check_opt_if"
+        require_relative "validations/check_opt_if_value"
+        require_relative "validations/check_opt_unless"
+        require_relative "validations/check_opt_unless_value"
 
         serializer_class::SeregaAttribute.include(SeregaAttributeInstanceMethods)
         serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)

data/lib/serega/plugins/metadata/metadata.rb

@@ -62,12 +62,12 @@ class Serega
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
 
-        require_relative "./meta_attribute"
-        require_relative "./validations/check_block"
-        require_relative "./validations/check_opt_hide_nil"
-        require_relative "./validations/check_opt_hide_empty"
-        require_relative "./validations/check_opts"
-        require_relative "./validations/check_path"
+        require_relative "meta_attribute"
+        require_relative "validations/check_block"
+        require_relative "validations/check_opt_hide_nil"
+        require_relative "validations/check_opt_hide_empty"
+        require_relative "validations/check_opts"
+        require_relative "validations/check_path"
 
         meta_attribute_class = Class.new(MetaAttribute)
         meta_attribute_class.serializer_class = serializer_class

data/lib/serega/plugins/preloads/lib/modules/attribute_normalizer.rb

@@ -36,7 +36,7 @@ class Serega
             if preloads_provided
               opts[:preload]
             elsif opts.key?(:serializer) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_serializer
-              key
+              method_name
             elsif opts.key?(:delegate) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_delegate
               opts[:delegate].fetch(:to)
             end

data/lib/serega/plugins/preloads/lib/preload_paths.rb

@@ -22,18 +22,25 @@ class Serega
           #
           # Transforms user provided preloads to array of paths
           #
-          # @param value [Array,Hash,String,Symbol,nil,false] preloads
+          # @param preloads [Array,Hash,String,Symbol,nil,false] association(s) to preload
           #
           # @return [Hash] preloads transformed to hash
           #
-          def call(preloads, path = [], result = [])
-            preloads = FormatUserPreloads.call(preloads)
+          def call(preloads)
+            formatted_preloads = FormatUserPreloads.call(preloads)
+            return FROZEN_EMPTY_ARRAY if formatted_preloads.empty?
 
-            preloads.each do |key, nested_preloads|
+            paths(formatted_preloads, [], [])
+          end
+
+          private
+
+          def paths(formatted_preloads, path, result)
+            formatted_preloads.each do |key, nested_preloads|
               path << key
               result << path.dup
 
-              call(nested_preloads, path, result)
+              paths(nested_preloads, path, result)
               path.pop
             end
 

data/lib/serega/plugins/preloads/lib/preloads_constructor.rb

@@ -11,7 +11,7 @@ class Serega
           #
           # Constructs preloads hash for given attributes plan
           #
-          # @param plan [Array<Serega::PlanPoint>] Serialization plan
+          # @param plan [Array<SeregaPlanPoint>] Serialization plan
           #
           # @return [Hash]
           #

data/lib/serega/plugins/preloads/preloads.rb

@@ -15,7 +15,7 @@ class Serega
     #
     # This options are very handy if you want to forget about finding preloads manually.
     #
-    # Preloads can be disabled with `preload: false` attribute option option.
+    # Preloads can be disabled with `preload: false` attribute option.
     # Also automatically added preloads can be overwritten with manually specified `preload: :another_value`.
     #
     # Some examples, **please read comments in the code below**
@@ -79,17 +79,17 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
-        require_relative "./lib/format_user_preloads"
-        require_relative "./lib/modules/attribute"
-        require_relative "./lib/modules/attribute_normalizer"
-        require_relative "./lib/modules/check_attribute_params"
-        require_relative "./lib/modules/config"
-        require_relative "./lib/modules/plan_point"
-        require_relative "./lib/preload_paths"
-        require_relative "./lib/preloads_config"
-        require_relative "./lib/preloads_constructor"
-        require_relative "./validations/check_opt_preload"
-        require_relative "./validations/check_opt_preload_path"
+        require_relative "lib/format_user_preloads"
+        require_relative "lib/modules/attribute"
+        require_relative "lib/modules/attribute_normalizer"
+        require_relative "lib/modules/check_attribute_params"
+        require_relative "lib/modules/config"
+        require_relative "lib/modules/plan_point"
+        require_relative "lib/preload_paths"
+        require_relative "lib/preloads_config"
+        require_relative "lib/preloads_constructor"
+        require_relative "validations/check_opt_preload"
+        require_relative "validations/check_opt_preload_path"
 
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaAttribute.include(AttributeInstanceMethods)

data/lib/serega/plugins/root/root.rb

@@ -127,7 +127,7 @@ class Serega
         # @option opts [Symbol, String, nil] :one root for single-object serialization
         # @option opts [Symbol, String, nil] :many root for many-objects serialization
         #
-        # @return [Serega::SeregaPlugins::Root::RootConfig] RootConfig object
+        # @return [SeregaPlugins::Root::RootConfig] RootConfig object
         #
         def initialize(opts)
           @opts = opts

data/lib/serega/plugins/string_modifiers/string_modifiers.rb

@@ -18,7 +18,7 @@ class Serega
       #
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.include(InstanceMethods)
-        require_relative "./parse_string_modifiers"
+        require_relative "parse_string_modifiers"
       end
 
       #

data/lib/serega/validations/attribute/check_opt_const.rb

@@ -26,7 +26,7 @@ class Serega
           private
 
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :const can not be used together with option :key" if opts.key?(:key)
+            raise SeregaError, "Option :const can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :const can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :const can not be used together with block" if block
           end

data/lib/serega/validations/attribute/check_opt_delegate.rb

@@ -32,8 +32,9 @@ class Serega
 
             delegate_opts = opts[:delegate]
             check_opt_delegate_to(delegate_opts)
-            check_opt_delegate_key(delegate_opts)
+            check_opt_delegate_method(delegate_opts)
             check_opt_delegate_allow_nil(delegate_opts)
+            check_opt_delegate_extra_opts(delegate_opts)
           end
 
           def check_opt_delegate_to(delegate_opts)
@@ -43,16 +44,20 @@ class Serega
             Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :to)
           end
 
-          def check_opt_delegate_key(delegate_opts)
-            Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :key)
+          def check_opt_delegate_method(delegate_opts)
+            Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :method)
           end
 
           def check_opt_delegate_allow_nil(delegate_opts)
             Utils::CheckOptIsBool.call(delegate_opts, :allow_nil)
           end
 
+          def check_opt_delegate_extra_opts(delegate_opts)
+            Utils::CheckAllowedKeys.call(delegate_opts, %i[to method allow_nil], :delegate)
+          end
+
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :delegate can not be used together with option :key" if opts.key?(:key)
+            raise SeregaError, "Option :delegate can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :delegate can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :delegate can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :delegate can not be used together with block" if block

data/lib/serega/validations/attribute/check_opt_many.rb

@@ -7,17 +7,34 @@ class Serega
       # Attribute `:many` option validator
       #
       class CheckOptMany
-        #
-        # Checks attribute :many option
-        #
-        # @param opts [Hash] Attribute options
-        #
-        # @raise [SeregaError] SeregaError that option has invalid value
-        #
-        # @return [void]
-        #
-        def self.call(opts)
-          Utils::CheckOptIsBool.call(opts, :many)
+        class << self
+          #
+          # Checks attribute :many option
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] SeregaError that option has invalid value
+          #
+          # @return [void]
+          #
+          def call(opts)
+            return unless opts.key?(:many)
+
+            check_many_option_makes_sence(opts)
+            Utils::CheckOptIsBool.call(opts, :many)
+          end
+
+          private
+
+          def check_many_option_makes_sence(opts)
+            return if many_option_makes_sence?(opts)
+
+            raise SeregaError, "Option :many can be provided only together with :serializer or :batch option"
+          end
+
+          def many_option_makes_sence?(opts)
+            opts[:serializer] || opts[:batch]
+          end
         end
       end
     end

data/lib/serega/validations/attribute/{check_opt_key.rb → check_opt_method.rb}

@@ -4,12 +4,12 @@ class Serega
   module SeregaValidations
     module Attribute
       #
-      # Attribute `:key` option validator
+      # Attribute `:method` option validator
       #
-      class CheckOptKey
+      class CheckOptMethod
         class << self
           #
-          # Checks attribute :key option
+          # Checks attribute :method option
           #
           # @param opts [Hash] Attribute options
           #
@@ -18,18 +18,18 @@ class Serega
           # @return [void]
           #
           def call(opts, block = nil)
-            return unless opts.key?(:key)
+            return unless opts.key?(:method)
 
             check_usage_with_other_params(opts, block)
-            Utils::CheckOptIsStringOrSymbol.call(opts, :key)
+            Utils::CheckOptIsStringOrSymbol.call(opts, :method)
           end
 
           private
 
           def check_usage_with_other_params(opts, block)
-            raise SeregaError, "Option :key can not be used together with option :const" if opts.key?(:const)
-            raise SeregaError, "Option :key can not be used together with option :value" if opts.key?(:value)
-            raise SeregaError, "Option :key can not be used together with block" if block
+            raise SeregaError, "Option :method can not be used together with option :const" if opts.key?(:const)
+            raise SeregaError, "Option :method can not be used together with option :value" if opts.key?(:value)
+            raise SeregaError, "Option :method can not be used together with block" if block
           end
         end
       end