grape 2.4.0 → 3.2.1

data/lib/grape/util/api_description.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    class ApiDescription
+      DSL_METHODS = %i[
+        body_name
+        consumes
+        default
+        deprecated
+        detail
+        entity
+        headers
+        hidden
+        http_codes
+        is_array
+        named
+        nickname
+        params
+        produces
+        security
+        summary
+        tags
+      ].freeze
+
+      def initialize(description, endpoint_configuration, &)
+        @endpoint_configuration = endpoint_configuration
+        @attributes = { description: }
+        instance_eval(&)
+      end
+
+      DSL_METHODS.each do |attribute|
+        define_method attribute do |value|
+          @attributes[attribute] = value
+        end
+      end
+
+      alias success entity
+      alias failure http_codes
+
+      def configuration
+        @configuration ||= eval_endpoint_config(@endpoint_configuration)
+      end
+
+      def settings
+        @attributes
+      end
+
+      private
+
+      def eval_endpoint_config(configuration)
+        return configuration if configuration.is_a?(Hash)
+
+        configuration.evaluate
+      end
+    end
+  end
+end

data/lib/grape/util/base_inheritable.rb

@@ -14,8 +14,11 @@ module Grape
         @new_values = {}
       end
 
-      def delete(key)
-        new_values.delete key
+      def delete(*keys)
+        keys.map do |key|
+          # since delete returns the deleted value, seems natural to `map` the result
+          new_values.delete key
+        end
       end
 
       def initialize_copy(other)

data/lib/grape/util/cache.rb

@@ -9,6 +9,7 @@ module Grape
 
       class << self
         extend Forwardable
+
         def_delegators :cache, :[]
         def_delegators :instance, :cache
       end

data/lib/grape/util/deep_freeze.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module DeepFreeze
+      module_function
+
+      # Recursively freezes Hash (keys and values), Array (elements), and String
+      # objects. All other types are returned as-is.
+      #
+      # Intentionally left unfrozen:
+      #   - Procs / lambdas — may be deferred DB-backed callables
+      #   - Coercers (e.g. ArrayCoercer) — use lazy ivar memoization at request time
+      #   - Classes / Modules — shared constants that must remain open
+      #   - ParamsScope — self-freezes at the end of its own initialize
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each do |k, v|
+            deep_freeze(k)
+            deep_freeze(v)
+          end
+          obj.freeze
+        when Array
+          obj.each { |v| deep_freeze(v) }
+          obj.freeze
+        when String
+          obj.freeze
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/grape/util/inheritable_setting.rb

@@ -55,7 +55,7 @@ module Grape
         namespace_reverse_stackable.inherited_values = parent.namespace_reverse_stackable
         self.route = parent.route.merge(route)
 
-        point_in_time_copies.map { |cloned_one| cloned_one.inherit_from parent }
+        point_in_time_copies.each { |cloned_one| cloned_one.inherit_from parent }
       end
 
       # Create a point-in-time copy of this settings instance, with clones of
@@ -95,6 +95,13 @@ module Grape
           namespace_reverse_stackable: namespace_reverse_stackable.to_hash
         }
       end
+
+      def namespace_stackable_with_hash(key)
+        data = namespace_stackable[key]
+        return if data.blank?
+
+        data.each_with_object({}) { |value, result| result.deep_merge!(value) }
+      end
     end
   end
 end

data/lib/grape/util/media_type.rb

@@ -7,7 +7,7 @@ module Grape
 
       # based on the HTTP Accept header with the pattern:
       # application/vnd.:vendor-:version+:format
-      VENDOR_VERSION_HEADER_REGEX = /\Avnd\.(?<vendor>[a-z0-9.\-_!^]+?)(?:-(?<version>[a-z0-9*.]+))?(?:\+(?<format>[a-z0-9*\-.]+))?\z/.freeze
+      VENDOR_VERSION_HEADER_REGEX = /\Avnd\.(?<vendor>[a-z0-9.\-_!^]+?)(?:-(?<version>[a-z0-9*.]+))?(?:\+(?<format>[a-z0-9*\-.]+))?\z/
 
       def initialize(type:, subtype:)
         @type = type
@@ -47,7 +47,7 @@ module Grape
           type, subtype = media_type.split('/', 2)
           return if type.blank? || subtype.blank?
 
-          new(type: type, subtype: subtype)
+          new(type:, subtype:)
         end
 
         def match?(media_type)

data/lib/grape/util/registry.rb

@@ -7,7 +7,7 @@ module Grape
         short_name = build_short_name(klass)
         return if short_name.nil?
 
-        warn "#{short_name} is already registered with class #{klass}" if registry.key?(short_name)
+        warn "#{short_name} is already registered with class #{registry[short_name]}. It will be overridden globally with the following: #{klass.name}" if registry.key?(short_name)
         registry[short_name] = klass
       end
 

