grape 1.8.0 → 4.0.1

data/lib/grape/util/lazy/base.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Lazy
+      # Abstract parent for lazy wrappers used by the remount/configuration
+      # machinery. Call sites can type-check with +is_a?(Grape::Util::Lazy::Base)+
+      # instead of enumerating the concrete subclasses.
+      class Base
+        def to_s
+          evaluate.to_s
+        end
+      end
+    end
+  end
+end

data/lib/grape/util/lazy/block.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Lazy
+      class Block < Base
+        def initialize(&new_block)
+          super()
+          @block = new_block
+        end
+
+        def evaluate_from(configuration)
+          @block.call(configuration)
+        end
+
+        def evaluate
+          @block.call({})
+        end
+      end
+    end
+  end
+end

data/lib/grape/util/lazy/value.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Lazy
+      class Value < Base
+        attr_reader :access_keys
+
+        def initialize(value, access_keys = [])
+          super()
+          @value = value
+          @access_keys = access_keys
+        end
+
+        def evaluate_from(configuration)
+          matching_lazy_value = configuration.fetch(@access_keys)
+          matching_lazy_value.evaluate
+        end
+
+        def evaluate
+          @value
+        end
+
+        def reached_by(parent_access_keys, access_key)
+          @access_keys = parent_access_keys + [access_key]
+          self
+        end
+      end
+    end
+  end
+end

data/lib/grape/util/lazy/value_array.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Lazy
+      class ValueArray < ValueEnumerable
+        def initialize(array)
+          super
+          @value_hash = []
+          array.each_with_index do |value, index|
+            self[index] = value
+          end
+        end
+
+        def evaluate
+          @value_hash.map(&:evaluate)
+        end
+      end
+    end
+  end
+end

data/lib/grape/util/lazy/value_enumerable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Lazy
+      class ValueEnumerable < Value
+        def [](key)
+          return Value.new(nil).reached_by(access_keys, key) if @value_hash[key].nil?
+
+          @value_hash[key].reached_by(access_keys, key)
+        end
+
+        def fetch(access_keys)
+          access_keys.reduce(self) { |node, key| node[key] }
+        end
+
+        def []=(key, value)
+          value_class = case value
+                        when Hash
+                          ValueHash
+                        when Array
+                          ValueArray
+                        else
+                          Value
+                        end
+          @value_hash[key] = value_class.new(value)
+        end
+      end
+    end
+  end
+end

data/lib/grape/util/lazy/value_hash.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Lazy
+      class ValueHash < ValueEnumerable
+        def initialize(hash)
+          super
+          @value_hash = ActiveSupport::HashWithIndifferentAccess.new
+          hash.each do |key, value|
+            self[key] = value
+          end
+        end
+
+        def evaluate
+          @value_hash.transform_values(&:evaluate)
+        end
+      end
+    end
+  end
+end

data/lib/grape/util/media_type.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    class MediaType
+      attr_reader :type, :subtype, :vendor, :version, :format
+
+      # based on the HTTP Accept header with the pattern:
+      # application/vnd.:vendor-:version+:format
+      #
+      # Matched against a down-cased media type: they are case-insensitive
+      # (RFC 9110 §8.3.1), while a vendor and version are declared in the DSL
+      # in the case they will be compared in.
+      VENDOR_VERSION_HEADER_REGEX = /\Avnd\.(?<vendor>[a-z0-9.\-_!^]+?)(?:-(?<version>[a-z0-9*.]+))?(?:\+(?<format>[a-z0-9*\-.]+))?\z/
+
+      def initialize(type:, subtype:)
+        @type = type
+        @subtype = subtype
+        VENDOR_VERSION_HEADER_REGEX.match(subtype) do |m|
+          @vendor = m[:vendor]
+          @version = m[:version]
+          @format = m[:format]
+        end
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          other.type == type &&
+          other.subtype == subtype &&
+          other.vendor == vendor &&
+          other.version == version &&
+          other.format == format
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, type, subtype, vendor, version, format].hash
+      end
+
+      class << self
+        def best_quality(header, available_media_types)
+          parse(best_quality_media_type(header, available_media_types))
+        end
+
+        def parse(media_type)
+          return if media_type.blank?
+
+          type, subtype = media_type.downcase.split('/', 2)
+          return if type.blank? || subtype.blank?
+
+          new(type:, subtype:)
+        end
+
+        def match?(media_type)
+          return false if media_type.blank?
+
+          subtype = media_type.downcase.split('/', 2).last
+          return false if subtype.blank?
+
+          VENDOR_VERSION_HEADER_REGEX.match?(subtype)
+        end
+
+        # The available types are registered in lower case and Rack matches them
+        # literally, so the header has to be down-cased to be compared against
+        # them at all.
+        def best_quality_media_type(header, available_media_types)
+          header.blank? ? available_media_types.first : Rack::Utils.best_q_match(header.downcase, available_media_types)
+        end
+      end
+
+      private_class_method :best_quality_media_type
+    end
+  end
+end

