grape 2.4.0 → 4.0.1

data/lib/grape/declared_params_handler.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Grape
+  class DeclaredParamsHandler
+    def initialize(include_missing: true, evaluate_given: false, stringify: false, contract_key_map: nil)
+      @include_missing = include_missing
+      @evaluate_given = evaluate_given
+      @stringify = stringify
+      @contract_key_map = contract_key_map
+    end
+
+    def call(passed_params, declared_params, route_params, renamed_params)
+      recursive_declared(
+        passed_params,
+        declared_params:,
+        route_params:,
+        renamed_params:
+      )
+    end
+
+    private
+
+    def recursive_declared(passed_params, declared_params:, route_params:, renamed_params:, params_nested_path: [])
+      res = if passed_params.is_a?(Array)
+              passed_params.map do |passed_param|
+                recursive_declared(passed_param, declared_params:, params_nested_path:, renamed_params:, route_params:)
+              end
+            else
+              declared_hash(passed_params, declared_params:, params_nested_path:, renamed_params:, route_params:)
+            end
+
+      @contract_key_map&.each { |key_map| key_map.write(passed_params, res) }
+
+      res
+    end
+
+    def declared_hash(passed_params, declared_params:, params_nested_path:, renamed_params:, route_params:)
+      declared_params.each_with_object(passed_params.class.new) do |declared_param_attr, memo|
+        next if @evaluate_given && !declared_param_attr.scope.attr_meets_dependency?(passed_params)
+
+        declared_hash_attr(
+          passed_params,
+          declared_param: declared_param_attr.key,
+          params_nested_path:,
+          memo:,
+          renamed_params:,
+          route_params:
+        )
+      end
+    end
+
+    def declared_hash_attr(passed_params, declared_param:, params_nested_path:, memo:, renamed_params:, route_params:)
+      return declare_leaf(passed_params, declared_param:, params_nested_path:, memo:, renamed_params:, route_params:) unless declared_param.is_a?(Hash)
+
+      declared_param.each_pair do |parent, children|
+        declare_nested(passed_params, parent:, children:, params_nested_path:, memo:, renamed_params:, route_params:)
+      end
+    end
+
+    def declare_nested(passed_params, parent:, children:, params_nested_path:, memo:, renamed_params:, route_params:)
+      return unless @include_missing || passed_params.key?(parent)
+
+      memo_key = build_memo_key(params_nested_path, parent, renamed_params)
+      passed_children = passed_params[parent] || passed_params.class.new
+      nested_path = nested_path_for(params_nested_path, parent)
+
+      memo[memo_key] = handle_passed_param(nested_path, route_params:, has_passed_children: passed_children.any?) do
+        recursive_declared(
+          passed_children,
+          declared_params: children,
+          params_nested_path: nested_path,
+          renamed_params:,
+          route_params:
+        )
+      end
+    end
+
+    # The declared param has no children. Find its value or set it to nil.
+    def declare_leaf(passed_params, declared_param:, params_nested_path:, memo:, renamed_params:, route_params:)
+      return unless @include_missing || (passed_params.respond_to?(:key?) && passed_params.key?(declared_param))
+
+      memo_key = build_memo_key(params_nested_path, declared_param, renamed_params)
+      passed_param = passed_params[declared_param]
+
+      memo[memo_key] = passed_param || handle_passed_param(nested_path_for(params_nested_path, declared_param), route_params:) do
+        passed_param
+      end
+    end
+
+    def build_memo_key(params_nested_path, declared_param, renamed_params)
+      renamed_param_name = renamed_params[nested_path_for(params_nested_path, declared_param)]
+      param = renamed_param_name || declared_param
+      @stringify ? param.to_s : param.to_sym
+    end
+
+    def nested_path_for(parent_path, key)
+      parent_path + [key.to_s]
+    end
+
+    def handle_passed_param(params_nested_path, route_params:, has_passed_children: false)
+      return yield if has_passed_children
+
+      key = params_nested_path.first
+      key += "[#{params_nested_path[1..].join('][')}]" if params_nested_path.size > 1
+
+      type = route_params.dig(key, :type)
+      return yield if type.nil?
+
+      return {} if type == 'Hash' && route_params.keys.none? { |k| k != key && k.start_with?("#{key}[") }
+      return [] if type == 'Array' || (type.start_with?('[') && !type.include?(','))
+      return Set.new if type == 'Set' || type.start_with?('#<Set', 'Set')
+
+      yield
+    end
+  end
+end

