grape 0.1.1 → 2.4.0

data/lib/grape/validations/types/custom_type_coercer.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # This class will detect type classes that implement
+      # a class-level +parse+ method. The method should accept one
+      # +String+ argument and should return the value coerced to
+      # the appropriate type. The method may raise an exception if
+      # there are any problems parsing the string.
+      #
+      # Alternately an optional +method+ may be supplied (see the
+      # +coerce_with+ option of {Grape::Dsl::Parameters#requires}).
+      # This may be any class or object implementing +parse+ or +call+,
+      # with the same contract as described above.
+      #
+      # Type Checking
+      # -------------
+      #
+      # Calls to +coerced?+ will consult this class to check
+      # that the coerced value produced above is in fact of the
+      # expected type. By default this class performs a basic check
+      # against the type supplied, but this behaviour will be
+      # overridden if the class implements a class-level
+      # +coerced?+ or +parsed?+ method. This method
+      # will receive a single parameter that is the coerced value
+      # and should return +true+ if the value meets type expectations.
+      # Arbitrary assertions may be made here but the grape validation
+      # system should be preferred.
+      #
+      # Alternately a proc or other object responding to +call+ may be
+      # supplied in place of a type. This should implement the same
+      # contract as +coerced?+, and must be supplied with a coercion
+      # +method+.
+      class CustomTypeCoercer
+        # A new coercer for the given type specification
+        # and coercion method.
+        #
+        # @param type [Class,#coerced?,#parsed?,#call?]
+        #   specifier for the target type. See class docs.
+        # @param method [#parse,#call]
+        #   optional coercion method. See class docs.
+        def initialize(type, method = nil)
+          coercion_method = infer_coercion_method type, method
+          @method = enforce_symbolized_keys type, coercion_method
+          @type_check = infer_type_check(type)
+        end
+
+        # Coerces the given value.
+        #
+        # @param value [String] value to be coerced, in grape
+        #   this should always be a string.
+        # @return [Object] the coerced result
+        def call(val)
+          coerced_val = @method.call(val)
+
+          return coerced_val if coerced_val.is_a?(InvalidValue)
+          return InvalidValue.new unless coerced?(coerced_val)
+
+          coerced_val
+        end
+
+        def coerced?(val)
+          val.nil? || @type_check.call(val)
+        end
+
+        private
+
+        # Determine the coercion method we're expected to use
+        # based on the parameters given.
+        #
+        # @param type see #new
+        # @param method see #new
+        # @return [#call] coercion method
+        def infer_coercion_method(type, method)
+          if method
+            if method.respond_to? :parse
+              method.method :parse
+            else
+              method
+            end
+          else
+            # Try to use parse() declared on the target type.
+            # This may raise an exception, but we are out of ideas anyway.
+            type.method :parse
+          end
+        end
+
+        # Determine how the type validity of a coerced
+        # value should be decided.
+        #
+        # @param type see #new
+        # @return [#call] a procedure which accepts a single parameter
+        #   and returns +true+ if the passed object is of the correct type.
+        def infer_type_check(type)
+          # First check for special class methods
+          if type.respond_to? :coerced?
+            type.method :coerced?
+          elsif type.respond_to? :parsed?
+            type.method :parsed?
+          elsif type.respond_to? :call
+            # Arbitrary proc passed for type validation.
+            # Note that this will fail unless a method is also
+            # passed, or if the type also implements a parse() method.
+            type
+          elsif type.is_a?(Enumerable)
+            lambda do |value|
+              value.is_a?(Enumerable) && value.all? do |val|
+                recursive_type_check(type.first, val)
+              end
+            end
+          else
+            # By default, do a simple type check
+            ->(value) { value.is_a? type }
+          end
+        end
+
+        def recursive_type_check(type, value)
+          if type.is_a?(Enumerable) && value.is_a?(Enumerable)
+            value.all? { |val| recursive_type_check(type.first, val) }
+          else
+            !type.is_a?(Enumerable) && value.is_a?(type)
+          end
+        end
+
+        # Enforce symbolized keys for complex types
+        # by wrapping the coercion method such that
+        # any Hash objects in the immediate heirarchy
+        # have their keys recursively symbolized.
+        # This helps common libs such as JSON to work easily.
+        #
+        # @param type see #new
+        # @param method see #infer_coercion_method
+        # @return [#call] +method+ wrapped in an additional
+        #   key-conversion step, or just returns +method+
+        #   itself if no conversion is deemed to be
+        #   necessary.
+        def enforce_symbolized_keys(type, method)
+          # Collections have all values processed individually
+          if [Array, Set].include?(type)
+            lambda do |val|
+              method.call(val).tap do |new_val|
+                new_val.map do |item|
+                  item.is_a?(Hash) ? item.deep_symbolize_keys : item
+                end
+              end
+            end
+
+          # Hash objects are processed directly
+          elsif type == Hash
+            lambda do |val|
+              method.call(val).deep_symbolize_keys
+            end
+
+          # Simple types are not processed.
+          # This includes Array<primitive> types.
+          else
+            method
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/custom_type_collection_coercer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # See {CustomTypeCoercer} for details on types
+      # that will be supported by this by this coercer.
+      # This coercer works in the same way as +CustomTypeCoercer+
+      # except that it expects to receive an array of strings to
+      # coerce and will return an array (or optionally, a set)
+      # of coerced values.
+      #
+      # +CustomTypeCoercer+ is already capable of providing type
+      # checking for arrays where an independent coercion method
+      # is supplied. As such, +CustomTypeCollectionCoercer+ does
+      # not allow for such a method to be supplied independently
+      # of the type.
+      class CustomTypeCollectionCoercer < CustomTypeCoercer
+        # A new coercer for collections of the given type.
+        #
+        # @param type [Class,#parse]
+        #   type to which items in the array should be coerced.
+        #   Must implement a +parse+ method which accepts a string,
+        #   and for the purposes of type-checking it may either be
+        #   a class, or it may implement a +coerced?+, +parsed?+ or
+        #   +call+ method (in that order of precedence) which
+        #   accepts a single argument and returns true if the given
+        #   array item has been coerced correctly.
+        # @param set [Boolean]
+        #   when true, a +Set+ will be returned by {#call} instead
+        #   of an +Array+ and duplicate items will be discarded.
+        def initialize(type, set = false)
+          super(type)
+          @set = set
+        end
+
+        # Coerces the given value.
+        #
+        # @param value [Array<String>] an array of values to be coerced
+        # @return [Array,Set] the coerced result. May be an +Array+ or a
+        #   +Set+ depending on the setting given to the constructor
+        def call(value)
+          coerced = value.map do |item|
+            coerced_item = super(item)
+
+            return coerced_item if coerced_item.is_a?(InvalidValue)
+
+            coerced_item
+          end
+
+          @set ? Set.new(coerced) : coerced
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/dry_type_coercer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module DryTypes
+  # Call +Dry.Types()+ to add all registered types to +DryTypes+ which is
+  # a container in this case. Check documentation for more information
+  # https://dry-rb.org/gems/dry-types/1.2/getting-started/
+  include Dry.Types()
+end
+
+module Grape
+  module Validations
+    module Types
+      # A base class for classes which must identify a coercer to be used.
+      # If the +strict+ argument is true, it won't coerce the given value
+      # but check its type. More information there
+      # https://dry-rb.org/gems/dry-types/1.2/built-in-types/
+      class DryTypeCoercer
+        class << self
+          # Returns a collection coercer which corresponds to a given type.
+          # Example:
+          #
+          #    collection_coercer_for(Array)
+          #    #=> Grape::Validations::Types::ArrayCoercer
+          def collection_coercer_for(type)
+            case type
+            when Array
+              ArrayCoercer
+            when Set
+              SetCoercer
+            else
+              raise ArgumentError, "Unknown type: #{type}"
+            end
+          end
+
+          # Returns an instance of a coercer for a given type
+          def coercer_instance_for(type, strict = false)
+            klass = type.instance_of?(Class) ? PrimitiveCoercer : collection_coercer_for(type)
+            klass.new(type, strict)
+          end
+        end
+
+        def initialize(type, strict = false)
+          @type = type
+          @strict = strict
+          @scope = strict ? DryTypes::Strict : DryTypes::Params
+        end
+
+        # Coerces the given value to a type which was specified during
+        # initialization as a type argument.
+        #
+        # @param val [Object]
+        def call(val)
+          return if val.nil?
+
+          @coercer[val]
+        rescue Dry::Types::CoercionError => _e
+          InvalidValue.new
+        end
+
+        protected
+
+        attr_reader :scope, :type, :strict
+      end
+    end
+  end
+end

