grape 3.3.4 → 4.0.0

data/lib/grape/api/instance.rb

@@ -21,11 +21,13 @@ module Grape
       Boolean = Grape::API::Boolean
 
       class << self
-        extend Forwardable
-
         attr_accessor :configuration
 
-        def_delegators :@base, :to_s
+        def to_s
+          @base&.to_s || super
+        end
+
+        attr_reader :base
 
         def base=(grape_api)
           @base = grape_api
@@ -52,20 +54,19 @@ module Grape
         # 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!
-          @instance.call(env)
+          compile!.call(env)
         end
 
+        # Returns the compiled instance, so callers serve the one they
+        # compiled rather than re-reading @instance — +change!+ can nil it
+        # between the two reads (see #call / #recognize_path).
         def compile!
-          return if @instance
-
-          LOCK.synchronize { @instance ||= new }
+          @instance || LOCK.synchronize { @instance ||= new }
         end
 
         # see Grape::Router#recognize_path
         def recognize_path(path)
-          compile!
-          @instance.router.recognize_path(path)
+          compile!.router.recognize_path(path)
         end
 
         # Wipe the compiled API so we can recompile after changes were made.
@@ -81,7 +82,7 @@ module Grape
           # Propagate any inherited params down to our endpoints, and reset any
           # compiled routes.
           endpoints.each do |e|
-            e.inherit_settings(top_level_setting.namespace_stackable)
+            e.inherit_settings(top_level_setting)
             e.reset_routes!
           end
 
@@ -110,13 +111,19 @@ module Grape
 
         @router.compile!
         @router.freeze
+        @cascade = resolve_cascade
       end
 
       # Handle a request. See Rack documentation for what `env` is.
       def call(env)
         status, headers, response = @router.call(env)
-        unless cascade?
-          headers = Grape::Util::Header.new.merge(headers)
+        unless @cascade
+          # +merge!+, not +merge+: the latter is a `dup` plus a `merge!`, so the
+          # Header built on this line would be allocated only to be discarded.
+          # The copy stays because +headers+ can come from a mounted Rack app,
+          # which is free to hand back a frozen or shared Hash that the delete
+          # below must not reach into.
+          headers = Grape::Util::Header.new.merge!(headers)
           headers.delete('X-Cascade')
         end
 
@@ -131,12 +138,13 @@ module Grape
       # In some applications (e.g. mounting grape on rails), one might need to trap
       # errors from reaching upstream. This is effectivelly done by unsetting
       # X-Cascade. Default :cascade is true.
+      #
+      # Resolved in the constructor rather than per request: answering it walks
+      # the whole scope chain twice, and it reads the same settings the routes
+      # were compiled and frozen from -- changing those has to go through
+      # +change!+, which discards this instance.
       def 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]
-
-        true
+        @cascade
       end
 
       reset!
@@ -152,18 +160,11 @@ module Grape
         # contain already versioning information when using path versioning.
         all_routes = self.class.endpoints.flat_map(&:routes)
 
-        # Read the settings the helper routes need from a *copy* with the
-        # root-prefix/versioning keys stripped, so adding these routes won't
-        # prepend versioning information again. This used to delete those keys
-        # from the shared class-level settings and restore them in an ensure;
-        # a request served concurrently on another instance during a runtime
-        # recompile could observe the missing keys (e.g. via #cascade?). A
-        # local copy keeps that mutation off the shared object.
-        namespace_inheritable = self.class.inheritable_setting.namespace_inheritable.to_hash.except(*ROOT_PREFIX_VERSIONING_KEYS)
-        collect_route_config_per_pattern(all_routes, namespace_inheritable)
+        collect_route_config_per_pattern(all_routes)
       end
 
-      def collect_route_config_per_pattern(all_routes, namespace_inheritable)
+      def collect_route_config_per_pattern(all_routes)
+        setting = self.class.inheritable_setting
         routes_by_regexp = all_routes.group_by(&:pattern_regexp)
 
         # Build the configuration based on the first endpoint and the collection of methods supported.
@@ -172,18 +173,24 @@ module Grape
 
           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 !namespace_inheritable[:do_not_route_head] && allowed_methods.include?(Rack::GET)
+          allowed_methods |= [Rack::HEAD] if !setting.do_not_route_head? && allowed_methods.include?(Rack::GET)
 
