grape 3.3.4 → 4.0.0

data/lib/grape/dsl/request_response.rb

@@ -6,66 +6,76 @@ module Grape
       # Specify the default format for the API's serializers.
       # May be `:json` or `:txt` (default).
       def default_format(new_format = nil)
-        return inheritable_setting.namespace_inheritable[:default_format] if new_format.nil?
+        return inheritable_setting.default_format if new_format.nil?
 
-        inheritable_setting.namespace_inheritable[:default_format] = new_format.to_sym
+        inheritable_setting.default_format = new_format.to_sym
       end
 
       # Specify the format for the API's serializers.
       # May be `:json`, `:xml`, `:txt`, etc.
       def format(new_format = nil)
-        return inheritable_setting.namespace_inheritable[:format] if new_format.nil?
+        return inheritable_setting.format if new_format.nil?
 
         symbolic_new_format = new_format.to_sym
-        inheritable_setting.namespace_inheritable[:format] = symbolic_new_format
-        inheritable_setting.namespace_inheritable[:default_error_formatter] = Grape::ErrorFormatter.formatter_for(symbolic_new_format)
+        inheritable_setting.format = symbolic_new_format
+        inheritable_setting.default_error_formatter = Grape::ErrorFormatter.formatter_for(symbolic_new_format)
 
         content_type = content_types[symbolic_new_format]
         raise Grape::Exceptions::MissingMimeType.new(new_format) unless content_type
 
-        inheritable_setting.namespace_stackable[:content_types] = { symbolic_new_format => content_type }
+        inheritable_setting.add_content_type(symbolic_new_format, content_type)
       end
 
       # Specify a custom formatter for a content-type.
       def formatter(content_type, new_formatter)
-        inheritable_setting.namespace_stackable[:formatters] = { content_type.to_sym => new_formatter }
+        inheritable_setting.add_formatter(content_type.to_sym, new_formatter)
       end
 
       # Specify a custom parser for a content-type.
       def parser(content_type, new_parser)
-        inheritable_setting.namespace_stackable[:parsers] = { content_type.to_sym => new_parser }
+        inheritable_setting.add_parser(content_type.to_sym, new_parser)
       end
 
-      # Specify a default error formatter.
+      # Specify a default error formatter, by the name it is registered under.
+      # A name nothing is registered for used to be stored as
+      # +ErrorFormatter::Txt+ — the fallback the lookup applied — so a typo
+      # read back as a working setting and silently rendered errors as text.
       def default_error_formatter(new_formatter_name = nil)
-        return inheritable_setting.namespace_inheritable[:default_error_formatter] if new_formatter_name.nil?
+        return inheritable_setting.default_error_formatter if new_formatter_name.nil?
 
-        new_formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
-        inheritable_setting.namespace_inheritable[:default_error_formatter] = new_formatter
+        formatter = Grape::ErrorFormatter.formatter_for(new_formatter_name)
+        raise Grape::Exceptions::UnknownErrorFormatter.new(new_formatter_name) if formatter.nil?
+
+        inheritable_setting.default_error_formatter = formatter
       end
 
+      # Specify a custom error formatter for a format, passed positionally or
+      # as +with:+. A nil formatter used to be registered as-is, which is the
+      # one thing the registration cannot mean: the format then resolves as if
+      # the call had never been made. Reject it here, where the mistake is.
       def error_formatter(format, options = nil, with: nil)
         formatter = with || options
-        inheritable_setting.namespace_stackable[:error_formatters] = { format.to_sym => formatter }
+        raise ArgumentError, "error_formatter `#{format.inspect}` requires a formatter, given positionally or as `with:`" if formatter.nil?
+
+        inheritable_setting.add_error_formatter(format.to_sym, formatter)
       end
 
       # Specify additional content-types, e.g.:
       #   content_type :xls, 'application/vnd.ms-excel'
       def content_type(key, val)
-        inheritable_setting.namespace_stackable[:content_types] = { key.to_sym => val }
+        inheritable_setting.add_content_type(key.to_sym, val)
       end
 
       # All available content types.
       def content_types
