grape 2.4.0 → 4.0.1

data/lib/grape/middleware/versioner/path.rb

@@ -17,23 +17,70 @@ module Grape
       #   env['api.version'] => 'v1'
       #
       class Path < Base
+        def initialize(app, **options)
+          super
+          @prefixes = [mount_path, Grape::Util::PathNormalizer.call(prefix)].select { |p| p.present? && p != '/' }.freeze
+        end
+
         def before
-          path_info = Grape::Router.normalize_path(env[Rack::PATH_INFO])
+          routed = routed_version
+          return env[Grape::Env::API_VERSION] = routed if routed
+
+          path_info = env[Grape::Env::GRAPE_NORMALIZED_PATH] || Grape::Util::PathNormalizer.call(env[Rack::PATH_INFO])
           return if path_info == '/'
 
-          [mount_path, Grape::Router.normalize_path(prefix)].each do |path|
-            path_info.delete_prefix!(path) if path.present? && path != '/' && path_info.start_with?(path)
-          end
+          # `each` rather than `reduce`: Array does not override Enumerable's,
+          # so the generic accumulator path costs more than the work it drives
+          # on a list that holds at most a mount path and a prefix — and most
+          # often nothing at all.
+          @prefixes.each { |prefix| path_info = path_info.delete_prefix(prefix) if path_info.start_with?(prefix) }
 
           slash_position = path_info.index('/', 1) # omit the first one
-          return unless slash_position
+          return version_from_first_segment(path_info, slash_position) if slash_position
 
-          potential_version = path_info[1..slash_position - 1]
-          return unless potential_version.match?(pattern)
+          version_from_only_segment(path_info)
+        end
+
+        private
 
+        # Under path versioning every route pattern carries the version as a
+        # named capture (Pattern::Path#build_parts inserts it), constrained to
+        # the declared versions -- so the router has already sliced the segment
+        # out and validated it, and re-deriving it from PATH_INFO would repeat
+        # the normalize, prefix-strip and slice below for the same answer.
+        #
+        # Nil, and the path parsed as before, when there are no routing args at
+        # all (the middleware used outside a Grape router) and for the greedy
+        # routes behind auto-OPTIONS and 405, which capture nothing. An Array
+        # means the route declared a +:version+ segment of its own on top of the
+        # versioning one: Mustermann then reports the capture as every position
+        # it matched rather than the single segment recorded here, so that too
+        # is left to the path parse.
+        def routed_version
+          version = env[Grape::Env::GRAPE_ROUTING_ARGS]&.[](:version)
+          version if version.is_a?(String)
+        end
+
+        def version_from_first_segment(path_info, slash_position)
+          potential_version = path_info[1..(slash_position - 1)]
           version_not_found! unless potential_version_match?(potential_version)
           env[Grape::Env::API_VERSION] = potential_version
         end
+
+        # The path is a single segment (e.g. `GET /v1` — the root route of a
+        # path-versioned API). Nothing follows to disambiguate a version from a
+        # plain path or from a `.format` suffix (`/v1.json`), so the version is
+        # only recorded on an exact match against the declared versions, and an
+        # unmatched segment is left for the router to resolve — never a 404.
+        def version_from_only_segment(path_info)
+          candidate = path_info[1..]
+          candidate = candidate[0...candidate.rindex('.')] while candidate.include?('.') && !declared_version?(candidate)
+          env[Grape::Env::API_VERSION] = candidate if declared_version?(candidate)
+        end
+
+        def declared_version?(candidate)
+          versions.present? && versions.include?(candidate)
+        end
       end
     end
   end