-          allow_header = namespace_inheritable[:do_not_route_options] ? allowed_methods : [Rack::OPTIONS] | allowed_methods
-          last_route.app.options_route_enabled = true unless namespace_inheritable[:do_not_route_options] || allowed_methods.include?(Rack::OPTIONS)
+          allow_header = setting.do_not_route_options? ? allowed_methods : [Rack::OPTIONS] | allowed_methods
+          last_route.app.options_route_enabled = true unless setting.do_not_route_options? || allowed_methods.include?(Rack::OPTIONS)
 
           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_KEYS = %i[version version_options root_prefix].freeze
-      private_constant :ROOT_PREFIX_VERSIONING_KEYS
+      # Backs {#cascade?}; called once, from the constructor.
+      def resolve_cascade
+        setting = self.class.inheritable_setting
+        return setting.cascade if setting.cascade_defined?
+        return setting.version_options.cascade if setting.version_options
+
+        true
+      end
     end
   end
 end

data/lib/grape/content_types.rb

@@ -22,7 +22,20 @@ module Grape
     def mime_types_for(from_settings)
       return MIME_TYPES if from_settings == Grape::ContentTypes::DEFAULTS
 
-      from_settings.invert.transform_keys! { |k| media_type(k) }
+      MimeTypesCache[from_settings]
+    end
+
+    # Every format under both spellings in one plain Hash, so a lookup is a
+    # single +Hash#[]+. +HashWithIndifferentAccess+ converted the key on every
+    # read instead, and this is read two or three times per request — to
+    # negotiate the format, and again to set the response content type.
+    #
+    # Keys arrive as Symbols: the +content_type+ DSL symbolizes what it is
+    # given and the defaults are Symbols. The key is stored as it came too,
+    # so a middleware constructed directly with String keys still answers to
+    # either spelling, as the indifferent hash did.
+    def lookup_for(from_settings)
+      LookupCache[from_settings]
     end
 
     # The media type of a content-type header: the part before any `;`
@@ -36,5 +49,38 @@ module Grape
       base = content_type.include?(';') ? content_type.split(';', 2).first : content_type
       base.strip
     end
+
+    # Both tables below are derived from nothing but the content-type registry,
+    # and one content-type-aware middleware is built per API instance — so an
+    # app mounting N APIs held N copies of tables it only ever reads. Keying
+    # the cache on the registry itself collapses them: Hash keys compare by
+    # value, so every API that registers the same content types shares one
+    # table.
+    #
+    # Both the key and the table are frozen: the caller's registry stays
+    # reachable (through +middleware.options[:content_types]+, among others)
+    # and mutating a live key would corrupt a cache that is now shared
+    # process-wide.
+
+    class MimeTypesCache < Grape::Util::Cache
+      def initialize
+        super
+        @cache = Hash.new do |h, from_settings|
+          h[from_settings.dup.freeze] = from_settings.invert.transform_keys! { |mime_type| Grape::ContentTypes.media_type(mime_type) }.freeze
+        end
+      end
+    end
+
+    class LookupCache < Grape::Util::Cache
+      def initialize
+        super
+        @cache = Hash.new do |h, from_settings|
+          h[from_settings.dup.freeze] = from_settings.each_with_object({}) do |(format, media_type), lookup|
+            lookup[format] = media_type
+            lookup[format.is_a?(String) ? format.to_sym : format.to_s] = media_type
+          end.freeze
+        end
+      end
+    end
   end
 end

data/lib/grape/dry_types.rb

@@ -48,7 +48,7 @@ module Grape
     def self.wrapped_dry_types_const_get(dry_type, type)
       dry_type.const_get(type.name, false)
     rescue NameError
-      raise ArgumentError, "type #{type} should support coercion via `[]`" unless type.respond_to?(:[])
+      raise ArgumentError, "type `#{type}` should support coercion via `[]`" unless type.respond_to?(:[])
     end
   end
 end

data/lib/grape/dsl/callbacks.rb

@@ -9,15 +9,9 @@ module Grape
       # after: execute the given block after the endpoint code has run except in unsuccessful
       # finally: execute the given block after the endpoint code even if unsuccessful
 
-      {
-        before: :befores,
-        before_validation: :before_validations,
-        after_validation: :after_validations,
-        after: :afters,
-        finally: :finallies
-      }.each do |method_name, plural_key|
-        define_method method_name do |&block|
-          inheritable_setting.namespace_stackable[plural_key] = block
+      %i[before before_validation after_validation after finally].each do |callback_name|
+        define_method callback_name do |&block|
+          inheritable_setting.add_callback(callback_name, block)
         end
       end
     end

