grape 0.13.0 → 0.14.0

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

@@ -0,0 +1,53 @@
+module Grape
+  module Validations
+    module Types
+      # Work out the +Virtus::Attribute+ object to
+      # use for coercing strings to the given +type+.
+      # Coercion +method+ will be inferred if none is
+      # supplied.
+      #
+      # If a +Virtus::Attribute+ object already built
+      # with +Virtus::Attribute.build+ is supplied as
+      # the +type+ it will be returned and +method+
+      # will be ignored.
+      #
+      # See {CustomTypeCoercer} for further details
+      # about coercion and type-checking inference.
+      #
+      # @param type [Class] the type to which input strings
+      #   should be coerced
+      # @param method [Class,#call] the coercion method to use
+      # @return [Virtus::Attribute] object to be used
+      #   for coercion and type validation
+      def self.build_coercer(type, method = nil)
+        # Accept pre-rolled virtus attributes without interference
+        return type if type.is_a? Virtus::Attribute
+
+        converter_options = {
+          nullify_blank: true
+        }
+        conversion_type = type
+
+        # Use a special coercer for multiply-typed parameters.
+        if Types.multiple?(type)
+          converter_options[:coercer] = Types::MultipleTypeCoercer.new(type, method)
+          conversion_type = Object
+
+        # Use a special coercer for custom types and coercion methods.
+        elsif method || Types.custom?(type)
+          converter_options[:coercer] = Types::CustomTypeCoercer.new(type, method)
+
+        # Grape swaps in its own Virtus::Attribute implementations
+        # for certain special types that merit first-class support
+        # (but not if a custom coercion method has been supplied).
+        elsif Types.special?(type)
+          conversion_type = Types::SPECIAL[type]
+        end
+
+        # Virtus will infer coercion and validation rules
+        # for many common ruby types.
+        Virtus::Attribute.build(conversion_type, converter_options)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+module Grape
+  module Validations
+    module Types
+      # Instances of this class may be passed to
+      # +Virtus::Attribute.build+ as the +:coercer+
+      # option for custom types that do not otherwise
+      # satisfy the requirements for +Virtus::Attribute::coerce+
+      # and +Virtus::Attribute::value_coerced?+ to work
+      # as expected.
+      #
+      # Subclasses of +Virtus::Attribute+ or +Axiom::Types::Type+
+      # (or for which an axiom type can be inferred, i.e. the
+      # primitives, +Date+, +Time+, etc.) do not need any such
+      # coercer to be passed with them.
+      #
+      # Coercion
+      # --------
+      #
+      # 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 +value_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+ iff 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
+        # Uses +Virtus::Attribute.build+ to build a new
+        # attribute that makes use of this class for
+        # coercion and type validation logic.
+        #
+        # @return [Virtus::Attribute]
+        def self.build(type, method = nil)
+          Virtus::Attribute.build(type, coercer: new(type, method))
+        end
+
+        # 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
+
+        # This method is called from somewhere within
+        # +Virtus::Attribute::coerce+ in order to coerce
+        # 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(value)
+          @method.call value
+        end
+
+        # This method is called from somewhere within
+        # +Virtus::Attribute::value_coerced?+ in order to
+        # assert that the value has been coerced successfully.
+        #
+        # @param _primitive [Axiom::Types::Type] primitive type
+        #   for the coercion as detected by axiom-types' inference
+        #   system. For custom types this is typically not much use
+        #   (i.e. it is +Axiom::Types::Object+) unless special
+        #   inference rules have been declared for the type.
+        # @param value [Object] a coerced result returned from {#call}
+        # @return [true,false] whether or not the coerced value
+        #   satisfies type requirements.
+        def success?(_primitive, value)
+          @type_check.call value
+        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
+          else
+            # By default, do a simple type check
+            ->(value) { 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
+        # are passed through +Hashie.symbolize_keys!+.
+        # 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 type == Array || type == Set
+            lambda do |val|
+              method.call(val).tap do |new_value|
+                new_value.each do |item|
+                  Hashie.symbolize_keys!(item) if item.is_a? Hash
+                end
+              end
+            end
+
+          # Hash objects are processed directly
+          elsif type == Hash
+            lambda do |val|
+              Hashie.symbolize_keys! method.call(val)
+            end
+
+          # Simple types are not processed.
+          # This includes Array<primitive> types.
+          else
+            method
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module Grape
+  module Validations
+    module Types
+      # +Virtus::Attribute+ 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, and to prevent virtus
+      # from interfering.
+      class File < Virtus::Attribute
+        def coerce(input)
+          # Processing of multipart file objects
+          # is already taken care of by Rack::Request.
+          # Nothing to do here.
+          input
+        end
+
+        def value_coerced?(value)
+          # Rack::Request creates a Hash with filename,
+          # content type and an IO object. Grape wraps that
+          # using hashie for convenience. Do a bit of basic
+          # duck-typing.
+          value.is_a?(Hashie::Mash) && value.key?(:tempfile)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+require 'json'
+
+module Grape
+  module Validations
+    module Types
+      # +Virtus::Attribute+ implementation that 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 < Virtus::Attribute
+        # Coerce the input into a JSON-like data structure.
+        #
+        # @param input [String] a JSON-encoded parameter value
+        # @return [Hash,Array<Hash>,nil]
+        def coerce(input)
+          # Allow nulls and blank strings
+          return if input.nil? || input =~ /^\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 {#coerce}
+        # @return [true,false]
+        def value_coerced?(value)
+          value.is_a?(::Hash) || coerced_collection?(value)
+        end
+
+        protected
+
+        # Is the value an array of JSON-like objects?
+        #
+        # @param value [Object] result of {#coerce}
+        # @return [true,false]
+        def coerced_collection?(value)
+          value.is_a?(::Array) && value.all? { |i| i.is_a? ::Hash }
+        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
+        # See {Json#coerce}. Wraps single objects in an array.
+        #
+        # @param input [String] JSON-encoded parameter value
+        # @return [Array<Hash>]
+        def coerce(input)
+          json = super
+          Array.wrap(json) unless json.nil?
+        end
+
+        # See {Json#coerced_collection?}
+        def value_coerced?(value)
+          coerced_collection? value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+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
+            else
+              Types.build_coercer type
+            end
+          end
+        end
+
+        # This method is called from somewhere within
+        # +Virtus::Attribute::coerce+ in order to coerce
+        # the given value.
+        #
+        # @param value [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(value)
+          return @method.call(value) if @method
+
+          @type_coercers.each do |coercer|
+            coerced = coercer.coerce(value)
+
+            return coerced if coercer.value_coerced? coerced
+          end
+
+          # Declare that we couldn't coerce the value in such a way
+          # that Grape won't ask us again if the value is valid
+          InvalidValue.new
+        end
+
+        # This method is called from somewhere within
+        # +Virtus::Attribute::value_coerced?+ in order to
+        # assert that the value has been coerced successfully.
+        # Due to Grape's design this will in fact only be called
+        # if a custom coercion method is being used, since {#call}
+        # returns an {InvalidValue} object if the value could not
+        # be coerced.
+        #
+        # @param _primitive [Axiom::Types::Type] primitive type
+        #   for the coercion as detected by axiom-types' inference
+        #   system. For custom types this is typically not much use
+        #   (i.e. it is +Axiom::Types::Object+) unless special
+        #   inference rules have been declared for the type.
+        # @param value [Object] a coerced result returned from {#call}
+        # @return [true,false] whether or not the coerced value
+        #   satisfies type requirements.
+        def success?(_primitive, value)
+          @type_coercers.any? { |coercer| coercer.value_coerced? value }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Grape
+  module Validations
+    module Types
+      # This class wraps {MultipleTypeCoercer}, for use with collections
+      # that allow members of more than one type.
+      class VariantCollectionCoercer < Virtus::Attribute
+        # 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 coerce(value)
+          return InvalidValue.new 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
+
+        # Assert that the value has been coerced successfully.
+        #
+        # @param value [Object] a coerced result returned from {#coerce}
+        # @return [true,false] whether or not the coerced value
+        #   satisfies type requirements.
+        def value_coerced?(value)
+          value.is_a?(@types.class) &&
+            value.all? { |v| @member_coercer.success?(@types, v) }
+        end
+      end
+    end
+  end
+end