data/lib/grape/util/translation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Translation
+      FALLBACK_LOCALE = :en
+      private_constant :FALLBACK_LOCALE
+      # Sentinel returned by I18n when a key is missing (passed as the default:
+      # value). Using a named class rather than plain Object.new makes it
+      # identifiable in debug output and immune to backends that call .to_s on
+      # the default before returning it.
+      MISSING = Class.new { def inspect = 'Grape::Util::Translation::MISSING' }.new.freeze
+      private_constant :MISSING
+
+      private
+
+      # Extra keyword args (**) are forwarded verbatim to I18n as interpolation
+      # variables (e.g. +min:+, +max:+ from LengthValidator's Hash message).
+      # Callers must not pass unintended keyword arguments — any extra keyword
+      # will silently become an I18n interpolation variable.
+      def translate(key, default: MISSING, scope: 'grape.errors.messages', locale: nil, **)
+        i18n_opts = { default:, scope:, ** }
+        i18n_opts[:locale] = locale if locale
+        message = ::I18n.translate(key, **i18n_opts)
+        return message unless message.equal?(MISSING)
+
+        effective_default = default.equal?(MISSING) ? [*Array(scope), key].join('.') : default
+        return effective_default if fallback_locale?(locale) || fallback_locale_unavailable?
+
+        ::I18n.translate(key, default: effective_default, scope:, locale: FALLBACK_LOCALE, **)
+      end
+
+      def fallback_locale?(locale)
+        (locale || ::I18n.locale) == FALLBACK_LOCALE
+      end
+
+      def fallback_locale_unavailable?
+        ::I18n.enforce_available_locales && !::I18n.available_locales.include?(FALLBACK_LOCALE)
+      end
+    end
+  end
+end

data/lib/grape/validations/attributes_iterator.rb

@@ -7,52 +7,67 @@ module Grape
 
       attr_reader :scope
 
-      def initialize(validator, scope, params)
+      def initialize(attrs, scope, params)
+        @attrs = attrs
         @scope = scope
-        @attrs = validator.attrs
         @original_params = scope.params(params)
         @params = Array.wrap(@original_params)
       end
 
-      def each(&block)
-        do_each(@params, &block) # because we need recursion for nested arrays
+      def each(&)
+        do_each(@params, &) # because we need recursion for nested arrays
       end
 
       private
 
-      def do_each(params_to_process, parent_indicies = [], &block)
-        @scope.reset_index # gets updated depending on the size of params_to_process
+      def do_each(params_to_process, parent_indices = [], &block)
         params_to_process.each_with_index do |resource_params, index|
           # when we get arrays of arrays it means that target element located inside array
-          # we need this because we want to know parent arrays indicies
+          # we need this because we want to know parent arrays indices
           if resource_params.is_a?(Array)
-            do_each(resource_params, [index] + parent_indicies, &block)
+            do_each(resource_params, [index] + parent_indices, &block)
             next
           end
 
           if @scope.type == Array
             next unless @original_params.is_a?(Array) # do not validate content of array if it isn't array
 
-            # fill current and parent scopes with correct array indicies
-            parent_scope = @scope.parent
-            parent_indicies.each do |parent_index|
-              parent_scope.index = parent_index
-              parent_scope = parent_scope.parent
-            end
-            @scope.index = index
+            store_indices(@scope, index, parent_indices)
+          elsif @original_params.is_a?(Array)
+            # Lateral scope (no @element) whose params resolved to an array —
+            # delegate index tracking to the nearest array-typed ancestor so
+            # that full_name produces the correct bracketed index.
+            target = @scope.nearest_array_ancestor
+            store_indices(target, index, parent_indices) if target
           end
 
-          yield_attributes(resource_params, @attrs, &block)
+          yield_attributes(resource_params, &block)
         end
       end
 
-      def yield_attributes(_resource_params, _attrs)
+      def store_indices(target_scope, index, parent_indices)
+        # No tracker means we're outside a ParamScopeTracker.track block (e.g.
+        # a unit test that invokes a validator directly). Index tracking is
+        # skipped — full_name will produce bracket-less names — but validation
+        # continues rather than crashing.
+        tracker = ParamScopeTracker.current or return
+        parent_scope = target_scope.parent
+        parent_indices.each do |parent_index|
+          break unless parent_scope
+
+          tracker.store_index(parent_scope, parent_index)
+          parent_scope = parent_scope.parent
+        end
+        tracker.store_index(target_scope, index)
+      end
+
+      def yield_attributes(_resource_params)
         raise NotImplementedError
       end
 
-      # This is a special case so that we can ignore tree's where option
-      # values are missing lower down. Unfortunately we can remove this
-      # are the parameter parsing stage as they are required to ensure
+      # This is a special case so that we can ignore trees where option
+      # values are missing lower down. Unfortunately we can't remove this
+      # at the parameter parsing stage as they are required to ensure
       # the correct indexing is maintained
       def skip?(val)
         val == Grape::DSL::Parameters::EmptyOptionalValue