data/lib/grape/dsl/declared.rb

@@ -22,11 +22,11 @@ module Grape
       def declared(passed_params, include_parent_namespaces: true, include_missing: true, evaluate_given: false, stringify: false)
         raise MethodNotYetAvailable unless before_filter_passed
 
-        contract_key_map = inheritable_setting.namespace_stackable[:contract_key_map]
+        contract_key_map = inheritable_setting.contract_key_maps
         handler = DeclaredParamsHandler.new(include_missing:, evaluate_given:, stringify:, contract_key_map:)
-        declared_params = include_parent_namespaces ? inheritable_setting.route[:declared_params] : (inheritable_setting.namespace_stackable[:declared_params].last || [])
-        renamed_params = inheritable_setting.route[:renamed_params] || {}
-        route_params = options.dig(:route_options, :params) || {} # options = endpoint's option
+        declared_params = include_parent_namespaces ? inheritable_setting.route_declared_params : (inheritable_setting.declared_params.last || [])
+        renamed_params = inheritable_setting.route_renamed_params
+        route_params = config.params
 
         handler.call(passed_params, declared_params, route_params, renamed_params)
       end

data/lib/grape/dsl/desc.rb

@@ -19,6 +19,9 @@ module Grape
       #   successful call to this action
       # @option options :http_codes [Array[Array]] possible HTTP codes this
       #   endpoint may return, with their meanings, in a 2d array
+      # @option options :default_response [Hash] the definition and entity used
+      #   to present this endpoint's default response. Was `:default`, which is
+      #   deprecated.
       # @option options :named [String] a specific name to help find this route
       # @option options :body_name [String] override the autogenerated body name param
       # @option options :headers [Hash] HTTP headers this method can accept
@@ -50,21 +53,28 @@ module Grape
       #       # ...
       #     end
       #
-      def desc(description, *legacy_options, **options, &config_block)
-        if legacy_options.any?
-          Grape.deprecator.warn('Passing a positional options Hash to `desc` is deprecated. Pass keyword arguments instead.')
-          options = legacy_options.first.merge(options)
-        end
+      def desc(description, **options, &config_block)
+        resolved_options =
+          if options.key?(:default)
+            Grape.deprecator.warn('The `default` option of `desc` is deprecated. Use `default_response` instead.')
+            # Rebuilt rather than mutated in place: an explicit +default_response+
+            # still wins, since the merged Hash is the one that keeps its key.
+            { default_response: options[:default] }.merge(options.except(:default))
+          else
+            options
+          end
 
         settings =
           if config_block
             endpoint_config = defined?(configuration) ? configuration : nil
             Grape::Util::ApiDescription.new(description, endpoint_config, &config_block).settings
           else
-            options.merge(description:)
+            resolved_options.merge(description:)
           end
-        inheritable_setting.namespace[:description] = settings
-        inheritable_setting.route[:description] = settings
+        # Only the route scope is consumed downstream (by +route+ and the
+        # route's readers, e.g. +http_codes+); the namespace scope was
+        # write-only, so it is no longer populated.
+        inheritable_setting.route_description = settings
       end
     end
   end

data/lib/grape/dsl/entity.rb

@@ -34,7 +34,7 @@ module Grape
         if key
           representation = body&.merge(key => representation) || { key => representation }
         elsif entity_class.present? && body
-          raise ArgumentError, "Representation of type #{representation.class} cannot be merged." unless representation.respond_to?(:merge)
+          raise ArgumentError, "representation of type `#{representation.class}` cannot be merged" unless representation.respond_to?(:merge)
 
           representation = body.merge(representation)
         end
@@ -45,34 +45,52 @@ module Grape
       # Attempt to locate the Entity class for a given object, if not given
       # explicitly. This is done by looking for the presence of Klass::Entity,
       # where Klass is the class of the `object` parameter, or one of its
-      # ancestors.
+      # ancestors. Object is excluded from the search: top-level constants
+      # live on it, so a global ::Entity class is not a representer.
       # @param object [Object] the object to locate the Entity class for
       # @return [Class] the located Entity class, or nil if none is found
       def entity_class_for_obj(object)