data/lib/grape/mountable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Grape
+  # Marker module for a mountable Grape application. Both {Grape::API} (the
+  # remountable user-facing class) and {Grape::API::Instance} (the compiled
+  # engine) extend it, so a mounted Grape app can be told apart from a bare
+  # Rack app with `is_a?(Grape::Mountable)` — a single, explicit predicate
+  # rather than duck-typing on an incidental internal method such as
+  # `inheritable_setting`.
+  #
+  # `Grape::API` and `Grape::API::Instance` are not related by inheritance and
+  # do not even respond to the same methods (the former to `mount_instance`,
+  # the latter to `inheritable_setting`/`endpoints`), so there is no common
+  # ancestor to key an `is_a?` check on without this marker.
+  #
+  # It answers identity only ("is this a Grape app?"). Capability checks that
+  # go on to call a stage-specific method — e.g. `respond_to?(:endpoints)`
+  # before reading `endpoints` — must stay as they are, since a `Mountable`
+  # does not necessarily respond to every such method.
+  module Mountable
+  end
+end

data/lib/grape/namespace.rb

@@ -5,31 +5,39 @@ module Grape
   # logical grouping of endpoints as well as sharing common configuration.
   # May also be referred to as group, segment, or resource.
   class Namespace
-    attr_reader :space, :options
+    attr_reader :space, :requirements, :options
 
     # @param space [String] the name of this namespace
     # @param options [Hash] options hash
     # @option options :requirements [Hash] param-regex pairs, all of which must
     #   be met by a request's params for all endpoints in this namespace, or
     #   validation will fail and return a 422.
-    def initialize(space, options)
+    def initialize(space, requirements: nil, **options)
       @space = space.to_s
+      @requirements = requirements
       @options = options
     end
 
-    # Retrieves the requirements from the options hash, if given.
-    # @return [Hash]
-    def requirements
-      options[:requirements] || {}
-    end
-
     # (see ::joined_space_path)
     def self.joined_space(settings)
       settings&.map(&:space)
     end
 
-    # Join the namespaces from a list of settings to create a path prefix.
-    # @param settings [Array] list of Grape::Util::InheritableSettings.
+    def ==(other)
+      other.class == self.class &&
+        other.space == space &&
+        other.requirements == requirements &&
+        other.options == options
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, space, requirements, options].hash
+    end
+
+    # Join the namespaces from a list of Namespace objects to create a path
+    # prefix.
+    # @param settings [Array] list of Grape::Namespace objects.
     def self.joined_space_path(settings)
       JoinedSpaceCache[joined_space(settings)]
     end
@@ -38,7 +46,7 @@ module Grape
       def initialize
         super
         @cache = Hash.new do |h, joined_space|
-          h[joined_space] = Grape::Router.normalize_path(joined_space.join('/'))
+          h[joined_space] = Grape::Util::PathNormalizer.call(joined_space.join('/'))
         end
       end
     end

data/lib/grape/params_builder/base.rb

@@ -8,6 +8,8 @@ module Grape
           raise NotImplementedError
         end
 
+        private
+
         def inherited(klass)
           super
           ParamsBuilder.register(klass)

data/lib/grape/params_builder/hash_with_indifferent_access.rb

@@ -4,7 +4,7 @@ module Grape
   module ParamsBuilder
     class HashWithIndifferentAccess < Base
       def self.call(params)
-        params.with_indifferent_access
+        ActiveSupport::HashWithIndifferentAccess.new(params)
       end
     end
   end

data/lib/grape/params_builder.rb

@@ -4,29 +4,12 @@ module Grape
   module ParamsBuilder
     extend Grape::Util::Registry
 
-    SHORT_NAME_LOOKUP = {
-      'Grape::Extensions::Hash::ParamBuilder' => :hash,
-      'Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder' => :hash_with_indifferent_access,
-      'Grape::Extensions::Hashie::Mash::ParamBuilder' => :hashie_mash
-    }.freeze
-
     module_function
 
     def params_builder_for(short_name)
-      verified_short_name = verify_short_name!(short_name)
-
-      raise Grape::Exceptions::UnknownParamsBuilder, verified_short_name unless registry.key?(verified_short_name)
-
-      registry[verified_short_name]
-    end
-
-    def verify_short_name!(short_name)
-      return short_name if short_name.is_a?(Symbol)
+      raise Grape::Exceptions::UnknownParamsBuilder, short_name unless registry.key?(short_name)
 
-      class_name = short_name.name
-      SHORT_NAME_LOOKUP[class_name].tap do |real_short_name|
-        Grape.deprecator.warn "#{class_name} has been deprecated. Use short name :#{real_short_name} instead."
-      end
+      registry[short_name]
     end
   end
 end