data/lib/grape/util/path_normalizer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module PathNormalizer
+      # Taken from Rails
+      #     call("/foo")  # => "/foo"
+      #     call("/foo/") # => "/foo"
+      #     call("foo")   # => "/foo"
+      #     call("")      # => "/"
+      #     call("/%ab")  # => "/%AB"
+      # https://github.com/rails/rails/blob/00cc4ff0259c0185fe08baadaa40e63ea2534f6e/actionpack/lib/action_dispatch/journey/router/utils.rb#L19
+      def self.call(path)
+        return '/' unless path
+        return path if path == '/'
+
+        # Fast path for the overwhelming majority of paths that don't need to be
+        # normalized. Two String#include? calls rather than one `%|//` regexp:
+        # same predicate, and the scan stays in C without building a match.
+        return path if path.start_with?('/') && !(path.end_with?('/') || path.include?('%') || path.include?('//'))
+
+        # Slow path. The bangs below are safe because +normalized+ is a fresh
+        # String built here, never the one the caller passed in.
+        encoding = path.encoding
+        normalized = "/#{path}"
+        normalized.squeeze!('/')
+
+        unless normalized == '/'
+          normalized.delete_suffix!('/')
+          normalized.gsub!(/(%[a-f0-9]{2})/) { ::Regexp.last_match(1).upcase }
+        end
+
+        normalized.force_encoding(encoding)
+      end
+    end
+  end
+end

data/lib/grape/util/registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    module Registry
+      def register(klass)
+        short_name = build_short_name(klass)
+        return if short_name.nil?
+
+        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] = registry[short_name.to_sym] = klass
+      end
+
+      private
+
+      def build_short_name(klass)
+        return if klass.name.blank?
+
+        klass.name.demodulize.underscore
+      end
+
+      # Every registration under both spellings in one plain Hash, so a lookup
+      # is a single +Hash#[]+. A +HashWithIndifferentAccess+ converted the key
+      # on every read instead -- and these registries are read on the request
+      # path, by +Grape::Formatter+ once per response, by +Grape::Parser+ once
+      # per parsed body and by +Grape::ParamsBuilder+ once per params build,
+      # always with a Symbol, which is the spelling +convert_key+ allocates a
+      # String for.
+      #
+      # +register+ derives the short name as a String, so the Symbol is the
+      # alias.
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/grape/util/shadowed_rescue_handlers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    # Diagnostics for +rescue_from+ registrations that can never run.
+    #
+    # Middleware::Error resolves with +find+, so within a scope the first
+    # matching class wins and one registered for a class an earlier handler
+    # already covers is dead code — silently, before this warned:
+    #
+    #   rescue_from StandardError do ... end   # wins
+    #   rescue_from ArgumentError do ... end   # never runs
+    #
+    # Warn rather than reorder: which should win is the author's call, and
+    # +rescue_from :all+ (consulted only after the registered handlers) already
+    # offers "broad first, specific still wins" to anyone who wants it.
+    module ShadowedRescueHandlers
+      module_function
+
+      # @param registered [Hash] the scope's own handlers, in registration order
+      # @param mapping [Hash] the handlers being registered now
+      # @return [void]
+      #
+      # Only a scope's own registrations are compared: across scopes the nearest
+      # one deliberately wins, so an inner +rescue_from StandardError+ shadowing
+      # an outer +rescue_from ArgumentError+ is the documented behaviour rather
+      # than a mistake. Classes sharing a handler object are skipped too, since
+      # +rescue_from A, B+ registers one handler for both and the entry that
+      # loses to the other changes nothing.
+      def warn_about(registered, mapping)
+        return if registered.empty?
+
+        mapping.each do |klass, handler|
+          covered_by, = registered.find { |already, existing| klass <= already && !existing.equal?(handler) }
+          next unless covered_by
+
+          warn(message_for(klass, covered_by))
+        end
+      end
+
+      def message_for(klass, covered_by)
+        return "Grape: rescue_from #{klass} was already registered in this scope; the first handler is kept and this one will never run." if klass == covered_by
+
+        "Grape: rescue_from #{klass} will never run — #{covered_by} was registered earlier in the same scope " \
+          'and is matched first. Register the more specific class before the broader one.'
+      end
+    end
+  end
+end

