grape 4.0.1 → 4.1.0

data/lib/grape/util/inheritable_setting.rb

@@ -55,6 +55,29 @@ module Grape
         @global = {}
       end
 
+      # Declares a nearest-wins scalar per key: a nested scope's assignment
+      # overrides an inherited one, hence a plain +=+ writer rather than the
+      # +add_*+ writers of the stackable registrations, and a reader that
+      # resolves the key along the chain, nil when never set. The backing
+      # store is an internal detail.
+      def self.inheritable_property(*keys)
+        keys.each do |key|
+          define_method(key) { inheritable(key) }
+          define_method(:"#{key}=") { |value| set_inheritable(key, value) }
+        end
+      end
+
+      # Declares a scope flag per key: a bang method setting it, after which it
+      # applies to the scope and everything nested under it, and a predicate,
+      # false when never set. The backing store is an internal detail.
+      def self.inheritable_flag(*keys)
+        keys.each do |key|
+          define_method(:"#{key}!") { set_inheritable(key, true) }
+          define_method(:"#{key}?") { inheritable(key) == true }
+        end
+      end
+      private_class_method :inheritable_property, :inheritable_flag
+
       # Instantiate a new settings instance, with blank values. The fresh
       # instance can then be set to inherit from an existing instance (see
       # #inherit_from).
@@ -99,7 +122,7 @@ module Grape
 
       # Create a point-in-time copy of this settings instance, with clones of
       # all our values. Note that, should this instance's parent be set or
-      # changed via #inherit_from, it will copy that inheritence to any copies
+      # changed via #inherit_from, it will copy that inheritance to any copies
       # which were made.
       def point_in_time_copy
         new_setting = self.class.new
@@ -172,8 +195,8 @@ module Grape
       end
 
       # The route-scope settings handed to each Grape::Router::Route: every
-      # +route_setting+ registration plus the description, minus the internal
-      # param snapshots (#route_validations / #route_declared_params).
+      # +route_setting+ registration, the description and renamed params,
+      # minus #route_validations / #route_declared_params.
       def route_settings
         route.except(:declared_params, :validations)
       end
@@ -193,10 +216,10 @@ module Grape
       # follow the ones already seeded from the surrounding scopes.
       def inherit_route_params(parent)
         parent_validations = parent.validations
-        route_validations.concat(parent_validations) if parent_validations.any?
+        route_validations.concat(parent_validations) unless parent_validations.empty?
 
         parent_declared_params = parent.declared_params
-        route_declared_params.concat(parent_declared_params.flatten) if parent_declared_params.any?
+        route_declared_params.concat(parent_declared_params.flatten) unless parent_declared_params.empty?
       end
 
       # Return a serializable hash of our values.
@@ -228,12 +251,7 @@ module Grape
         # compared resolved.
         return to_hash == other.to_hash unless parent.equal?(other.parent)
 
-        same_own_store?(@stackable_values, other.stackable_values) &&
-          route == other.route &&
-          @namespace_inheritable == other.namespace_inheritable &&
-          namespace == other.namespace &&
-          rescue_handlers == other.rescue_handlers &&
-          base_only_rescue_handlers == other.base_only_rescue_handlers
+        same_own_state?(other)
       end
       alias eql? ==
 
@@ -442,9 +460,9 @@ module Grape
 
       # Middleware specs recorded by the middleware DSL (+use+, +insert+,
       # +insert_before+, +insert_after+; see DSL::Middleware), one
-      # [operation, *arguments] Array per registration, outermost scope
-      # first. Record them with #add_middleware; the backing store is an
-      # internal detail.
+      # [operation, *arguments, block] Array per registration, the block +nil+
+      # when none was given, outermost scope first. Record them with
+      # #add_middleware; the backing store is an internal detail.
       def middleware
         stacked(:middleware)
       end
@@ -490,7 +508,7 @@ module Grape
       end
 
       # The path a Grape API is mounted under, recorded on the mounted API's
-      # top-level settings by +mount+ (see DSL::Routing). Reading returns the
+      # top-level settings by +mount+ (see DSL::Mounting). Reading returns the
       # outermost mount path — nil when the API is not mounted; the backing
       # store is an internal detail.
       def mount_path
@@ -526,151 +544,51 @@ module Grape
       # +format+ is the enforced API format, +default_format+ the fallback
       # used when a request doesn't specify one, and
       # +default_error_formatter+ / +default_error_status+ shape error
