grape 1.8.0 → 3.3.5

data/lib/grape/dsl/routing.rb

@@ -3,228 +3,303 @@
 module Grape
   module DSL
     module Routing
-      extend ActiveSupport::Concern
-      include Grape::DSL::Configuration
-
-      module ClassMethods
-        attr_reader :endpoints
-
-        # Specify an API version.
-        #
-        # @example API with legacy support.
-        #   class MyAPI < Grape::API
-        #     version 'v2'
-        #
-        #     get '/main' do
-        #       {some: 'data'}
-        #     end
-        #
-        #     version 'v1' do
-        #       get '/main' do
-        #         {legacy: 'data'}
-        #       end
-        #     end
-        #   end
-        #
-        def version(*args, &block)
-          if args.any?
-            options = args.extract_options!
-            options = options.reverse_merge(using: :path)
-            requested_versions = args.flatten
-
-            raise Grape::Exceptions::MissingVendorOption.new if options[:using] == :header && !options.key?(:vendor)
-
-            @versions = versions | requested_versions
-
-            if block
-              within_namespace do
-                namespace_inheritable(:version, requested_versions)
-                namespace_inheritable(:version_options, options)
-
-                instance_eval(&block)
-              end
-            else
-              namespace_inheritable(:version, requested_versions)
-              namespace_inheritable(:version_options, options)
-            end
-          end
+      attr_reader :endpoints
 
-          @versions.last if instance_variable_defined?(:@versions) && @versions
-        end
+      def given(conditional_option, &)
+        return unless conditional_option
 
-        # Define a root URL prefix for your entire API.
-        def prefix(prefix = nil)
-          namespace_inheritable(:root_prefix, prefix)
-        end
+        mounted(&)
+      end
+
+      def mounted(&block)
+        evaluate_as_instance_with_configuration(block, lazy: true)
+      end
 
-        # Create a scope without affecting the URL.
-        #
-        # @param _name [Symbol] Purely placebo, just allows to name the scope to
-        # make the code more readable.
-        def scope(_name = nil, &block)
+      def cascade(value = nil)
+        return inheritable_setting.namespace_inheritable.key?(:cascade) ? !inheritable_setting.namespace_inheritable[:cascade].nil? : true if value.nil?
+
+        inheritable_setting.namespace_inheritable[:cascade] = value
+      end
+
+      # Specify an API version.
+      #
+      # Called without arguments, returns the most recently declared version
+      # (or +nil+). Called with one or more version strings, registers them
+      # and stores a {Grape::DSL::VersionOptions} value object on the
+      # inheritable settings; when given a block, the registration applies
+      # within a nested namespace.
+      #
+      # @example API with legacy support.
+      #   class MyAPI < Grape::API
+      #     version 'v2'
+      #
+      #     get '/main' do
+      #       {some: 'data'}
+      #     end
+      #
+      #     version 'v1' do
+      #       get '/main' do
+      #         {legacy: 'data'}
+      #       end
+      #     end
+      #   end
+      #
+      # @param args [Array<String, Symbol>] one or more version identifiers.
+      # @param using [Symbol] versioning strategy — one of +:path+ (default),
+      #   +:header+, +:param+, or +:accept_version_header+.
+      # @param cascade [Boolean] forward to subsequent routes via the
+      #   +X-Cascade+ header on version mismatch. Defaults to +true+.
+      # @param parameter [String] name of the query/body parameter that
+      #   carries the version when +using: :param+. Defaults to +'apiver'+.
+      # @param strict [Boolean] reject requests that don't supply a usable
+      #   version (header strategies). Defaults to +false+.
+      # @param vendor [String, nil] vendor segment for the +:header+
+      #   strategy (+application/vnd.<vendor>-<version>+); required when
+      #   +using: :header+.
+      # @yield optional block to scope routes under this version.
+      # @return [String, nil] the most recently declared version.
+      # @raise [Grape::Exceptions::MissingVendorOption] when +using: :header+
+      #   is supplied without a +:vendor+.
+      def version(*args, using: :path, cascade: true, parameter: 'apiver', strict: false, vendor: nil, &block)
+        return @versions&.last if args.empty?
+
+        raise Grape::Exceptions::MissingVendorOption.new if using == :header && vendor.nil?
+
+        requested_versions = args.flatten.map(&:to_s)
+        options = VersionOptions.new(using:, cascade:, parameter:, strict:, vendor:)
+
+        @versions = versions | requested_versions
+
+        if block
           within_namespace do
-            nest(block)
+            inheritable_setting.namespace_inheritable[:version] = requested_versions
+            inheritable_setting.namespace_inheritable[:version_options] = options
+            instance_eval(&block)
           end
+        else
+          inheritable_setting.namespace_inheritable[:version] = requested_versions
+          inheritable_setting.namespace_inheritable[:version_options] = options
         end
 