data/lib/grape/validations/types/file.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # Implementation for parameters that are multipart file objects.
+      # Actual handling of these objects is provided by +Rack::Request+;
+      # this class is here only to assert that rack's handling has succeeded.
+      class File
+        class << self
+          def parse(input)
+            return if input.nil?
+            return InvalidValue.new unless parsed?(input)
+
+            # Processing of multipart file objects
+            # is already taken care of by Rack::Request.
+            # Nothing to do here.
+            input
+          end
+
+          def parsed?(value)
+            # Rack::Request creates a Hash with filename,
+            # content type and an IO object. Do a bit of basic
+            # duck-typing.
+            value.is_a?(::Hash) && value.key?(:tempfile) && value[:tempfile].is_a?(Tempfile)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/invalid_value.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # Instances of this class may be used as tokens to denote that a parameter value could not be
+      # coerced. The given message will be used as a validation error.
+      class InvalidValue
+        attr_reader :message
+
+        def initialize(message = nil)
+          @message = message
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/json.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # Handles coercion and type checking for parameters that are complex
+      # types given as JSON-encoded strings. It accepts both JSON objects
+      # and arrays of objects, and will coerce the input to a +Hash+
+      # or +Array+ object respectively. In either case the Grape
+      # validation system will apply nested validation rules to
+      # all returned objects.
+      class Json
+        class << self
+          # Coerce the input into a JSON-like data structure.
+          #
+          # @param input [String] a JSON-encoded parameter value
+          # @return [Hash,Array<Hash>,nil]
+          def parse(input)
+            return input if parsed?(input)
+
+            # Allow nulls and blank strings
+            return if input.nil? || input.match?(/^\s*$/)
+
+            JSON.parse(input, symbolize_names: true)
+          end
+
+          # Checks that the input was parsed successfully
+          # and isn't something odd such as an array of primitives.
+          #
+          # @param value [Object] result of {#parse}
+          # @return [true,false]
+          def parsed?(value)
+            value.is_a?(::Hash) || coerced_collection?(value)
+          end
+
+          protected
+
+          # Is the value an array of JSON-like objects?
+          #
+          # @param value [Object] result of {#parse}
+          # @return [true,false]
+          def coerced_collection?(value)
+            value.is_a?(::Array) && value.all?(::Hash)
+          end
+        end
+      end
+
+      # Specialization of the {Json} attribute that is guaranteed
+      # to return an array of objects. Accepts both JSON-encoded
+      # objects and arrays of objects, but wraps single objects
+      # in an Array.
+      class JsonArray < Json
+        class << self
+          # See {Json#parse}. Wraps single objects in an array.
+          #
+          # @param input [String] JSON-encoded parameter value
+          # @return [Array<Hash>]
+          def parse(input)
+            json = super
+            Array.wrap(json) unless json.nil?
+          end
+
+          # See {Json#coerced_collection?}
+          def parsed?(value)
+            coerced_collection? value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/multiple_type_coercer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # This class is intended for use with Grape endpoint parameters that
+      # have been declared to be of variant-type using the +:types+ option.
+      # +MultipleTypeCoercer+ will build a coercer for each type declared
+      # in the array passed to +:types+ using {Types.build_coercer}. It will
+      # apply these coercers to parameter values in the order given to
+      # +:types+, and will return the value returned by the first coercer
+      # to successfully coerce the parameter value. Therefore if +String+ is
+      # an allowed type it should be declared last, since it will always
+      # successfully "coerce" the value.
+      class MultipleTypeCoercer
+        # Construct a new coercer that will attempt to coerce
+        # values to the given list of types in the given order.
+        #
+        # @param types [Array<Class>] list of allowed types
+        # @param method [#call,#parse] method by which values should be
+        #   coerced. See class docs for default behaviour.
+        def initialize(types, method = nil)
+          @method = method.respond_to?(:parse) ? method.method(:parse) : method
+
+          @type_coercers = types.map do |type|
+            if Types.multiple? type
+              VariantCollectionCoercer.new type, @method
+            else
+              Types.build_coercer type, strict: !@method.nil?
+            end
+          end
+        end
+
+        # Coerces the given value.
+        #
+        # @param val [String] value to be coerced, in grape
+        #   this should always be a string.
+        # @return [Object,InvalidValue] the coerced result, or an instance
+        #   of {InvalidValue} if the value could not be coerced.
+        def call(val)
+          # once the value is coerced by the custom method, its type should be checked
+          val = @method.call(val) if @method
+
+          coerced_val = InvalidValue.new
+
+          @type_coercers.each do |coercer|
+            coerced_val = coercer.call(val)
+
+            return coerced_val unless coerced_val.is_a?(InvalidValue)
+          end
+
+          coerced_val
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/primitive_coercer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # Coerces the given value to a type defined via a +type+ argument during
+      # initialization. When +strict+ is true, it doesn't coerce a value but check
+      # that it has the proper type.
+      class PrimitiveCoercer < DryTypeCoercer
+        MAPPING = {
+          Grape::API::Boolean => DryTypes::Params::Bool,
+          BigDecimal => DryTypes::Params::Decimal,
+          Numeric => DryTypes::Params::Integer | DryTypes::Params::Float | DryTypes::Params::Decimal,
+          TrueClass => DryTypes::Params::Bool.constrained(eql: true),
+          FalseClass => DryTypes::Params::Bool.constrained(eql: false),
+
+          # unfortunately, a +Params+ scope doesn't contain String
+          String => DryTypes::Coercible::String
+        }.freeze
+
+        STRICT_MAPPING = {
+          Grape::API::Boolean => DryTypes::Strict::Bool,
+          BigDecimal => DryTypes::Strict::Decimal,
+          Numeric => DryTypes::Strict::Integer | DryTypes::Strict::Float | DryTypes::Strict::Decimal,
+          TrueClass => DryTypes::Strict::Bool.constrained(eql: true),
+          FalseClass => DryTypes::Strict::Bool.constrained(eql: false)
+        }.freeze
+
+        def initialize(type, strict = false)
+          super
+
+          @type = type
+
+          @coercer = (strict ? STRICT_MAPPING : MAPPING).fetch(type) do
+            scope.const_get(type.name, false)
+          rescue NameError
+            raise ArgumentError, "type #{type} should support coercion via `[]`" unless type.respond_to?(:[])
+
+            type
+          end
+        end
+
+        def call(val)
+          return InvalidValue.new if reject?(val)
+          return nil if val.nil? || treat_as_nil?(val)
+
+          super
+        end
+
+        protected
+
+        attr_reader :type
+
+        # This method maintains logic which was defined by Virtus. For example,
+        # dry-types is ok to convert an array or a hash to a string, it is supported,
+        # but Virtus wouldn't accept it. So, this method only exists to not introduce
+        # breaking changes.
+        def reject?(val)
+          (val.is_a?(Array) && type == String) ||
+            (val.is_a?(String) && type == Hash) ||
+            (val.is_a?(Hash) && type == String)
+        end
+
+        # Dry-Types treats an empty string as invalid. However, Grape considers an empty string as
+        # absence of a value and coerces it into nil. See a discussion there
+        # https://github.com/ruby-grape/grape/pull/2045
+        def treat_as_nil?(val)
+          val == '' && type != String
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/set_coercer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # Takes the given array and converts it to a set. Every element of the set
+      # is also coerced.
+      class SetCoercer < ArrayCoercer
+        def initialize(type, strict = false)
+          super
+
+          @coercer = nil
+        end
+
+        def call(value)
+          return InvalidValue.new unless value.is_a?(Array)
+
+          coerce_elements(value)
+        end
+
+        protected
+
+        def coerce_elements(collection)
+          collection.each_with_object(Set.new) do |elem, memo|
+            coerced_elem = elem_coercer.call(elem)
+
+            return coerced_elem if coerced_elem.is_a?(InvalidValue)
+
+            memo.add(coerced_elem)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/validations/types/variant_collection_coercer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    module Types
+      # This class wraps {MultipleTypeCoercer}, for use with collections
+      # that allow members of more than one type.
+      class VariantCollectionCoercer
+        # Construct a new coercer that will attempt to coerce
+        # a list of values such that all members are of one of
+        # the given types. The container may also optionally be
+        # coerced to a +Set+. An arbitrary coercion +method+ may
+        # be supplied, which will be passed the entire collection
+        # as a parameter and should return a new collection, or
+        # may return the same one if no coercion was required.
+        #
+        # @param types [Array<Class>,Set<Class>] list of allowed types,
+        #   also specifying the container type
+        # @param method [#call,#parse] method by which values should be coerced
+        def initialize(types, method = nil)
+          @types = types
+          @method = method.respond_to?(:parse) ? method.method(:parse) : method
+
+          # If we have a coercion method, pass it in here to save
+          # building another one, even though we call it directly.
+          @member_coercer = MultipleTypeCoercer.new types, method
+        end
+
+        # Coerce the given value.
+        #
+        # @param value [Array<String>] collection of values to be coerced
+        # @return [Array<Object>,Set<Object>,InvalidValue]
+        #   the coerced result, or an instance
+        #   of {InvalidValue} if the value could not be coerced.
+        def call(value)
+          return unless value.is_a? Array
+
+          value =
+            if @method
+              @method.call(value)
+            else
+              value.map { |v| @member_coercer.call(v) }
+            end
+          return Set.new value if @types.is_a? Set
+
+          value
+        end
+      end
+    end
+  end
+end