data/lib/grape/dry_types.rb

@@ -2,9 +2,53 @@
 
 module Grape
   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()
+    # https://dry-rb.org/gems/dry-types/main/getting-started/
+    # limit to what Grape is using
+    include Dry.Types(:params, :coercible, :strict)
+
+    class StrictCache < Grape::Util::Cache
+      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
+        super
+        @cache = Hash.new do |h, strict_type|
+          h[strict_type] = MAPPING.fetch(strict_type) do
+            DryTypes.wrapped_dry_types_const_get(DryTypes::Strict, strict_type)
+          end
+        end
+      end
+    end
+
+    class ParamsCache < Grape::Util::Cache
+      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),
+        String => DryTypes::Coercible::String
+      }.freeze
+
+      def initialize
+        super
+        @cache = Hash.new do |h, params_type|
+          h[params_type] = MAPPING.fetch(params_type) do
+            DryTypes.wrapped_dry_types_const_get(DryTypes::Params, params_type)
+          end
+        end
+      end
+    end
+
+    def self.wrapped_dry_types_const_get(dry_type, type)
+      dry_type.const_get(type.name, false)
+    rescue NameError
+      raise ArgumentError, "type `#{type}` should support coercion via `[]`" unless type.respond_to?(:[])
+    end
   end
 end

data/lib/grape/dsl/callbacks.rb

@@ -2,66 +2,16 @@
 
 module Grape
   module DSL
-    # Blocks can be executed before or after every API call, using `before`, `after`,
-    # `before_validation` and `after_validation`.
-    #
-    # Before and after callbacks execute in the following order:
-    #
-    # 1. `before`
-    # 2. `before_validation`
-    # 3. _validations_
-    # 4. `after_validation`
-    # 5. _the API call_
-    # 6. `after`
-    #
-    # Steps 4, 5 and 6 only happen if validation succeeds.
     module Callbacks
-      extend ActiveSupport::Concern
+      # before: execute the given block before validation, coercion, or any endpoint
+      # before_validation: execute the given block after `before`, but prior to validation or coercion
+      # after_validation: execute the given block after validations and coercions, but before any endpoint code
+      # after: execute the given block after the endpoint code has run except in unsuccessful
+      # finally: execute the given block after the endpoint code even if unsuccessful
 
-      include Grape::DSL::Configuration
-
-      module ClassMethods
-        # Execute the given block before validation, coercion, or any endpoint
-        # code is executed.
-        def before(&block)
-          namespace_stackable(:befores, block)
-        end
-
-        # Execute the given block after `before`, but prior to validation or
-        # coercion.
-        def before_validation(&block)
-          namespace_stackable(:before_validations, block)
-        end
-
-        # Execute the given block after validations and coercions, but before
-        # any endpoint code.
-        def after_validation(&block)
-          namespace_stackable(:after_validations, block)
-        end
-
-        # Execute the given block after the endpoint code has run.
-        def after(&block)
-          namespace_stackable(:afters, block)
-        end
-
-        # Allows you to specify a something that will always be executed after a call
-        # API call. Unlike the `after` block, this code will run even on
-        # unsuccesful requests.
-        # @example
-        #   class ExampleAPI < Grape::API
-        #     before do
-        #       ApiLogger.start
-        #     end
-        #     finally do
-        #       ApiLogger.close
-        #     end
-        #   end
-        #
-        # This will make sure that the ApiLogger is opened and closed around every
-        # request
-        # @param  ensured_block [Proc] The block to be executed after every api_call
-        def finally(&block)
-          namespace_stackable(:finallies, block)
+      %i[before before_validation after_validation after finally].each do |callback_name|
+        define_method callback_name do |&block|
+          inheritable_setting.add_callback(callback_name, block)
         end
       end
     end

