grape 2.3.0 → 3.0.0

data/lib/grape/dsl/routing.rb

@@ -3,236 +3,272 @@
 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.map(&:to_s)
-
-            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)
+      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, **options, &block)
+        if args.any?
+          options = options.reverse_merge(using: :path)
+          requested_versions = args.flatten.map(&:to_s)
+
+          raise Grape::Exceptions::MissingVendorOption.new if options[:using] == :header && !options.key?(:vendor)
+
+          @versions = versions | requested_versions
+
+          if block
+            within_namespace do
+              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
-
-          @versions.last if instance_variable_defined?(:@versions) && @versions
         end
 
-        # Define a root URL prefix for your entire API.
-        def prefix(prefix = nil)
-          namespace_inheritable(:root_prefix, prefix&.to_s)
-        end
+        @versions.last if instance_variable_defined?(:@versions) && @versions
+      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
+      # Define a root URL prefix for your entire API.
+      def prefix(prefix = nil)
+        return inheritable_setting.namespace_inheritable[:root_prefix] if prefix.nil?
 
-        # Do not route HEAD requests to GET requests automatically.
-        def do_not_route_head!
-          namespace_inheritable(:do_not_route_head, true)
-        end
+        inheritable_setting.namespace_inheritable[:root_prefix] = prefix.to_s
+      end
 
-        # Do not automatically route OPTIONS.
-        def do_not_route_options!
-          namespace_inheritable(:do_not_route_options, true)
+      # 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 do_not_document!
-          namespace_inheritable(:do_not_document, true)
-        end
+      def build_with(build_with)
+        inheritable_setting.namespace_inheritable[:build_params_with] = build_with
+      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.first[:with] : {}
-              mount({ app.mount_instance(configuration: opts_with) => path }, *opts)
-              next
-            end
-            in_setting = inheritable_setting
+      # Do not route HEAD requests to GET requests automatically.
+      def do_not_route_head!
+        inheritable_setting.namespace_inheritable[:do_not_route_head] = true
+      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 automatically route OPTIONS.
+      def do_not_route_options!
+        inheritable_setting.namespace_inheritable[:do_not_route_options] = true
+      end
 
-              app.inherit_settings(inheritable_setting)
+      def lint!
+        inheritable_setting.namespace_inheritable[:lint] = true
+      end
 
-              in_setting = app.top_level_setting
+      def do_not_document!
+        inheritable_setting.namespace_inheritable[:do_not_document] = true
+      end
 
-              app.change!
-              change!
-            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.first[:with] : {}
+            mount({ app.mount_instance(configuration: opts_with) => path }, *opts)
+            next
+          end
+          in_setting = inheritable_setting
 
-            # 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
+          if app.respond_to?(:inheritable_setting, true)
+            mount_path = Grape::Router.normalize_path(path)
+            app.top_level_setting.namespace_stackable[:mount_path] = mount_path
 