data/lib/grape/parser/json.rb

@@ -4,7 +4,7 @@ module Grape
   module Parser
     class Json < Base
       def self.call(object, _env)
-        ::Grape::Json.load(object)
+        ::Grape::Json.parse(object)
       rescue ::Grape::Json::ParseError
         # handle JSON parsing errors via the rescue handlers or provide error message
         raise Grape::Exceptions::InvalidMessageBody.new('application/json')

data/lib/grape/path.rb

@@ -1,76 +1,12 @@
 # frozen_string_literal: true
 
 module Grape
-  # Represents a path to an endpoint.
-  class Path
-    DEFAULT_FORMAT_SEGMENT = '(/.:format)'
-    NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT = '(.:format)'
-    VERSION_SEGMENT = ':version'
-
-    attr_reader :origin, :suffix
-
-    def initialize(raw_path, raw_namespace, settings)
-      @origin = PartsCache[build_parts(raw_path, raw_namespace, settings)]
-      @suffix = build_suffix(raw_path, raw_namespace, settings)
-    end
-
-    def to_s
-      "#{origin}#{suffix}"
-    end
-
-    private
-
-    def build_suffix(raw_path, raw_namespace, settings)
-      if uses_specific_format?(settings)
-        "(.#{settings[:format]})"
-      elsif !uses_path_versioning?(settings) || (valid_part?(raw_namespace) || valid_part?(raw_path))
-        NO_VERSIONING_WITH_VALID_PATH_FORMAT_SEGMENT
-      else
-        DEFAULT_FORMAT_SEGMENT
-      end
-    end
-
-    def build_parts(raw_path, raw_namespace, settings)
-      [].tap do |parts|
-        add_part(parts, settings[:mount_path])
-        add_part(parts, settings[:root_prefix])
-        parts << VERSION_SEGMENT if uses_path_versioning?(settings)
-        add_part(parts, raw_namespace)
-        add_part(parts, raw_path)
-      end
-    end
-
-    def add_part(parts, value)
-      parts << value if value && not_slash?(value)
-    end
-
-    def not_slash?(value)
-      value != '/'
-    end
-
-    def uses_specific_format?(settings)
-      return false unless settings.key?(:format) && settings.key?(:content_types)
-
-      settings[:format] && Array(settings[:content_types]).size == 1
-    end
-
-    def uses_path_versioning?(settings)
-      return false unless settings.key?(:version) && settings[:version_options]&.key?(:using)
-
-      settings[:version] && settings[:version_options][:using] == :path
-    end
-
-    def valid_part?(part)
-      part&.match?(/^\S/) && not_slash?(part)
-    end
-
-    class PartsCache < Grape::Util::Cache
-      def initialize
-        super
-        @cache = Hash.new do |h, parts|
-          h[parts] = Grape::Router.normalize_path(parts.join('/'))
-        end
-      end
-    end
-  end
+  # @deprecated +Grape::Path+ moved to {Grape::Router::Pattern::Path}, since it
+  #   is a router-internal detail that only exists to build a
+  #   {Grape::Router::Pattern}. Reference the new constant instead.
+  Path = ActiveSupport::Deprecation::DeprecatedConstantProxy.new(
+    'Grape::Path',
+    'Grape::Router::Pattern::Path',
+    Grape.deprecator
+  )
 end