data/lib/grape/util/stackable_values.rb

@@ -1,28 +1,55 @@
 # frozen_string_literal: true
 
-require_relative 'base_inheritable'
-
 module Grape
   module Util
-    class StackableValues < BaseInheritable
-      # Even if there is no value, an empty array will be returned.
+    # A read-only view of one settings scope's stackable registrations.
+    #
+    # Grape stores nothing here anymore: the registrations live on
+    # Grape::Util::InheritableSetting, one Array per key per scope, and are
+    # reached through its semantic accessors (+helpers+, +middleware+,
+    # +namespaces+, ...). This class survives only because grape-swagger
+    # reads InheritableSetting#namespace_stackable directly — including
+    # walking the #inherited_values chain and reading each level's own
+    # #new_values to recover per-scope registrations — and is expected to be
+    # removed once grape-swagger reads those accessors instead.
+    #
+    # Instances are built on demand by InheritableSetting#namespace_stackable
+    # and are not the backing store: writing to #new_values does not register
+    # anything.
+    class StackableValues
+      EMPTY = [].freeze
+
+      attr_reader :inherited_values, :new_values
+
+      # @param new_values [Hash, nil] the scope's own registrations, one Array
+      #   per key; nil when the scope never registered anything.
+      # @param inherited_values [StackableValues, Hash] the enclosing scope's
+      #   view, or an empty Hash at the root of the chain.
+      def initialize(new_values, inherited_values)
+        @new_values = new_values
+        @inherited_values = inherited_values
+      end
+
+      # Outermost scope first. Even if there is no value, an empty (frozen)
+      # array will be returned.
       def [](name)
-        inherited_value = inherited_values[name]
-        new_value = new_values[name]
+        inherited_value = @inherited_values[name]
+        new_value = @new_values && @new_values[name]
 
-        return new_value || [] unless inherited_value
+        return new_value || EMPTY unless inherited_value
 
         concat_values(inherited_value, new_value)
       end
 
-      def []=(name, value)
-        new_values[name] ||= []
-        new_values[name].push value
+      def keys
+        return @inherited_values.keys if @new_values.nil? || @new_values.empty?
+
+        (@inherited_values.keys + @new_values.keys).uniq
       end
 
       def to_hash
-        keys.each_with_object({}) do |key, result|
-          result[key] = self[key]
+        keys.to_h do |key|
+          [key, self[key]]
         end
       end
 
@@ -31,10 +58,7 @@ module Grape
       def concat_values(inherited_value, new_value)
         return inherited_value unless new_value
 
-        [].tap do |value|
-          value.concat(inherited_value)
-          value.concat(new_value)
-        end
+        inherited_value + new_value
       end
     end
   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

@@ -3,55 +3,88 @@
 module Grape
   module Validations
     class AttributesIterator