-        # Do not route HEAD requests to GET requests automatically.
-        def do_not_route_head!
-          namespace_inheritable(:do_not_route_head, true)
-        end
+        @versions&.last
+      end
 
-        # Do not automatically route OPTIONS.
-        def do_not_route_options!
-          namespace_inheritable(:do_not_route_options, true)
-        end
+      # Define a root URL prefix for your entire API.
+      def prefix(prefix = nil)
+        return inheritable_setting.namespace_inheritable[:root_prefix] if prefix.nil?
 
-        def do_not_document!
-          namespace_inheritable(:do_not_document, true)
+        inheritable_setting.namespace_inheritable[:root_prefix] = prefix.to_s
+      end
+
+      # Create a scope without affecting the URL.
+      #
+      # @param _name [Symbol] Purely placebo, just allows to name the scope to
+      # make the code more readable.
+      def scope(_name = nil, &block)
+        within_namespace do
+          nest(block)
         end
+      end
 
-        def mount(mounts, *opts)
-          mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair)
-          mounts.each_pair do |app, path|
-            if app.respond_to?(:mount_instance)
-              opts_with = opts.any? ? opts.shift[:with] : {}
-              mount({ app.mount_instance(configuration: opts_with) => path })
-              next
-            end
-            in_setting = inheritable_setting
+      def build_with(build_with)
+        inheritable_setting.namespace_inheritable[:build_params_with] = build_with
+      end
 
-            if app.respond_to?(:inheritable_setting, true)
-              mount_path = Grape::Router.normalize_path(path)
-              app.top_level_setting.namespace_stackable[:mount_path] = mount_path
+      # Do not route HEAD requests to GET requests automatically.
+      def do_not_route_head!
+        inheritable_setting.namespace_inheritable[:do_not_route_head] = true
+      end
 
-              app.inherit_settings(inheritable_setting)
+      # Do not automatically route OPTIONS.
+      def do_not_route_options!
+        inheritable_setting.namespace_inheritable[:do_not_route_options] = true
+      end
 
-              in_setting = app.top_level_setting
+      def lint!
+        inheritable_setting.namespace_inheritable[:lint] = true
+      end
 
-              app.change!
-              change!
-            end
+      def do_not_document!
+        inheritable_setting.namespace_inheritable[:do_not_document] = true
+      end
 
-            endpoints << Grape::Endpoint.new(
-              in_setting,
-              method: :any,
-              path: path,
-              app: app,
-              route_options: { anchor: false },
-              forward_match: !app.respond_to?(:inheritable_setting),
-              for: self
-            )
+      def mount(mounts, *opts)
+        mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair)
+        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)
+            next
           end
-        end
+          in_setting = inheritable_setting
 
-        # Defines a route that will be recognized
-        # by the Grape API.
-        #
-        # @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.
-        #
-        # @example Defining a basic route.
-        #   class MyAPI < Grape::API
-        #     route(:any, '/hello') do
-        #       {hello: 'world'}
-        #     end
-        #   end
-        def route(methods, paths = ['/'], route_options = {}, &block)
-          methods = '*' if methods == :any
-          endpoint_options = {
-            method: methods,
-            path: paths,
-            for: self,
-            route_options: {
-              params: namespace_stackable_with_hash(:params) || {}
-            }.deep_merge(route_setting(:description) || {}).deep_merge(route_options || {})
-          }
-
-          new_endpoint = Grape::Endpoint.new(inheritable_setting, endpoint_options, &block)
-          endpoints << new_endpoint unless endpoints.any? { |e| e.equals?(new_endpoint) }
-
-          route_end
-          reset_validations!
-        end
+          # Past the mount_instance branch above, a Grape app here is an already
+          # 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.inherit_settings(inheritable_setting)
 
-        Grape::Http::Headers::SUPPORTED_METHODS.each do |supported_method|
-          define_method supported_method.downcase do |*args, &block|
-            options = args.extract_options!
-            paths = args.first || ['/']
-            route(supported_method, paths, options, &block)
+            in_setting = app.top_level_setting
+
+            app.change!
+            change!
           end
-        end
 
-        # Declare a "namespace", which prefixes all subordinate routes with its
-        # name. Any endpoints within a namespace, group, resource or segment,
-        # etc., will share their parent context as well as any configuration
-        # done in the namespace context.
-        #
-        # @example
-        #
-        #     namespace :foo do
-        #       get 'bar' do
-        #         # defines the endpoint: GET /foo/bar
-        #       end
-        #     end
-        def namespace(space = nil, options = {}, &block)
-          @namespace_description = nil unless instance_variable_defined?(:@namespace_description) && @namespace_description
-
-          if space || block
-            within_namespace do
-              previous_namespace_description = @namespace_description
-              @namespace_description = (@namespace_description || {}).deep_merge(namespace_setting(:description) || {})
-              nest(block) do
-                namespace_stackable(:namespace, Namespace.new(space, **options)) if space
-              end
-              @namespace_description = previous_namespace_description
+          # 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
-          else
-            Namespace.joined_space_path(namespace_stackable(:namespace))
           end
