grape 1.8.0 → 4.0.1

data/lib/grape/content_types.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
-require 'grape/util/registrable'
-
 module Grape
   module ContentTypes
-    extend Util::Registrable
+    module_function
 
     # Content types are listed in order of preference.
-    CONTENT_TYPES = {
+    DEFAULTS = {
       xml: 'application/xml',
       serializable_hash: 'application/json',
       json: 'application/json',
@@ -15,13 +13,73 @@ module Grape
       txt: 'text/plain'
     }.freeze
 
-    class << self
-      def content_types_for_settings(settings)
-        settings&.inject(:merge!)
+    MIME_TYPES = Grape::ContentTypes::DEFAULTS.except(:serializable_hash).invert.freeze
+
+    def content_types_for(from_settings)
+      from_settings.presence || DEFAULTS
+    end
+
+    def mime_types_for(from_settings)
+      return MIME_TYPES if from_settings == Grape::ContentTypes::DEFAULTS
+
+      MimeTypesCache[from_settings]
+    end
+
+    # Every format under both spellings in one plain Hash, so a lookup is a
+    # single +Hash#[]+. +HashWithIndifferentAccess+ converted the key on every
+    # read instead, and this is read two or three times per request — to
+    # negotiate the format, and again to set the response content type.
+    #
+    # Keys arrive as Symbols: the +content_type+ DSL symbolizes what it is
+    # given and the defaults are Symbols. The key is stored as it came too,
+    # so a middleware constructed directly with String keys still answers to
+    # either spelling, as the indifferent hash did.
+    def lookup_for(from_settings)
+      LookupCache[from_settings]
+    end
+
+    # The media type of a content-type header: the part before any `;`
+    # parameters, with surrounding whitespace removed
+    # (e.g. `'text/html'` for `'text/html; charset=utf-8'`). Returns nil for a
+    # nil content type. Skips the split (and its allocation) when there are no
+    # parameters, which is the common case.
+    def media_type(content_type)
+      return if content_type.nil?
+
+      base = content_type.include?(';') ? content_type.split(';', 2).first : content_type
+      base.strip
+    end
+
+    # Both tables below are derived from nothing but the content-type registry,
+    # and one content-type-aware middleware is built per API instance — so an
+    # app mounting N APIs held N copies of tables it only ever reads. Keying
+    # the cache on the registry itself collapses them: Hash keys compare by
+    # value, so every API that registers the same content types shares one
+    # table.
+    #
+    # Both the key and the table are frozen: the caller's registry stays
+    # reachable (through +middleware.options[:content_types]+, among others)
+    # and mutating a live key would corrupt a cache that is now shared
+    # process-wide.
+
+    class MimeTypesCache < Grape::Util::Cache
+      def initialize
+        super
+        @cache = Hash.new do |h, from_settings|
+          h[from_settings.dup.freeze] = from_settings.invert.transform_keys! { |mime_type| Grape::ContentTypes.media_type(mime_type) }.freeze
+        end
       end
+    end
 
-      def content_types_for(from_settings)
-        from_settings.presence || Grape::ContentTypes::CONTENT_TYPES.merge(default_elements)
+    class LookupCache < Grape::Util::Cache
+      def initialize
+        super
+        @cache = Hash.new do |h, from_settings|
+          h[from_settings.dup.freeze] = from_settings.each_with_object({}) do |(format, media_type), lookup|
+            lookup[format] = media_type
+            lookup[format.is_a?(String) ? format.to_sym : format.to_s] = media_type
+          end.freeze
+        end
       end
     end
   end

data/lib/grape/cookies.rb

@@ -2,42 +2,45 @@
 
 module Grape
   class Cookies
-    def initialize
-      @cookies = {}
-      @send_cookies = {}
-    end
+    extend Forwardable
 
-    def read(request)
-      request.cookies.each do |name, value|
-        @cookies[name.to_s] = value
-      end
-    end
+    DELETED_COOKIES_ATTRS = {
+      max_age: '0',
+      value: '',
+      expires: Time.at(0)
+    }.freeze
 
-    def write(header)
-      @cookies.select { |key, _value| @send_cookies[key] == true }.each do |name, value|
-        cookie_value = value.is_a?(Hash) ? value : { value: value }
-        Rack::Utils.set_cookie_header! header, name, cookie_value
-      end
+    def_delegators :cookies, :[], :each
+
+    def initialize(rack_cookies)
+      @cookies = ActiveSupport::HashWithIndifferentAccess.new(rack_cookies)
+      @send_cookies = nil
     end
 
-    def [](name)
-      @cookies[name.to_s]
+    def response_cookies
+      return unless @send_cookies
+
+      send_cookies.each do |name|
+        yield name, cookies[name]
+      end
     end
 
     def []=(name, value)
-      @cookies[name.to_s] = value
-      @send_cookies[name.to_s] = true
+      cookies[name] = value
+      send_cookies << name
     end
 
-    def each(&block)
-      @cookies.each(&block)
+    # see https://github.com/rack/rack/blob/main/lib/rack/utils.rb#L338-L340
+    def delete(name, **opts)
+      self.[]=(name, opts.merge(DELETED_COOKIES_ATTRS))
     end
 
-    # rubocop:disable Layout/SpaceBeforeBrackets
-    def delete(name, **opts)
-      options = opts.merge(value: 'deleted', expires: Time.at(0))
-      self.[]=(name, options)
+    private
+
+    attr_reader :cookies
+
+    def send_cookies
+      @send_cookies ||= Set.new
     end
-    # rubocop:enable Layout/SpaceBeforeBrackets
   end
 end

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

@@ -1,12 +1,54 @@
 # frozen_string_literal: true
 
-require 'dry-types'
-
 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,13 +3,14 @@
 module Grape
   module DSL
     module Desc
-      include Grape::DSL::Settings
+      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
@@ -18,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
@@ -49,70 +53,28 @@ module Grape
       #       # ...
       #     end
       #
-      def desc(description, options = {}, &config_block)
-        if config_block
-          endpoint_configuration = if defined?(configuration)
-                                     # When the instance is mounted - the configuration is executed on mount time
-                                     if configuration.respond_to?(:evaluate)
-                                       configuration.evaluate
-                                     # Within `given` or `mounted blocks` the configuration is already evaluated
-                                     elsif configuration.is_a?(Hash)
-                                       configuration
-                                     end
-                                   end
-          endpoint_configuration ||= {}
-          config_class = desc_container(endpoint_configuration)
-
-          config_class.configure do
-            description description
-          end
-
-          config_class.configure(&config_block)
-          ActiveSupport::Deprecation.warn('Passing a options hash and a block to `desc` is deprecated. Move all hash options to block.') if options.any?
-          options = config_class.settings
-        else
-          options = options.merge(description: description)
-        end
-
-        namespace_setting :description, options
-        route_setting :description, options
-      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(
-            :summary,
-            :description,
-            :detail,
-            :params,
-            :entity,
-            :http_codes,
-            :named,
-            :body_name,
-            :headers,
-            :hidden,
-            :deprecated,
-            :is_array,
-            :nickname,
-            :produces,
-            :consumes,
-            :security,
-            :tags,
-            :default
-          )
-          config_context.define_singleton_method(:configuration) do
-            endpoint_configuration
-          end
-
-          def config_context.success(*args)
-            entity(*args)
+      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
           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
+        # 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