grape 1.1.0 → 1.5.3

data/lib/grape/api/helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class API
     module Helpers

data/lib/grape/api/instance.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require 'grape/router'
+
+module Grape
+  class API
+    # The API Instance class, is the engine behind Grape::API. Each class that inherits
+    # from this will represent a different API instance
+    class Instance
+      include Grape::DSL::API
+
+      class << self
+        attr_reader :instance
+        attr_reader :base
+        attr_accessor :configuration
+
+        def given(conditional_option, &block)
+          evaluate_as_instance_with_configuration(block, lazy: true) if conditional_option && block_given?
+        end
+
+        def mounted(&block)
+          evaluate_as_instance_with_configuration(block, lazy: true)
+        end
+
+        def base=(grape_api)
+          @base = grape_api
+          grape_api.instances << self
+        end
+
+        def to_s
+          (base && base.to_s) || super
+        end
+
+        def base_instance?
+          self == base.base_instance
+        end
+
+        # A class-level lock to ensure the API is not compiled by multiple
+        # threads simultaneously within the same process.
+        LOCK = Mutex.new
+
+        # Clears all defined routes, endpoints, etc., on this API.
+        def reset!
+          reset_endpoints!
+          reset_routes!
+          reset_validations!
+        end
+
+        # Parses the API's definition and compiles it into an instance of
+        # Grape::API.
+        def compile
+          @instance ||= new
+        end
+
+        # Wipe the compiled API so we can recompile after changes were made.
+        def change!
+          @instance = nil
+        end
+
+        # This is the interface point between Rack and Grape; it accepts a request
+        # from Rack and ultimately returns an array of three values: the status,
+        # 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!
+          call!(env)
+        end
+
+        # A non-synchronized version of ::call.
+        def call!(env)
+          instance.call(env)
+        end
+
+        # (see #cascade?)
+        def cascade(value = nil)
+          if value.nil?
+            inheritable_setting.namespace_inheritable.key?(:cascade) ? !namespace_inheritable(:cascade).nil? : true
+          else
+            namespace_inheritable(:cascade, value)
+          end
+        end
+
+        def compile!
+          return if instance
+          LOCK.synchronize { compile unless instance }
+        end
+
+        # see Grape::Router#recognize_path
+        def recognize_path(path)
+          compile!
+          instance.router.recognize_path(path)
+        end
+
+        protected
+
+        def prepare_routes
+          endpoints.map(&:routes).flatten
+        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.reject!(&:nil?)
+          if blocks.any?
+            evaluate_as_instance_with_configuration(block) if block_given?
+            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::LazyBlock.new do |configuration|
+            value_for_configuration = configuration
+            if value_for_configuration.respond_to?(:lazy?) && value_for_configuration.lazy?
+              self.configuration = value_for_configuration.evaluate
+            end
+            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
+
+        def inherited(subclass)
+          subclass.reset!
+          subclass.logger = logger.clone
+        end
+
+        def inherit_settings(other_settings)
+          top_level_setting.inherit_from other_settings.point_in_time_copy
+
+          # 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.reset_routes!
+          end
+
+          reset_routes!
+        end
+      end
+
+      attr_reader :router
+
+      # Builds the routes from the defined endpoints, effectively compiling
+      # this API into a usable form.
+      def initialize
+        @router = Router.new
+        add_head_not_allowed_methods_and_options_methods
+        self.class.endpoints.each do |endpoint|
+          endpoint.mount_in(@router)
+        end
+
+        @router.compile!
+        @router.freeze
+      end
+
+      # Handle a request. See Rack documentation for what `env` is.
+      def call(env)
+        result = @router.call(env)
+        result[1].delete(Grape::Http::Headers::X_CASCADE) unless cascade?
+        result
+      end
+
+      # Some requests may return a HTTP 404 error if grape cannot find a matching
+      # route. In this case, Grape::Router adds a X-Cascade header to the response
+      # and sets it to 'pass', indicating to grape's parents they should keep
+      # looking for a matching route on other resources.
+      #
+      # 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.
+      def cascade?
+        return self.class.namespace_inheritable(:cascade) if self.class.inheritable_setting.namespace_inheritable.key?(:cascade)
+        return self.class.namespace_inheritable(:version_options)[:cascade] if self.class.namespace_inheritable(:version_options) && self.class.namespace_inheritable(:version_options).key?(:cascade)
+        true
+      end
+
+      reset!
+
+      private
+
+      # For every resource add a 'OPTIONS' route that returns an HTTP 204 response
+      # with a list of HTTP methods that can be called. Also add a route that
+      # will return an HTTP 405 response for any HTTP method that the resource
+      # cannot handle.
+      def add_head_not_allowed_methods_and_options_methods
+        versioned_route_configs = collect_route_config_per_pattern
+        # The paths we collected are prepared (cf. Path#prepare), so they
+        # contain already versioning information when using path versioning.
+        # Disable versioning so adding a route won't prepend versioning
+        # informations again.
+        without_root_prefix do
+          without_versioning do
+            versioned_route_configs.each do |config|
+              allowed_methods = config[:methods].dup
+
+              unless self.class.namespace_inheritable(:do_not_route_head)
+                allowed_methods |= [Grape::Http::Headers::HEAD] if allowed_methods.include?(Grape::Http::Headers::GET)
+              end
+
+              allow_header = (self.class.namespace_inheritable(:do_not_route_options) ? allowed_methods : [Grape::Http::Headers::OPTIONS] | allowed_methods)
+
+              unless self.class.namespace_inheritable(:do_not_route_options) || allowed_methods.include?(Grape::Http::Headers::OPTIONS)
+                config[:endpoint].options[:options_route_enabled] = true
+              end
+
+              attributes = config.merge(allowed_methods: allowed_methods, allow_header: allow_header)
+              generate_not_allowed_method(config[:pattern], **attributes)
+            end
+          end
+        end
+      end
+
+      def collect_route_config_per_pattern
+        all_routes       = self.class.endpoints.map(&:routes).flatten
+        routes_by_regexp = all_routes.group_by { |route| route.pattern.to_regexp }
+
+        # Build the configuration based on the first endpoint and the collection of methods supported.
+        routes_by_regexp.values.map do |routes|
+          last_route        = routes.last # Most of the configuration is taken from the last endpoint
+          matching_wildchar = routes.any? { |route| route.request_method == '*' }
+          {
+            options: {},
+            pattern: last_route.pattern,
+            requirements: last_route.requirements,
+            path: last_route.origin,
+            endpoint: last_route.app,
+            methods: matching_wildchar ? Grape::Http::Headers::SUPPORTED_METHODS : routes.map(&:request_method)
+          }
+        end
+      end
+
+      # Generate a route that returns an HTTP 405 response for a user defined
+      # path on methods not specified
+      def generate_not_allowed_method(pattern, allowed_methods: [], **attributes)
+        supported_methods =
+          if self.class.namespace_inheritable(:do_not_route_options)
+            Grape::Http::Headers::SUPPORTED_METHODS
+          else
+            Grape::Http::Headers::SUPPORTED_METHODS_WITHOUT_OPTIONS
+          end
+        not_allowed_methods = supported_methods - allowed_methods
+        return if not_allowed_methods.empty?
+        @router.associate_routes(pattern, not_allowed_methods: not_allowed_methods, **attributes)
+      end
+
+      # Allows definition of endpoints that ignore the versioning configuration
+      # used by the rest of your API.
+      def without_versioning(&_block)
+        old_version = self.class.namespace_inheritable(:version)
+        old_version_options = self.class.namespace_inheritable(:version_options)
+
+        self.class.namespace_inheritable_to_nil(:version)
+        self.class.namespace_inheritable_to_nil(:version_options)
+
+        yield
+
+        self.class.namespace_inheritable(:version, old_version)
+        self.class.namespace_inheritable(:version_options, old_version_options)
+      end
+
+      # Allows definition of endpoints that ignore the root prefix used by the
+      # rest of your API.
+      def without_root_prefix(&_block)
+        old_prefix = self.class.namespace_inheritable(:root_prefix)
+
+        self.class.namespace_inheritable_to_nil(:root_prefix)
+
+        yield
+
+        self.class.namespace_inheritable(:root_prefix, old_prefix)
+      end
+    end
+  end
+end