-        c_types = inheritable_setting.namespace_stackable_with_hash(:content_types)
-        Grape::ContentTypes.content_types_for c_types
+        Grape::ContentTypes.content_types_for(inheritable_setting.content_types)
       end
 
       # Specify the default status code for errors.
       def default_error_status(new_status = nil)
-        return inheritable_setting.namespace_inheritable[:default_error_status] if new_status.nil?
+        return inheritable_setting.default_error_status if new_status.nil?
 
-        inheritable_setting.namespace_inheritable[:default_error_status] = new_status
+        inheritable_setting.default_error_status = new_status
       end
 
       # Allows you to rescue certain exceptions that occur to return
@@ -99,32 +109,20 @@ module Grape
       def rescue_from(*args, with: nil, rescue_subclasses: true, backtrace: false, original_exception: false, &block)
         handler = extract_handler(args, with:, block:)
         meta_selector = (args & META_RESCUE_SELECTORS).first
-        raise ArgumentError, "rescue_from #{meta_selector.inspect} does not accept additional arguments" if meta_selector && args.size > 1
-
-        namespace_inheritable = nil
-        arg = nil
-
-        if args.one?
-          arg = args.first
-          namespace_inheritable = inheritable_setting.namespace_inheritable
-        end
+        raise ArgumentError, "rescue_from `#{meta_selector.inspect}` does not accept additional arguments" if meta_selector && args.size > 1
 
-        case arg
+        case meta_selector
         when :all
-          namespace_inheritable[:rescue_all] = true
-          namespace_inheritable[:all_rescue_handler] = handler
+          inheritable_setting.add_all_rescue_handler(handler)
         when :grape_exceptions
-          namespace_inheritable[:rescue_all] = true
-          namespace_inheritable[:rescue_grape_exceptions] = true
-          namespace_inheritable[:grape_exceptions_rescue_handler] = handler
+          inheritable_setting.add_grape_exceptions_rescue_handler(handler)
         when :internal_grape_exceptions
-          namespace_inheritable[:internal_grape_exceptions_rescue_handler] = handler
+          inheritable_setting.add_internal_grape_exceptions_rescue_handler(handler)
         else
-          handler_type = rescue_subclasses ? :rescue_handlers : :base_only_rescue_handlers
-          inheritable_setting.namespace_reverse_stackable[handler_type] = args.to_h { |klass| [klass, handler] }
+          inheritable_setting.add_rescue_handlers(args.to_h { |klass| [klass, handler] }, subclasses: rescue_subclasses)
         end
 
-        inheritable_setting.namespace_stackable[:rescue_options] = RescueOptions.new(backtrace:, original_exception:)
+        inheritable_setting.add_rescue_options(RescueOptions.new(backtrace:, original_exception:))
       end
 
       # Allows you to specify a default representation entity for a
@@ -150,7 +148,7 @@ module Grape
       def represent(model_class, with:)
         raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless with.is_a?(Class)
 
-        inheritable_setting.namespace_stackable[:representations] = { model_class => with }
+        inheritable_setting.add_representation(model_class, with)
       end
 
       private
@@ -165,7 +163,7 @@ module Grape
         case with
         when Proc, Symbol then with
         when String then with.to_sym
-        else raise ArgumentError, "with: #{with.class}, expected Symbol, String or Proc"
+        else raise ArgumentError, "with: `#{with.class}`, expected Symbol, String or Proc"
         end
       end
     end

data/lib/grape/dsl/rescue_options.rb

@@ -3,9 +3,10 @@
 module Grape
   module DSL
     # Immutable value object holding the response-shaping booleans accepted
-    # by +Grape::DSL::RequestResponse#rescue_from+. Stored on the
-    # inheritable settings as +namespace_stackable[:rescue_options]+ and
-    # delegated to by +Grape::Middleware::Error+ (which forwards
+    # by +Grape::DSL::RequestResponse#rescue_from+. Recorded on the
+    # inheritable settings via +Grape::Util::InheritableSetting#add_rescue_options+
+    # (the nearest scope's latest registration wins on read, see
+    # +#rescue_options+) and delegated to by +Grape::Middleware::Error+ (which forwards
     # +backtrace+/+original_exception+ to the formatter as
     # +include_backtrace+/+include_original_exception+).
     #
