grape 3.3.4 → 4.0.0

data/lib/grape/router.rb

@@ -2,14 +2,6 @@
 
 module Grape
   class Router
-    # @deprecated Use {Grape::Util::PathNormalizer.call} instead.
-    def self.normalize_path(path)
-      Grape.deprecator.warn(
-        '`Grape::Router.normalize_path` is deprecated. Use `Grape::Util::PathNormalizer.call` instead.'
-      )
-      Grape::Util::PathNormalizer.call(path)
-    end
-
     def initialize
       @neutral_map = []
       @neutral_regexes = []
@@ -23,14 +15,18 @@ module Grape
     def compile!
       return if @compiled
 
-      @union = Regexp.union(@neutral_regexes)
+      @union = resolve_capture_groups(Regexp.union(@neutral_regexes), @neutral_map)
       @neutral_regexes = nil
-      (Grape::HTTP_SUPPORTED_METHODS + ['*']).each do |method|
-        next unless @map.key?(method)
-
-        routes = @map[method]
+      # Compiled from the routes actually registered rather than from
+      # Grape::HTTP_SUPPORTED_METHODS. A route declared with any other verb
+      # (`route :purge, '/cache'`) is accepted at definition time and is
+      # already collected into the resource's Allow header, so skipping it here
+      # left it in @map but out of @optimized_map — the only map #match? reads.
+      # The resource then advertised a method that could never be matched and
+      # answered every request for it with 405.
+      @map.each do |method, routes|
         optimized_map = routes.map.with_index { |route, index| route.to_regexp(index) }
-        @optimized_map[method] = Regexp.union(optimized_map)
+        @optimized_map[method] = resolve_capture_groups(Regexp.union(optimized_map), routes)
       end
       @map.freeze
       @optimized_map.freeze
@@ -48,10 +44,11 @@ module Grape
 
     def call(env)
       with_optimization do
-        input = Grape::Util::PathNormalizer.call(env[Rack::PATH_INFO])
-        method = env[Rack::REQUEST_METHOD]
-        response, route = identity(input, method, env)
-        response || rotation(input, method, env, route)
+        # Published on the env so the middleware the matched route runs -- the
+        # path versioner above all -- reads the path this routed on instead of
+        # normalizing PATH_INFO a second time.
+        input = env[Grape::Env::GRAPE_NORMALIZED_PATH] = Grape::Util::PathNormalizer.call(env[Rack::PATH_INFO])
+        transaction(input, env[Rack::REQUEST_METHOD], env)
       end
     end
 
@@ -67,52 +64,69 @@ module Grape
 
     private
 
-    def identity(input, method, env)
-      route = nil
-      response = transaction(input, method, env) do
-        route = match?(input, method)
-        process_route(route, input, env) if route
-      end
-      [response, route]
-    end
-
-    def rotation(input, method, env, exact_route)
-      response = nil
-      @map[method]&.each do |route|
-        next if exact_route == route
-        next unless route.match?(input)
-
-        response = process_route(route, input, env)
-        break unless cascade?(response)
-      end
-      response
-    end
-
+    # Resolve +input+ against the compiled routes, in priority order:
+    #
+    # 1. the routes registered for +method+ — the compiled-union match first,
+    #    then, when that route cascades, its siblings (see #rotation);
+    # 2. the ANY (+'*'+) routes;
+    # 3. the greedy neighbour, which answers auto-OPTIONS and 405.
+    #
+    # Returns nil when nothing answered, leaving the caller to 404. A response
+    # that cascades is never final: it is returned only once every later
+    # candidate has declined too, so the caller (or a mounting app upstream)
+    # can keep looking.
     def transaction(input, method, env)
-      response = yield
+      exact_route = match?(input, method)
+      response = process_route(exact_route, input, env) if exact_route
       return response if halt?(response)
 
-      last_response_cascade = !response.nil?
+      # A cascading route has only declined this request. Its siblings — the
+      # routes sharing this path but differing in, say, version — must be
+      # tried before falling back to the ANY routes and the greedy neighbour.
+      # Skipped when nothing matched: the compiled union is the disjunction of
+      # the same patterns #rotation walks, so a miss there is a miss here.
+      cascaded = !response.nil?
+      if cascaded
+        response = rotation(input, method, env, exact_route)
+        return response if response && !cascade?(response)
+      end
+
       last_neighbor_route = greedy_match?(input)
 
       # If last_neighbor_route exists and request method is OPTIONS,
       # return response by using #include_allow_header.