data/lib/grape/precompiled_json.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Grape
+  # Marks a body as JSON that has already been rendered, so the JSON formatters
+  # serve it verbatim instead of encoding it a second time.
+  #
+  # +Grape::Formatter::Json+ calls +to_json+ on whatever the endpoint returned, so a
+  # String holding pre-rendered JSON — a blob cached in Redis, a +json_agg+ column read
+  # straight from Postgres, output from another serializer — comes back encoded twice:
+  #
+  #   '{"a":1}'  =>  "\"{\\\"a\\\":1}\""
+  #
+  # Wrapping the body opts that one response out of encoding:
+  #
+  #   get '/cached' do
+  #     body Grape::PrecompiledJson.new(Rails.cache.read('payload'))
+  #   end
+  #
+  # An Array is joined into a JSON array without its members being parsed, which is
+  # what makes a cached collection cheap — N rendered blobs are spliced together
+  # rather than round-tripped:
+  #
+  #   Grape::PrecompiledJson.new(['{"id":1}', '{"id":2}']).to_s # => '[{"id":1},{"id":2}]'
+  #
+  # +Array#join+ calls +to_s+ on each member, so members may themselves be
+  # +PrecompiledJson+ instances.
+  #
+  # Wrap only the whole body. A wrapper nested inside a Hash or Array that is then
+  # handed to an encoder is serialized as an ordinary object — +ActiveSupport::JSON+
+  # renders it through +as_json+ as +{"value":"{\"a\":1}"}+ — because no encoder knows
+  # to unwrap it. Nothing checks that the String actually holds JSON; that is the
+  # caller's responsibility.
+  class PrecompiledJson
+    # @param value [String, Array<String>] pre-rendered JSON
+    def initialize(value)
+      @value = value
+    end
+
+    # @return [String] the JSON to serve
+    # @raise [Grape::Exceptions::InvalidFormatter] if the value is neither a String
+    #   nor an Array; the formatter middleware turns this into a 500 rather than
+    #   letting a body Rack cannot serve reach the SPEC check.
+    def to_s
+      return @value if @value.is_a?(String)
+      return "[#{@value.join(',')}]" if @value.is_a?(Array)
+
+      raise Grape::Exceptions::InvalidFormatter.new(@value.class, 'json')
+    end
+  end
+end

data/lib/grape/request.rb

@@ -132,8 +132,8 @@ module Grape
       X-UA-Compatible
       X-WebKit-CS
       X-XSS-Protection
-    ].each_with_object({}) do |header, response|
-      response["HTTP_#{header.upcase.tr('-', '_')}"] = header
+    ].to_h do |header|
+      ["HTTP_#{header.upcase.tr('-', '_')}", header]
     end.freeze
 
     alias rack_params params
@@ -141,7 +141,7 @@ module Grape
 
     def initialize(env, build_params_with: nil)
       super(env)
-      @params_builder = Grape::ParamsBuilder.params_builder_for(build_params_with || Grape.config.param_builder)
+      @build_params_with = build_params_with
     end
 
     def params
@@ -153,38 +153,75 @@ module Grape
     end
 
     def cookies
-      @cookies ||= Grape::Cookies.new(-> { rack_cookies })
+      @cookies ||= Grape::Cookies.new(rack_cookies)
     end
 
-    # needs to be public until extensions param_builder are removed
-    def grape_routing_args
-      # preserve version from query string parameters
-      env[Grape::Env::GRAPE_ROUTING_ARGS]&.except(:version, :route_info) || {}
+    # True once the cookie jar has been materialized (a cookie was read or
+    # written this request). Lets the endpoint skip response-cookie flushing,
+    # and the Grape::Cookies allocation it triggers, when no cookie was
+    # touched on the request.
+    def cookies?
+      !@cookies.nil?
     end
 
     private
 
+    # Resolved on first use rather than in the constructor: a request that never
+    # reads +params+ -- an endpoint with no validations whose block does not ask
+    # for them -- pays neither the registry lookup nor the global config read,
+    # and every request builds a Grape::Request.
+    def params_builder
+      @params_builder ||= Grape::ParamsBuilder.params_builder_for(@build_params_with || Grape.config[:param_builder])
+    end
+
     def make_params