-      # responses. Nearest-wins scalars — a nested scope's assignment
-      # overrides an inherited one, hence plain +=+ writers rather than the
-      # +add_*+ writers used for stackable registrations. Readers return nil
-      # when never set (Endpoint applies the request-serving fallbacks); the
-      # backing store is an internal detail.
-      def format
-        inheritable(:format)
-      end
-
-      def format=(format)
-        set_inheritable(:format, format)
-      end
-
-      def default_format
-        inheritable(:default_format)
-      end
-
-      def default_format=(default_format)
-        set_inheritable(:default_format, default_format)
-      end
-
-      def default_error_formatter
-        inheritable(:default_error_formatter)
-      end
-
-      def default_error_formatter=(formatter)
-        set_inheritable(:default_error_formatter, formatter)
-      end
+      # responses. Endpoint applies the request-serving fallbacks to a nil.
+      inheritable_property :format, :default_format, :default_error_formatter, :default_error_status
 
-      def default_error_status
-        inheritable(:default_error_status)
-      end
-
-      def default_error_status=(status)
-        set_inheritable(:default_error_status, status)
-      end
-
-      # Versioning state recorded by the routing DSL (see DSL::Routing):
+      # Versioning state recorded by the DSL (see DSL::Versioning and DSL::Routing):
       # +version+ holds the Array of version strings registered by the
       # +version+ DSL method, +version_options+ its DSL::VersionOptions
       # value object, and +root_prefix+ the path prefix set by +prefix+.
-      # Nearest-wins scalars with plain += writers; readers return nil when
-      # never set; the backing store is an internal detail.
-      def version
-        inheritable(:version)
-      end
+      inheritable_property :version, :version_options, :root_prefix
 
-      def version=(versions)
-        set_inheritable(:version, versions)
-      end
-
-      def version_options
-        inheritable(:version_options)
-      end
+      # Cascade flag assigned by the +cascade+ DSL. An explicit nil is distinct
+      # from never-set, which #cascade_defined? tells apart; when never set,
+      # Grape::API::Instance falls back to the version options' cascade, then true.
+      inheritable_property :cascade
 
-      def version_options=(options)
-        set_inheritable(:version_options, options)
-      end
-
-      def root_prefix
-        inheritable(:root_prefix)
-      end
-
-      def root_prefix=(prefix)
-        set_inheritable(:root_prefix, prefix)
-      end
-
-      # Cascade flag assigned by the +cascade+ DSL. An explicit nil is
-      # meaningful and distinct from never-set (the backing store is
-      # key-presence based), so #cascade_defined? reports whether any scope
-      # assigned it — Grape::API::Instance#cascade? falls back to the
-      # version options' cascade, then to true, when it was never assigned.
-      def cascade
-        inheritable(:cascade)
-      end
-
-      def cascade=(value)
-        set_inheritable(:cascade, value)
-      end
+      # The params-builder strategy set by +build_with+ (both the
+      # API-level DSL::Routing#build_with and the params-block
+      # DSL::Parameters#build_with write it), consumed when the endpoint
+      # builds its Grape::Request.
+      inheritable_property :build_params_with
 
-      def cascade_defined?
-        inheritable?(:cascade)
-      end
+      # The authentication configuration Hash recorded by the +auth+ DSL
+      # (see Middleware::Auth::DSL): {type:, proc:, **options}; nil when no
+      # authenticator is declared — Endpoint uses that to warn about
+      # unauthenticated bare Rack mounts.
+      inheritable_property :auth
 
       # Scope flags flipped by the routing DSL's bang methods (see
       # DSL::Routing#do_not_route_head! and friends; Validations::OneofCollector
-      # also flips +do_not_document!+): once set in a scope they apply to it
-      # and everything nested under it. Readers return false when never set;
-      # the backing store is an internal detail.
-      def do_not_route_head!
-        set_inheritable(:do_not_route_head, true)
-      end
+      # also flips +do_not_document!+).
+      inheritable_flag :do_not_route_head, :do_not_route_options, :do_not_document, :lint
 
