grape 2.0.0 → 2.4.0

data/UPGRADING.md

@@ -1,6 +1,281 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 2.4.0
+
+#### Grape::Middleware::Auth::Base
+`type` is now validated at compile time and will raise a `Grape::Exceptions::UnknownAuthStrategy` if unknown.
+
+#### Grape::Middleware::Base
+
+- Second argument `options` is now a double splat (**) instead of single splat (*). If you're redefining `initialize` in your middleware and/or calling `super` in it, you might have to adapt the signature and the `super` call. Also, you might have to remove `{}` if you're pass `options` as a literal `Hash` or add `**` if you're using a variable.
+- `Grape::Middleware::Helpers` has been removed. The equivalent method `context` is now part of `Grape::Middleware::Base`.
+
+#### Grape::Http::Headers, Grape::Util::Lazy::Object
+
+Both have been removed. See [2554](https://github.com/ruby-grape/grape/pull/2554).
+Here are the notable changes:
+
+- Constants like `HTTP_ACCEPT` have been replaced by their literal value.
+- `SUPPORTED_METHODS` has been moved to `Grape` module.
+- `HTTP_HEADERS` has been moved to `Grape::Request` and renamed `KNOWN_HEADERS`. The last has been refreshed with new headers, and it's not lazy anymore.
+- `SUPPORTED_METHODS_WITHOUT_OPTIONS` and `find_supported_method` have been removed.
+
+#### Grape::Middleware::Base
+
+- Constant `TEXT_HTML` has been removed in favor of using literal string 'text/html'.
+- `rack_request` and `query_params` have been added. Feel free to call these in your middlewares.
+
+#### Params Builder
+
+- Passing a class to `build_with` or `Grape.config.param_builder` has been deprecated in favor of a symbolized short_name. See `SHORTNAME_LOOKUP` in [params_builder](lib/grape/params_builder.rb).
+- Including Grape's extensions like `Grape::Extensions::Hashie::Mash::ParamBuilder` has been deprecated in favor of using `build_with` at the route level.
+
+#### Accept Header Negotiation Harmonized
+
+[Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept) header is now fully interpreted through `Rack::Utils.best_q_match` which is following [RFC2616 14.1](https://datatracker.ietf.org/doc/html/rfc2616#section-14.1). Since [Grape 2.1.0](https://github.com/ruby-grape/grape/blob/master/CHANGELOG.md#210-20240615), the [header versioning strategy](https://github.com/ruby-grape/grape?tab=readme-ov-file#header) was adhering to it, but `Grape::Middleware::Formatter` never did.
+
+Your API might act differently since it will strictly follow the [RFC2616 14.1](https://datatracker.ietf.org/doc/html/rfc2616#section-14.1) when interpreting the `Accept` header. Here are the differences:
+
+##### Invalid or missing quality ranking
+The following used to yield `application/xml` and now will yield `application/json` as the preferred media type:
+- `application/json;q=invalid,application/xml;q=0.5`
+- `application/json,application/xml;q=1.0`
+
+For the invalid case, the value `invalid` was automatically `to_f` and `invalid.to_f` equals `0.0`. Now, since it doesn't match [Rack's regex](https://github.com/rack/rack/blob/3-1-stable/lib/rack/utils.rb#L138), its interpreted as non provided and its quality ranking equals 1.0.
+
+For the non provided case, 1.0 was automatically assigned and in a case of multiple best matches, the first was returned based on Ruby's sort_by `quality`. Now, 1.0 is still assigned and the last is returned in case of multiple best matches. See [Rack's implementation](https://github.com/rack/rack/blob/e8f47608668d507e0f231a932fa37c9ca551c0a5/lib/rack/utils.rb#L167) of the RFC.
+
+##### Considering the closest generic when vendor tree
+Excluding the [header versioning strategy](https://github.com/ruby-grape/grape?tab=readme-ov-file#header), whenever a media type with the [vendor tree](https://datatracker.ietf.org/doc/html/rfc6838#section-3.2) leading facet `vnd.` like `application/vnd.api+json` was provided, Grape would also consider its closest generic when negotiating. In that case, `application/json` was added to the negotiation. Now, it will just consider the provided media types without considering any closest generics, and you'll need to [register](https://github.com/ruby-grape/grape?tab=readme-ov-file#api-formats) it.
+You can find the official vendor tree registrations on [IANA](https://www.iana.org/assignments/media-types/media-types.xhtml)
+
+#### Custom Validators
+
+If you now receive an error of `'Grape::Validations.require_validator': unknown validator: your_custom_validation (Grape::Exceptions::UnknownValidator)` after upgrading to 2.4.0 then you will need to ensure that you require the `your_custom_validation` file before your Grape API code is loaded.
+
+See [2533](https://github.com/ruby-grape/grape/issues/2533) for more information.
+
+### Upgrading to >= 2.3.0
+
+### `content_type` vs `api.format` inside API
+
+Before 2.3.0, `content_type` had priority over `env['api.format']` when set in an API, which was incorrect. The priority has been flipped and `env['api.format']` will be checked first.
+In addition, the function `api_format` has been added. Instead of setting `env['api.format']` directly, you can call `api_format`.
+See [#2506](https://github.com/ruby-grape/grape/pull/2506) for more information.
+
+#### Remove Deprecated Methods and Options
+
+- Deprecated `file` method has been removed. Use `send_file` or `stream`.
+See [#2500](https://github.com/ruby-grape/grape/pull/2500) for more information.
+
+- The `except` and `proc` options have been removed from the `values` validator. Use `except_values` validator or assign `proc` directly to `values`.
+See [#2501](https://github.com/ruby-grape/grape/pull/2501) for more information.
+
+- `Passing an options hash and a block to 'desc'` deprecation has been removed. Move all hash options to block instead.
+See [#2502](https://github.com/ruby-grape/grape/pull/2502) for more information.
+
+### Upgrading to >= 2.2.0
+
+### `Length` validator
+
+After Grape 2.2.0, `length` validator will only take effect for parameters with types that support `#length` method, will not throw `ArgumentError` exception.
+
+See [#2464](https://github.com/ruby-grape/grape/pull/2464) for more information.
+
+### Upgrading to >= 2.1.0
+
+#### Optional Builder
+
+The `builder` gem dependency has been made optional as it's only used when generating XML. If your code does, add `builder` to your `Gemfile`.
+
+See [#2445](https://github.com/ruby-grape/grape/pull/2445) for more information.
+
+#### Deep Merging of Parameter Attributes
+
+Grape now uses `deep_merge` to combine parameter attributes within the `with` method. Previously, attributes defined at the parameter level would override those defined at the group level.
+With deep merge, attributes are now combined, allowing for more detailed and nuanced API specifications.
+
+For example:
+
+```ruby
+with(documentation: { in: 'body' }) do
+  optional :vault, documentation: { default: 33 }
+end
+```
+
+Before it was equivalent to:
+
+```ruby
+optional :vault, documentation: { default: 33 }
+```
+
+After it is an equivalent of:
+
+```ruby
+optional :vault, documentation: { in: 'body', default: 33 }
+```
+
+See [#2432](https://github.com/ruby-grape/grape/pull/2432) for more information.
+
+#### Zeitwerk
+
+Grape's autoloader has been updated and it's now based on [Zeitwerk](https://github.com/fxn/zeitwerk).
+If you MP (Monkey Patch) some files and you're not following the [file structure](https://github.com/fxn/zeitwerk?tab=readme-ov-file#file-structure), you might end up with a Zeitwerk error.
+
+See [#2363](https://github.com/ruby-grape/grape/pull/2363) for more information.
+
+#### Changes in rescue_from
+
+The `rack_response` method has been deprecated and the `error_response` method has been removed. Use `error!` instead.
+
+See [#2414](https://github.com/ruby-grape/grape/pull/2414) for more information.
+
+#### Change in parameters precedence
+
+When using together with `Grape::Extensions::Hash::ParamBuilder`, `route_param` takes higher precedence over a regular parameter defined with same name, which now matches the default param builder behavior.
+
+This was a regression introduced by [#2326](https://github.com/ruby-grape/grape/pull/2326) in Grape v1.8.0.
+
+```ruby
+Grape.configure do |config|
+  config.param_builder = Grape::Extensions::Hash::ParamBuilder
+end
+
+params do
+  requires :foo, type: String
+end
+route_param :foo do
+  get do
+    { value: params[:foo] }
+  end
+end
+```
+
+Request:
+
+```bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/bar -d '{"foo": "baz"}'
+```
+
+Response prior to v1.8.0:
+
+```json
+{
+  "value": "bar"
+}
+```
+
+v1.8.0..v2.0.0:
+
+```json
+{
+  "value": "baz"
+}
+```
+
+v2.1.0+:
+
+```json
+{
+  "value": "bar"
+}
+```
+
+See [#2378](https://github.com/ruby-grape/grape/pull/2378) for details.
+
+#### Grape::Router::Route.route_xxx methods have been removed
+
+- `route_method` is accessible through `request_method`
+- `route_path` is accessible through `path`
+- Any other `route_xyz` are accessible through `options[xyz]`
+
+#### Instance variables scope
+
+Due to the changes done in [#2377](https://github.com/ruby-grape/grape/pull/2377), the instance variables defined inside each of the endpoints (or inside a `before` validator) are now accessible inside the `rescue_from`. The behavior of the instance variables was undefined until `2.1.0`.
+
+If you were using the same variable name defined inside an endpoint or `before` validator inside a `rescue_from` handler, you need to take in mind that you can start getting different values or you can be overriding values.
+
+Before:
+```ruby
+class TwitterAPI < Grape::API
+  before do
+    @var = 1
+  end
+
+  get '/' do
+    puts @var # => 1
+    raise
+  end
+
+  rescue_from :all do
+    puts @var # => nil
+  end
+end
+```
+
+After:
+```ruby
+class TwitterAPI < Grape::API
+  before do
+    @var = 1
+  end
+
+  get '/' do
+    puts @var # => 1
+    raise
+  end
+
+  rescue_from :all do
+    puts @var # => 1
+  end
+end
+```
+
+#### Recognizing Path
+
+Grape now considers the types of the configured `route_params` in order to determine the endpoint that matches with the performed request.
+
+So taking into account this `Grape::API` class
+
+```ruby
+class Books < Grape::API
+  resource :books do
+    route_param :id, type: Integer do
+      # GET /books/:id
+      get do
+        #...
+      end
+    end
+
+    resource :share do
+      # POST /books/share
+      post do
+      # ....
+      end
+    end
+  end
+end
+```
+
+Before:
+```ruby
+API.recognize_path '/books/1' # => /books/:id
+API.recognize_path '/books/share' # => /books/:id
+API.recognize_path '/books/other' # => /books/:id
+```
+
+After:
+```ruby
+API.recognize_path '/books/1' # => /books/:id
+API.recognize_path '/books/share' # => /books/share
+API.recognize_path '/books/other' # => nil
+```
+
+This implies that before this changes, when you performed `/books/other` and it matched with the `/books/:id` endpoint, you get a `400 Bad Request` response because the type of the provided `:id` param was not an `Integer`. However, after upgrading to version `2.1.0` you will get a `404 Not Found` response, because there is not a defined endpoint that matches with `/books/other`.
+
+See [#2379](https://github.com/ruby-grape/grape/pull/2379) for more information.
+
 ### Upgrading to >= 2.0.0
 
 #### Headers
@@ -19,7 +294,7 @@ If you are using Rack 3 in your application then the headers will be set to:
 { "content-type" => "application/json", "secret-password" => "foo"}
 ```
 
-This means if you are checking for header values in your application, you would need to change your code to use downcased keys. 
+This means if you are checking for header values in your application, you would need to change your code to use downcased keys.
 
 ```ruby
 get do
@@ -474,8 +749,7 @@ end
 
 ##### `name` (and other caveats) of the mounted API
 
-After the patch, the mounted API is no longer a Named class inheriting from `Grape::API`, it is an anonymous class
-which inherit from `Grape::API::Instance`.
+After the patch, the mounted API is no longer a Named class inheriting from `Grape::API`, it is an anonymous class which inherit from `Grape::API::Instance`.
 
 What this means in practice, is:
 
@@ -855,8 +1129,7 @@ See [#1114](https://github.com/ruby-grape/grape/pull/1114) for more information.
 
 #### Bypasses formatters when status code indicates no content
 
-To be consistent with rack and it's handling of standard responses associated with no content, both default and custom formatters will now
-be bypassed when processing responses for status codes defined [by rack](https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L567)
+To be consistent with rack and it's handling of standard responses associated with no content, both default and custom formatters will now be bypassed when processing responses for status codes defined [by rack](https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L567)
 
 See [#1190](https://github.com/ruby-grape/grape/pull/1190) for more information.
 
@@ -1297,8 +1570,7 @@ As replacement can be used
 * `Grape::Middleware::Auth::Digest` => [`Rack::Auth::Digest::MD5`](https://github.com/rack/rack/blob/master/lib/rack/auth/digest/md5.rb)
 * `Grape::Middleware::Auth::OAuth2` => [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2)
 
-If this is not possible you can extract the middleware files from [grape v0.7.0](https://github.com/ruby-grape/grape/tree/v0.7.0/lib/grape/middleware/auth)
-and host these files within your application
+If this is not possible you can extract the middleware files from [grape v0.7.0](https://github.com/ruby-grape/grape/tree/v0.7.0/lib/grape/middleware/auth) and host these files within your application
 
 See [#703](https://github.com/ruby-grape/Grape/pull/703) for more information.
 

data/grape.gemspec

@@ -17,17 +17,17 @@ Gem::Specification.new do |s|
     'bug_tracker_uri' => 'https://github.com/ruby-grape/grape/issues',
     'changelog_uri' => "https://github.com/ruby-grape/grape/blob/v#{s.version}/CHANGELOG.md",
     'documentation_uri' => "https://www.rubydoc.info/gems/grape/#{s.version}",
-    'source_code_uri' => "https://github.com/ruby-grape/grape/tree/v#{s.version}"
+    'source_code_uri' => "https://github.com/ruby-grape/grape/tree/v#{s.version}",
+    'rubygems_mfa_required' => 'true'
   }
 
-  s.add_runtime_dependency 'activesupport', '>= 5'
-  s.add_runtime_dependency 'builder'
-  s.add_runtime_dependency 'dry-types', '>= 1.1'
-  s.add_runtime_dependency 'mustermann-grape', '~> 1.0.0'
-  s.add_runtime_dependency 'rack', '>= 1.3.0'
-  s.add_runtime_dependency 'rack-accept'
+  s.add_dependency 'activesupport', '>= 6.1'
+  s.add_dependency 'dry-types', '>= 1.1'
+  s.add_dependency 'mustermann-grape', '~> 1.1.0'
+  s.add_dependency 'rack', '>= 2'
+  s.add_dependency 'zeitwerk'
 
   s.files = Dir['lib/**/*', 'CHANGELOG.md', 'CONTRIBUTING.md', 'README.md', 'grape.png', 'UPGRADING.md', 'LICENSE', 'grape.gemspec']
   s.require_paths = ['lib']
-  s.required_ruby_version = '>= 2.6.0'
+  s.required_ruby_version = '>= 2.7.0'
 end

data/lib/grape/api/instance.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
-require 'grape/router'
-
 module Grape
   class API
     # The API Instance class, is the engine behind Grape::API. Each class that inherits
     # from this will represent a different API instance
     class Instance
+      extend Grape::Middleware::Auth::DSL
       include Grape::DSL::API
 
       class << self
@@ -48,7 +47,7 @@ module Grape
         # Parses the API's definition and compiles it into an instance of
         # Grape::API.
         def compile
-          @instance ||= new
+          @instance ||= new # rubocop:disable Naming/MemoizedInstanceVariableName
         end
 
         # Wipe the compiled API so we can recompile after changes were made.
@@ -112,9 +111,9 @@ module Grape
         end
 
         def evaluate_as_instance_with_configuration(block, lazy: false)
-          lazy_block = Grape::Util::LazyBlock.new do |configuration|
+          lazy_block = Grape::Util::Lazy::Block.new do |configuration|
             value_for_configuration = configuration
-            self.configuration = value_for_configuration.evaluate if value_for_configuration.respond_to?(:lazy?) && value_for_configuration.lazy?
+            self.configuration = value_for_configuration.evaluate if value_for_configuration.try(:lazy?)
             response = instance_eval(&block)
             self.configuration = value_for_configuration
             response
@@ -127,6 +126,7 @@ module Grape
         end
 
         def inherited(subclass)
+          super
           subclass.reset!
           subclass.logger = logger.clone
         end
@@ -162,9 +162,13 @@ module Grape
 
       # Handle a request. See Rack documentation for what `env` is.
       def call(env)
-        result = @router.call(env)
-        result[1].delete(Grape::Http::Headers::X_CASCADE) unless cascade?
-        result
+        status, headers, response = @router.call(env)
+        unless cascade?
+          headers = Grape::Util::Header.new.merge(headers)
+          headers.delete('X-Cascade')
+        end
+
+        [status, headers, response]
       end
 
       # Some requests may return a HTTP 404 error if grape cannot find a matching
@@ -191,88 +195,52 @@ module Grape
       # will return an HTTP 405 response for any HTTP method that the resource
       # cannot handle.
       def add_head_not_allowed_methods_and_options_methods
-        versioned_route_configs = collect_route_config_per_pattern
         # The paths we collected are prepared (cf. Path#prepare), so they
         # contain already versioning information when using path versioning.
+        all_routes = self.class.endpoints.map(&:routes).flatten
+
         # Disable versioning so adding a route won't prepend versioning
         # informations again.
-        without_root_prefix do
-          without_versioning do
-            versioned_route_configs.each do |config|
-              next if config[:options][:matching_wildchar]
-
-              allowed_methods = config[:methods].dup
-
-              allowed_methods |= [Grape::Http::Headers::HEAD] if !self.class.namespace_inheritable(:do_not_route_head) && allowed_methods.include?(Grape::Http::Headers::GET)
+        without_root_prefix_and_versioning { collect_route_config_per_pattern(all_routes) }
+      end
 
-              allow_header = (self.class.namespace_inheritable(:do_not_route_options) ? allowed_methods : [Grape::Http::Headers::OPTIONS] | allowed_methods)
+      def collect_route_config_per_pattern(all_routes)
+        routes_by_regexp = all_routes.group_by(&:pattern_regexp)
 
-              config[:endpoint].options[:options_route_enabled] = true unless self.class.namespace_inheritable(:do_not_route_options) || allowed_methods.include?(Grape::Http::Headers::OPTIONS)
+        # Build the configuration based on the first endpoint and the collection of methods supported.
+        routes_by_regexp.each_value do |routes|
+          last_route = routes.last # Most of the configuration is taken from the last endpoint
+          next if routes.any? { |route| route.request_method == '*' }
 
-              attributes = config.merge(allowed_methods: allowed_methods, allow_header: allow_header)
-              generate_not_allowed_method(config[:pattern], **attributes)
-            end
-          end
-        end
-      end
+          allowed_methods = routes.map(&:request_method)
+          allowed_methods |= [Rack::HEAD] if !self.class.namespace_inheritable(:do_not_route_head) && allowed_methods.include?(Rack::GET)
 
-      def collect_route_config_per_pattern
-        all_routes       = self.class.endpoints.map(&:routes).flatten
-        routes_by_regexp = all_routes.group_by { |route| route.pattern.to_regexp }
+          allow_header = self.class.namespace_inheritable(:do_not_route_options) ? allowed_methods : [Rack::OPTIONS] | allowed_methods
+          last_route.app.options[:options_route_enabled] = true unless self.class.namespace_inheritable(:do_not_route_options) || allowed_methods.include?(Rack::OPTIONS)
 
-        # Build the configuration based on the first endpoint and the collection of methods supported.
-        routes_by_regexp.values.map do |routes|
-          last_route        = routes.last # Most of the configuration is taken from the last endpoint
-          matching_wildchar = routes.any? { |route| route.request_method == '*' }
-          {
-            options: { matching_wildchar: matching_wildchar },
-            pattern: last_route.pattern,
-            requirements: last_route.requirements,
-            path: last_route.origin,
-            endpoint: last_route.app,
-            methods: matching_wildchar ? Grape::Http::Headers::SUPPORTED_METHODS : routes.map(&:request_method)
-          }
+          @router.associate_routes(last_route.pattern, {
+                                     endpoint: last_route.app,
+                                     allow_header: allow_header
+                                   })
         end
       end
 
-      # Generate a route that returns an HTTP 405 response for a user defined
-      # path on methods not specified
-      def generate_not_allowed_method(pattern, allowed_methods: [], **attributes)
-        supported_methods =
-          if self.class.namespace_inheritable(:do_not_route_options)
-            Grape::Http::Headers::SUPPORTED_METHODS
-          else
-            Grape::Http::Headers::SUPPORTED_METHODS_WITHOUT_OPTIONS
-          end
-        not_allowed_methods = supported_methods - allowed_methods
-        @router.associate_routes(pattern, not_allowed_methods: not_allowed_methods, **attributes)
-      end
-
       # Allows definition of endpoints that ignore the versioning configuration
       # used by the rest of your API.
-      def without_versioning(&_block)
+      def without_root_prefix_and_versioning
         old_version = self.class.namespace_inheritable(:version)
         old_version_options = self.class.namespace_inheritable(:version_options)
+        old_root_prefix = self.class.namespace_inheritable(:root_prefix)
 
         self.class.namespace_inheritable_to_nil(:version)
         self.class.namespace_inheritable_to_nil(:version_options)
+        self.class.namespace_inheritable_to_nil(:root_prefix)
 
         yield
 
         self.class.namespace_inheritable(:version, old_version)
         self.class.namespace_inheritable(:version_options, old_version_options)
-      end
-
-      # Allows definition of endpoints that ignore the root prefix used by the
-      # rest of your API.
-      def without_root_prefix(&_block)
-        old_prefix = self.class.namespace_inheritable(:root_prefix)
-
-        self.class.namespace_inheritable_to_nil(:root_prefix)
-
-        yield
-
-        self.class.namespace_inheritable(:root_prefix, old_prefix)
+        self.class.namespace_inheritable(:root_prefix, old_root_prefix)
       end
     end
   end