-        klass = object_class(object)
-
-        representations = inheritable_setting.namespace_stackable_with_hash(:representations)
-        if representations
-          potential = klass.ancestors.detect { |potential| representations.key?(potential) }
-          return representations[potential] if potential && representations[potential]
-        end
-
-        return unless klass.const_defined?(:Entity)
-
-        entity = klass.const_get(:Entity)
-        entity if entity.respond_to?(:represent)
+        entity_for_class(object.class) || entity_for_class(element_class(object))
       end
 
       private
 
-      # Resolves the class used to look up the Entity for +object+.
+      # The class standing in for a collection or wrapper: ActiveRecord::Relation
+      # and the like expose #klass, anything else falls back to the class of its
+      # first element.
+      #
+      # Consulted only once the object's own class has come up empty, because
+      # both tests are duck-typed and plenty of single objects answer them —
+      # a Struct is Enumerable, so it responds to #first, and so does any model
+      # that includes Enumerable. Asking this first meant `represent Model,
+      # with: Entity` was silently ignored for those, the entity for the
+      # *element* type being looked up instead. Deferring it also keeps #first
+      # from being called at all when the object resolves on its own class.
+      #
       # @param object [Object] the object to represent.
-      # @return [Class] the object's collection element class, wrapped class, or its own class.
-      def object_class(object)
+      # @return [Class, nil]
+      def element_class(object)
         return object.klass if object.respond_to?(:klass)
-        return object.first.class if object.respond_to?(:first)
 
-        object.class
+        object.first.class if object.respond_to?(:first)
+      end
+
+      # @param klass [Class, nil] the class to look an entity up for.
+      # @return [Class, nil] the registered or conventionally named entity.
+      def entity_for_class(klass)
+        return if klass.nil?
+
+        representations = inheritable_setting.representations
+        if representations
+          potential = klass.ancestors.detect { |ancestor| representations.key?(ancestor) }
+          return representations[potential] if potential && representations[potential]
+        end
+
+        owner = klass.ancestors.detect { |ancestor| ancestor != Object && ancestor.const_defined?(:Entity, false) }
+        return unless owner
+
+        entity = owner.const_get(:Entity, false)
+        entity if entity.respond_to?(:represent)
       end
 
       # @param entity_class [Class] the entity class to use for representation.

data/lib/grape/dsl/helpers.rb

@@ -52,12 +52,12 @@ module Grape
       def make_inclusion(mod, &)
         define_boolean_in_mod(mod)
         inject_api_helpers_to_mod(mod, &)
-        inheritable_setting.namespace_stackable[:helpers] = mod
+        inheritable_setting.add_helper(mod)
       end
 
       def include_all_in_scope
         mod = Module.new
-        namespace_stackable(:helpers).each { |mod_to_include| mod.include mod_to_include }
+        inheritable_setting.helpers.each { |mod_to_include| mod.include mod_to_include }
         change!
         mod
       end
@@ -115,7 +115,7 @@ module Grape
         def process_named_params
           return if @named_params.blank?
 
-          api.inheritable_setting.namespace_stackable[:named_params] = @named_params
+          api.inheritable_setting.add_named_params(@named_params)
         end
       end
     end

data/lib/grape/dsl/inside_route.rb

@@ -15,7 +15,7 @@ module Grape
       end
 
       def configuration
-        config.for.configuration.evaluate
+        config.api.configuration.evaluate
       end
 
       # End the request and display an error to the
@@ -27,10 +27,10 @@ module Grape
       # @param backtrace [Array<String>] The backtrace of the exception that caused the error.
       # @param original_exception [Exception] The original exception that caused the error.
       def error!(message, status = nil, additional_headers = nil, backtrace = nil, original_exception = nil)
-        status = self.status(status || inheritable_setting.namespace_inheritable[:default_error_status])
+        resolved_status = self.status(status || inheritable_setting.default_error_status)
         headers = additional_headers.present? ? header.merge(additional_headers) : header
         throw :error, Grape::Exceptions::ErrorResponse.new(
-          message:, status:, headers:, backtrace:, original_exception:
+          message:, status: resolved_status, headers:, backtrace:, original_exception:
         )
       end
 
@@ -53,6 +53,12 @@ module Grape
         end
         header 'Location', url
         content_type 'text/plain'
+        # Render the message Grape generated as the plain text it is. Setting
+        # only the header left it to the API's own formatter, which on a JSON
+        # API returned the sentence wrapped in quotes under a text/plain content
+        # type. A caller-supplied body keeps the API's format: it may be
+        # structured, and the txt formatter would render a Hash through `to_s`.
+        api_format :txt unless body
         body body_message
       end
 