-      include Enumerable
-
-      attr_reader :scope
-
-      def initialize(validator, scope, params)
+      # +attrs+ and +scope+ are static per validator; only +params+ varies
+      # per request, so an instance can be built once and reused (it keeps
+      # no request-derived state). Reused instances are shared across
+      # threads, so +each+ must stay free of mutable instance state.
+      def initialize(attrs, scope)
+        @attrs = attrs
         @scope = scope
-        @attrs = validator.attrs
-        @original_params = scope.params(params)
-        @params = Array.wrap(@original_params)
+        # How many times #do_each may descend into a nested array. The
+        # declaration allows one level per Array-typed scope on the chain, less
+        # the one +Array.wrap+ already consumes in #each. Anything deeper was
+        # put there by the request, not by the declaration.
+        @max_nesting = [scope.array_depth - 1, 0].max
       end
 
-      def each(&block)
-        do_each(@params, &block) # because we need recursion for nested arrays
+      def each(params, &)
+        original_params = @scope.params(params)
+        # A scope resolves to a Hash unless the declaration nests arrays, and
+        # then #do_each has nothing to do but hand it straight back: Array.wrap
+        # boxes it, the loop unboxes it on its only iteration, and with no Array
+        # anywhere neither the nesting descent nor the index bookkeeping
+        # applies. Every validator on a flat +params+ block comes through here.
+        return yield_attributes(original_params, &) if original_params.is_a?(Hash) && !@scope.iterates_elements?
+
+        # because we need recursion for nested arrays
+        do_each(Array.wrap(original_params), original_params, &)
       end
 
       private
 
-      def do_each(params_to_process, parent_indicies = [], &block)
+      def do_each(params_to_process, original_params, 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
-          if resource_params.is_a?(Array)
-            do_each(resource_params, [index] + parent_indicies, &block)
+          # we need this because we want to know parent arrays indices
+          #
+          # Only descend as far as the declaration nests. A request that wraps
+          # its elements deeper than that is yielded as-is, so the attribute
+          # validators see a non-hash and fail it the same way any other
+          # unexpected element type does.
+          if resource_params.is_a?(Array) && parent_indices.size < @max_nesting
+            do_each(resource_params, original_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
+          if @scope.iterates_elements?
+            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 element-iterating 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 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, _attrs)
+      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/coerce_options.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    # Immutable value object describing how a parameter is coerced. Assembled
+    # by {ValidationsSpec#coerce_options} from the parsed +type+/+coerce_with+/
+    # +coerce_message+ declaration — never written by the user — and consumed
+    # by {ParamsScope#check_coerce_with} / {ParamsScope#validate_coerce} and by
+    # {Validators::Validators::CoerceValidator} (which receives it as its
+    # +options+ argument).
+    #
+    # All three fields may be +nil+ (e.g. a remountable API evaluated on its
+    # base instance has no resolved +type+ yet).
+    # +coerce_method+ (not +method+) avoids shadowing +Object#method+.
+    CoerceOptions = Data.define(:type, :coerce_method, :message) do
+      def initialize(type: nil, coerce_method: nil, message: nil)
+        super
+      end
+    end
+  end
+end

data/lib/grape/validations/contract_scope.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    class ContractScope
+      # Declare the contract to be used for the endpoint's parameters.
+      # @param api [API] the API endpoint to modify.
+      # @param contract the contract or schema to be used for validation. Optional.
+      # @yield a block yielding a new schema class. Optional.
+      def initialize(api, contract = nil, &block)
+        # When block is passed, the first arg is either schema or nil.
+        declared = block ? Dry::Schema.Params(parent: contract, &block) : contract
+
+        if declared.respond_to?(:schema)
+          # It's a Dry::Validation::Contract, then.
+          schema = declared.new
+          key_map = schema.schema.key_map
+        else
+          # Dry::Schema::Processor, hopefully.
+          schema = declared
+          key_map = declared.key_map
+        end
+
+        api.inheritable_setting.add_contract_key_map(key_map)
+        api.inheritable_setting.add_validation(Validators::ContractScopeValidator.new(schema:))
+      end
+    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