@@ -13,8 +14,8 @@ module Grape
     # signature on purpose: keeping them on both sides means each entry point
     # is self-documenting without needing to import a shared constant — the
     # DSL signature shows what a user sees in the IDE, and the Data object
-    # has working defaults when constructed directly (middleware
-    # `DEFAULT_OPTIONS`, spec fixtures, etc.). The two must stay in lockstep.
+    # has working defaults when constructed directly (spec fixtures, a
+    # middleware built by hand). The two must stay in lockstep.
     RescueOptions = Data.define(:backtrace, :original_exception) do
       def initialize(backtrace: false, original_exception: false)
         super

data/lib/grape/dsl/routing.rb

@@ -16,9 +16,9 @@ module Grape
       end
 
       def cascade(value = nil)
-        return inheritable_setting.namespace_inheritable.key?(:cascade) ? !inheritable_setting.namespace_inheritable[:cascade].nil? : true if value.nil?
+        return inheritable_setting.cascade_defined? ? inheritable_setting.cascade : true if value.nil?
 
-        inheritable_setting.namespace_inheritable[:cascade] = value
+        inheritable_setting.cascade = value
       end
 
       # Specify an API version.
@@ -72,13 +72,13 @@ module Grape
 
         if block
           within_namespace do
-            inheritable_setting.namespace_inheritable[:version] = requested_versions
-            inheritable_setting.namespace_inheritable[:version_options] = options
+            inheritable_setting.version = requested_versions
+            inheritable_setting.version_options = options
             instance_eval(&block)
           end
         else
-          inheritable_setting.namespace_inheritable[:version] = requested_versions
-          inheritable_setting.namespace_inheritable[:version_options] = options
+          inheritable_setting.version = requested_versions
+          inheritable_setting.version_options = options
         end
 
         @versions&.last
@@ -86,9 +86,9 @@ module Grape
 
       # Define a root URL prefix for your entire API.
       def prefix(prefix = nil)
-        return inheritable_setting.namespace_inheritable[:root_prefix] if prefix.nil?
+        return inheritable_setting.root_prefix if prefix.nil?
 
-        inheritable_setting.namespace_inheritable[:root_prefix] = prefix.to_s
+        inheritable_setting.root_prefix = prefix.to_s
       end
 
       # Create a scope without affecting the URL.
@@ -102,33 +102,40 @@ module Grape
       end
 
       def build_with(build_with)
-        inheritable_setting.namespace_inheritable[:build_params_with] = build_with
+        inheritable_setting.build_params_with = build_with
       end
 
       # Do not route HEAD requests to GET requests automatically.
       def do_not_route_head!
-        inheritable_setting.namespace_inheritable[:do_not_route_head] = true
+        inheritable_setting.do_not_route_head!
       end
 
       # Do not automatically route OPTIONS.
       def do_not_route_options!
-        inheritable_setting.namespace_inheritable[:do_not_route_options] = true
+        inheritable_setting.do_not_route_options!
       end
 
       def lint!
-        inheritable_setting.namespace_inheritable[:lint] = true
+        inheritable_setting.lint!
       end
 
       def do_not_document!
-        inheritable_setting.namespace_inheritable[:do_not_document] = true
+        inheritable_setting.do_not_document!
       end
 
-      def mount(mounts, *opts)
-        mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair)
-        mounts.each_pair do |app, path|
+      def mount(mounts, opts = {})
+        mount_opts = opts
+        if opts[:refresh_already_mounted]
+          Grape.deprecator.warn('`refresh_already_mounted` is not a `mount` option and will be ignored in a future release.')
+          drop_endpoints_mounted_for(mounts)
+          # Dropped before the recursion below re-enters with the same options,
+          # so a Grape API does not warn once per mount and once per instance.
+          mount_opts = opts.except(:refresh_already_mounted)
+        end
+
+        normalize_mounts(mounts).each_pair do |app, path|
           if app.respond_to?(:mount_instance)
-            opts_with = opts.any? ? opts.first[:with] : {}
-            mount({ app.mount_instance(configuration: opts_with) => path }, *opts)
+            mount({ app.mount_instance(configuration: mount_opts[:with] || {}) => path }, mount_opts)
             next
           end
           in_setting = inheritable_setting