-            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
-            )
-          end
-        end
+            app.inherit_settings(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
+            in_setting = app.top_level_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)
+            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)
-          return Namespace.joined_space_path(namespace_stackable(:namespace)) unless space || block
-
-          within_namespace do
-            nest(block) do
-              namespace_stackable(:namespace, Namespace.new(space, options)) if space
+          # 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,
+            path: path,
+            app: 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 = {}, &block)
+        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&.any?
+
+        endpoint_options = {
+          method: method,
+          path: paths,
+          for: self,
+          route_options: all_route_options
+        }
+
+        new_endpoint = Grape::Endpoint.new(inheritable_setting, endpoint_options, &block)
+        endpoints << new_endpoint unless endpoints.any? { |e| e.equals?(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 |*args, **options, &block|
+          paths = args.first || ['/']
+          route(supported_method, paths, 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, 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, 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)
+      # Remove all defined routes.
+      def reset_routes!
+        endpoints.each(&:reset_routes!)
+        @routes = nil
+      end
 
-          Grape::Validations::ParamsScope.new(api: self) do
-            requires param, type: options[:type]
-          end if options.key?(:type)
+      def reset_endpoints!
+        @endpoints = []
+      end
 
-          namespace(":#{param}", options, &block)
-        end
+      # 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
 
-        # @return array of defined versions
-        def versions
-          @versions ||= []
-        end
+        options[:requirements] = {
+          param.to_sym => options[:requirements]
+        } if options[:requirements].is_a?(Regexp)
 
-        private
+        Grape::Validations::ParamsScope.new(api: self) do
+          requires param, type: options[:type]
+        end if options.key?(:type)
 
-        def refresh_mounted_api(mounts, *opts)
-          opts << { refresh_already_mounted: true }
-          mount(mounts, *opts)
+        namespace(":#{param}", options, &block)
+      end
+
+      # @return array of defined versions
+      def versions
+        @versions ||= []
+      end
+
+      private
+
+      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!
+        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
       end
     end

data/lib/grape/dsl/settings.rb

@@ -7,13 +7,17 @@ module Grape
     # matter where they're defined, and inheritable settings which apply only
     # in the current scope and scopes nested under it.
     module Settings
-      extend ActiveSupport::Concern
-
       attr_writer :inheritable_setting, :top_level_setting
 
       # Fetch our top-level settings, which apply to all endpoints in the API.
       def top_level_setting
-        @top_level_setting ||= build_top_level_setting
+        @top_level_setting ||= Grape::Util::InheritableSetting.new.tap do |setting|
+          # Doesn't try to inherit settings from +Grape::API::Instance+ which also responds to
+          # +inheritable_setting+, however, it doesn't contain any user-defined settings.
+          # Otherwise, it would lead to an extra instance of +Grape::Util::InheritableSetting+
+          # in the chain for every endpoint.
+          setting.inherit_from superclass.inheritable_setting if defined?(superclass) && superclass.respond_to?(:inheritable_setting) && superclass != Grape::API::Instance
+        end
       end
 
       # Fetch our current inheritable settings, which are inherited by
@@ -22,157 +26,41 @@ module Grape
         @inheritable_setting ||= Grape::Util::InheritableSetting.new.tap { |new_settings| new_settings.inherit_from top_level_setting }
       end
 
-      # @param type [Symbol]
-      # @param key [Symbol]
-      def unset(type, key)
-        setting = inheritable_setting.send(type)
-        setting.delete key
-      end
-
-      # @param type [Symbol]
-      # @param key [Symbol]
-      # @param value [Object] will be stored if the value is currently empty
-      # @return either the old value, if it wasn't nil, or the given value
-      def get_or_set(type, key, value)
-        setting = inheritable_setting.send(type)
-        if value.nil?
-          setting[key]
-        else
-          setting[key] = value
-        end
-      end
-
-      # @param key [Symbol]
-      # @param value [Object]
-      # @return (see #get_or_set)
       def global_setting(key, value = nil)
-        get_or_set :global, key, value
+        get_or_set(inheritable_setting.global, key, value)
       end
 
-      # @param key [Symbol]
-      def unset_global_setting(key)
-        unset :global, key
-      end
-
-      # (see #global_setting)
       def route_setting(key, value = nil)
-        get_or_set :route, key, value
-      end
-
-      # (see #unset_global_setting)
-      def unset_route_setting(key)
-        unset :route, key
+        get_or_set(inheritable_setting.route, key, value)
       end
 
-      # (see #global_setting)
       def namespace_setting(key, value = nil)
-        get_or_set :namespace, key, value
-      end
-
-      # (see #unset_global_setting)
-      def unset_namespace_setting(key)
-        unset :namespace, key
-      end
-
-      # (see #global_setting)
-      def namespace_inheritable(key, value = nil)
-        get_or_set :namespace_inheritable, key, value
-      end
-
-      # (see #unset_global_setting)
-      def unset_namespace_inheritable(key)
-        unset :namespace_inheritable, key
+        get_or_set(inheritable_setting.namespace, key, value)
       end
 
-      # @param key [Symbol]
-      def namespace_inheritable_to_nil(key)
-        inheritable_setting.namespace_inheritable[key] = nil
-      end
-
-      # (see #global_setting)
-      def namespace_stackable(key, value = nil)
-        get_or_set :namespace_stackable, key, value
-      end
-
-      def namespace_reverse_stackable(key, value = nil)
-        get_or_set :namespace_reverse_stackable, key, value
-      end
-
-      def namespace_stackable_with_hash(key)
-        settings = get_or_set :namespace_stackable, key, nil
-        return if settings.blank?
-
-        settings.each_with_object({}) { |value, result| result.deep_merge!(value) }
-      end
-
-      def namespace_reverse_stackable_with_hash(key)
-        settings = get_or_set :namespace_reverse_stackable, key, nil
-        return if settings.blank?
-
-        settings.each_with_object({}) do |setting, result|
-          result.merge!(setting) { |_k, s1, _s2| s1 }
-        end
-      end
-
-      # (see #unset_global_setting)
-      def unset_namespace_stackable(key)
-        unset :namespace_stackable, key
-      end
-
-      # (see #global_setting)
-      def api_class_setting(key, value = nil)
-        get_or_set :api_class, key, value
-      end
-
-      # (see #unset_global_setting)
-      def unset_api_class_setting(key)
-        unset :api_class, key
-      end
-
-      # Fork our inheritable settings to a new instance, copied from our
-      # parent's, but separate so we won't modify it. Every call to this
-      # method should have an answering call to #namespace_end.
-      def namespace_start
-        @inheritable_setting = Grape::Util::InheritableSetting.new.tap { |new_settings| new_settings.inherit_from inheritable_setting }
-      end
-
-      # Set the inheritable settings pointer back up by one level.
-      def namespace_end
-        route_end
-        @inheritable_setting = inheritable_setting.parent
-      end
-
-      # Stop defining settings for the current route and clear them for the
-      # next, within a namespace.
-      def route_end
-        inheritable_setting.route_end
-      end
+      private
 
       # Execute the block within a context where our inheritable settings are forked
       # to a new copy (see #namespace_start).
-      def within_namespace(&block)
-        namespace_start
+      def within_namespace
+        new_inheritable_settings = Grape::Util::InheritableSetting.new
+        new_inheritable_settings.inherit_from inheritable_setting
 
-        result = yield if block
+        @inheritable_setting = new_inheritable_settings
 
-        namespace_end
+        result = yield
+
+        inheritable_setting.route_end
+        @inheritable_setting = inheritable_setting.parent
         reset_validations!
 
         result
       end
 
-      private
+      def get_or_set(setting, key, value)
+        return setting[key] if value.nil?
 
-      # Builds the current class :inheritable_setting. If available, it inherits from
-      # the superclass's :inheritable_setting.
-      def build_top_level_setting
-        Grape::Util::InheritableSetting.new.tap do |setting|
-          # Doesn't try to inherit settings from +Grape::API::Instance+ which also responds to
-          # +inheritable_setting+, however, it doesn't contain any user-defined settings.
-          # Otherwise, it would lead to an extra instance of +Grape::Util::InheritableSetting+
-          # in the chain for every endpoint.
-          setting.inherit_from superclass.inheritable_setting if defined?(superclass) && superclass.respond_to?(:inheritable_setting) && superclass != Grape::API::Instance
-        end
+        setting[key] = value
       end
     end
   end