+
+          endpoints << Grape::Endpoint.new(
+            in_setting,
+            method: :any,
+            path:,
+            app:,
+            route_options: { anchor: false },
+            forward_match: !app.respond_to?(:inheritable_setting),
+            for: self
+          )
         end
+      end
 
-        alias group namespace
-        alias resource namespace
-        alias resources namespace
-        alias segment namespace
+      # Defines a route that will be recognized
+      # by the Grape API.
+      #
+      # @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.
+      #
+      # @example Defining a basic route.
+      #   class MyAPI < Grape::API
+      #     route(:any, '/hello') do
+      #       {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
+        all_route_options.deep_merge!(route_options) if route_options.present?
+
+        new_endpoint = Grape::Endpoint.new(
+          inheritable_setting,
+          method:,
+          path: paths,
+          for: self,
+          route_options: all_route_options,
+          &
+        )
+        endpoints << new_endpoint unless endpoints.include?(new_endpoint)
+
+        inheritable_setting.route_end
+        reset_validations!
+      end
 
-        # An array of API routes.
-        def routes
-          @routes ||= prepare_routes
+      Grape::HTTP_SUPPORTED_METHODS.each do |supported_method|
+        define_method supported_method.downcase do |path = '/', **options, &block|
+          route(supported_method, path, options, &block)
         end
+      end
 
-        # Remove all defined routes.
-        def reset_routes!
-          endpoints.each(&:reset_routes!)
-          @routes = nil
+      # Declare a "namespace", which prefixes all subordinate routes with its
+      # name. Any endpoints within a namespace, group, resource or segment,
+      # etc., will share their parent context as well as any configuration
+      # done in the namespace context.
+      #
+      # @example
+      #
+      #     namespace :foo do
+      #       get 'bar' do
+      #         # defines the endpoint: GET /foo/bar
+      #       end
+      #     end
+      def namespace(space = nil, requirements: nil, **options, &block)
+        return Namespace.joined_space_path(inheritable_setting.namespace_stackable[:namespace]) unless space || block
+
+        within_namespace do
+          nest(block) do
+            inheritable_setting.namespace_stackable[:namespace] = Grape::Namespace.new(space, requirements:, **options) if space
+          end
         end
+      end
 
-        def reset_endpoints!
-          @endpoints = []
-        end
+      alias group namespace
+      alias resource namespace
+      alias resources namespace
+      alias segment namespace
 
-        # This method allows you to quickly define a parameter route segment
-        # 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.
-        def route_param(param, options = {}, &block)
-          options = options.dup
+      # An array of API routes.
+      def routes
+        @routes ||= endpoints.map(&:routes).flatten
+      end
 
-          options[:requirements] = {
-            param.to_sym => options[:requirements]
-          } if options[:requirements].is_a?(Regexp)
+      # This method allows you to quickly define a parameter route segment
+      # 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.
+      def route_param(param, requirements: nil, type: nil, **, &)
+        requirements = { param.to_sym => requirements } if requirements.is_a?(Regexp)
 
-          Grape::Validations::ParamsScope.new(api: self) do
-            requires param, type: options[:type]
-          end if options.key?(:type)
+        Grape::Validations::ParamsScope.new(api: self) do
+          requires param, type: type
+        end if type
 
-          namespace(":#{param}", options, &block)
-        end
+        namespace(":#{param}", requirements:, **, &)
+      end
 
-        # @return array of defined versions
-        def versions
-          @versions ||= []
+      # @return array of defined versions
+      def versions
+        @versions ||= []
+      end
+
+      private
+
+      # Remove all defined routes.
+      def reset_routes!
+        endpoints.each(&:reset_routes!)
+        @routes = nil
+      end
+
+      def reset_endpoints!
+        @endpoints = []
+      end
+
+      def refresh_mounted_api(mounts, *opts)
+        opts << { refresh_already_mounted: true }
+        mount(mounts, *opts)
+      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!
+        return instance_eval(&block) if blocks.empty?
+
+        evaluate_as_instance_with_configuration(block) if block
+        blocks.each { |b| evaluate_as_instance_with_configuration(b) }
+        reset_validations!
+      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.is_a?(Grape::Util::Lazy::Base)
+          response = instance_eval(&block)
+          self.configuration = value_for_configuration
+          response
         end
+        return lazy_block if @base && base_instance? && lazy
+
+        lazy_block.evaluate_from(configuration)
       end
     end
   end