@@ -137,7 +144,7 @@ module Grape
           # instantiated Grape::API::Instance (vs. a bare Rack app).
           if app.is_a?(Grape::Mountable)
             mount_path = Grape::Util::PathNormalizer.call(path)
-            app.top_level_setting.namespace_stackable[:mount_path] = mount_path
+            app.top_level_setting.add_mount_path(mount_path)
 
             app.inherit_settings(inheritable_setting)
 
@@ -147,23 +154,13 @@ module Grape
             change!
           end
 
-          # When trying to mount multiple times the same endpoint, remove the previous ones
-          # from the list of endpoints if refresh_already_mounted parameter is true
-          refresh_already_mounted = opts.any? ? opts.first[:refresh_already_mounted] : false
-          if refresh_already_mounted && !endpoints.empty?
-            endpoints.delete_if do |endpoint|
-              endpoint.options[:app].to_s == app.to_s
-            end
-          end
-
           endpoints << Grape::Endpoint.new(
             in_setting,
-            method: :any,
+            http_methods: :any,
             path:,
             app:,
-            route_options: { anchor: false },
-            forward_match: !app.respond_to?(:inheritable_setting),
-            for: self
+            anchor: false,
+            api: self
           )
         end
       end
@@ -173,6 +170,9 @@ module Grape
       #
       # @param methods [HTTP Verb] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
       # @param paths [String] One or more strings representing the URL segment(s) for this route.
+      # @param requirements [Hash] Regular-expression constraints for named path params; the route matches only when every requirement is satisfied.
+      # @param anchor [Boolean] Whether the route is anchored to the whole path. Defaults to `true`; pass `false` for catch-all routes (e.g. `'/(*:path)'`).
+      # @param route_options [Hash] Any additional custom options, carried through to `route.options`.
       #
       # @example Defining a basic route.
       #   class MyAPI < Grape::API
@@ -180,19 +180,27 @@ module Grape
       #       {hello: 'world'}
       #     end
       #   end
-      def route(methods, paths = ['/'], route_options = {}, &)
-        method = methods == :any ? '*' : methods
-        endpoint_params = inheritable_setting.namespace_stackable_with_hash(:params) || {}
-        endpoint_description = inheritable_setting.route[:description]
-        all_route_options = { params: endpoint_params }
-        all_route_options.deep_merge!(endpoint_description) if endpoint_description
+      def route(methods, paths = ['/'], requirements: nil, anchor: true, **route_options, &)
+        validate_requirements!(requirements)
+
+        http_methods = methods == :any ? '*' : methods
+        endpoint_description = inheritable_setting.route_description
+
+        # +params+, +requirements+ and +anchor+ each travel as their own endpoint
+        # input; the route-options bag keeps the description's other keys
+        # (+success+, +tags+, …) plus any custom options.
+        params = prepare_params(endpoint_description[:params])
+        all_route_options = endpoint_description.except(:params)
         all_route_options.deep_merge!(route_options) if route_options.present?
 
         new_endpoint = Grape::Endpoint.new(
           inheritable_setting,
-          method:,
+          http_methods:,
           path: paths,
-          for: self,
+          api: self,
+          params:,
+          requirements:,
+          anchor:,
           route_options: all_route_options,
           &
         )
@@ -204,7 +212,7 @@ module Grape
 
       Grape::HTTP_SUPPORTED_METHODS.each do |supported_method|
         define_method supported_method.downcase do |path = '/', **options, &block|
-          route(supported_method, path, options, &block)
+          route(supported_method, path, **options, &block)
         end
       end
 
@@ -221,11 +229,13 @@ module Grape
       #       end
       #     end
       def namespace(space = nil, requirements: nil, **options, &block)
-        return Namespace.joined_space_path(inheritable_setting.namespace_stackable[:namespace]) unless space || block
+        return inheritable_setting.namespace_path unless space || block
+
+        validate_requirements!(requirements)
 
         within_namespace do
           nest(block) do
-            inheritable_setting.namespace_stackable[:namespace] = Grape::Namespace.new(space, requirements:, **options) if space
+            inheritable_setting.add_namespace(Grape::Namespace.new(space, requirements:, **options)) if space
           end
         end
       end