data/lib/grape/dsl/declared.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Declared
+      # Denotes a situation where a DSL method has been invoked in a
+      # filter which it should not yet be available in
+      class MethodNotYetAvailable < StandardError
+        def initialize(msg = '#declared is not available prior to parameter validation')
+          super
+        end
+      end
+
+      # A filtering method that will return a hash
+      # consisting only of keys that have been declared by a
+      # `params` statement against the current/target endpoint or parent
+      # namespaces.
+      # @param params [Hash] The initial hash to filter. Usually this will just be `params`
+      # @param options [Hash] Can pass `:include_missing`, `:stringify` and `:include_parent_namespaces`
+      # options. `:include_parent_namespaces` defaults to true, hence must be set to false if
+      # you want only to return params declared against the current/target endpoint.
+      def declared(passed_params, include_parent_namespaces: true, include_missing: true, evaluate_given: false, stringify: false)
+        raise MethodNotYetAvailable unless before_filter_passed
+
+        contract_key_map = inheritable_setting.contract_key_maps
+        handler = DeclaredParamsHandler.new(include_missing:, evaluate_given:, stringify:, contract_key_map:)
+        declared_params = include_parent_namespaces ? inheritable_setting.route_declared_params : (inheritable_setting.declared_params.last || [])
+        renamed_params = inheritable_setting.route_renamed_params
+        route_params = config.params
+
+        handler.call(passed_params, declared_params, route_params, renamed_params)
+      end
+    end
+  end
+end

data/lib/grape/dsl/desc.rb

@@ -3,34 +3,14 @@
 module Grape
   module DSL
     module Desc
-      include Grape::DSL::Settings
-
-      ROUTE_ATTRIBUTES = %i[
-        body_name
-        consumes
-        default
-        deprecated
-        description
-        detail
-        entity
-        headers
-        hidden
-        http_codes
-        is_array
-        named
-        nickname
-        params
-        produces
-        security
-        summary
-        tags
-      ].freeze
+      extend Grape::DSL::Settings
 
       # Add a description to the next namespace or function.
       # @param description [String] descriptive string for this endpoint
       #   or namespace
       # @param options [Hash] other properties you can set to describe the
-      #   endpoint or namespace. Optional.
+      #   endpoint or namespace. Optional. Pass these as keyword arguments;
+      #   passing a positional options Hash is deprecated.
       # @option options :detail [String] additional detail about this endpoint
       # @option options :summary [String] summary for this endpoint
       # @option options :params [Hash] param types and info. normally, you set
@@ -39,6 +19,9 @@ module Grape
       #   successful call to this action
       # @option options :http_codes [Array[Array]] possible HTTP codes this
       #   endpoint may return, with their meanings, in a 2d array
+      # @option options :default_response [Hash] the definition and entity used
+      #   to present this endpoint's default response. Was `:default`, which is
+      #   deprecated.
       # @option options :named [String] a specific name to help find this route
       # @option options :body_name [String] override the autogenerated body name param
       # @option options :headers [Hash] HTTP headers this method can accept
@@ -70,54 +53,28 @@ module Grape
       #       # ...
       #     end
       #
-      def desc(description, options = nil, &config_block)
-        opts =
-          if config_block
-            desc_container(endpoint_configuration).then do |config_class|
-              config_class.configure do
-                description(description)
-              end
-
-              config_class.configure(&config_block)
-              config_class.settings
-            end
+      def desc(description, **options, &config_block)
+        resolved_options =
+          if options.key?(:default)
+            Grape.deprecator.warn('The `default` option of `desc` is deprecated. Use `default_response` instead.')
+            # Rebuilt rather than mutated in place: an explicit +default_response+
+            # still wins, since the merged Hash is the one that keeps its key.
+            { default_response: options[:default] }.merge(options.except(:default))
           else
-            options&.merge(description: description) || { description: description }
-          end
-
-        namespace_setting :description, opts
-        route_setting :description, opts
-      end
-
-      # Returns an object which configures itself via an instance-context DSL.
-      def desc_container(endpoint_configuration)
-        Module.new do
-          include Grape::Util::StrictHashConfiguration.module(*ROUTE_ATTRIBUTES)
-          config_context.define_singleton_method(:configuration) do
-            endpoint_configuration
+            options
           end
 
-          def config_context.success(*args)
-            entity(*args)
-          end
-
-          def config_context.failure(*args)
-            http_codes(*args)
+        settings =
+          if config_block
+            endpoint_config = defined?(configuration) ? configuration : nil
+            Grape::Util::ApiDescription.new(description, endpoint_config, &config_block).settings
+          else
+            resolved_options.merge(description:)
           end
-        end
-      end
-
-      private
-
-      def endpoint_configuration
-        return {} unless defined?(configuration)
-
-        if configuration.respond_to?(:evaluate)
-          configuration.evaluate
-          # Within `given` or `mounted blocks` the configuration is already evaluated
-        elsif configuration.is_a?(Hash)
-          configuration
-        end
+        # Only the route scope is consumed downstream (by +route+ and the
+        # route's readers, e.g. +http_codes+); the namespace scope was
+        # write-only, so it is no longer populated.
+        inheritable_setting.route_description = settings
       end
     end
   end