data/lib/grape/config.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Grape
+  module Config
+    class Configuration
+      ATTRIBUTES = %i[
+        param_builder
+      ].freeze
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize
+        reset
+      end
+
+      def reset
+        self.param_builder = Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder
+      end
+    end
+
+    def self.extended(base)
+      def base.configure
+        block_given? ? yield(config) : config
+      end
+
+      def base.config
+        @configuration ||= Grape::Config::Configuration.new
+      end
+    end
+  end
+end
+
+Grape.extend Grape::Config
+Grape.config.reset

data/lib/grape/content_types.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'grape/util/registrable'
+
+module Grape
+  module ContentTypes
+    extend Util::Registrable
+
+    # Content types are listed in order of preference.
+    CONTENT_TYPES = {
+      xml: 'application/xml',
+      serializable_hash: 'application/json',
+      json: 'application/json',
+      binary: 'application/octet-stream',
+      txt: 'text/plain'
+    }.freeze
+
+    class << self
+      def content_types_for_settings(settings)
+        return if settings.blank?
+
+        settings.each_with_object({}) { |value, result| result.merge!(value) }
+      end
+
+      def content_types_for(from_settings)
+        if from_settings.present?
+          from_settings
+        else
+          Grape::ContentTypes::CONTENT_TYPES.merge(default_elements)
+        end
+      end
+    end
+  end
+end