@@ -244,15 +254,20 @@ module Grape
       # in your API.
       #
       # @param param [Symbol] The name of the parameter you wish to declare.
-      # @option options [Regexp] You may supply a regular expression that the declared parameter must meet.
+      # @option options [Regexp, Class, Symbol] The constraint the declared parameter must meet — a Regexp, or a capture type such as +Integer+.
       def route_param(param, requirements: nil, type: nil, **, &)
-        requirements = { param.to_sym => requirements } if requirements.is_a?(Regexp)
+        # The param is named here, so the constraint is its own: nest whatever
+        # it is, not just a Regexp. A Hash would name the param twice, or key a
+        # capture this namespace does not introduce, and belongs on +namespace+.
+        raise ArgumentError, "route_param :`#{param}` constrains :`#{param}`; pass the constraint itself, or a Hash of requirements to the enclosing namespace" if requirements.respond_to?(:to_hash)
+
+        param_requirements = requirements ? { param.to_sym => requirements } : requirements
 
         Grape::Validations::ParamsScope.new(api: self) do
           requires param, type: type
         end if type
 
-        namespace(":#{param}", requirements:, **, &)
+        namespace(":#{param}", requirements: param_requirements, **, &)
       end
 
       # @return array of defined versions
@@ -262,6 +277,24 @@ module Grape
 
       private
 
+      # Requirements are keyed by param name and merged across namespaces, so
+      # anything else has nothing to attach to. Rejected here rather than at
+      # the merge, which runs on the first request that builds the routes.
+      def validate_requirements!(requirements)
+        return if requirements.nil? || requirements.respond_to?(:to_hash)
+
+        raise ArgumentError, "requirements must be a Hash of param name => constraint, got `#{requirements.class}`"
+      end
+
+      # Compose a route's params: the declared params (+params do … end+) deep-merged
+      # with any documented alongside +desc ..., params:+ (+description_params+).
+      def prepare_params(description_params)
+        endpoint_params = inheritable_setting.params_documentation || {}
+        return endpoint_params if description_params.blank?
+
+        endpoint_params.deep_merge(description_params)
+      end
+
       # Remove all defined routes.
       def reset_routes!
         endpoints.each(&:reset_routes!)
@@ -272,9 +305,43 @@ module Grape
         @endpoints = []
       end
 
-      def refresh_mounted_api(mounts, *opts)
-        opts << { refresh_already_mounted: true }
-        mount(mounts, *opts)
+      # Re-mount +mounts+, replacing any endpoint already mounted for the same
+      # base API rather than adding a second one. Called by
+      # {Grape::API.refresh_mount_step} when a class-level method runs after the
+      # API was mounted.
+      def refresh_mounted_api(mounts, opts = {})
+        drop_endpoints_mounted_for(mounts)
+        mount(mounts, opts)
+      end
+
+      # A mounted Grape API is stored as the throwaway instance +mount+ built
+      # for it, never as the class that was written, so endpoints are matched on
+      # the base API both of them share.
+      def drop_endpoints_mounted_for(mounts)
+        normalize_mounts(mounts).each_key do |app|
+          endpoints.delete_if { |endpoint| same_mounted_app?(endpoint.mounted_app, app) }
+        end
+      end
+
+      # A bare app mounts at the root. The test is +Hash+ rather than
+      # +respond_to?(:each_pair)+ because a Struct or an OpenStruct answers that
+      # too, and neither can express an app => path mapping — their keys are
+      # member names. Reading one as a mapping would silently mount nonsense
+      # instead of mounting the app itself.
+      def normalize_mounts(mounts)
+        mounts.is_a?(Hash) ? mounts : { mounts => '/' }
+      end
+
+      # Two mounts refer to the same app when they share the same base Grape
+      # API. +mount+ turns every mounted Grape API into a throwaway
+      # +mount_instance+ (a fresh +Class.new+ per mount), so object identity
+      # never holds across mounts; comparing the base is the real signal.
+      # Plain Rack apps have no base and are mounted as-is, so they fall back
+      # to object identity.
+      def same_mounted_app?(mounted, app)
+        return mounted.base.equal?(app.base) if mounted.respond_to?(:base) && app.respond_to?(:base)
+
+        mounted.equal?(app)
       end
 
       # Execute first the provided block, then each of the

