grape 0.1.1 → 2.4.0

data/lib/grape/dsl/routing.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+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)
+            end
+          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
+
+        # 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 build_with(build_with)
+          namespace_inheritable(:build_params_with, build_with)
+        end
+
+        # Do not route HEAD requests to GET requests automatically.
+        def do_not_route_head!
+          namespace_inheritable(:do_not_route_head, true)
+        end
+
+        # Do not automatically route OPTIONS.
+        def do_not_route_options!
+          namespace_inheritable(:do_not_route_options, true)
+        end
+
+        def lint!
+          namespace_inheritable(:lint, true)
+        end
+
+        def do_not_document!
+          namespace_inheritable(:do_not_document, true)
+        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
+
+            if app.respond_to?(:inheritable_setting, true)
+              mount_path = Grape::Router.normalize_path(path)
+              app.top_level_setting.namespace_stackable[:mount_path] = mount_path
+
+              app.inherit_settings(inheritable_setting)
+
+              in_setting = app.top_level_setting
+
+              app.change!
+              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,
+              path: path,
+              app: app,
+              route_options: { anchor: false },
+              forward_match: !app.respond_to?(:inheritable_setting),
+              for: self
+            )
+          end
+        end
+
+        # 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
+
+        Grape::HTTP_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)
+          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
+            end
+          end
+        end
+
+        alias group namespace
+        alias resource namespace
+        alias resources namespace
+        alias segment namespace
+
+        # An array of API routes.
+        def routes
+          @routes ||= prepare_routes
+        end
+
+        # Remove all defined routes.
+        def reset_routes!
+          endpoints.each(&:reset_routes!)
+          @routes = nil
+        end
+
+        def reset_endpoints!
+          @endpoints = []
+        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
+
+          options[:requirements] = {
+            param.to_sym => options[:requirements]
+          } if options[:requirements].is_a?(Regexp)
+
+          Grape::Validations::ParamsScope.new(api: self) do
+            requires param, type: options[:type]
+          end if options.key?(:type)
+
+          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
+      end
+    end
+  end
+end

data/lib/grape/dsl/settings.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    # Keeps track of settings (implemented as key-value pairs, grouped by
+    # types), in two contexts: top-level settings which apply globally no
+    # 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
+      end
+
+      # Fetch our current inheritable settings, which are inherited by
+      # nested scopes but not shared across siblings.
+      def inheritable_setting
+        @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
+      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
+      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
+      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
+
+      # 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
+
+        result = yield if block
+
+        namespace_end
+        reset_validations!
+
+        result
+      end
+
+      private
+
+      # 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
+      end
+    end
+  end
+end

data/lib/grape/dsl/validations.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Validations
+      extend ActiveSupport::Concern
+
+      include Grape::DSL::Configuration
+
+      module ClassMethods
+        # Clears all defined parameters and validations. The main purpose of it is to clean up
+        # settings, so next endpoint won't interfere with previous one.
+        #
+        #    params do
+        #      # params for the endpoint below this block
+        #    end
+        #    post '/current' do
+        #      # whatever
+        #    end
+        #
+        #    # somewhere between them the reset_validations! method gets called
+        #
+        #    params do
+        #      # params for the endpoint below this block
+        #    end
+        #    post '/next' do
+        #      # whatever
+        #    end
+        def reset_validations!
+          unset_namespace_stackable :declared_params
+          unset_namespace_stackable :validations
+          unset_namespace_stackable :params
+        end
+
+        # Opens a root-level ParamsScope, defining parameter coercions and
+        # validations for the endpoint.
+        # @yield instance context of the new scope
+        def params(&block)
+          Grape::Validations::ParamsScope.new(api: self, type: Hash, &block)
+        end
+
+        # Declare the contract to be used for the endpoint's parameters.
+        # @param contract [Class<Dry::Validation::Contract> | Dry::Schema::Processor]
+        #   The contract or schema to be used for validation. Optional.
+        # @yield a block yielding a new instance of Dry::Schema::Params
+        #   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)
+
+          Grape::Validations::ContractScope.new(self, contract, &block)
+        end
+      end
+    end
+  end
+end