-      def do_not_route_head?
-        inheritable(:do_not_route_head) == true
-      end
-
-      def do_not_route_options!
-        set_inheritable(:do_not_route_options, true)
-      end
-
-      def do_not_route_options?
-        inheritable(:do_not_route_options) == true
-      end
-
-      def do_not_document!
-        set_inheritable(:do_not_document, true)
-      end
-
-      def do_not_document?
-        inheritable(:do_not_document) == true
-      end
-
-      def lint!
-        set_inheritable(:lint, true)
-      end
-
-      def lint?
-        inheritable(:lint) == true
-      end
-
-      # The params-builder strategy set by +build_with+ (both the
-      # API-level DSL::Routing#build_with and the params-block
-      # DSL::Parameters#build_with write it), consumed when the endpoint
-      # builds its Grape::Request. Nearest-wins scalar; nil when never set;
-      # the backing store is an internal detail.
-      def build_params_with
-        inheritable(:build_params_with)
-      end
-
-      def build_params_with=(strategy)
-        set_inheritable(:build_params_with, strategy)
+      def cascade_defined?
+        inheritable?(:cascade)
       end
 
-      # The authentication configuration Hash recorded by the +auth+ DSL
-      # (see Middleware::Auth::DSL): {type:, proc:, **options}. Nearest-wins
-      # scalar; nil when no authenticator is declared — Endpoint uses that
-      # to warn about unauthenticated bare Rack mounts; the backing store is
-      # an internal detail.
-      def auth
-        inheritable(:auth)
+      # The logger assigned by the +logger+ DSL (see DSL::Logger), written to
+      # an API's top-level settings so that it reaches the APIs mounted under
+      # it. Nearest-wins scalar; nil when never set, where DSL::Logger falls
+      # back to its default; the backing store is an internal detail.
+      def logger
+        inheritable(:logger)
       end
 
-      def auth=(auth_options)
-        set_inheritable(:auth, auth_options)
+      def logger=(logger)
+        set_inheritable(:logger, logger)
       end
 
       # Immutable snapshot of the settings Router::Pattern::Path reads to
@@ -701,7 +619,7 @@ module Grape
       protected
 
       # This scope's own inheritable overrides, before inheritance; nil when
-      # the scope overrode nothing. Peer access for #copy_state_from.
+      # the scope overrode nothing. Peer access for #copy_state_from and #==.
       attr_reader :namespace_inheritable
 
       # The nearest scope's value for +key+: this scope's own override when it
@@ -723,9 +641,7 @@ module Grape
       end
 
       # Every inheritable value along the chain resolved into one Hash, nearest
-      # scope winning. Like #stacked it hands back the backing Hash when only
-      # one scope in the chain has values, so callers must treat the result as
-      # read-only.
+      # scope winning. May be the root scope's own Hash: treat it as read-only.
       def inheritable_values
         inherited = parent&.inheritable_values
         own = @namespace_inheritable
@@ -739,14 +655,12 @@ module Grape
       attr_reader :rescue_handler_maps
 
       # This scope's own stackable registrations, before inheritance; nil when
-      # the scope registered nothing. Peer access for #copy_state_from.
+      # the scope registered nothing. Peer access for #copy_state_from and #==.
       attr_reader :stackable_values
 
-      # Every registration for +key+ along the chain, outermost scope first.
-      # Returns the frozen EMPTY_STACK when nothing is registered anywhere, and
-      # — like the store it replaced — the backing Array itself when only this
-      # scope registered anything, so callers must treat the result as
-      # read-only.
+      # Every registration for +key+ along the chain, outermost scope first;
+      # the frozen EMPTY_STACK when there is none. May be the root scope's own
+      # Array: treat it as read-only.
       def stacked(key)
         inherited = parent&.stacked(key)
         own = @stackable_values&.[](key)
@@ -758,7 +672,7 @@ module Grape
       # Every key registered along the chain, outermost scope's keys first.
       def stacked_keys
         inherited = parent&.stacked_keys || EMPTY_STACK
-        return inherited if @stackable_values.blank?
+        return inherited if @stackable_values.nil? || @stackable_values.empty?
 
         (inherited + @stackable_values.keys).uniq
       end
@@ -816,11 +730,16 @@ module Grape
         keys.each { |key| @stackable_values.delete(key) }
       end
 
-      # Compares two lazily-allocated own-registration stores (see #stack and
-      # #add_rescue_handlers): nil and an emptied Hash both mean "this scope
-      # registered nothing", so #== must not tell them apart.
+      # #== between two scopes hanging off the same parent.
+      def same_own_state?(other)
+        same_own_store?(@stackable_values, other.stackable_values) && route == other.route && @namespace_inheritable == other.namespace_inheritable &&
+          namespace == other.namespace && rescue_handlers == other.rescue_handlers && base_only_rescue_handlers == other.base_only_rescue_handlers
+      end
+
+      # Compares two lazily-allocated own stackable stores (see #stack): nil and
+      # an emptied Hash both mean "registered nothing".
       def same_own_store?(mine, theirs)