data/lib/grape/validations/contract_scope.rb

@@ -20,14 +20,8 @@ module Grape
           key_map = contract.key_map
         end
 
-        api.namespace_stackable(:contract_key_map, key_map)
-
-        validator_options = {
-          validator_class: Grape::Validations.require_validator(:contract_scope),
-          opts: { schema: contract, fail_fast: false }
-        }
-
-        api.namespace_stackable(:validations, validator_options)
+        api.inheritable_setting.namespace_stackable[:contract_key_map] = key_map
+        api.inheritable_setting.namespace_stackable[:validations] = Validators::ContractScopeValidator.new(schema: contract)
       end
     end
   end

data/lib/grape/validations/multiple_attributes_iterator.rb

@@ -5,7 +5,7 @@ module Grape
     class MultipleAttributesIterator < AttributesIterator
       private
 
-      def yield_attributes(resource_params, _attrs)
+      def yield_attributes(resource_params)
         yield resource_params unless skip?(resource_params)
       end
     end

data/lib/grape/validations/param_scope_tracker.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    # Holds per-request mutable state that must not live on shared ParamsScope
+    # instances. Both trackers are identity-keyed hashes so that ParamsScope
+    # objects can serve as keys without relying on value equality.
+    #
+    # Lifecycle is managed by Endpoint#run_validators via +.track+.
+    # Use +.current+ to access the instance for the running request.
+    class ParamScopeTracker
+      # Fiber-local key used to store the current tracker.
+      # Fiber[] (Ruby 3.0+) is used instead of Thread.current[] so that
+      # fiber-based servers (e.g. Falcon with async) isolate each request's
+      # tracker within its own fiber rather than sharing state across all
+      # fibers running on the same thread.
+      FIBER_KEY = :grape_param_scope_tracker
+      EMPTY_PARAMS = [].freeze
+
+      def self.track
+        previous = Fiber[FIBER_KEY]
+        Fiber[FIBER_KEY] = new
+        yield
+      ensure
+        Fiber[FIBER_KEY] = previous
+      end
+
+      def self.current
+        Fiber[FIBER_KEY]
+      end
+
+      def initialize
+        @index_tracker = {}.compare_by_identity
+        @qualifying_params_tracker = {}.compare_by_identity
+      end
+
+      def store_index(scope, index)
+        @index_tracker.store(scope, index)
+      end
+
+      def index_for(scope)
+        @index_tracker[scope]
+      end
+
+      # Returns qualifying params for +scope+, or EMPTY_PARAMS if none were stored.
+      # Note: an explicitly stored empty array and "never stored" are treated identically
+      # by callers (both yield a blank result that falls through to the parent params).
+      def qualifying_params(scope)
+        @qualifying_params_tracker.fetch(scope, EMPTY_PARAMS)
+      end
+
+      def store_qualifying_params(scope, params)
+        @qualifying_params_tracker.store(scope, params)
+      end
+    end
+  end
+end

data/lib/grape/validations/params_documentation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    # Documents parameters of an endpoint. If documentation isn't needed (for instance, it is an
+    # internal API), the class only cleans up attributes to avoid junk in RAM.
+
+    module ParamsDocumentation
+      def document_params(attrs, validations, type = nil, values = nil, except_values = nil)
+        return validations.except!(:desc, :description, :documentation) if @api.inheritable_setting.namespace_inheritable[:do_not_document]
+
+        documented_attrs = attrs.each_with_object({}) do |name, memo|
+          memo[full_name(name)] = extract_details(validations, type, values, except_values)
+        end
+        @api.inheritable_setting.namespace_stackable[:params] = documented_attrs
+      end
+
+      private
+
+      def extract_details(validations, type, values, except_values)
+        {}.tap do |details|
+          details[:required] = validations.key?(:presence)
+          details[:type] = TypeCache[type] if type
+          details[:values] = values if values
+          details[:except_values] = except_values if except_values
+          details[:default] = validations[:default] if validations.key?(:default)
+          if validations.key?(:length)
+            details[:min_length] = validations[:length][:min] if validations[:length].key?(:min)
+            details[:max_length] = validations[:length][:max] if validations[:length].key?(:max)
+          end
+
+          desc = validations.delete(:desc) || validations.delete(:description)
+          details[:desc] = desc if desc
+
+          documentation = validations.delete(:documentation)
+          details[:documentation] = documentation if documentation
+        end
+      end
+
+      class TypeCache < Grape::Util::Cache
+        def initialize
+          super
+          @cache = Hash.new do |h, type|
+            h[type] = type.to_s
+          end
+        end
+      end
+    end
+  end
+end