-      return process_route(last_neighbor_route, input, env, include_allow_header: true) if !last_response_cascade && method == Rack::OPTIONS && last_neighbor_route
-
-      route = match?(input, '*')
+      return process_route(last_neighbor_route, input, env, include_allow_header: true) if !cascaded && method == Rack::OPTIONS && last_neighbor_route
 
-      return last_neighbor_route.call(env) if last_neighbor_route && last_response_cascade && route
+      star_route = match?(input, '*')
 
-      if route
-        route_response = process_route(route, input, env)
-        return route_response if halt?(route_response)
+      if star_route
+        close_body(response) if response # superseded by the ANY route
+        response = process_route(star_route, input, env)
+        return response if halt?(response)
 
-        last_response_cascade = !route_response.nil?
+        cascaded ||= !response.nil?
       end
 
-      return process_route(last_neighbor_route, input, env, include_allow_header: true) if !last_response_cascade && last_neighbor_route
+      return process_route(last_neighbor_route, input, env, include_allow_header: true) if !cascaded && last_neighbor_route
 
-      nil
+      response
+    end
+
+    # The routes registered for +method+ other than +exact_route+, tried in
+    # registration order until one answers without cascading. Returns the last
+    # response processed — a cascading one when every sibling declined, so the
+    # caller can hand it back — or nil when no sibling matched.
+    def rotation(input, method, env, exact_route)
+      response = nil
+      @map[method]&.each do |route|
+        next if exact_route == route
+        next unless route.match?(input)
+
+        close_body(response) if response # the previous sibling cascaded
+        response = process_route(route, input, env)
+        break unless cascade?(response)
+      end
+      response
     end
 
     # Returns true if `response` should be returned as-is from the enclosing
@@ -122,18 +136,42 @@ module Grape
       return false unless response
 
       cascade = cascade?(response)
-      response[2].close if cascade && response[2].respond_to?(:close)
+      close_body(response) if cascade
       !cascade
     end
 
+    # Releases a response the router has decided not to return. Rack requires
+    # every body it hands out to be closed, and a cascading candidate is
+    # discarded as soon as a later one answers.
+    def close_body(response)
+      body = response[2]
+      body.close if body.respond_to?(:close)
+    end
+
+    # Routing args are rebuilt for every attempt: when a route cascades
+    # (X-Cascade pass), the next candidate must not observe the previous
+    # attempt's +route_info+ or path captures.
     def process_route(route, input, env, include_allow_header: false)
-      route_params = route.params(input)
-      env[Grape::Env::GRAPE_ROUTING_ARGS] ||= { route_info: route }
-      env[Grape::Env::GRAPE_ROUTING_ARGS].merge!(route_params) if route_params.present?
+      # The path captures are the hash: +route_info+ is written into them
+      # rather than merged in from a second one.
+      routing_args = route.params_for(input) || {}
+      routing_args[:route_info] = route
+      env[Grape::Env::GRAPE_ROUTING_ARGS] = routing_args
       env[Grape::Env::GRAPE_ALLOWED_METHODS] = route.allow_header if include_allow_header
       route.call(env)
     end
 
+    # Tells each route the number of the group it ended up as in +union+. The
+    # numbering is a property of the union rather than of the route's own
+    # pattern -- every route ahead of it contributes however many groups its
+    # pattern declares -- so it can only be resolved once the union is built.
+    # Returns the union, so a caller can assign it in one expression.
+    def resolve_capture_groups(union, routes)
+      named_captures = union.named_captures
+      routes.each { |route| route.resolve_capture_group!(named_captures) }
+      union
+    end
+
     def with_optimization
       compile!
       yield || default_response
@@ -143,12 +181,17 @@ module Grape
       [404, DEFAULT_RESPONSE_HEADERS.dup, DEFAULT_RESPONSE_BODY.dup]
     end
 
+    # Which alternative of the union matched is answered by scanning one group
+    # per registered route, so on an API with many of them that scan is what a
+    # request costs. The groups are indexed by number rather than by name: a
+    # name sends MatchData through the pattern's name table on every lookup,
+    # a number indexes the match region directly.
     def match?(input, method)