data/lib/grape/cookies.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Cookies
     def initialize

data/lib/grape/dsl/api.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/concern'
 
 module Grape

data/lib/grape/dsl/callbacks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/concern'
 
 module Grape
@@ -43,6 +45,26 @@ module Grape
         def after(&block)
           namespace_stackable(:afters, block)
         end
+
+        # Allows you to specify a something that will always be executed after a call
+        # API call. Unlike the `after` block, this code will run even on
+        # unsuccesful requests.
+        # @example
+        #   class ExampleAPI < Grape::API
+        #     before do
+        #       ApiLogger.start
+        #     end
+        #     finally do
+        #       ApiLogger.close
+        #     end
+        #   end
+        #
+        # This will make sure that the ApiLogger is opened and closed around every
+        # request
+        # @param  ensured_block [Proc] The block to be executed after every api_call
+        def finally(&block)
+          namespace_stackable(:finallies, block)
+        end
       end
     end
   end

data/lib/grape/dsl/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/concern'
 
 module Grape

data/lib/grape/dsl/desc.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   module DSL
     module Desc
@@ -9,6 +11,7 @@ module Grape
       # @param options [Hash] other properties you can set to describe the
       #   endpoint or namespace. Optional.
       # @option options :detail [String] additional detail about this endpoint
+      # @option options :summary [String] summary for this endpoint
       # @option options :params [Hash] param types and info. normally, you set
       #   these via the `params` dsl method.
       # @option options :entity [Grape::Entity] the entity returned upon a
@@ -16,7 +19,16 @@ module Grape
       # @option options :http_codes [Array[Array]] possible HTTP codes this
       #   endpoint may return, with their meanings, in a 2d array
       # @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
+      # @option options :hidden [Boolean] hide the endpoint or not
+      # @option options :deprecated [Boolean] deprecate the endpoint or not
+      # @option options :is_array [Boolean] response entity is array or not
+      # @option options :nickname [String] nickname of the endpoint
+      # @option options :produces [Array[String]] a list of MIME types the endpoint produce
+      # @option options :consumes [Array[String]] a list of MIME types the endpoint consume
+      # @option options :security [Array[Hash]] a list of security schemes
+      # @option options :tags [Array[String]] a list of tags
       # @yield a block yielding an instance context with methods mapping to
       #   each of the above, except that :entity is also aliased as #success
       #   and :http_codes is aliased as #failure.
@@ -39,7 +51,17 @@ module Grape
       #
       def desc(description, options = {}, &config_block)
         if block_given?
-          config_class = desc_container
+          endpoint_configuration = if defined?(configuration)
+                                     # When the instance is mounted - the configuration is executed on mount time
+                                     if configuration.respond_to?(:evaluate)
+                                       configuration.evaluate
+                                     # Within `given` or `mounted blocks` the configuration is already evaluated
+                                     elsif configuration.is_a?(Hash)
+                                       configuration
+                                     end
+                                   end
+          endpoint_configuration ||= {}
+          config_class = desc_container(endpoint_configuration)
 
           config_class.configure do
             description description
@@ -59,13 +81,12 @@ module Grape
       end
 
       def description_field(field, value = nil)
+        description = route_setting(:description)
         if value
-          description = route_setting(:description)
           description ||= route_setting(:description, {})
           description[field] = value
-        else
-          description = route_setting(:description)
-          description[field] if description
+        elsif description
+          description[field]
         end
       end
 
@@ -75,17 +96,30 @@ module Grape
       end
 
       # Returns an object which configures itself via an instance-context DSL.
-      def desc_container
+      def desc_container(endpoint_configuration)
         Module.new do
           include Grape::Util::StrictHashConfiguration.module(
+            :summary,
             :description,
             :detail,
             :params,
             :entity,
             :http_codes,
             :named,
-            :headers
+            :body_name,
+            :headers,
+            :hidden,
+            :deprecated,
+            :is_array,
+            :nickname,
+            :produces,
+            :consumes,
+            :security,
+            :tags
           )
+          config_context.define_singleton_method(:configuration) do
+            endpoint_configuration
+          end
 
           def config_context.success(*args)
             entity(*args)