-        return theirs.blank? if mine.blank?
+        return theirs.nil? || theirs.empty? if mine.nil? || mine.empty?
 
         mine == theirs
       end
@@ -829,7 +748,7 @@ module Grape
       # scope winning; nil when nothing is registered.
       def namespace_stackable_with_hash(key)
         data = stacked(key)
-        return if data.blank?
+        return if data.empty?
 
         data.each_with_object({}) { |value, result| result.deep_merge!(value) }
       end

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

@@ -3,27 +3,68 @@
 module Grape
   module Util
     module Lazy
+      # A read of a mount-time configuration, taken before there is one to read.
+      #
+      # A remountable API reads its configuration while its own class body runs,
+      # long before anybody mounts it and supplies one:
+      #
+      #   class Votes < Grape::API
+      #     get configuration[:path] do
+      #       configuration[:response]
+      #     end
+      #   end
+      #
+      #   Root.mount Votes, with: { path: 'votes', response: '10 votes' }
+      #
+      # +configuration[:path]+ cannot answer 'votes' yet, so it answers with a
+      # Value instead: the configuration it was read from, plus the path of keys
+      # taken to reach it. Grape records the +get+ step unevaluated and replays
+      # it once per mount, where {#evaluate_from} walks that same path through
+      # the configuration that mount supplied.
+      #
+      # Reads chain, so +configuration[:db][:host]+ and
+      # +configuration[:hosts][0]+ are Values holding a two-key path.
       class Value < Base
-        attr_reader :access_keys
+        attr_reader :path
 
-        def initialize(value, access_keys = [])
+        def initialize(config, path = [])
           super()
-          @value = value
-          @access_keys = access_keys
+          @config = config
+          @path = path
         end
 
-        def evaluate_from(configuration)
-          matching_lazy_value = configuration.fetch(@access_keys)
-          matching_lazy_value.evaluate
+        # @return [Value] the same read, one key deeper.
+        def [](key)
+          Value.new(@config, @path + [key])
+        end
+
+        # Writes back to the configuration this was read from, backing
+        # <tt>API.configure { |config| config[:key] = value }</tt>.
+        def []=(key, value)
+          evaluate[key] = value
         end
 
+        # @return [Object] what this path holds in the configuration it was read
+        #   from, or +nil+ where the path leads nowhere - which is every path on
+        #   a base instance, whose configuration stays empty until it is mounted.
         def evaluate
-          @value
+          at(@path)
+        end
+
+        # @return [Object] what this path holds in +configuration+, the
+        #   configuration of the instance being mounted right now.
+        def evaluate_from(configuration)
+          configuration.at(@path)
         end
 
-        def reached_by(parent_access_keys, access_key)
-          @access_keys = parent_access_keys + [access_key]
-          self
+        protected
+
+        def at(keys)
+          keys.reduce(@config) do |node, key|
+            break nil unless node.is_a?(Hash) || node.is_a?(Array)
+
+            node[key]
+          end
         end
       end
     end

data/lib/grape/util/media_type.rb

@@ -13,14 +13,40 @@ module Grape
       # 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]
+      # The pattern above cannot tell where a vendor ends and a version begins
+      # when either holds a hyphen, so it keeps hyphens out of the version: a
+      # dated version such as +2024-06-20+ read as vendor +acme-2024-06+ and
+      # version +20+. Given the vendor it is parsed for, the vendor is spelled
+      # out and everything after it up to the format is the version.
+      #
+      # Keyed by the vendors APIs declare, never by what a client sends.
+      class VendorVersionHeaderRegexCache < Grape::Util::Cache
+        def initialize
+          super
+          @cache = Hash.new do |h, vendor|
+            h[vendor] = /\Avnd\.(?<vendor>#{Regexp.escape(vendor)})(?:-(?<version>[a-z0-9*.-]+))?(?:\+(?<format>[a-z0-9*\-.]+))?\z/
+          end
+        end
+      end
+
+      # Immutable, strings included: the header versioner shares one instance
+      # per declared media type across every request that sends it, and these
+      # strings are what it writes into the env. The arguments are copied
+      # rather than frozen, as they are the caller's.
+      #
+      # A +subtype+ naming a vendor other than +vendor+ is parsed as it would
+      # be without one.
+      def initialize(type:, subtype:, vendor: nil)
+        @type = -type
+        @subtype = -subtype
+        match = VendorVersionHeaderRegexCache[vendor].match(@subtype) if vendor
+        match ||= VENDOR_VERSION_HEADER_REGEX.match(@subtype)
+        if match
+          @vendor = match[:vendor].freeze
+          @version = match[:version].freeze
+          @format = match[:format].freeze
         end
+        freeze
       end
 
       def ==(other)
@@ -38,26 +64,23 @@ module Grape
       end
 
       class << self
-        def best_quality(header, available_media_types)
-          parse(best_quality_media_type(header, available_media_types))
+        def best_quality(header, available_media_types, vendor: nil)
+          parse(best_quality_media_type(header, available_media_types), vendor:)
         end
 
-        def parse(media_type)
+        def parse(media_type, vendor: nil)
           return if media_type.blank?
 
           type, subtype = media_type.downcase.split('/', 2)
           return if type.blank? || subtype.blank?
 
-          new(type:, subtype:)
+          new(type:, subtype:, vendor:)
         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)