@@ -66,7 +72,7 @@ module Grape
         when Symbol, Integer
           @status = Rack::Utils.status_code(status)
         else
-          raise ArgumentError, 'Status code must be Integer or Symbol.'
+          raise ArgumentError, 'status code must be Integer or Symbol'
         end
       end
 
@@ -122,7 +128,7 @@ module Grape
       def sendfile(value = nil)
         return stream if value.nil?
 
-        raise ArgumentError, 'Argument must be a file path' unless value.is_a?(String)
+        raise ArgumentError, 'argument must be a file path' unless value.is_a?(String)
 
         file_body = Grape::ServeStream::FileBody.new(value)
         @stream = Grape::ServeStream::StreamResponse.new(file_body)
@@ -185,15 +191,21 @@ module Grape
       def stream_body(value)
         return Grape::ServeStream::FileBody.new(value) if value.is_a?(String)
 
-        raise ArgumentError, 'Stream object must respond to :each.' unless value.respond_to?(:each)
+        raise ArgumentError, 'stream object must respond to :each' unless value.respond_to?(:each)
 
         value
       end
 
       # The default HTTP status when none has been set explicitly.
+      # Reads the request method once instead of asking through +post?+ and
+      # +delete?+, each of which reads it again. Every response that did not set
+      # a status of its own comes through here, so it is read straight off the
+      # env: +Grape::Request+ wraps the very same Hash and answers
+      # +request_method+ with the same lookup, two method calls further down.
       def default_status
-        return 201 if request.post?
-        return 204 if request.delete? && @body.blank?
+        request_method = env[Rack::REQUEST_METHOD]
+        return 201 if request_method == Rack::POST
+        return 204 if request_method == Rack::DELETE && @body.blank?
 
         200
       end

data/lib/grape/dsl/middleware.rb

@@ -13,7 +13,7 @@ module Grape
         arr = [:use, middleware_class, *args]
         arr << block if block
 
-        inheritable_setting.namespace_stackable[:middleware] = arr
+        inheritable_setting.add_middleware(arr)
       end
 
       %i[insert insert_before insert_after].each do |method_name|
@@ -21,7 +21,7 @@ module Grape
           arr = [method_name, *args]
           arr << block if block
 
-          inheritable_setting.namespace_stackable[:middleware] = arr
+          inheritable_setting.add_middleware(arr)
         end
       end
 
@@ -29,7 +29,7 @@ module Grape
       # and arguments that are currently applied to the
       # application.
       def middleware
-        inheritable_setting.namespace_stackable[:middleware] || []
+        inheritable_setting.middleware
       end
     end
   end

data/lib/grape/dsl/parameters.rb

@@ -29,7 +29,7 @@ module Grape
       #       end
       #     end
       def build_with(build_with)
-        @api.inheritable_setting.namespace_inheritable[:build_params_with] = build_with
+        @api.inheritable_setting.build_params_with = build_with
       end
 
       # Include reusable params rules among current.
@@ -54,7 +54,9 @@ module Grape
       #       end
       #     end
       def use(*names, **options)
-        named_params = @api.inheritable_setting.namespace_stackable_with_hash(:named_params) || {}
+        return redispatch_legacy_options(:use, names, options) if legacy_options?(names)
+
+        named_params = @api.inheritable_setting.named_params || {}
         names.each do |name|
           params_block = named_params.fetch(name) do
             raise "Params :#{name} not found!"
@@ -74,8 +76,8 @@ module Grape
       #
       # @param attrs list of parameters names, or, if :using is
       #   passed as an option, which keys to include (:all or :none) from
-      #   the :using hash. The last key can be a hash, which specifies
-      #   options for the parameters
+      #   the :using hash. Passing the options as a trailing positional Hash
+      #   is deprecated; pass them as keyword arguments instead.
       # @option attrs :type [Class] the type to coerce this parameter to before
       #   passing it to the endpoint. See {Grape::Validations::Types} for a list of
       #   types that are supported automatically. Custom classes may be used
@@ -122,34 +124,20 @@ module Grape
       #         requires :name, type: String
       #       end
       #     end