-      @optimized_map[method]&.match(input) { |m| @map[method].detect { |route| m[route.regexp_capture_index] } }
+      @optimized_map[method]&.match(input) { |m| @map[method].detect { |route| m[route.regexp_capture_group] } }
     end
 
     def greedy_match?(input)
-      @union.match(input) { |m| @neutral_map.detect { |route| m[route.regexp_capture_index] } }
+      @union.match(input) { |m| @neutral_map.detect { |route| m[route.regexp_capture_group] } }
     end
 
     def cascade?(response)

data/lib/grape/serve_stream/file_body.rb

@@ -32,6 +32,12 @@ module Grape
         path == other.path
       end
       alias eql? ==
+
+      # Mirrors #==, which keys on the path alone and does not check the
+      # class, so the class must stay out of the hash too.
+      def hash
+        path.hash
+      end
     end
   end
 end

data/lib/grape/serve_stream/stream_response.rb

@@ -19,6 +19,12 @@ module Grape
         stream == other.stream
       end
       alias eql? ==
+
+      # Mirrors #==, which keys on the stream alone and does not check the
+      # class, so the class must stay out of the hash too.
+      def hash
+        stream.hash
+      end
     end
   end
 end

data/lib/grape/util/api_description.rb

@@ -6,7 +6,7 @@ module Grape
       DSL_METHODS = %i[
         body_name
         consumes
-        default
+        default_response
         deprecated
         detail
         entity
@@ -38,6 +38,15 @@ module Grape
       alias success entity
       alias failure http_codes
 
+      # @deprecated Use {#default_response}. The description is read back
+      #   through an ActiveSupport::OrderedOptions, where +default+ is
+      #   +Hash#default+ rather than a key lookup, and grape-swagger has always
+      #   asked the route for +default_response+.
+      def default(value)
+        Grape.deprecator.warn('`default` in a `desc` block is deprecated. Use `default_response` instead.')
+        default_response(value)
+      end
+
       def configuration
         @configuration ||= eval_endpoint_config(@endpoint_configuration)
       end

data/lib/grape/util/cache.rb

@@ -2,16 +2,35 @@
 
 module Grape
   module Util
+    # Base class for the lazily-filled lookup caches (coercers, dry-types,
+    # path parts, ...). Subclasses assign a default-block +Hash+ to +@cache+
+    # in their +initialize+.
+    #
+    # Lookups are synchronized: caches are written at API *definition* time
+    # (a +params+ block runs when the class body is evaluated), which is not
+    # covered by the compile-time +Grape::API::Instance::LOCK+ and can happen
+    # concurrently — e.g. parallel eager loading, or two threads autoloading
+    # different API files. A +Monitor+ (reentrant) rather than a +Mutex+,
+    # because a cache miss may re-enter the same cache: building a
+    # multiple-type coercer through +Types::CoercerCache+ builds its member
+    # coercers through +Types.build_coercer+, which lands in the same cache.
     class Cache
       include Singleton
 
       attr_reader :cache
 
+      def initialize
+        @monitor = Monitor.new
+      end
+
+      def [](key)
+        @monitor.synchronize { @cache[key] }
+      end
+
       class << self
         extend Forwardable
 
-        def_delegators :cache, :[]
-        def_delegators :instance, :cache
+        def_delegators :instance, :[], :cache
       end
     end
   end

data/lib/grape/util/deep_freeze.rb

@@ -10,9 +10,8 @@ module Grape
       #
       # 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
+      #   - Coercers and ParamsScope — self-freeze at construction
       def deep_freeze(obj)
         case obj
         when Hash

data/lib/grape/util/freeze_on_new.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Grape
+  module Util
+    # Extend into a class whose instances are shared across requests:
+    # +new+ returns a frozen instance, so any later ivar write — e.g.
+    # request-time memoization — raises FrozenError instead of being a
+    # latent data race.
+    #
+    # Must stay a +new+ wrapper (never an +initialize+ wrapper): the freeze
+    # runs after the entire initialize chain, so subclasses may assign ivars
+    # after +super+. Extending a hierarchy base covers its subclasses —
+    # singleton classes inherit along the class hierarchy.
+    module FreezeOnNew
+      def new(...)
+        super.freeze
+      end
+    end
+  end
+end