-      @params_builder.call(rack_params).deep_merge!(grape_routing_args)
-    rescue EOFError
-      raise Grape::Exceptions::EmptyMessageBody.new(content_type)
-    rescue Rack::Multipart::MultipartPartLimitError, Rack::Multipart::MultipartTotalPartLimitError
-      raise Grape::Exceptions::TooManyMultipartFiles.new(Rack::Utils.multipart_part_limit)
-    rescue Rack::QueryParser::ParamsTooDeepError
-      raise Grape::Exceptions::TooDeepParameters.new(Rack::Utils.param_depth_limit)
-    rescue Rack::Utils::ParameterTypeError
-      raise Grape::Exceptions::ConflictingTypes
-    rescue Rack::Utils::InvalidParameterError
-      raise Grape::Exceptions::InvalidParameters
+      params = params_builder.call(rack_params)
+      filtered = routing_args_as_params(env[Grape::Env::GRAPE_ROUTING_ARGS])
+      return params if filtered.blank?
+
+      params.deep_merge!(filtered)
+    rescue *Grape::RACK_ERRORS
+      raise Grape::Exceptions::RequestError
+    end
+
+    # The routing args carry two things that are not request params:
+    # +:route_info+, which is always Grape's own, and +:version+, which is only
+    # Grape's own when the API declared a version — that is captured as a path
+    # segment and exposed through +env['api.version']+ instead.
+    #
+    # An API that declares no version can legitimately name a param +:version+
+    # (`route_param :version`, `get '/:version'`), and that capture belongs to
+    # the application. Dropping it unconditionally left `params[:version]` nil
+    # on a route that had matched, losing the segment silently.
+    def routing_args_as_params(routing_args)
+      return if routing_args.nil?
+      return routing_args.except(:version, :route_info) if grape_owns_version?(routing_args)
+
+      routing_args.except(:route_info)
+    end
+
+    # A route reports a +version+ only when the API declared one, which is the
+    # case where the captured segment is Grape's rather than the application's.
+    def grape_owns_version?(routing_args)
+      return false unless routing_args.key?(:version)
+
+      route = routing_args[:route_info]
+      route.respond_to?(:version) && !route.version.nil?
     end
 
+    # Uses a plain `each_header` block instead of `each_header.with_object`:
+    # `with_object` can only pass the block one value plus the memo, so the
+    # `k, v` pair would be boxed into a throwaway Array on every header. A
+    # two-arg block receives `k`/`v` directly and allocates nothing extra.
     def build_headers
-      each_header.with_object(Grape::Util::Header.new) do |(k, v), headers|
+      headers = Grape::Util::Header.new
+      each_header do |k, v|
         next unless k.start_with? 'HTTP_'
 
         transformed_header = KNOWN_HEADERS.fetch(k) { -k[5..].tr('_', '-').downcase }
         headers[transformed_header] = v
       end
+      headers
     end
   end
 end

data/lib/grape/router/base_route.rb

@@ -3,29 +3,75 @@
 module Grape
   class Router
     class BaseRoute
+      extend Forwardable
+
       delegate_missing_to :@options
 
-      attr_reader :index, :pattern, :options
+      attr_reader :options, :pattern, :prefix, :settings, :namespace
+
+      # +version+, +anchor+ and +requirements+ shape the matcher, so they are
+      # read from the pattern rather than stored again on the route.
+      def_delegators :@pattern, :path, :origin, :version, :anchor, :requirements
+      def_delegators :@options, :description, *Grape::Util::ApiDescription::DSL_METHODS
 
-      def initialize(options)
+      def initialize(pattern, options = {}, namespace: nil, prefix: nil, settings: nil)
+        @pattern = pattern
         @options = options.is_a?(ActiveSupport::OrderedOptions) ? options : ActiveSupport::OrderedOptions.new.update(options)
+        @namespace = namespace
+        @prefix = prefix
+        @settings = settings
       end
 
-      alias attributes options
+      # +success+ and +failure+ are the +desc+ DSL's names for +entity+ and
+      # +http_codes+: the block form writes the canonical key, a keyword option
+      # keeps the name it was written with, so both spellings are read here.
+      # Without this they resolve through +delegate_missing_to+, which answers
+      # nil for whichever of the two keys the description did not use.
+      def success
+        @options[:entity] || @options[:success]
+      end
+
+      def failure
+        @options[:http_codes] || @options[:failure]
+      end
 