+          VENDOR_VERSION_HEADER_REGEX.match?(media_type.downcase.split('/', 2).last)
         end
 
         # The available types are registered in lower case and Rack matches them

data/lib/grape/util/path_normalizer.rb

@@ -19,8 +19,12 @@ module Grape
         # 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.
+        normalize(path)
+      end
+
+      # The slow path. The bangs are safe because +normalized+ is a fresh String
+      # built here, never the one the caller passed in.
+      def self.normalize(path)
         encoding = path.encoding
         normalized = "/#{path}"
         normalized.squeeze!('/')
@@ -32,6 +36,7 @@ module Grape
 
         normalized.force_encoding(encoding)
       end
+      private_class_method :normalize
     end
   end
 end

data/lib/grape/util/registry.rb

@@ -8,7 +8,7 @@ module Grape
         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
+        @registry = registry.merge(short_name => klass, short_name.to_sym => klass).freeze
       end
 
       private
@@ -29,8 +29,15 @@ module Grape
       #
       # +register+ derives the short name as a String, so the Symbol is the
       # alias.
+      #
+      # Registration replaces the Hash instead of writing into it, and freezes
+      # the replacement: a registry is written when a formatter, parser,
+      # params builder, validator or versioner class is defined, and from then
+      # on it is only ever looked up -- on the request path, at that. Nothing
+      # holding a registry can find it changed underneath, and nothing can
+      # write to one without going through +register+.
       def registry
-        @registry ||= {}
+        @registry ||= {}.freeze
       end
     end
   end

data/lib/grape/util/scrub.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    # Outside input -- a param, a header, a query value, a body a route sets
+    # -- can hold bytes its encoding does not allow: a query string
+    # percent-encoding half a character, say. Much of String raises on such a
+    # value (+blank?+'s whitespace regexp, +match?+, +downcase+), so it is
+    # scrubbed, or asked about through {.blank?}, before anything else reads
+    # it.
+    #
+    # Called on the module rather than included: an included +blank?+ that
+    # takes an argument would shadow +Object#blank?+, which +present?+ calls.
+    module Scrub
+      # +value+ with each invalid byte replaced, or +value+ itself when it
+      # holds none or is not a String.
+      def self.scrub(value)
+        return value if !value.respond_to?(:valid_encoding?) || value.valid_encoding?
+
+        value.scrub
+      end
+
+      # +value.blank?+, answered without the copy +scrub(value).blank?+ would
+      # build: a String holding an invalid byte is never blank, since an
+      # invalid byte is not whitespace.
+      def self.blank?(value)
+        return false if value.is_a?(String) && !value.valid_encoding?
+
+        value.blank?
+      end
+    end
+  end
+end

data/lib/grape/util/translation.rb

@@ -6,9 +6,7 @@ module Grape
       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.
+      # value). Its +inspect+ names it in debug output.
       MISSING = Class.new { def inspect = 'Grape::Util::Translation::MISSING' }.new.freeze
       private_constant :MISSING
 
@@ -24,10 +22,12 @@ module Grape
         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?
+        # Only a call without +default:+ gets here: I18n answers any other with
+        # that default, so a miss falls back to the key's full path instead.
+        scoped_key = [*Array(scope), key].join('.')
+        return scoped_key if fallback_locale?(locale) || fallback_locale_unavailable?
 
-        ::I18n.translate(key, default: effective_default, scope:, locale: FALLBACK_LOCALE, **)
+        ::I18n.translate(key, default: scoped_key, scope:, locale: FALLBACK_LOCALE, **)
       end
 
       def fallback_locale?(locale)