data/lib/grape/dsl/settings.rb

@@ -37,7 +37,7 @@ module Grape
       end
 
       def route_setting(key, value = nil)
-        get_or_set(inheritable_setting.route, key, value)
+        inheritable_setting.route_setting(key, value)
       end
 
       def namespace_setting(key, value = nil)

data/lib/grape/dsl/validations.rb

@@ -17,8 +17,8 @@ module Grape
       #   subclass, allowing to define the schema inline. When the
       #   +contract+ parameter is a schema, it will be used as a parent. Optional.
       def contract(contract = nil, &block)
-        raise ArgumentError, 'Either contract or block must be provided' unless contract || block
-        raise ArgumentError, 'Cannot inherit from contract, only schema' if block && contract.respond_to?(:schema)
+        raise ArgumentError, 'either contract or block must be provided' unless contract || block
+        raise ArgumentError, 'cannot inherit from contract, only schema' if block && contract.respond_to?(:schema)
 
         Grape::Validations::ContractScope.new(self, contract, &block)
       end
@@ -44,7 +44,7 @@ module Grape
       #      # whatever
       #    end
       def reset_validations!
-        inheritable_setting.namespace_stackable.delete(:declared_params, :params, :validations)
+        inheritable_setting.reset_validations!
       end
     end
   end

data/lib/grape/dsl/version_options.rb

@@ -4,7 +4,7 @@ module Grape
   module DSL
     # Immutable value object holding the resolved options from
     # +Grape::DSL::Routing#version+. Stored on the inheritable settings as
-    # +namespace_inheritable[:version_options]+ and read by internal call
+    # +Grape::Util::InheritableSetting#version_options+ and read by internal call
     # sites (`Path`, `Endpoint`, `API::Instance#cascade?`,
     # `Middleware::Versioner::Base`) via accessors.
     #
@@ -12,8 +12,8 @@ module Grape
     # signature on purpose: keeping them on both sides means each entry point
     # is self-documenting without needing to import a shared constant — the
     # DSL signature shows what a user sees in the IDE, and the Data object
-    # has working defaults when constructed directly (middleware
-    # `DEFAULT_OPTIONS`, spec fixtures, etc.). The two must stay in lockstep.
+    # has working defaults when constructed directly (spec fixtures, a
+    # middleware built by hand). The two must stay in lockstep.
     VersionOptions = Data.define(:using, :cascade, :parameter, :strict, :vendor) do
       def initialize(using: :path, cascade: true, parameter: 'apiver', strict: false, vendor: nil)
         super

data/lib/grape/endpoint/options.rb

@@ -6,13 +6,19 @@ module Grape
     # +Grape::Endpoint.new+. Internal to {Grape::Endpoint}, which builds it
     # from the +**options+ Hash in #initialize so the public +options+ reader
     # stays a plain Hash for downstream gems (e.g. grape-swagger).
-    # +:method+ is renamed to +:http_methods+ on the value object to avoid
-    # shadowing +Object#method+ via the generated Data accessor.
-    Options = Data.define(:path, :http_methods, :for, :route_options, :app, :format, :forward_match) do
-      def initialize(path:, method:, route_options: {}, app: nil, format: nil, forward_match: nil, **rest)
-        path = Array(path)
-        path << '/' if path.empty?
-        super(path:, http_methods: Array(method), route_options:, app:, format:, forward_match:, **rest)
+    Options = Data.define(:path, :http_methods, :api, :route_options, :app, :params, :requirements, :anchor) do
+      def initialize(path:, http_methods:, api:, route_options: {}, app: nil, params: {}, requirements: nil, anchor: true)
+        # +Array()+ hands back the very Array it was given, so defaulting an
+        # empty one by appending would append to the caller's Array — and raise
+        # FrozenError on a frozen one. Build a new Array instead of growing
+        # theirs: nothing about constructing an endpoint should be visible in
+        # the path the caller passed in.
+        paths = Array(path)
+        super(
+          path: paths.presence || ['/'],
+          http_methods: Array(http_methods),
+          api:, route_options:, app:, params:, requirements:, anchor:
+        )
       end
     end
   end