grape 2.4.0 → 3.2.1

data/UPGRADING.md

@@ -1,6 +1,160 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 3.2
+
+#### Rack parameter parsing errors now raise `Grape::Exceptions::RequestError`
+
+Rack errors raised during parameter parsing (malformed multipart, parameter type conflicts, encoding issues, etc.) are now wrapped in `Grape::Exceptions::RequestError` instead of their previous specific exception classes (`Grape::Exceptions::EmptyMessageBody`, `Grape::Exceptions::TooManyMultipartFiles`, `Grape::Exceptions::TooDeepParameters`, `Grape::Exceptions::ConflictingTypes`, `Grape::Exceptions::InvalidParameters`). Those classes have been removed.
+
+If you rescue any of these specific exceptions, update your rescue clauses to use `Grape::Exceptions::RequestError`:
+
+```ruby
+# Before
+rescue Grape::Exceptions::ConflictingTypes, Grape::Exceptions::TooDeepParameters => e
+  # ...
+
+# After
+rescue Grape::Exceptions::RequestError => e
+  # ...
+```
+
+The error message is now forwarded directly from Rack rather than translated through Grape's locale system. On Rack 3, all Rack bad-request errors share the `Rack::BadRequest` marker module and are covered by a single rescue.
+
+#### `endpoint_run_validators.grape` notification no longer fired when there are no validators
+
+`ActiveSupport::Notifications` subscribers listening to `endpoint_run_validators.grape` will no longer receive an event for endpoints that have no validators. If you rely on this notification to measure every request, subscribe to `endpoint_run.grape` instead, which always fires.
+
+#### Custom validators: use `default_message_key` and `validation_error!`
+
+Validators are now instantiated once at definition time and frozen. Any setup should happen in `initialize`, not in `validate_param!`.
+
+If your custom validator did work in `validate_param!` that only depends on the validator's options (not the param value), move it to `initialize`. A common case is compiling a value derived from options — for example, building a `Regexp`. Previously this may have been cached back into `@options`, which now raises `FrozenError` since `@options` and its nested values are deep-frozen by the base class:
+
+**Before:**
+```ruby
+class MyValidator < Grape::Validations::Validators::Base
+  def validate_param!(attr_name, params)
+    # raises FrozenError: @options is frozen, cannot store compiled pattern back into it
+    @options[:compiled] ||= Regexp.new(@options[:pattern])
+    validation_error!(attr_name) unless params[attr_name].match?(@options[:compiled])
+  end
+end
+```
+
+**After:**
+```ruby
+class MyValidator < Grape::Validations::Validators::Base
+  def initialize(attrs, options, required, scope, opts)
+    super
+    @pattern = Regexp.new(@options[:pattern]).freeze
+  end
+
+  def validate_param!(attr_name, params)
+    validation_error!(attr_name) unless params[attr_name].match?(@pattern)
+  end
+end
+```
+
+Any Array or Hash derived from options and stored in an ivar should be frozen, since the validator instance is shared across requests. `@options` itself (and any nested Hash/Array/String values within it) is deep-frozen by the base class, so mutations like `@options[:values] << 'extra'` will also raise a `FrozenError`.
+
+#### Custom validators: rename `@option` to `@options`
+
+The instance variable holding the validator's option value has been renamed from `@option` to `@options`. `@option` remains as an alias for backwards compatibility but will be removed in the next major release. Update any custom validators to use `@options` instead.
+
+Several new helpers are available — see [Available helpers](README.md#available-helpers) in the README for full documentation and examples.
+
+#### `with` now uses keyword arguments
+
+The `with` DSL method now uses `**opts` instead of a positional hash. Calls using bare keyword syntax are unaffected:
+
+```ruby
+# still works
+with(type: String, documentation: { in: 'body' }) { ... }
+```
+
+However, passing an explicit hash literal will now raise an `ArgumentError`:
+
+```ruby
+# raises ArgumentError
+with({ type: String }) { ... }
+```
+
+See [#2663](https://github.com/ruby-grape/grape/pull/2663) for more information.
+
+#### Custom validators: use `translate` instead of `I18n` directly
+
+`Grape::Util::Translation` is now included in `Grape::Validations::Validators::Base`. Custom validators that previously called `I18n.t` or `I18n.translate` directly should switch to the `translate`, which provides the same `:en` fallback logic used by all built-in validators.
+
+Key points:
+- `scope` defaults to `'grape.errors.messages'` — no need to specify it for standard error message keys.
+- Interpolation variables are passed directly to I18n.
+- `format` is no longer needed — `translate` returns the fully interpolated string.
+
+```ruby
+# Before
+raise Grape::Exceptions::Validation.new(
+  params: [@scope.full_name(attr_name)],
+  message: format(I18n.t(:my_key, scope: 'grape.errors.messages'), min: 2, max: 10)
+)
+
+# After
+raise Grape::Exceptions::Validation.new(
+  params: [@scope.full_name(attr_name)],
+  message: translate(:my_key, min: 2, max: 10)
+)
+```
+
+See [#2662](https://github.com/ruby-grape/grape/pull/2662) for more information.
+
+### Upgrading to >= 3.1
+
+#### Explicit kwargs for `namespace` and `route_param`
+
+The `API#namespace` and `route_param` methods are now defined with `**options` instead of `options = {}`. In addtion, `requirements` in explicitly defined so it's not in `options` anymore. You can still call `requirements` like before but `options[:requirements]` will be empty. For `route_param`, `type` is also an explicit parameter so it's not in `options` anymore. See [#2647](https://github.com/ruby-grape/grape/pull/2647) for more information.
+
+#### ParamsBuilder Grape::Extensions
+
+Deprecated [ParamsBuilder's extensions](https://github.com/ruby-grape/grape/blob/master/UPGRADING.md#params-builder) have been removed.
+
+#### Enhanced API compile!
+
+Endpoints are now "compiled" instead of lazy loaded. Historically, when calling `YourAPI.compile!` in `config.ru` (or just receiving the first API call), only routing was compiled see [Grape::Router#compile!](https://github.com/ruby-grape/grape/blob/bf90e95c3b17c415c944363b1c07eb9727089ee7/lib/grape/router.rb#L41-L54) and endpoints were lazy loaded. Now, it's part of the API compilation. See [#2645](https://github.com/ruby-grape/grape/pull/2645) for more information.
+
+### Upgrading to >= 3.0.0
+
+#### Ruby 3+ Argument Delegation Modernization
+
+Grape has been modernized to use Ruby 3+'s preferred argument delegation patterns. This change replaces `args.extract_options!` with explicit `**kwargs` parameters throughout the codebase.
+
+- All DSL methods now use explicit keyword arguments (`**kwargs`) instead of extracting options from mixed argument lists
+- Method signatures are now more explicit and follow Ruby 3+ best practices
+- The `active_support/core_ext/array/extract_options` dependency has been removed
+
+This is a modernization effort that improves code quality while maintaining full backward compatibility.
+
+See [#2618](https://github.com/ruby-grape/grape/pull/2618) for more information.
+
+#### Configuration API Migration from ActiveSupport::Configurable to Dry::Configurable
+
+Grape has migrated from `ActiveSupport::Configurable` to `Dry::Configurable` for its configuration system since its [deprecated](https://github.com/rails/rails/blob/1cdd190a25e483b65f1f25bbd0f13a25d696b461/activesupport/lib/active_support/configurable.rb#L3-L7).
+
+See [#2617](https://github.com/ruby-grape/grape/pull/2617) for more information.
+
+#### Endpoint execution simplified and `return` deprecated
+
+Executing a endpoint's block has been simplified and calling `return` in it has been deprecated. Use `next` instead.
+
+See [#2577](https://github.com/ruby-grape/grape/pull/2577) for more information.
+
+#### Old Deprecations Clean Up
+
+- `rack_response` has been removed in favor of using `error!`.
+- `Grape::Exceptions::MissingGroupType` and `Grape::Exceptions::UnsupportedGroupType` aliases `MissingGroupTypeError and `UnsupportedGroupType` have been removed.
+- `Grape::Validations::Base` has been removed in favor of `Grape::Validations::Validators::Base`.
+
+See [2573](https://github.com/ruby-grape/grape/pull/2573) for more information.
+
 ### Upgrading to >= 2.4.0
 
 #### Grape::Middleware::Auth::Base

data/grape.gemspec

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-$LOAD_PATH.unshift File.expand_path('lib', __dir__)
-require 'grape/version'
+require_relative 'lib/grape/version'
 
 Gem::Specification.new do |s|
   s.name        = 'grape'
@@ -21,7 +20,8 @@ Gem::Specification.new do |s|
     'rubygems_mfa_required' => 'true'
   }
 
-  s.add_dependency 'activesupport', '>= 6.1'
+  s.add_dependency 'activesupport', '>= 7.2'
+  s.add_dependency 'dry-configurable'
   s.add_dependency 'dry-types', '>= 1.1'
   s.add_dependency 'mustermann-grape', '~> 1.1.0'
   s.add_dependency 'rack', '>= 2'
@@ -29,5 +29,5 @@ Gem::Specification.new do |s|
 
   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.7.0'
+  s.required_ruby_version = '>= 3.2'
 end

data/lib/grape/api/instance.rb

@@ -5,32 +5,33 @@ module Grape
     # 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::DSL::Settings
+      extend Grape::DSL::Desc
+      extend Grape::DSL::Validations
+      extend Grape::DSL::Callbacks
+      extend Grape::DSL::Logger
+      extend Grape::DSL::Middleware
+      extend Grape::DSL::RequestResponse
+      extend Grape::DSL::Routing
+      extend Grape::DSL::Helpers
       extend Grape::Middleware::Auth::DSL
-      include Grape::DSL::API
+
+      Boolean = Grape::API::Boolean
 
       class << self
-        attr_reader :instance, :base
+        extend Forwardable
+
         attr_accessor :configuration
 
-        def given(conditional_option, &block)
-          evaluate_as_instance_with_configuration(block, lazy: true) if conditional_option && block
-        end
-
-        def mounted(&block)
-          evaluate_as_instance_with_configuration(block, lazy: true)
-        end
+        def_delegators :@base, :to_s
 
         def base=(grape_api)
           @base = grape_api
           grape_api.instances << self
         end
 
-        def to_s
-          base&.to_s || super
-        end
-
         def base_instance?
-          self == base.base_instance
+          self == @base.base_instance
         end
 
         # A class-level lock to ensure the API is not compiled by multiple
@@ -44,92 +45,33 @@ module Grape
           reset_validations!
         end
 
-        # Parses the API's definition and compiles it into an instance of
-        # Grape::API.
-        def compile
-          @instance ||= new # rubocop:disable Naming/MemoizedInstanceVariableName
-        end
-
-        # Wipe the compiled API so we can recompile after changes were made.
-        def change!
-          @instance = nil
-        end
-
         # This is the interface point between Rack and Grape; it accepts a request
         # from Rack and ultimately returns an array of three values: the status,
         # the headers, and the body. See [the rack specification]
         # (http://www.rubydoc.info/github/rack/rack/master/file/SPEC) for more.
         def call(env)
           compile!
-          call!(env)
-        end
-
-        # A non-synchronized version of ::call.
-        def call!(env)
-          instance.call(env)
-        end
-
-        # (see #cascade?)
-        def cascade(value = nil)
-          if value.nil?
-            inheritable_setting.namespace_inheritable.key?(:cascade) ? !namespace_inheritable(:cascade).nil? : true
-          else
-            namespace_inheritable(:cascade, value)
-          end
+          @instance.call(env)
         end
 
         def compile!
-          return if instance
+          return if @instance
 
-          LOCK.synchronize { compile unless instance }
+          LOCK.synchronize { @instance ||= new }
         end
 
         # see Grape::Router#recognize_path
         def recognize_path(path)
           compile!
-          instance.router.recognize_path(path)
+          @instance.router.recognize_path(path)
         end
 
-        protected
-
-        def prepare_routes
-          endpoints.map(&:routes).flatten
-        end
-
-        # Execute first the provided block, then each of the
-        # block passed in. Allows for simple 'before' setups
-        # of settings stack pushes.
-        def nest(*blocks, &block)
-          blocks.compact!
-          if blocks.any?
-            evaluate_as_instance_with_configuration(block) if block
-            blocks.each { |b| evaluate_as_instance_with_configuration(b) }
-            reset_validations!
-          else
-            instance_eval(&block)
-          end
-        end
-
-        def evaluate_as_instance_with_configuration(block, lazy: false)
-          lazy_block = Grape::Util::Lazy::Block.new do |configuration|
-            value_for_configuration = configuration
-            self.configuration = value_for_configuration.evaluate if value_for_configuration.try(:lazy?)
-            response = instance_eval(&block)
-            self.configuration = value_for_configuration
-            response
-          end
-          if base && base_instance? && lazy
-            lazy_block
-          else
-            lazy_block.evaluate_from(configuration)
-          end
+        # Wipe the compiled API so we can recompile after changes were made.
+        def change!
+          @instance = nil
         end
 
-        def inherited(subclass)
-          super
-          subclass.reset!
-          subclass.logger = logger.clone
-        end
+        protected
 
         def inherit_settings(other_settings)
           top_level_setting.inherit_from other_settings.point_in_time_copy
@@ -143,6 +85,14 @@ module Grape
 
           reset_routes!
         end
+
+        private
+
+        def inherited(subclass)
+          super
+          subclass.reset!
+          subclass.logger logger.clone
+        end
       end
 
       attr_reader :router
@@ -180,8 +130,9 @@ module Grape
       # errors from reaching upstream. This is effectivelly done by unsetting
       # X-Cascade. Default :cascade is true.
       def cascade?
-        return self.class.namespace_inheritable(:cascade) if self.class.inheritable_setting.namespace_inheritable.key?(:cascade)
-        return self.class.namespace_inheritable(:version_options)[:cascade] if self.class.namespace_inheritable(:version_options)&.key?(:cascade)
+        namespace_inheritable = self.class.inheritable_setting.namespace_inheritable
+        return namespace_inheritable[:cascade] if namespace_inheritable.key?(:cascade)
+        return namespace_inheritable[:version_options][:cascade] if namespace_inheritable[:version_options]&.key?(:cascade)
 
         true
       end
@@ -197,7 +148,7 @@ module Grape
       def add_head_not_allowed_methods_and_options_methods
         # 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
+        all_routes = self.class.endpoints.flat_map(&:routes)
 
         # Disable versioning so adding a route won't prepend versioning
         # informations again.
@@ -206,41 +157,37 @@ module Grape
 
       def collect_route_config_per_pattern(all_routes)
         routes_by_regexp = all_routes.group_by(&:pattern_regexp)
+        namespace_inheritable = self.class.inheritable_setting.namespace_inheritable
 
         # 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 == '*' }
 
+          last_route = routes.last # Most of the configuration is taken from the last endpoint
           allowed_methods = routes.map(&:request_method)
-          allowed_methods |= [Rack::HEAD] if !self.class.namespace_inheritable(:do_not_route_head) && allowed_methods.include?(Rack::GET)
+          allowed_methods |= [Rack::HEAD] if !namespace_inheritable[:do_not_route_head] && allowed_methods.include?(Rack::GET)
 
-          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)
+          allow_header = namespace_inheritable[:do_not_route_options] ? allowed_methods : [Rack::OPTIONS] | allowed_methods
+          last_route.app.options[:options_route_enabled] = true unless namespace_inheritable[:do_not_route_options] || allowed_methods.include?(Rack::OPTIONS)
 
-          @router.associate_routes(last_route.pattern, {
-                                     endpoint: last_route.app,
-                                     allow_header: allow_header
-                                   })
+          greedy_route = Grape::Router::GreedyRoute.new(last_route.pattern, endpoint: last_route.app, allow_header:)
+          @router.associate_routes(greedy_route)
         end
       end
 
+      ROOT_PREFIX_VERSIONING_KEY = %i[version version_options root_prefix].freeze
+      private_constant :ROOT_PREFIX_VERSIONING_KEY
+
       # Allows definition of endpoints that ignore the versioning configuration
       # used by the rest of your API.
       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)
-
+        inheritable_setting = self.class.inheritable_setting
+        deleted_values = inheritable_setting.namespace_inheritable.delete(*ROOT_PREFIX_VERSIONING_KEY)
         yield
-
-        self.class.namespace_inheritable(:version, old_version)
-        self.class.namespace_inheritable(:version_options, old_version_options)
-        self.class.namespace_inheritable(:root_prefix, old_root_prefix)
+      ensure
+        ROOT_PREFIX_VERSIONING_KEY.each_with_index do |key, index|
+          inheritable_setting.namespace_inheritable[key] = deleted_values[index]
+        end
       end
     end
   end

data/lib/grape/api.rb

@@ -5,7 +5,9 @@ module Grape
   # should subclass this class in order to build an API.
   class API
     # Class methods that we want to call on the API rather than on the API object
-    NON_OVERRIDABLE = %i[call call! configuration compile! inherited recognize_path].freeze
+    NON_OVERRIDABLE = %i[base= base_instance? call change! configuration compile! inherit_settings recognize_path reset! routes top_level_setting= top_level_setting].freeze
+
+    Helpers = Grape::DSL::Helpers::BaseHelper
 
     class Boolean
       def self.build(val)
@@ -15,32 +17,19 @@ module Grape
       end
     end
 
-    class Instance
-      Boolean = Grape::API::Boolean
-    end
-
     class << self
       extend Forwardable
+
       attr_accessor :base_instance, :instances
 
       delegate_missing_to :base_instance
-      def_delegators :base_instance, :new, :configuration
 
       # This is the interface point between Rack and Grape; it accepts a request
       # from Rack and ultimately returns an array of three values: the status,
       # the headers, and the body. See [the rack specification]
-      # (http://www.rubydoc.info/github/rack/rack/master/file/SPEC) for more.
+      # (https://github.com/rack/rack/blob/main/SPEC.rdoc) for more.
       # NOTE: This will only be called on an API directly mounted on RACK
-      def_delegators :instance_for_rack, :call, :compile!
-
-      # When inherited, will create a list of all instances (times the API was mounted)
-      # It will listen to the setup required to mount that endpoint, and replicate it on any new instance
-      def inherited(api)
-        super
-
-        api.initial_setup(self == Grape::API ? Grape::API::Instance : @base_instance)
-        api.override_all_methods!
-      end
+      def_delegators :base_instance, :new, :configuration, :call, :change!, :compile!, :recognize_path, :routes
 
       # Initialize the instance variables on the remountable class, and the base_instance
       # an instance that will be used to create the set up but will not be mounted
@@ -54,8 +43,8 @@ module Grape
       # Redefines all methods so that are forwarded to add_setup and be recorded
       def override_all_methods!
         (base_instance.methods - Class.methods - NON_OVERRIDABLE).each do |method_override|
-          define_singleton_method(method_override) do |*args, &block|
-            add_setup(method: method_override, args: args, block: block)
+          define_singleton_method(method_override) do |*args, **kwargs, &block|
+            add_setup(method: method_override, args:, kwargs:, block:)
           end
         end
       end
@@ -89,6 +78,15 @@ module Grape
 
       private
 
+      # When inherited, will create a list of all instances (times the API was mounted)
+      # It will listen to the setup required to mount that endpoint, and replicate it on any new instance
+      def inherited(api)
+        super
+
+        api.initial_setup(self == Grape::API ? Grape::API::Instance : @base_instance)
+        api.override_all_methods!
+      end
+
       # Replays the set up to produce an API as defined in this class, can be called
       # on classes that inherit from Grape::API
       def replay_setup_on(instance)
@@ -97,16 +95,8 @@ module Grape
         end
       end
 
-      def instance_for_rack
-        if never_mounted?
-          base_instance
-        else
-          mounted_instances.first
-        end
-      end
-
       # Adds a new stage to the set up require to get a Grape::API up and running
-      def add_setup(step)
+      def add_setup(**step)
         @setup << step
         last_response = nil
         @instances.each do |instance|
@@ -130,12 +120,13 @@ module Grape
         end
       end
 
-      def replay_step_on(instance, method:, args:, block:)
-        return if skip_immediate_run?(instance, args)
+      def replay_step_on(instance, method:, args:, kwargs:, block:)
+        return if skip_immediate_run?(instance, args, kwargs)
 
         eval_args = evaluate_arguments(instance.configuration, *args)
-        response = instance.send(method, *eval_args, &block)
-        if skip_immediate_run?(instance, [response])
+        eval_kwargs = kwargs.deep_transform_values { |v| evaluate_arguments(instance.configuration, v).first }
+        response = instance.__send__(method, *eval_args, **eval_kwargs, &block)
+        if skip_immediate_run?(instance, [response], kwargs)
           response
         else
           evaluate_arguments(instance.configuration, response).first
@@ -143,18 +134,18 @@ module Grape
       end
 
       # Skips steps that contain arguments to be lazily executed (on re-mount time)
-      def skip_immediate_run?(instance, args)
+      def skip_immediate_run?(instance, args, kwargs)
         instance.base_instance? &&
-          (any_lazy?(args) || args.any? { |arg| arg.is_a?(Hash) && any_lazy?(arg.values) })
+          (any_lazy?(args) || args.any? { |arg| arg.is_a?(Hash) && any_lazy?(arg.values) } || any_lazy?(kwargs.values))
       end
 
       def any_lazy?(args)
-        args.any? { |argument| argument.try(:lazy?) }
+        args.any? { |argument| argument_lazy?(argument) }
       end
 
       def evaluate_arguments(configuration, *args)
         args.map do |argument|
-          if argument.try(:lazy?)
+          if argument_lazy?(argument)
             argument.evaluate_from(configuration)
           elsif argument.is_a?(Hash)
             argument.transform_values { |value| evaluate_arguments(configuration, value).first }
@@ -166,12 +157,8 @@ module Grape
         end
       end
 
-      def never_mounted?
-        mounted_instances.empty?
-      end
-
-      def mounted_instances
-        instances - [base_instance]
+      def argument_lazy?(argument)
+        argument.respond_to?(:lazy?) && argument.lazy?
       end
     end
   end

data/lib/grape/content_types.rb

@@ -22,10 +22,7 @@ module Grape
     def mime_types_for(from_settings)
       return MIME_TYPES if from_settings == Grape::ContentTypes::DEFAULTS
 
-      from_settings.each_with_object({}) do |(k, v), types_without_params|
-        # remove optional parameter
-        types_without_params[v.split(';', 2).first] = k
-      end
+      from_settings.invert.transform_keys! { |k| k.include?(';') ? k.split(';', 2).first : k }
     end
   end
 end