-      def requires(*attrs, using: nil, except: nil, **opts, &block)
-        opts[:presence] = { value: true, message: opts[:message] }
-        opts = @group.deep_merge(opts) if @group
-
-        return require_required_and_optional_fields(attrs.first, using:, except:) if using
+      def requires(*attrs, using: nil, except: nil, as: nil, **opts, &)
+        return redispatch_legacy_options(:requires, attrs, { using:, except:, as: }.compact.merge(opts), &) if legacy_options?(attrs)
 
-        validate_attributes(attrs, **opts, &block)
-        block ? new_scope(attrs.first, type: opts[:type], as: opts[:as], &block) : push_declared_params(attrs, as: opts[:as])
+        declare(attrs, opts, required: true, using:, except:, as:, &)
       end
 
       # Allow, but don't require, one or more parameters for the current
       #   endpoint.
       # @param (see #requires)
       # @option (see #requires)
-      def optional(*attrs, using: nil, except: nil, **opts, &block)
-        type = opts[:type]
-        opts = @group.deep_merge(opts) if @group
-
-        # check type for optional parameter group
-        if attrs && block
-          raise Grape::Exceptions::MissingGroupType if type.nil?
-          raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
-        end
-
-        return require_optional_fields(attrs.first, using:, except:) if using
+      def optional(*attrs, using: nil, except: nil, as: nil, **opts, &)
+        return redispatch_legacy_options(:optional, attrs, { using:, except:, as: }.compact.merge(opts), &) if legacy_options?(attrs)
 
-        validate_attributes(attrs, **opts, &block)
-        block ? new_scope(attrs.first, type: opts[:type], as: opts[:as], optional: true, &block) : push_declared_params(attrs, as: opts[:as])
+        declare(attrs, opts, required: false, using:, except:, as:, &)
       end
 
       # Define common settings for one or more parameters
@@ -162,7 +150,7 @@ module Grape
 
       %i[mutually_exclusive exactly_one_of at_least_one_of all_or_none_of].each do |validator|
         define_method validator do |*attrs, message: nil|
-          validates(attrs, validator => { value: true, message: })
+          validates(attrs, { validator => { value: true, message: } })
         end
       end
 
@@ -203,13 +191,51 @@ module Grape
       # @return hash of parameters relevant for the current scope
       # @api private
       def params(params)
-        params = @parent.qualifying_params.presence || @parent.params(params) if @parent
-        params = map_params(params, @element) if @element
-        params
+        scoped = @parent ? (@parent.qualifying_params.presence || @parent.params(params)) : params
+        @element ? map_params(scoped, @element) : scoped
       end
 
       private
 
+      # @deprecated A trailing positional options Hash is deprecated; pass keyword
+      #   arguments instead. Before Ruby 3 keyword separation this Hash was pulled
+      #   off the argument list by `extract_options!`; now it lands in the splat and
+      #   would silently be treated as a parameter name.
+      # +requires+ and +optional+ differ only in whether what they declare is
+      # required, so the declaration itself lives here.
+      #
+      # The two +using:+ helpers stay separate. They are not one computation
+      # with a flag flipped: +requires+ treats +except+ as "these go in the
+      # other bucket", while +optional+ has no other bucket — +:all+ ignores
+      # +except+ and +:none+ uses it to drop fields entirely.
+      def declare(attrs, opts, required:, using:, except:, as:, &block)
+        merged_opts = @group&.deep_merge(opts) || opts
+        declared_as = as || merged_opts[:as]
+
+        if using
+          return require_required_and_optional_fields(attrs.first, using:, except:) if required
+
+          return require_optional_fields(attrs.first, using:, except:)
+        end
+
+        validates(attrs, merged_opts, required:)
+        return push_declared_params(attrs, as: declared_as) unless block
+
+        new_scope(attrs.first, type: merged_opts[:type], as: declared_as, optional: !required, &block)
+      end
+
+      def legacy_options?(args)
+        args.size > 1 && args.last.is_a?(Hash)
+      end
+
+      # Re-invokes +method_name+ with the trailing Hash splatted as keyword
+      # arguments, so Ruby routes its keys to the same place they would have
+      # reached had the caller omitted the braces.
+      def redispatch_legacy_options(method_name, args, opts, &)
+        Grape.deprecator.warn("Passing a positional options Hash to `#{method_name}` is deprecated. Pass keyword arguments instead.")
+        __send__(method_name, *args[0..-2], **args.last.merge(opts), &)
+      end
+
       def first_hash_key_or_param(parameter)
         parameter.is_a?(Hash) ? parameter.keys.first : parameter
       end