data/lib/grape/dsl/entity.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Entity
+      # Allows you to make use of Grape Entities by setting
+      # the response body to the serializable hash of the
+      # entity provided in the `:with` option. This has the
+      # added benefit of automatically passing along environment
+      # and version information to the serialization, making it
+      # very easy to do conditional exposures. See Entity docs
+      # for more info.
+      #
+      # @param args [Array] either `(object)` or `(key, object)` where key is a Symbol
+      #   used to nest the representation under that key in the response body.
+      # @param root [Symbol, String, nil] wraps the representation under this root key.
+      # @param with [Class, nil] the entity class to use for representation.
+      #   If omitted, the entity class is inferred from the object via {#entity_class_for_obj}.
+      # @param options [Hash] additional options forwarded to the entity's `represent` call.
+      #
+      # @example
+      #
+      #   get '/users/:id' do
+      #     present User.find(params[:id]),
+      #       with: API::Entities::User,
+      #       admin: current_user.admin?
+      #   end
+      def present(*args, root: nil, with: nil, **options)
+        key, object = args.count == 2 && args.first.is_a?(Symbol) ? args : [nil, args.first]
+        entity_class = with || entity_class_for_obj(object)
+        representation = entity_class ? entity_representation_for(entity_class, object, options) : object
+        representation = { root => representation } if root
+
+        if key
+          representation = body&.merge(key => representation) || { key => representation }
+        elsif entity_class.present? && body
+          raise ArgumentError, "representation of type `#{representation.class}` cannot be merged" unless representation.respond_to?(:merge)
+
+          representation = body.merge(representation)
+        end
+
+        body representation
+      end
+
+      # Attempt to locate the Entity class for a given object, if not given
+      # explicitly. This is done by looking for the presence of Klass::Entity,
+      # where Klass is the class of the `object` parameter, or one of its
+      # ancestors. Object is excluded from the search: top-level constants
+      # live on it, so a global ::Entity class is not a representer.
+      # @param object [Object] the object to locate the Entity class for
+      # @return [Class] the located Entity class, or nil if none is found
+      def entity_class_for_obj(object)
+        entity_for_class(object.class) || entity_for_class(element_class(object))
+      end
+
+      private
+
+      # The class standing in for a collection or wrapper: ActiveRecord::Relation
+      # and the like expose #klass, anything else falls back to the class of its
+      # first element.
+      #
+      # Consulted only once the object's own class has come up empty, because
+      # both tests are duck-typed and plenty of single objects answer them —
+      # a Struct is Enumerable, so it responds to #first, and so does any model
+      # that includes Enumerable. Asking this first meant `represent Model,
+      # with: Entity` was silently ignored for those, the entity for the
+      # *element* type being looked up instead. Deferring it also keeps #first
+      # from being called at all when the object resolves on its own class.
+      #
+      # @param object [Object] the object to represent.
+      # @return [Class, nil]
+      def element_class(object)
+        return object.klass if object.respond_to?(:klass)
+
+        object.first.class if object.respond_to?(:first)
+      end
+
+      # @param klass [Class, nil] the class to look an entity up for.
+      # @return [Class, nil] the registered or conventionally named entity.
+      def entity_for_class(klass)
+        return if klass.nil?
+
+        representations = inheritable_setting.representations
+        if representations
+          potential = klass.ancestors.detect { |ancestor| representations.key?(ancestor) }
+          return representations[potential] if potential && representations[potential]
+        end
+
+        owner = klass.ancestors.detect { |ancestor| ancestor != Object && ancestor.const_defined?(:Entity, false) }
+        return unless owner
+
+        entity = owner.const_get(:Entity, false)
+        entity if entity.respond_to?(:represent)
+      end
+
+      # @param entity_class [Class] the entity class to use for representation.
+      # @param object [Object] the object to represent.
+      # @param options [Hash] additional options forwarded to the entity's `represent` call.
+      # @return the representation of the given object as done through the given entity_class.
+      def entity_representation_for(entity_class, object, options)
+        embeds = env.key?(Grape::Env::API_VERSION) ? { env:, version: env[Grape::Env::API_VERSION] } : { env: }
+        entity_class.represent(object, **embeds, **options)
+      end
+    end
+  end
+end