-      def regexp_capture_index
-        CaptureIndexCache[index]
+      # @deprecated Use {#default_response}, the name grape-swagger asks for.
+      #   This one has to be written out rather than delegated like the rest:
+      #   an ActiveSupport::OrderedOptions answers an unknown name with that
+      #   key's value, but +default+ is not unknown to it — it is +Hash#default+,
+      #   the Hash's own default value — so a delegator would report nil for
+      #   every route.
+      def default
+        Grape.deprecator.warn('`Grape::Router::Route#default` is deprecated. Use `#default_response` instead.')
+        default_response
       end
 
+      # Assigned eagerly in {#to_regexp} (router compilation) rather than
+      # memoized here: this reader is called from request-time route matching
+      # on instances shared across threads, so it must not write state.
+      attr_reader :regexp_capture_index
+
+      # The number of the group this route occupies in the union the router
+      # compiled it into. Only the union can say what it is, so it is written
+      # back by {Router#compile!} right after building one, and like
+      # +regexp_capture_index+ it is never assigned at request time.
+      attr_reader :regexp_capture_group
+
       def pattern_regexp
-        pattern.to_regexp
+        @pattern.to_regexp
       end
 
       def to_regexp(index)
-        @index = index
+        @regexp_capture_index = CaptureIndexCache[index]
         Regexp.new("(?<#{regexp_capture_index}>#{pattern_regexp})")
       end
 
+      # @api private
+      # @see #regexp_capture_group
+      def resolve_capture_group!(union_named_captures)
+        @regexp_capture_group = union_named_captures.fetch(regexp_capture_index).first
+      end
+
       class CaptureIndexCache < Grape::Util::Cache
         def initialize
           super

data/lib/grape/router/greedy_route.rb

@@ -6,14 +6,24 @@
 module Grape
   class Router
     class GreedyRoute < BaseRoute
-      def initialize(pattern, options)
-        @pattern = pattern
-        super(options)
+      extend Forwardable
+
+      def_delegators :@endpoint, :call
+
+      attr_reader :endpoint, :allow_header
+
+      def initialize(pattern, endpoint:, allow_header:)
+        super(pattern)
+        @endpoint = endpoint
+        @allow_header = allow_header
+      end
+
+      def params
+        nil
       end
 
-      # Grape::Router:Route defines params as a function
-      def params(_input = nil)
-        options[:params] || {}
+      def params_for(_input)
+        nil
       end
     end
   end

data/lib/grape/router/mustermann_pattern.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Grape
+  class Router
+    # Grape-style path patterns for Mustermann: `:param`, `*splat`, `{name}` /
+    # `{+splat}`, `( )` optionals, `|`, and an Integer digit-only constraint
+    # (driven by Grape's `params` option).
+    #
+    # Inlined from the mustermann-grape gem (MIT) by namusyaka, Konstantin Haase
+    # and Daniel Doubrovkine. Grape instantiates this class directly (see
+    # {Grape::Router::Pattern}), so unlike the gem it is not registered as a
+    # Mustermann `type: :grape`.
+    class MustermannPattern < ::Mustermann::AST::Pattern
+      supported_options :params
+
+      on(nil, '?', ')') { |c| unexpected(c) }
+
+      on('*') { |_c| scan(/\w+/) ? node(:named_splat, buffer.matched) : node(:splat) }
+      on(':') do |_c|
+        param_name = scan(/\w+/)
+        # Integer params (declared via Grape's `params` option) match digits only;
+        # any other capture matches a single path segment (anything but / ? # .).
+        param_type = pattern&.options&.dig(:params, param_name, :type)
+        constraint = param_type == 'Integer' ? /\d/ : '[^/?#.]'
+        node(:capture, param_name, constraint:) { scan(/\w+/) }
+      end
+      on('\\') { |_c| node(:char, expect(/./)) }
+      on('(') { |_c| node(:optional, node(:group) { read unless scan(')') }) }
+      on('|') { |_c| node(:or) }
+
+      on('{') do |_c|
+        type = scan('+') ? :named_splat : :capture
+        name = expect(/[\w.]+/)
+        type = :splat if (type == :named_splat) && (name == 'splat')
+        expect('}')
+        node(type, name)
+      end
+
+      suffix('?') do |_c, element|
+        node(:optional, element)
+      end
+    end
+  end
+end